pooltool.physics

Physics subpackage for pooltool

Overview

Classes

PhysicsEngine	A billiards engine for pluggable physics.
BallBallModel	An Enum for different ball-ball collision models
BallBallFrictionModel	An Enum for different ball-ball friction models
BallCCushionModel	An Enum for different ball-circular cushion collision models
BallLCushionModel	An Enum for different ball-linear cushion collision models
BallPocketModel	An Enum for different ball-pocket collision models
Resolver	A physics engine component that characterizes event resolution
StickBallModel	An Enum for different stick-ball collision models
BallTransitionModel	An Enum for different transition models

Function

evolve_ball_motion(state, rvw, R, m, u_s, u_sp, u_r, g, t)	-
evolve_perpendicular_spin_component(wz, R, u_sp, g, t)	-
evolve_perpendicular_spin_state(rvw, R, u_sp, g, t)	-
evolve_roll_state(rvw, R, u_r, u_sp, g, t)	-
evolve_slide_state(rvw, R, m, u_s, u_sp, g, t)	-
display_models()	-

Attributes

ball_ball_models	-
ball_ball_friction_models	-
ball_ccushion_models	-
ball_lcushion_models	-
ball_pocket_models	-
RESOLVER_PATH	The location of the resolver path YAML.
stick_ball_models	-
ball_transition_models	-

Classes

class pooltool.physics.PhysicsEngine(resolver: Resolver = NOTHING)

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.BallBallModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

An Enum for different ball-ball collision models

FRICTIONLESS_ELASTIC

A frictionless, instantaneous, elastic, equal mass collision resolver.

This is as simple as it gets.

See also

• This physics of this model is blogged about at https://ekiefl.github.io/2020/04/24/pooltool-theory/#1-elastic-instantaneous-frictionless

FRICTIONAL_INELASTIC

A simple ball-ball collision model including ball-ball friction, and coefficient of restitution for equal-mass balls.

Largely inspired by Dr. David Alciatore’s technical proofs (https://billiards.colostate.edu/technical_proofs), in particular, TP_A-5, TP_A-6, and TP_A-14. These ideas have been extended to include motion of both balls, and a more complete analysis of velocity and angular velocity in their vector forms.

FRICTIONAL_MATHAVAN

Ball-ball collision resolver for the Mathavan et al. (2014) collision model.

The model “uses general theories of dynamics of spheres rolling on a flat surface and general frictional impact dynamics under the assumption of point contacts between the balls under collision and that of the table.”

The authors compare the model predictions to experimental exit velocities and angles measured with a high speed camera system and illustrate marked improvement over previous theories, which unlike this model, fail to account for spin.

References

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

Available at https://billiards.colostate.edu/physics_articles/Mathavan_Sports_2014.pdf

Bases: pooltool.utils.strenum.StrEnum

class pooltool.physics.BallBallFrictionModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

An Enum for different ball-ball friction models

AVERAGE

The friction is calculated as the average of ball-ball sliding friction of the two balls.

ALCIATORE

Friction fit curve \(u_b = a + b e^{ -c v_{rel} }\) used in David Alciatore’s TP A-14.

Bases: pooltool.utils.strenum.StrEnum

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

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.

MATHAVAN_2010

Ball-cushion collision resolver for the Mathavan et al. (2010) collision model.

This work predicts ball bounce angles and bounce speeds for the ball’s collisions with a cushion, under the assumption of insignificant cushion deformation. Differential equations are derived for the ball dynamics during the impact and these these equations are solved numerically.

References

Mathavan S, Jackson MR, Parkin RM. A theoretical analysis of billiard ball-cushion dynamics under cushion impacts. Proceedings of the Institution of Mechanical Engineers, Part C. 2010;224(9):1863-1873. doi:10.1243/09544062JMES1964

Available at https://drdavepoolinfo.com//physics_articles/Mathavan_IMechE_2010.pdf

Bases: pooltool.utils.strenum.StrEnum

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

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.

MATHAVAN_2010

Ball-cushion collision resolver for the Mathavan et al. (2010) collision model.

This work predicts ball bounce angles and bounce speeds for the ball’s collisions with a cushion, under the assumption of insignificant cushion deformation. Differential equations are derived for the ball dynamics during the impact and these these equations are solved numerically.

References

Mathavan S, Jackson MR, Parkin RM. A theoretical analysis of billiard ball-cushion dynamics under cushion impacts. Proceedings of the Institution of Mechanical Engineers, Part C. 2010;224(9):1863-1873. doi:10.1243/09544062JMES1964

Available at https://drdavepoolinfo.com//physics_articles/Mathavan_IMechE_2010.pdf

Bases: pooltool.utils.strenum.StrEnum

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

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.Resolver(ball_ball: BallBallCollisionStrategy, ball_linear_cushion: BallLCushionCollisionStrategy, ball_circular_cushion: BallCCushionCollisionStrategy, ball_pocket: BallPocketStrategy, stick_ball: StickBallCollisionStrategy, transition: BallTransitionStrategy, version: int | None = None)

A physics engine component that characterizes event resolution

Important

For everything you need to know about this class, see Modular Physics.

Methods:

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

Resolve an event for a system

save(path: pooltool.serialize.Pathish) → pathlib.Path

Return type:

pathlib.Path

classmethod load(path: pooltool.serialize.Pathish) → Resolver

Return type:

Resolver

classmethod default() → Resolver

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

Return type:

Resolver

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

An Enum for different stick-ball collision models

INSTANTANEOUS_POINT

Instantaneous and point-like stick-ball interaction.

This collision assumes the stick-ball interaction is instantaneous and point-like.

Note

• A derivation of this model can be found in Dr. Dave Billiard’s technical proof A-30 (https://billiards.colostate.edu/technical_proofs/new/TP_A-30.pdf)

Additionally, a deflection (squirt) angle is calculated via pooltool.physics.resolve.stick_ball.squirt).

Bases: pooltool.utils.strenum.StrEnum

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

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

Functions

pooltool.physics.evolve_ball_motion(state: int, rvw: numpy.typing.NDArray[numpy.float64], R: float, m: float, u_s: float, u_sp: float, u_r: float, g: float, t: float) → tuple[numpy.typing.NDArray[numpy.float64], int]

Return type:

tuple[numpy.typing.NDArray[numpy.float64], int]

pooltool.physics.evolve_perpendicular_spin_component(wz: float, R: float, u_sp: float, g: float, t: float) → float

Return type:

float

pooltool.physics.evolve_perpendicular_spin_state(rvw: numpy.typing.NDArray[numpy.float64], R: float, u_sp: float, g: float, t: float) → numpy.typing.NDArray[numpy.float64]

Return type:

numpy.typing.NDArray[numpy.float64]

pooltool.physics.evolve_roll_state(rvw: numpy.typing.NDArray[numpy.float64], R: float, u_r: float, u_sp: float, g: float, t: float) → numpy.typing.NDArray[numpy.float64]

Return type:

numpy.typing.NDArray[numpy.float64]

pooltool.physics.evolve_slide_state(rvw: numpy.typing.NDArray[numpy.float64], R: float, m: float, u_s: float, u_sp: float, g: float, t: float) → numpy.typing.NDArray[numpy.float64]

Return type:

numpy.typing.NDArray[numpy.float64]

pooltool.physics.display_models()

Attributes

pooltool.physics.ball_ball_models: dict[pooltool.physics.resolve.models.BallBallModel, type[core.BallBallCollisionStrategy]]

pooltool.physics.ball_ball_friction_models: dict[BallBallFrictionModel, type[BallBallFrictionStrategy]]

pooltool.physics.ball_ccushion_models: dict[pooltool.physics.resolve.models.BallCCushionModel, type[core.BallCCushionCollisionStrategy]]

pooltool.physics.ball_lcushion_models: dict[pooltool.physics.resolve.models.BallLCushionModel, type[core.BallLCushionCollisionStrategy]]

pooltool.physics.ball_pocket_models: dict[pooltool.physics.resolve.models.BallPocketModel, type[BallPocketStrategy]]

pooltool.physics.RESOLVER_PATH

The location of the resolver path YAML.

pooltool.physics.stick_ball_models: dict[pooltool.physics.resolve.models.StickBallModel, type[core.StickBallCollisionStrategy]]

pooltool.physics.ball_transition_models: dict[pooltool.physics.resolve.models.BallTransitionModel, type[BallTransitionStrategy]]