Pooltool Pre-submission Inquiry

[ekiefl]

Submitting Author: Evan Kiefl (@ekiefl)
Package Name: pooltool
One-Line Description of Package: Pooltool is a general purpose billiards simulator crafted specifically for science and engineering.
Repository Link (if existing): https://github.com/ekiefl/pooltool

---

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.

Community Partnerships

We partner with communities to support peer review with an additional layer of
checks that satisfy community requirements. If your package fits into an
existing community please check below:

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

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

• Explain how and why the package falls under these categories (briefly, 1-2 sentences). Please note any areas you are unsure of:

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 the 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 similar things? 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.

• Any other questions or issues we should be aware of:

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

[Batalex]

Hello, and welcome to pyOpenSci! Thank you for this submission, just letting you know we have seen this issue and will get back to you with pre-review checks shortly. 🐈‍⬛

[Batalex]

Hey @ekiefl,
Congratulations on making Pooltool, I was truly blown away by the sheer amount of passion and dedication I saw in this project. I think that this project is in scope for us. More science projects could benefit from a gaming interface 😁 , but at the end of the day, what really got me hooked was your blog.

Would you mind opening a new issue referencing this pre-submission inquiry? Thanks

[ekiefl]

Hi @Batalex, thanks so much for your kind words. I'm really happy to hear you guys think this is in scope. I'll submit today 😁

[Batalex]

Superseded by #173