Merge pull request #141 from ekiefl/joss

Update paper

.github/workflows/paper.yml

@@ -11,12 +11,12 @@ jobs:
         uses: openjournals/openjournals-draft-action@master
         with:
           journal: joss
-          paper-path: paper.md
+          paper-path: paper/paper.md
       - name: Upload
         uses: actions/upload-artifact@v4
         with:
           name: paper
           # This is the output path where Pandoc will write the compiled
           # PDF. Note, this should be the same directory as the input
           # paper.md
-          path: paper.pdf
+          path: paper/paper.pdf

.github/workflows/test.yml

@@ -33,6 +33,9 @@ jobs:
           key: venv-${{ hashFiles('poetry.lock') }}
       - name: Install project dependencies
         run: poetry install
+        env:
+          # Don't give up too soon
+          POETRY_REQUESTS_TIMEOUT: '120'
       - name: Run tests
         run: poetry run pytest
 

docs/getting_started/interface.md

@@ -58,13 +58,19 @@ Make sure you play a game or two to get comfortable with the controls.
 
 ## From within python
 
-**NOTE**: This section is incomplete.
-
-To visualize shots generated from within a python script, see [](#pooltool.interact.ShotViewer).
+In the next section you'll become more familiar with the Python API, however below is a minimal example for building a system, simulating it, and visualizing the results in the interface.
+
+```python
+import pooltool as pt
+system = pt.System.example()
+pt.simulate(system, inplace=True)
+gui = pt.ShotViewer()
+gui.show(system)
+```
 
 Once a shot is visualized in the interface, all of the controls related to camera movement and animation control are applicable. If a multisystem is being visualized, different shots can be toggled by pressing *n* (next) and *p* (previous).
 
-##  Next
+## Next
 
 Next, you'll write a small Python script that simulates a pool shot and visualizes the results in the interface.
 

docs/getting_started/script.md

@@ -36,13 +36,13 @@ For those interested in some exposition, below is a line-by-line explanation.
 
 ## Explanation
 
-First thing first, the pootool package is imported which gives you access to the [top-level API](#pooltool):
+First thing first, the pootool package is imported which gives you access to the {py:mod}`top-level API <pooltool>`:
 
 ```python
 import pooltool as pt
 ```
 
-Then a table, a cue stick, and a collection of balls are created and wrapped up into a [](#pooltool.system.datatypes.System):
+Then a table, a cue stick, and a collection of balls are created and wrapped up into a {py:class}`System <pooltool.System>`:
 
 ```python
 # We need a table, some balls, and a cue stick
@@ -54,7 +54,7 @@ cue = pt.Cue(cue_ball_id="cue")
 shot = pt.System(table=table, balls=balls, cue=cue)
 ```
 
-The cue stick parameters are then set with [](#pooltool.objects.cue.datatypes.Cue.set_state). A large impact speed of `V0=8` (m/s) is chosen, and an aiming utility function is used to aim the cue ball directly at the one-ball.
+The cue stick parameters are then set with {py:meth}`pooltool.Cue.set_state`. A large impact speed of `V0=8` (m/s) is chosen, and an aiming utility function is used to aim the cue ball directly at the one-ball.
 
 ```python
 # Aim at the head ball with a strong impact
@@ -66,12 +66,12 @@ shot.cue.set_state(V0=8, phi=pt.aim.at_ball(shot, "1"))
 A description of the cue's parameters can be found in the API docs:
 
 ```{eval-rst}
-.. autoclass:: pooltool.objects.cue.datatypes.Cue
+.. autoclass:: pooltool.Cue
     :noindex:
 ```
 :::
 
-The cue parameters have been set, but the system still hasn't been simulated. This is done with a call to [](#pooltool.evolution.event_based.simulate.simulate):
+The cue parameters have been set, but the system still hasn't been simulated. This is done with a call to {py:func}`pooltool.simulate`.
 
 ```python
 # Evolve the shot.
@@ -80,7 +80,7 @@ pt.simulate(shot, inplace=True)
 
 The system has now been evolved from its initial to its final state.
 
-To visualize the shot, open the GUI with [](#pooltool.interact.ShotViewer):
+To visualize the shot, open the GUI with {py:class}`pooltool.ShotViewer`:
 
 ```python
 # Open up the shot in the GUI
@@ -90,5 +90,4 @@ interface.show(shot)
 
 ## Next
 
-Obviously this script is just the beginning. Pooltool offers much more than this, which means you have much more to learn. From here, I suggest you check out the [Examples](examples) page and dive into whatever topic interests you.
-
+Obviously this script is just the beginning. Pooltool offers much more than this, which means you have much more to learn. From here, I suggest you check out the [Examples](../examples/index.md) page and dive into whatever topic interests you.

paper.bib → paper/paper.bib

@@ -934,3 +934,43 @@ @misc{FastFiz2023
   howpublished = {\url{https://github.com/ekiefl/FastFiz}},
   note = {Accessed: 2024-04-03}
 }
+
+@software{siu_kwan_lam_2024_11642058,
+  author       = {Siu Kwan Lam and
+                  stuartarchibald and
+                  Antoine Pitrou and
+                  Mark Florisson and
+                  Graham Markall and
+                  Stan Seibert and
+                  Emergency Self-Construct and
+                  Todd A. Anderson and
+                  Guilherme Leobas and
+                  rjenc29 and
+                  Michael Collison and
+                  luk-f-a and
+                  Kaustubh and
+                  Jay Bourque and
+                  Aaron Meurer and
+                  Travis E. Oliphant and
+                  Nick Riasanovsky and
+                  Michael Wang and
+                  densmirn and
+                  KrisMinchev and
+                  Andre Masella and
+                  Ethan Pronovost and
+                  njwhite and
+                  Eric Wieser and
+                  Ehsan Totoni and
+                  Stefan Seefeld and
+                  Hernan Grecco and
+                  Pearu Peterson and
+                  Isaac Virshup and
+                  MattyG},
+  title        = {numba/numba: 0.60.0},
+  month        = jun,
+  year         = 2024,
+  publisher    = {Zenodo},
+  version      = {0.60.0},
+  doi          = {10.5281/zenodo.11642058},
+  url          = {https://doi.org/10.5281/zenodo.11642058}
+}

paper/paper.md

@@ -0,0 +1,52 @@
+---
+title: 'Pooltool: A Python package for realistic billiards simulation'
+tags:
+  - Python
+  - billiards
+  - simulation
+authors:
+  - name: Evan Kiefl
+    orcid: 0000-0002-6473-0921
+    affiliation: 1
+affiliations:
+ - name: Independent Researcher
+   index: 1
+date: 3 April 2024
+bibliography: paper.bib
+---
+
+# Summary
+
+Billiards, a broad classification for games like pool and snooker, supports a robust, multidisciplinary research and engineering community that investigates topics in physics, game theory, computer vision, robotics, and cue sports analytics. Central to these pursuits is the need for accurate simulation.
+
+Pooltool is a general-purpose billiards simulator crafted specifically for science and engineering. Its core design principles focus on speed, ease of visualization, and fine-grained analysis. It features customizable physics, an interactive 3D interface, a robust API, and extensive documentation, enabling users to easily simulate, visualize, and analyze billiards shots for generic research and engineering applications. Bolstered by a growing community and active development, pooltool aims to be a systemic tool for billiards-related research.
+
+# Statement of need
+
+Billiards simulation serves as the foundation for a wide array of research topics that collectively encompass billiards-related studies. Specifically, the application of game theory to develop AI billiards players has led to simulations becoming critical environments for the training of autonomous agents [@Smith2007-jq; @Archibald2010-av; @Fragkiadaki2015-oh; @Archibald2016-sd; @Silva2018-cm; @Chen2019-dk; @Tung2019-zu]. Meanwhile, billiards-playing robot research, which relies on simulations to predict the outcome of potential actions, has progressed significantly in the last 30 years and serves as a benchmark for broader advancements within sports robotics [@Sang1994-jv; @Alian2004-zs; @Greenspan2008-wg; @Nierhoff2012-st; @Mathavan2016-ck; @Bhagat2018-bx]. Billiards simulations also enrich computer vision (CV) capabilities, facilitating precise ball trajectory tracking and enhancing shot reconstruction for player analysis and training (for a review, see @Rodriguez-Lozano2023-hq). Additionally, through augmented reality (AR) and broadcast overlays, simulations have the potential to extend their impact by offering shot prediction and strategy formulation in contexts such as personal training apps and TV broadcasting, creating a more immersive understanding of the game.
+
+Unfortunately, the current billiards simulation software 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 a lack of 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*[^1], is unpackaged, unmaintained, provides no modularity for custom geometries or 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 [@Archibald2010-av]. Another option, *Billiards*[^2], 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++*[^3] is a 3D game with realistic physics, yet is not a general-purpose billiards simulator, instead focusing on game experience and aesthetics. Other offerings suffer from drawbacks already mentioned.
+
+The lack of suitable software for billiards simulation in research contexts forces researchers to develop case-specific simulators that meet their research requirements but 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. Pooltool fills this niche by providing a billiards simulation platform designed with speed, flexibility, and extensibility in mind.
+
+[^1]: [https://github.com/ekiefl/FastFiz](https://github.com/ekiefl/FastFiz)
+[^2]: [https://www.nongnu.org/billiards/](https://www.nongnu.org/billiards/)
+[^3]: [https://foobillardplus.sourceforge.net/](https://foobillardplus.sourceforge.net/)
+
+# Implementation
+
+Pooltool is implemented as a Python package, and thus can be utilized within Python scripts, Jupyter notebooks, other Python packages, or any environment that supports Python.
+
+Pooltool employs an event-based simulation algorithm that significantly increases computational efficiency compared to traditional methods that rely on small, discrete time steps [@Leckie2006-cc]. By utilizing analytical formulations of the equations of motion in billiards, pooltool advances the system state directly to the next significant event—such as a collision or a change in a ball's motion—by precisely calculating when these events occur. To further increase efficiency, all computationally intensive portions of the shot evolution algorithm are accelerated with just-in-time (JIT) compilation using Numba [@siu_kwan_lam_2024_11642058], which compiles Python code to machine code at runtime.
+
+Pooltool includes an interactive 3D interface written with the Python game engine, *Panda3D* [^4]. The interface is a central feature of pooltool and can be launched either from the command line or directly through the Python API. It offers a controllable camera for visualizing shot trajectories in a realistic 3D environment, along with a comprehensive set of playback controls—including options to pause, slow down, rewind, and fast-forward shots. Beyond visualization, users can also interactively simulate shots in real time, utilizing game-like controls to stroke the cue stick via keyboard and mouse inputs. Additionally, shots can be programmatically generated and visualized, making it a flexible tool for both interactive play and scripted simulations.
+
+[^4]: [https://www.panda3d.org/](https://www.panda3d.org/)
+
+![Screenshots from the interactive interface.](interface.png)
+
+# Usage
+
+Pooltool's API enables precise control over billiard system construction, simulation, and analysis. Up-to-date tutorials and examples can be found in the official documentation: [pooltool.readthedocs.io](https://pooltool.readthedocs.io/en/latest/).
+
+# References