Merge pull request #120 from ekiefl/api-redesign

Api redesign

Author: ekiefl

docs/_templates/autoapi/python/module.rst

@@ -10,7 +10,16 @@
 .. py:module:: {{ obj.name }}
 
 {% if obj.docstring %}
-    {{ obj.docstring|indent(3) }}
+    {% set docstring_lines = obj.docstring.split('\n') %}
+    {% set first_line = docstring_lines[0] %}
+    {{ first_line }}
+    {{ "-" * first_line|length }}
+    
+    {% if docstring_lines|length > 1 %}
+    {% for line in docstring_lines[1:] %}
+    {{ line }}
+    {% endfor %}
+    {% endif %}
 {% endif %}
 
 {% block subpackages %}

docs/conf.py

@@ -133,6 +133,8 @@
         "*/ani/mouse.py",
         "*/ani/tasks.py",
         "*/ani/utils.py",
+        "*/error.py",
+        "*/terminal.py",
     ]
 )
 

docs/index.md

@@ -4,10 +4,9 @@ Pooltool is a general purpose billiards simulator crafted specifically for scien
 
 Its core design principles focus on speed, flexibility, and the ease of visualization and analysis. With an interactive 3D interface, a robust API, and extensive documentation, pooltool aims to be a systemic tool in billiards-related research. Continuously evolving through active maintenance and bolstered by a growing community, this vision for pooltool emphasizes not just its current capabilities, but also its potential for growth and adaptation within billiards simulation.
 
-## Contents
-
 ```{eval-rst}
 .. toctree::
+   :hidden:
    :maxdepth: 3
 
    self

docs/local.sh

@@ -1,4 +1,4 @@
 #!/bin/bash
 rm -rf autoapi _build
 sphinx-build -b html . _build
-#open _build/index.html
+open _build/index.html

pooltool/__init__.py

@@ -1,167 +1,94 @@
-"""The primary interface for the pooltool library
+"""The top-level API for the pooltool library
 
-Members on this page have been chosen to selectively capture the most common /
-expected use cases of pooltool, and can be used simply by importing the ``pooltool``
-package. For instance:
+**Important and highly used objects are placed in this top-level API**. For example,
+``System`` can be imported directly from the top module:
 
     >>> import pooltool as pt
-    >>> ball = pt.Ball("cue")
+    >>> system = pt.System.example()
 
-Note:
-    You can of course, also import ``Ball`` from it's source
-    (:class:`pooltool.objects.ball.datatypes.Ball`):
+Alternatively, it can be imported directly from its source location:
 
-        >>> from pooltool.objects.ball.datatypes import Ball
+    >>> from pooltool.system.datatypes import System
+    >>> system = System.example()
 
-There are many other components of pooltool's API that can also be accessed, but
-that require a more detailed importing. As just an example:
-
-    >>> from pooltool.physics.resolve.ball_cushion.han_2005 import model
-
-If you believe that a component deserves to graduate to the top-level API, your
-input is valuable and such changes can be considered.
+If the object you're looking for isn't in this top-level API, **search for it in
+the submodules** listed below. Relatedly, if you believe that an objects deserves to
+graduate to the top-level API, **your input is valuable** and such changes can be
+considered.
 """
 
 __version__ = "0.2.2.1-dev"
 
 import pooltool.ai as ai
 import pooltool.ai.aim as aim
 import pooltool.ai.pot as pot
-from pooltool import terminal
-from pooltool.ani.animate import FrameStepper
-from pooltool.ani.image import (
-    GzipArrayImages,
-    HDF5Images,
-    ImageZip,
-    NpyImages,
-    image_stack,
-    save_images,
-)
-from pooltool.events import (
-    Agent,
-    AgentType,
-    Event,
-    EventType,
-    ball_ball_collision,
-    ball_circular_cushion_collision,
-    ball_linear_cushion_collision,
-    ball_pocket_collision,
-    by_ball,
-    by_time,
-    by_type,
-    filter_ball,
-    filter_events,
-    filter_time,
-    filter_type,
-    null_event,
-    rolling_spinning_transition,
-    rolling_stationary_transition,
-    sliding_rolling_transition,
-    spinning_stationary_transition,
-    stick_ball_collision,
-)
-from pooltool.evolution import simulate
-from pooltool.evolution.continuize import continuize
+import pooltool.ani.image as image
+import pooltool.constants as constants
+import pooltool.events as events
+import pooltool.evolution as evolution
+import pooltool.game as game
+import pooltool.interact as interact
+import pooltool.layouts as layouts
+import pooltool.objects as objects
+import pooltool.physics as physics
+import pooltool.ptmath as ptmath
+import pooltool.ruleset as ruleset
+import pooltool.serialize as serialize
+import pooltool.system as system
+import pooltool.terminal as terminal
+import pooltool.utils as utils
+from pooltool.events import EventType
+from pooltool.evolution import continuize, simulate
 from pooltool.game.datatypes import GameType
-from pooltool.game.layouts import generate_layout, get_rack
-from pooltool.game.ruleset import get_ruleset
-from pooltool.game.ruleset.datatypes import Player, Ruleset
 from pooltool.interact import Game, ShotViewer
+from pooltool.layouts import generate_layout, get_rack
 from pooltool.objects import (
     Ball,
-    BallHistory,
-    BallOrientation,
     BallParams,
-    BallSet,
-    BallState,
-    BilliardTableSpecs,
-    CircularCushionSegment,
     Cue,
-    CueSpecs,
-    CushionDirection,
-    CushionSegments,
-    LinearCushionSegment,
-    Pocket,
-    PocketTableSpecs,
-    SnookerTableSpecs,
     Table,
-    TableModelDescr,
     TableType,
-    get_ballset,
 )
-from pooltool.physics.engine import PhysicsEngine
-from pooltool.system import MultiSystem, System, SystemController, multisystem, visual
-
-run = terminal.Run()
-progress = terminal.Progress()
-
+from pooltool.ruleset import Player, get_ruleset
+from pooltool.system import MultiSystem, System
 
 __all__ = [
+    # subpackages
+    "serialize",
+    "constants",
+    "game",
+    "system",
+    "physics",
+    "ptmath",
+    "objects",
+    "interact",
+    "evolution",
+    "ruleset",
+    "layouts",
+    "events",
+    "terminal",
+    "image",
+    "ai",
+    "pot",
+    "aim",
+    "utils",
+    # objects
+    "Player",
     "System",
-    "MultiSystem",
-    "PhysicsEngine",
-    "multisystem",
-    "SystemController",
-    "visual",
-    "filter_ball",
-    "filter_time",
-    "filter_type",
-    "filter_events",
-    "by_type",
-    "by_ball",
-    "by_time",
-    "FrameStepper",
-    "null_event",
-    "ball_ball_collision",
-    "ball_linear_cushion_collision",
-    "ball_circular_cushion_collision",
-    "ball_pocket_collision",
-    "stick_ball_collision",
-    "spinning_stationary_transition",
-    "rolling_stationary_transition",
-    "rolling_spinning_transition",
-    "sliding_rolling_transition",
     "GameType",
-    "Event",
-    "EventType",
-    "AgentType",
-    "Agent",
+    "MultiSystem",
     "Ball",
-    "BallSet",
-    "BallState",
     "BallParams",
-    "BallHistory",
-    "BallOrientation",
-    "CueSpecs",
     "Cue",
-    "Pocket",
-    "LinearCushionSegment",
-    "CircularCushionSegment",
-    "CushionSegments",
-    "CushionDirection",
-    "ImageZip",
-    "HDF5Images",
-    "GzipArrayImages",
-    "NpyImages",
     "Table",
-    "TableModelDescr",
     "TableType",
-    "PocketTableSpecs",
-    "BilliardTableSpecs",
-    "SnookerTableSpecs",
     "Game",
-    "save_images",
-    "image_stack",
     "ShotViewer",
+    "EventType",
+    # functions
+    "get_rack",
+    "get_ruleset",
     "simulate",
     "continuize",
-    "get_rack",
     "generate_layout",
-    "get_ruleset",
-    "Player",
-    "Ruleset",
-    "get_ballset",
-    "ai",
-    "pot",
-    "aim",
 ]

pooltool/ai/__init__.py

@@ -1 +0,0 @@
-"""This is a test"""

pooltool/ani/animate.py

@@ -30,11 +30,11 @@
 from pooltool.ani.mouse import mouse
 from pooltool.evolution.continuize import continuize
 from pooltool.game.datatypes import GameType
-from pooltool.game.layouts import get_rack
-from pooltool.game.ruleset import get_ruleset
-from pooltool.game.ruleset.datatypes import Player
+from pooltool.layouts import get_rack
 from pooltool.objects.cue.datatypes import Cue
 from pooltool.objects.table.datatypes import Table
+from pooltool.ruleset import get_ruleset
+from pooltool.ruleset.datatypes import Player
 from pooltool.system.datatypes import MultiSystem, System, multisystem
 from pooltool.system.render import PlaybackMode, visual
 from pooltool.utils import get_total_memory_usage

pooltool/ani/modes/ball_in_hand.py

@@ -13,7 +13,7 @@
 from pooltool.ani.globals import Global
 from pooltool.ani.modes.datatypes import BaseMode, Mode
 from pooltool.ani.mouse import MouseMode, mouse
-from pooltool.game.ruleset.datatypes import BallInHandOptions
+from pooltool.ruleset.datatypes import BallInHandOptions
 from pooltool.system.render import visual
 from pooltool.utils import panda_path
 

pooltool/constants.py

@@ -1,9 +1,13 @@
 #! /usr/bin/env python
-"""Constants and other
+"""Constants
 
-All units are SI unless otherwise stated.
+Notes:
+    - **Developer note**: This should really be dissolved into config and motion state
+      sections of code
 """
 
+from typing import Dict
+
 import numpy as np
 
 use_numba_cache = True
@@ -13,13 +17,35 @@
 EPS_SPACE = 1e-9
 
 # Ball states
-stationary = 0
-spinning = 1
-sliding = 2
-rolling = 3
-pocketed = 4
+stationary: int = 0
+"""The stationary motion state label
+
+A ball with this motion state is both motionless and not in a pocket.
+"""
+spinning: int = 1
+"""The spinning motion state label
+
+A ball with this motion state is spinning in place.
+"""
+sliding: int = 2
+"""The sliding motion state label
+
+A ball with this motion state is sliding. For details on what this means precisely, see
+this `blog <https://ekiefl.github.io/2020/04/24/pooltool-theory/#case-4-sliding>`_.
+"""
+rolling: int = 3
+"""The rolling motion state label
+
+A ball with this motion state is rolling. For details on what this means precisely, see
+this `blog <https://ekiefl.github.io/2020/04/24/pooltool-theory/#case-3-rolling>`_.
+"""
+pocketed: int = 4
+"""The pocketed motion state label
+
+A ball with this motion state is in a pocket.
+"""
 
-state_dict = {
+state_dict: Dict[int, str] = {
     0: "stationary",
     1: "spinning",
     2: "sliding",

pooltool/events/__init__.py

@@ -1,3 +1,9 @@
+"""Event, detection, and filtration
+
+See `here <https://ekiefl.github.io/2020/12/20/pooltool-alg/#2-what-are-events>`_ to
+learn about events and why they matter.
+"""
+
 from pooltool.events.datatypes import Agent, AgentType, Event, EventType
 from pooltool.events.factory import (
     ball_ball_collision,

pooltool/events/filter.py

@@ -147,8 +147,8 @@ def filter_events(events: List[Event], *funcs: FilterFunc) -> List[Event]:
         filtering for the cue-ball pocket event. Option 1 is to call :func:`filter_type`
         and then :func:`filter_ball`:
 
-        >>> filtered_events = pt.filter_type(events, pt.EventType.BALL_POCKET)
-        >>> filtered_events = pt.filter_ball(filtered_events, "cue")
+        >>> filtered_events = pt.events.filter_type(events, pt.EventType.BALL_POCKET)
+        >>> filtered_events = pt.events.filter_ball(filtered_events, "cue")
         >>> event_of_interest = filtered_events[0]
         >>> event_of_interest
         <Event object at 0x7fa855e7e6c0>
@@ -158,10 +158,10 @@ def filter_events(events: List[Event], *funcs: FilterFunc) -> List[Event]:
 
         Option 2, the better option, is to use :func:`filter_events`:
 
-        >>> filtered_events = pt.filter_events(
+        >>> filtered_events = pt.events.filter_events(
         >>>     events,
-        >>>     pt.by_type(pt.EventType.BALL_POCKET),
-        >>>     pt.by_ball("cue"),
+        >>>     pt.events.by_type(pt.EventType.BALL_POCKET),
+        >>>     pt.events.by_ball("cue"),
         >>> )
         >>> event_of_interest = filtered_events[0]
         >>> event_of_interest

pooltool/evolution/__init__.py

@@ -1,3 +1,5 @@
+"""Shot evolution algorithm routines"""
+
 from pooltool.evolution.continuize import continuize
 from pooltool.evolution.event_based.simulate import simulate