pooltool.physics.resolve.ball_ball¶

Models for ball-ball collisions.¶

Overview¶

Classes¶
`FrictionalMathavan`	Ball-ball collision resolver for the Mathavan et al. (2014) collision model.
`FrictionlessElastic`	A frictionless, instantaneous, elastic, equal mass collision resolver.
`BallBallModel`	An Enum for different ball-ball collision models

Function¶
`get_ball_ball_model`(model, params)	Returns a ball-ball collision model

Classes¶

class pooltool.physics.resolve.ball_ball.FrictionalMathavan(num_iterations: int = 1000)[source]¶

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.physics.resolve.ball_ball.core.CoreBallBallCollision

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]¶

Resolve ball-ball collision via Mathavan et al. (2014).

This method computes the post-collision linear and angular velocities of two balls colliding on a rough surface, taking into account both ball-to-ball friction and ball-to-surface friction. The collision model is based on the method described by Mathavan et al. (2014), which considers point contacts and frictional impact dynamics between the balls.

The function transforms the velocities and angular velocities into a local coordinate frame defined by the line connecting the centers of the two balls at the point of collision. It then iteratively calculates the collision dynamics, including the effects of friction and restitution during the compression and restitution phases of the collision. Once the collision dynamics criteria are met, the updated velocities and angular velocities are transformed back into the global coordinate frame and returned.

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

class pooltool.physics.resolve.ball_ball.FrictionlessElastic[source]¶

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

This is as simple as it gets.

Functions¶

pooltool.physics.resolve.ball_ball.get_ball_ball_model(model: BallBallModel | None = None, params: pooltool.physics.resolve.types.ModelArgs = {}) → core.BallBallCollisionStrategy[source]¶

Returns a ball-ball collision model

Parameters:

model (Optional[BallBallModel]) -- An Enum specifying the desired model. If not passed, FrictionalMathavan 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 BallBallCollisionStrategy protocol.

Return type:

core.BallBallCollisionStrategy