pooltool.physics¶

Physics subpackage for pooltool¶

Subpackages¶

Submodules¶

pooltool.physics.engine

Overview¶

Classes¶
`PhysicsEngine`	A billiards engine for pluggable physics.
`BallBallCollisionStrategy`	Ball-ball collision models must satisfy this protocol
`BallBallModel`	An Enum for different ball-ball collision models
`BallCCushionCollisionStrategy`	Ball-circular cushion collision models must satisfy this protocol
`BallCCushionModel`	An Enum for different ball-circular cushion collision models
`BallLCushionCollisionStrategy`	Ball-linear cushion collision models must satisfy this protocol
`BallLCushionModel`	An Enum for different ball-linear cushion collision models
`BallPocketModel`	An Enum for different ball-pocket collision models
`BallPocketStrategy`	Ball-pocket collision models must satisfy this protocol
`Resolver`	A physics engine component that characterizes event resolution
`StickBallCollisionStrategy`	Stick-ball collision models must satisfy this protocol
`StickBallModel`	An Enum for different stick-ball collision models
`BallTransitionModel`	An Enum for different transition models
`BallTransitionStrategy`	Ball transition models must satisfy this protocol

Attributes¶
`RESOLVER_PATH`	The location of the resolver path YAML.

Classes¶

class pooltool.physics.PhysicsEngine(resolver: Resolver = NOTHING)[source]¶

A billiards engine for pluggable physics.

Important

Currently, only event resolution is a part of this class. The sliding, rolling, and spinning ball trajectory evolution is currently “hard-coded”, however can in theory be added to this class to enable alternative trajectory models.

resolver¶

The physics engine responsible for resolving events.

Type:: pooltool.physics.resolve.resolver.Resolver

class pooltool.physics.BallBallCollisionStrategy(*args, **kwargs)[source]¶

Ball-ball collision models must satisfy this protocol

Bases: _BaseStrategy, Protocol

Methods:

solve(ball1: pooltool.objects.ball.datatypes.Ball, ball2: pooltool.objects.ball.datatypes.Ball) → Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.ball.datatypes.Ball][source]¶

This method resolves a ball-ball collision

Return type:: Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.ball.datatypes.Ball]

class pooltool.physics.BallBallModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

An Enum for different ball-ball collision models

FRICTIONLESS_ELASTIC¶: Frictionless, instantaneous, elastic, equal mass collision.

FRICTIONAL_INELASTIC¶: Frictional, inelastic, equal mass collision. (https://billiards.colostate.edu/technical_proofs/new/TP_A-14.pdf).

FRICTIONAL_MATHAVAN¶: Mathavan, S., Jackson, M.R. & Parkin, R.M. Numerical simulations of the frictional collisions of solid balls on a rough surface. Sports Eng 17, 227–237 (2014). https://doi.org/10.1007/s12283-014-0158-y

Bases: pooltool.utils.strenum.StrEnum

class pooltool.physics.BallCCushionCollisionStrategy(*args, **kwargs)[source]¶

Ball-circular cushion collision models must satisfy this protocol

Bases: _BaseCircularStrategy, Protocol

Methods:

solve(ball: pooltool.objects.ball.datatypes.Ball, cushion: pooltool.objects.table.components.CircularCushionSegment) → Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.CircularCushionSegment][source]¶

This method resolves a ball-circular cushion collision

Return type:: Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.CircularCushionSegment]

class pooltool.physics.BallCCushionModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

An Enum for different ball-circular cushion collision models

HAN_2005¶: https://ekiefl.github.io/2020/04/24/pooltool-theory/#3-han-2005

UNREALISTIC¶: An unrealistic model in which balls are perfectly reflected. Spin is left untouched by the interaction.

Bases: pooltool.utils.strenum.StrEnum

class pooltool.physics.BallLCushionCollisionStrategy(*args, **kwargs)[source]¶

Ball-linear cushion collision models must satisfy this protocol

Bases: _BaseLinearStrategy, Protocol

Methods:

solve(ball: pooltool.objects.ball.datatypes.Ball, cushion: pooltool.objects.table.components.LinearCushionSegment) → Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.LinearCushionSegment][source]¶

This method resolves a ball-circular cushion collision

Return type:: Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.LinearCushionSegment]

class pooltool.physics.BallLCushionModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

An Enum for different ball-linear cushion collision models

HAN_2005¶: https://ekiefl.github.io/2020/04/24/pooltool-theory/#3-han-2005.

UNREALISTIC¶: An unrealistic model in which balls are perfectly reflected. Spin is left untouched by the interaction.

Bases: pooltool.utils.strenum.StrEnum

class pooltool.physics.BallPocketModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

An Enum for different ball-pocket collision models

CANONICAL¶: Sets the ball into the bottom of pocket and sets the state to pocketed.

Bases: pooltool.utils.strenum.StrEnum

class pooltool.physics.BallPocketStrategy(*args, **kwargs)[source]¶

Ball-pocket collision models must satisfy this protocol

Bases: Protocol

Methods:

resolve(ball: pooltool.objects.ball.datatypes.Ball, pocket: pooltool.objects.table.components.Pocket, inplace: bool = False) → Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.Pocket][source]¶

This method resolves a ball-circular cushion collision

Return type:: Tuple[pooltool.objects.ball.datatypes.Ball, pooltool.objects.table.components.Pocket]

class pooltool.physics.Resolver(ball_ball: BallBallCollisionStrategy, ball_linear_cushion: BallLCushionCollisionStrategy, ball_circular_cushion: BallCCushionCollisionStrategy, ball_pocket: BallPocketStrategy, stick_ball: StickBallCollisionStrategy, transition: BallTransitionStrategy, version: int | None = None)[source]¶

A physics engine component that characterizes event resolution

Important

For everything you need to know about this class, see :doc:`Modular Physics </resources/custom_physics>`_.

Methods:

resolve(shot: pooltool.system.datatypes.System, event: pooltool.events.datatypes.Event) → None[source]¶

Resolve an event for a system

classmethod default() → Resolver[source]¶

Load ~/.config/pooltool/physics/resolver.yaml if exists, create otherwise

Return type:: Resolver

class pooltool.physics.StickBallCollisionStrategy(*args, **kwargs)[source]¶

Stick-ball collision models must satisfy this protocol

Bases: _BaseStrategy, Protocol

Methods:

solve(cue: pooltool.objects.cue.datatypes.Cue, ball: pooltool.objects.ball.datatypes.Ball) → Tuple[pooltool.objects.cue.datatypes.Cue, pooltool.objects.ball.datatypes.Ball][source]¶

This method resolves a ball-circular cushion collision

Return type:: Tuple[pooltool.objects.cue.datatypes.Cue, pooltool.objects.ball.datatypes.Ball]

class pooltool.physics.StickBallModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

An Enum for different stick-ball collision models

INSTANTANEOUS_POINT¶: Instantaneous and point-like stick-ball interaction.

Bases: pooltool.utils.strenum.StrEnum

class pooltool.physics.BallTransitionModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

An Enum for different transition models

CANONICAL¶: Sets the ball to appropriate state. Sets any residual quantities to 0 when appropriate.

Bases: pooltool.utils.strenum.StrEnum

class pooltool.physics.BallTransitionStrategy(*args, **kwargs)[source]¶

Ball transition models must satisfy this protocol

Bases: Protocol

Methods:

resolve(ball: pooltool.objects.ball.datatypes.Ball, transition: pooltool.events.datatypes.EventType, inplace: bool = False) → pooltool.objects.ball.datatypes.Ball[source]¶

This method resolves a ball transition

Return type:: pooltool.objects.ball.datatypes.Ball

Attributes¶

pooltool.physics.RESOLVER_PATH¶: The location of the resolver path YAML.