pooltool.evolution.event_based.simulate#

Overview#

Function#
`simulate`(shot, engine, inplace, continuous, dt, t_final, quartic_solver, include, max_events)	Run a simulation on a system and return it
`get_next_ball_ball_collision`(shot, solver)	Returns next ball-ball collision
`get_next_ball_circular_cushion_event`(shot, solver)	Returns next ball-cushion collision (circular cushion segment)
`get_next_ball_linear_cushion_collision`(shot)	Returns next ball-cushion collision (linear cushion segment)
`get_next_ball_pocket_collision`(shot, solver)	Returns next ball-pocket collision

Functions#

pooltool.evolution.event_based.simulate.simulate(shot: pooltool.system.datatypes.System, engine: pooltool.physics.engine.PhysicsEngine | None = None, inplace: bool = False, continuous: bool = False, dt: float | None = None, t_final: float | None = None, quartic_solver: pooltool.ptmath.roots.quartic.QuarticSolver = QuarticSolver.HYBRID, include: Set[pooltool.events.EventType] = INCLUDED_EVENTS, max_events: int = 0) → pooltool.system.datatypes.System[source]#

Run a simulation on a system and return it

Parameters:

shot (pooltool.system.datatypes.System) -- The system you would like simulated. The system should already have energy, otherwise there will be nothing to simulate.
engine (Optional[pooltool.physics.engine.PhysicsEngine]) -- The engine holds all of the physics. You can instantiate your very own pooltool.physics.engine.PhysicsEngine object, or you can modify ~/.config/pooltool/physics/resolver.json to change the default engine.
inplace (bool) -- By default, a copy of the passed system is simulated and returned. This leaves the passed system unmodified. If inplace is set to True, the passed system is modified in place, meaning no copy is made and the returned system is the passed system. For a more practical distinction, see Examples below.
continuous (bool) -- If True, the system will not only be simulated, but it will also be “continuized”. This means each ball will be populated with a ball history with small fixed timesteps that make it ready for visualization.
dt (Optional[float]) -- The small fixed timestep used when continuous is True.
t_final (Optional[float]) -- If set, the simulation will end prematurely after the calculation of an event with event.time > t_final.
quartic_solver (pooltool.ptmath.roots.quartic.QuarticSolver) -- Which QuarticSolver do you want to use for solving quartic polynomials?
include (Set[pooltool.events.EventType]) -- Which EventType are you interested in resolving? By default, all detected events are resolved.
max_events (int) -- If this is greater than 0, and the shot has more than this many events, the simulation is stopped and the balls are set to stationary.

Returns:

The simulated system.

Return type:

System

Examples

Standard usage:

>>> # Simulate a system
>>> import pooltool as pt
>>> system = pt.System.example()
>>> simulated_system = pt.simulate(system)
>>> assert not system.simulated
>>> assert simulated_system.simulated

The returned system is simulated, but the passed system remains unchanged.

You can also modify the system in place:

>>> # Simulate a system in place
>>> import pooltool as pt
>>> system = pt.System.example()
>>> simulated_system = pt.simulate(system, inplace=True)
>>> assert system.simulated
>>> assert simulated_system.simulated
>>> assert system is simulated_system

Notice that the returned system _is_ the simulated system. Therefore, there is no point catching the return object when inplace is True:

>>> # Simulate a system in place
>>> import pooltool as pt
>>> system = pt.System.example()
>>> assert not system.simulated
>>> pt.simulate(system, inplace=True)
>>> assert system.simulated

You can continuize the ball trajectories with continuous

>>> # Simulate a system in place
>>> import pooltool as pt
>>> system = pt.simulate(pt.System.example(), continuous=True)
>>> for ball in system.balls.values(): assert len(ball.history_cts) > 0