Pooltool Submission

[ekiefl]

Submitting Author: Evan Kiefl (@ekiefl)
All current maintainers: (@ekiefl)
Package Name: pooltool
One-Line Description of Package: Pooltool is a general purpose billiards simulator crafted specifically for science and engineering.
Repository Link: https://github.com/ekiefl/pooltool
Version submitted: v0.3.3
EiC: @Batalex
Editor: @cmarmo
Reviewer 1: @sebastianotronto
Reviewer 2: @eliotwrobson
Archive:
JOSS DOI:
Version accepted: 0.4.1
Date accepted (month/day/year): 09/16/2024

---

Code of Conduct & Commitment to Maintain Package

• I agree to abide by pyOpenSci's Code of Conduct during the review process and in maintaining my package after should it be accepted.
• I have read and will commit to package maintenance after the review as per the pyOpenSci Policies Guidelines.

Description

• Include a brief paragraph describing what your package does:

Pooltool is a platform to simulate, analyze, and interactively visualize billiards shots. A defining feature is pooltool’s flexible physics architecture, which supports customizable physics models to foster novel applications and encourage community-driven advancements in realism. Pooltool uses parametric table geometries that accommodate custom measurements, and even supports non-traditional table designs built with linear and circular cushion segments. Its robust object-oriented design simplifies data accessibility and analysis, which is complemented by the ability to losslessly encode/decode raw simulation data into common storage formats. Pooltool is performant due to just-in-time compilation, an event-based evolution algorithm, and efficiently designed data structures. Pooltool is packaged with an interactive 3D interface, with a comprehensive suite of controls. Through the interface, one can interactively simulate different billiards games or visualize programmatically-generated shots. Continuously evolving through active maintenance and bolstered by a growing community, pooltool represents a significant stride in the realm of billiards simulation for research purposes.

Scope

• Please indicate which category or categories.
  Check out our package scope page to learn more about our
  scope. (If you are unsure of which category you fit, we suggest you make a pre-submission inquiry):

  • Data retrieval
  • Data extraction
  • Data processing/munging
  • Data deposition
  • Data validation and testing
  • Data visualization¹
  • Workflow automation
  • Citation management and bibliometrics
  • Scientific software wrappers
  • Database interoperability

Domain Specific

• Geospatial
• Education

Community Partnerships

If your package is associated with an
existing community please check below:

• Astropy:My package adheres to Astropy community standards
• Pangeo: My package adheres to the Pangeo standards listed in the pyOpenSci peer review guidebook

• For all submissions, explain how the and why the package falls under the categories you indicated above. In your explanation, please address the following points (briefly, 1-2 sentences for each):

Data processing/munging: Pooltool is a physics simulator that both generates simulation data and provides a convenient, object-oriented design for simplifying data accessibility and analysis, which aligns with data processing/munging. Pooltool uses user-facing data structures, compute efficient algorithms, and lossless serialization/deserialization routines to enhance its performance as a data processing / munging utility for billiards simulation.

Data visualization: Pooltool includes a 3D interactive interface with a comprehensive suite of controls for visualizing and simulating billiards games. This promotes an exploratory approach to billiards simulation, and complete interactive control for interpreting and understanding data generated by the software.

• Who is the target audience and what are scientific applications of this package?

Billiards, a term describing games like pool and snooker, supports a robust, multidisciplinary research community investigating topics in physics, game theory, computer vision, robotics, and cue sports analytics.

More than just a collection of physics equations, billiards simulation requires algorithms that coordinate the proper usage of these equations, in order to calculate a comprehensive trajectory of the system through time. Accurate billiards simulation is critical for game theory applications (e.g. developing AI players), billiards-playing robots, computer-vision powered data analytics, shot prediction for assistive learning applications and improved TV broadcasting, and more. In short, pooltool is designed for researchers who require accurate, open, and customizable billiards simulation for their research applications.

• Are there other Python packages that accomplish the same thing? If so, how does yours differ?

In short, no.

The current landscape reveals a stark contrast between the realistic physics seen in some commercially-produced games (i.e. Shooterspool and VirtualPool4), and the limited functionality of open-source projects. Commercial products have little, if any, utility in research contexts, due to closed source code and no open APIs. Conversely, available open source tools lack realism, usability, and adaptability for generic research needs. The most widely cited simulator in research studies, FastFiz, is unpackaged, unmaintained, provides no modularity for custom geometries nor for physical models, offers restrictive 2D visualizations, outputs minimal simulation results with no built in capabilities for introspection, and was custom built for hosting the Association for the Advancement of Artificial Intelligence (AAAI) Computational Pool Tournament from 2005-2008. Billiards offers a visually appealing 3D game experience, realistic physics, and supports customization via Lua scripting. However, as a standalone application, it lacks interoperability with commonly used systems and tools in research. Written in Lua, an uncommon language in the scientific community, it has limited appeal in research settings. The lack of Windows support is another drawback. FooBilliard++ is another 3D game with realistic physics, yet is not a general purpose billiards simulator, instead focusing on game experience and aesthetics. python-billiards is an overly simplistic 2D world. Others suffer from drawbacks already mentioned.

The lack of suitable software for billiards simulation in research contexts, let alone software written in Python, forces researchers to develop case-specific simulators that meet their research requirements, but that fall short of serving the broader community as general purpose simulators. This fragments the research collective, renders cross-study results difficult or impossible to compare, and leads to wasted effort spent reinventing the wheel.

• If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted:

#171 (@Batalex)

Technical checks

For details about the pyOpenSci packaging requirements, see our packaging guide. Confirm each of the following by checking the box. This package:

• does not violate the Terms of Service of any service it interacts with.
• uses an OSI approved license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions.
• contains a tutorial with examples of its essential functions and uses.
• has a test suite.
• has continuous integration setup, such as GitHub Actions CircleCI, and/or others.

Publication Options

• Do you wish to automatically submit to the Journal of Open Source Software? If so:

JOSS Checks

• The package has an obvious research application according to JOSS's definition in their submission requirements. Be aware that completing the pyOpenSci review process does not guarantee acceptance to JOSS. Be sure to read their submission requirements (linked above) if you are interested in submitting to JOSS.
• The package is not a "minor utility" as defined by JOSS's submission requirements: "Minor ‘utility’ packages, including ‘thin’ API clients, are not acceptable." pyOpenSci welcomes these packages under "Data Retrieval", but JOSS has slightly different criteria.
• The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
• The package is deposited in a long-term repository with the DOI: 10.5281/zenodo.10995499

Note: JOSS accepts our review as theirs. You will NOT need to go through another full review. JOSS will only review your paper.md file. Be sure to link to this pyOpenSci issue when a JOSS issue is opened for your package. Also be sure to tell the JOSS editor that this is a pyOpenSci reviewed package once you reach this step.

Are you OK with Reviewers Submitting Issues and/or pull requests to your Repo Directly?

This option will allow reviewers to open smaller issues that can then be linked to PR's rather than submitting a more dense text based review. It will also allow you to demonstrate addressing the issue via PR links.

• Yes I am OK with reviewers submitting requested changes as issues to my repo. Reviewers will then link to the issues in their submitted review.

Confirm each of the following by checking the box.

• I have read the author guide.
• I expect to maintain this package for at least 2 years and can help find a replacement for the maintainer (team) if needed.

Please fill out our survey

• Last but not least please fill out our pre-review survey. This helps us track
  submission and improve our peer review process. We will also ask our reviewers
  and editors to fill this out.

P.S. Have feedback/comments about our review process? Leave a comment here

Editor and Review Templates

The editor template can be found here.

The review template can be found here.

Footnotes

1. Please fill out a pre-submission inquiry before submitting a data visualization package. ↩

[Batalex]

Editor in Chief checks

Hi there! Thank you for submitting your package for pyOpenSci
review. Below are the basic checks that your package needs to pass
to begin our review. If some of these are missing, we will ask you
to work on them before the review process begins.

Please check our Python packaging guide for more information on the elements
below.

• Installation The package can be installed from a community repository such as PyPI (preferred), and/or a community channel on conda (e.g. conda-forge, bioconda).
  • The package imports properly into a standard Python environment import package.
• Fit The package meets criteria for fit and overlap.
• Documentation The package has sufficient online documentation to allow us to evaluate package function and scope without installing the package. This includes:
  • User-facing documentation that overviews how to install and start using the package.
  • Short tutorials that help a user understand how to use the package and what it can do for them.
  • API documentation (documentation for your code's functions, classes, methods and attributes): this includes clearly written docstrings with variables defined using a standard docstring format.
• Core GitHub repository Files
  • README The package has a README.md file with clear explanation of what the package does, instructions on how to install it, and a link to development instructions.
  • Contributing File The package has a CONTRIBUTING.md file that details how to install and contribute to the package.
  • Code of Conduct The package has a CODE_OF_CONDUCT.md file.
  • License The package has an OSI approved license.
    NOTE: We prefer that you have development instructions in your documentation too.
• Issue Submission Documentation All of the information is filled out in the YAML header of the issue (located at the top of the issue template).
• Automated tests Package has a testing suite and is tested via a Continuous Integration service.
• Repository The repository link resolves correctly.
• Package overlap The package doesn't entirely overlap with the functionality of other packages that have already been submitted to pyOpenSci.
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly.
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?

---

• Initial onboarding survey was filled out
  We appreciate each maintainer of the package filling out this survey individually. 🙌
  Thank you authors in advance for setting aside five to ten minutes to do this. It truly helps our organization. 🙌

---

---

Editor comments

paper.md not yet merged, but this is not blocking https://github.com/ekiefl/pooltool/pull/122/files

[ekiefl]

Hi @Batalex, I've made the following changes:

1. I've merged paper.md
2. I made a new release (v0.3.2)
3. I made a DOI for v0.3.2: https://doi.org/10.5281/zenodo.10995500

I edited the first post with the bumped version (v0.3.2) and the DOI.

Regarding the survey: I already filled this out, but if your records show otherwise, I'm happy to do it again.

With this all finished, I think we're done with pre-review checks. Please let me know if there's anything else left to do.

Thanks for your time.

[ekiefl]

In anticipating pooltool being reviewed in pyOpenSci, I've given a lot of thought about my licensing and I've decided to switch licenses from GPLv3 to Apache v2. I figured it would be better to do this before any reviews start, so I've made the following changes:

1. Merged the license change (Change of LICENSE from GPL to Apache ekiefl/pooltool#123)
2. Made a new release (v0.3.3)
3. I made a DOI for v0.3.3: https://doi.org/10.5281/zenodo.11171124

I edited the first post with the bumped version (v0.3.3) and the DOI.

[Batalex]

Hey @ekiefl,
I am very pleased to announce that @cmarmo will oversee leading the review as the editor! Chiara will be your first line responder from now on, though you are welcome to ask anyone if you have any question during the process.
Happy review!