pooltool.physics.resolve.transition¶

Defining and handling ball state transitions¶

Note

If this module is ever extended to support multiple treatments for ball transitions, expand this file into a file structure modelled after ../ball_ball or ../ball_cushion

Overview¶

Classes¶
`EventType`	An Enum of event types
`Ball`	A billiards ball
`StrEnum`	Enum where members are also (and must be) strings
`BallTransitionStrategy`	Ball transition models must satisfy this protocol
`BallTransitionModel`	An Enum for different transition models

Function¶
`get_transition_model`(model, params)	Returns a transition model

Attributes¶
`ModelArgs`	A mapping of argument names to argument values

Classes¶

class pooltool.physics.resolve.transition.EventType(value)[source]¶

An Enum of event types

NONE¶: The null event.

BALL_BALL¶: A ball-ball collision.

BALL_LINEAR_CUSHION¶: A ball collision with a linear cushion segment.

BALL_CIRCULAR_CUSHION¶: A ball collision with a circular cushion segment.

BALL_POCKET¶: A ball pocket “collision”. This marks the point at which the ball crosses the point of no return.

STICK_BALL¶: A cue-stick ball collision.

SPINNING_STATIONARY¶: A ball transition from spinning to stationary.

ROLLING_STATIONARY¶: A ball transition from rolling to stationary.

ROLLING_SPINNING¶: A ball transition from rolling to spinning.

SLIDING_ROLLING¶: A ball transition from sliding to rolling.

Bases: pooltool.utils.strenum.StrEnum

Methods:

is_collision() → bool[source]¶

Returns whether the member is a collision

Return type:: bool

is_transition() → bool[source]¶

Returns whether the member is a transition

Return type:: bool

class pooltool.physics.resolve.transition.Ball(id: str, state: BallState = BallState.default, params: BallParams = BallParams.default, ballset: BallSet | None = None, initial_orientation: BallOrientation = BallOrientation.random, history: BallHistory = BallHistory.factory, history_cts: BallHistory = BallHistory.factory)[source]¶

A billiards ball

This class represents a billiards ball. It stores its parameters (mass, radius, etc.), it’s state (coordinates, velocity, spin, etc), its history (a time-resolved trajectory of its state), amongst other things.

id¶

An ID for the ball.

Use strings (e.g. “1” not 1).

Type:: str

state¶

The ball’s state.

This is the current state of the ball.

See also

See the Important section in Ball for a description of the role of states during simulation.

Type:: pooltool.objects.ball.datatypes.BallState

params¶

The ball’s physical parameters.

The physical parameters of the ball.

Type:: pooltool.objects.ball.params.BallParams

ballset¶

The ball set that the ball belongs to.

Important if rendering the ball in a scene.

See also

See Ball.set_ballset() for details

Type:: pooltool.objects.ball.sets.BallSet | None

initial_orientation¶

The initial rendered orientation of the ball.

Important if rendering the ball in a scene.

This is the orientation of the ball at \(t = 0\).

Type:: pooltool.objects.ball.datatypes.BallOrientation

history¶

The ball’s state history

The historical states of the ball from \(t_{initial}\) to \(t_{final}\).

See also

See the Important section in Ball for a description of the role of history during simulation.

Type:: pooltool.objects.ball.datatypes.BallHistory

history_cts¶

The ball’s continuous state history

The historical states of the ball from \(t_{initial}\) to \(t_{final}\) densely sampled with respect to time.

See also

See pooltool.evolution.event_based.continuize.continuize() for a details about continuizing a simulated system.
See the Important section in Ball for a description of the role of history_cts during simulation.

Type:: pooltool.objects.ball.datatypes.BallHistory

Important

To instantiate this class, consider using the create() constructor. Or, use functions within pooltool.layouts to generate entire collection of balls. Or, of course, construct as normal with __init__.

Important

The following explains how a Ball object is modified when its parent system is simulated (pooltool.evolution.event_based.simulate.simulate()).

At the start of the simulation process, state represents the ball state at \(t = 0\). A copy of state is appended to history.

For each timestep of the simulation, state is used to inform how the system should advance forward in time. Once determined, state is updated to reflect the ball’s new state. A copy of state is appended to history.

When the simulation is finished, state represents the final resting state of the ball. So too does history[-1].

Finally, if the system is continuized (see pooltool.evolution.continuize.continuize()), history_cts is populated. Otherwise it remains empty.

property xyz¶

The displacement (from origin) vector of the ball.

A shortcut for self.state.rvw[0].

property vel¶

The velocity vector of the ball.

A shortcut for self.state.rvw[1].

property avel¶

The angular velocity vector of the ball.

A shortcut for self.state.rvw[2].

Methods:

set_ballset(ballset: pooltool.objects.ball.sets.BallSet) → None[source]¶

Update the ballset

Raises:: ValueError -- If the ball ID doesn’t match to a model name of the ballset.

See also

See pooltool.objects.ball.sets for details about ball sets.
See pooltool.system.datatypes.System.set_ballset() for setting the ballset for all the balls in a system.

copy(drop_history: bool = False) → Ball[source]¶

Create a copy

Parameters:: drop_history (bool) -- If True, the returned copy history and history_cts attributes are both set to empty BallHistory objects.
Return type:: Ball

static create(id: str, *, xy: Sequence[float] | None = None, ballset: pooltool.objects.ball.sets.BallSet | None = None, **kwargs) → Ball[source]¶

Create a ball using keyword arguments.

This constructor flattens the tunable parameter space, allowing one to construct a Ball without directly instancing objects like like pooltool.objects.balls.params.BallParams and BallState.

Parameters:

xy (Optional[Sequence[float]]) -- The x and y coordinates of the ball position.
ballset (Optional[pooltool.objects.ball.sets.BallSet]) -- A ballset.
**kwargs -- Arguments accepted by pooltool.objects.balls.params.BallParams

Return type:

Ball

class pooltool.physics.resolve.transition.StrEnum(value)[source]¶

Enum where members are also (and must be) strings

Bases: str, enum.Enum

class pooltool.physics.resolve.transition.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

class pooltool.physics.resolve.transition.BallTransitionModel(value)[source]¶

An Enum for different transition models

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

Bases: pooltool.utils.strenum.StrEnum

Functions¶

pooltool.physics.resolve.transition.get_transition_model(model: BallTransitionModel | None = None, params: pooltool.physics.resolve.types.ModelArgs = {}) → BallTransitionStrategy[source]¶

Returns a transition model

Parameters:

model (Optional[BallTransitionModel]) -- An Enum specifying the desired model. If not passed, CanonicalTransition is passed with empty params.
params (pooltool.physics.resolve.types.ModelArgs) -- A mapping of parameters accepted by the model.

Returns:

An instantiated model that satisfies the BallTransitionStrategy protocol.

Return type:

BallTransitionStrategy

Attributes¶

pooltool.physics.resolve.transition.ModelArgs¶: A mapping of argument names to argument values