`pooltool.events`¶

Events, their detection, creation, and filtration.

See here to learn about events and why they matter.

Classes¶

An event agent.

This class represents an agent involved in events. The agent can be in different states before and after an event, represented by initial and final states.

Attributes:

id : str ¶: ID for the agent.

agent_type : AgentType ¶: The type of the agent.

initial : pooltool.objects.datatypes.NullObject | Cue | Ball | Pocket | LinearCushionSegment | CircularCushionSegment | None ¶: The state of the agent before an event.

final : pooltool.objects.datatypes.NullObject | Cue | Ball | Pocket | LinearCushionSegment | CircularCushionSegment | None ¶: The state of the agent after an event.

Methods:

set_initial(obj: Object) → None[source]¶

Sets the initial state of the agent (before event resolution).

This makes a copy of the passed object and sets it to initial.

In the case of a pooltool.events.AgentType.BALL agent type, it drops history fields before copying to save time and memory.

Parameters:

obj : Object

The object from which initial will be set.

set_final(obj: Object) → None[source]¶

Sets the final state of the agent (after event resolution).

This makes a copy of the passed object and sets it to final.

In the case of a pooltool.events.AgentType.BALL agent type, it drops history fields before copying to save time and memory.

Parameters:

obj : Object

The object from which final will be set.

static from_object(obj: Object, set_initial: bool = False) → Agent[source]¶

Creates an agent instance from an object.

Optionally sets the initial state of the agent based on the provided object. The final state is not set.

Parameters:

obj : Object

The object to create the agent from.
set_initial : bool

If True, sets the initial state of the agent to the object’s state.

Returns:

A new instance of Agent.

Return type:

Agent

copy() → Agent[source]¶

Create a copy.

Return type:: Agent

class AgentType[source]¶

An Enum of event agents

Base Classes:

pooltool.utils.strenum.StrEnum

Attributes:

NULL¶: A null agent.

CUE¶: A cue stick agent.

BALL¶: A ball agent.

POCKET¶: A pocket agent.

LINEAR_CUSHION_SEGMENT¶: A linear cushion segment agent.

CIRCULAR_CUSHION_SEGMENT¶: A circular cushion segment agent.

class Event(event_type: EventType, agents: tuple[Agent, ...], time: float)[source]¶

Represents an event.

This class models an event characterized by its type, the agents involved, and the time at which the event occurs.

Agent states before and after event resolution are stored in the pooltool.events.Agent.initial and pooltool.events.Agent.final attributes of agents within agents.

Attributes:

event_type : EventType ¶: The type of the event, indicating the nature of the event.

agents : tuple[Agent, ...]¶

A tuple containing one or two agents involved in the event.

Events that are collisions (pooltool.events.EventType.is_collision()) have two agents, while events that are transitions (pooltool.events.EventType.is_transition()), or events with event type pooltool.events.EventType.NONE, have one agent.

By convention, the order of the agents matches how the pooltool.events.EventType attributes are named.

time : float ¶: The time at which the event occurs.

property ids: tuple[str, ...]¶

Retrieves the IDs of the agents involved in the event.

This property provides access to a tuple of agent IDs, allowing identification of the agents involved in the event.

Returns:: A tuple containing the IDs of the agents involved in the event.
Return type:: Tuple[str, ...]

Methods:

copy() → Event[source]¶

Create a copy.

Return type:: Event

get_ball(ball_id: str, initial: bool = True) → Ball[source]¶

Return the Ball object with the given ID, either final or initial.

Parameters:

ball_id : str

The ID of the ball to retrieve.
initial : bool

If True, return the ball’s initial state; otherwise final state.

Raises:

ValueError -- If the event does not involve a ball or if no matching ball is found.

Return type:

Ball

get_pocket(pocket_id: str, initial: bool = True) → Pocket[source]¶

Return the Pocket object with the given ID, either final or initial.

Return type:: Pocket

get_cushion(cushion_id: str) → LinearCushionSegment | CircularCushionSegment[source]¶

Return the cushion segment with the given ID.

Return type:: LinearCushionSegment | CircularCushionSegment

get_stick(stick_id: str) → Pocket[source]¶

Return the cue stick with the given ID.

Return type:: Pocket

class EventType[source]¶

An Enum of event types

Base Classes:

pooltool.utils.strenum.StrEnum

Attributes:

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.

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

has_ball() → bool[source]¶

Returns True if this event type can involve a Ball.

Return type:: bool

has_cushion() → bool[source]¶

Returns True if this event type can involve a cushion (linear or circular).

Return type:: bool

has_pocket() → bool[source]¶

Returns True if this event type can involve a Pocket.

Return type:: bool

has_stick() → bool[source]¶

Returns True if this event type can involve a CueStick.

Return type:: bool

Functions¶

ball_ball_collision(ball1: Ball, ball2: Ball, time: float, set_initial: bool = False) → Event[source]¶

Create a ball-ball collision.

Return type:: Event

ball_circular_cushion_collision(ball: Ball, cushion: CircularCushionSegment, time: float, set_initial: bool = False) → Event[source]¶

Create a ball-circular-cushion collision.

Return type:: Event

ball_linear_cushion_collision(ball: Ball, cushion: LinearCushionSegment, time: float, set_initial: bool = False) → Event[source]¶

Create a ball-linear-cushion collision.

Return type:: Event

ball_pocket_collision(ball: Ball, pocket: Pocket, time: float, set_initial: bool = False) → Event[source]¶

Create a ball-pocket collision.

Return type:: Event

null_event(time: float, set_initial: bool = False) → Event[source]¶

Create a null event.

Return type:: Event

rolling_spinning_transition(ball: Ball, time: float, set_initial: bool = False) → Event[source]¶

Create a rolling-spinning transition.

Return type:: Event

rolling_stationary_transition(ball: Ball, time: float, set_initial: bool = False) → Event[source]¶

Create a rolling-stationary transition.

Return type:: Event

sliding_rolling_transition(ball: Ball, time: float, set_initial: bool = False) → Event[source]¶

Create a sliding-rolling transition.

Return type:: Event

spinning_stationary_transition(ball: Ball, time: float, set_initial: bool = False) → Event[source]¶

Create a spinning-stationary transition.

Return type:: Event

stick_ball_collision(stick: Cue, ball: Ball, time: float, set_initial: bool = False) → Event[source]¶

Create a cue stick-ball collision.

Return type:: Event

by_ball(ball_ids: str | list[str], keep_nonevent: bool = False) → FilterFunc[source]¶

Returns a function that filters events based on ball IDs.

Parameters:

ball_ids : str | list[str]

A collection of ball IDs.
keep_nonevent : bool

Retain non-events (pooltool.events.EventType.NONE).

Returns:

A function that when passed a list of events, returns a filtered list containing only events that involve balls matching the passed ball ID(s).

Return type:

FilterFunc

by_time(t: float, after: bool = True) → FilterFunc[source]¶

Returns a function that filter events with respect to a time cutoff.

Parameters:

t : float

The cutoff time for filtering events.
after : bool

If True, return events after time t (non-inclusive). If False, return events before time t (non-inclusive).

Returns:

A function that when passed a list of events, returns a filtered list containing only events before or after the cutoff time, non-inclusive.

Return type:

FilterFunc

by_type(types: EventType | list[EventType]) → FilterFunc[source]¶

Returns a function that filters events based on event type.

Parameters:

types : EventType | list[EventType]

Event type(s) you want to include in your result. All others will be filtered.

Returns:

A function that when passed a list of events, returns a filtered list containing only events matching the passed event type(s).

Return type:

FilterFunc

filter_ball(events: list[Event], ball_ids: str | list[str], keep_nonevent: bool = False) → list[Event][source]¶

Filter events based on ball IDs.

Parameters:

events : list[Event]

A list of chronological events.
ball_ids : str | list[str]

A collection of ball IDs.
keep_nonevent : bool

Retain non-events (pooltool.events.EventType.NONE).

Returns:

A filtered event list containing only events that involve balls matching the passed ball ID(s).

Return type:

List[Event]

See also

If you’re filtering based on multiple criteria, you can (and should!) use pooltool.events.filter_events().

filter_events(events: list[Event], *funcs: FilterFunc) → list[Event][source]¶

Filter events using multiple criteria.

A convenient way to filter based multiple filtering criteria.

Parameters:

events : list[Event]

A list of chronological events.
*funcs : FilterFunc

An arbitrary number of functions that take a list of events as input, and gives a subset of that list as input. It sounds laborious--it’s not. See Examples.

Returns:

A filtered event list containing only events passing the supplied criteria.

Return type:

List[Event]

Examples

Generate a list of events.

>>> import pooltool as pt
>>> system = pt.System.example()
>>> system.cue.set_state(a=0.68)
>>> pt.simulate(system, inplace=True)
>>> events = system.events

In this shot, both the cue-ball and the 1-ball are potted. We are interested in filtering for the cue-ball pocket event. Option 1 is to call pooltool.events.filter_type() and then pooltool.events.filter_ball():

>>> filtered_events = pt.events.filter_type(events, pt.EventType.BALL_POCKET)
>>> filtered_events = pt.events.filter_ball(filtered_events, "cue")
>>> event_of_interest = filtered_events[0]
>>> event_of_interest
<Event object at 0x7fa855e7e6c0>
 ├── type   : ball_pocket
 ├── time   : 3.231130101576186
 └── agents : ('cue', 'rt')

Option 2, the better option, is to use pooltool.events.filter_events():

>>> filtered_events = pt.events.filter_events(
>>>     events,
>>>     pt.events.by_type(pt.EventType.BALL_POCKET),
>>>     pt.events.by_ball("cue"),
>>> )
>>> event_of_interest = filtered_events[0]
>>> event_of_interest
<Event object at 0x7fa855e7e6c0>
 ├── type   : ball_pocket
 ├── time   : 3.231130101576186
 └── agents : ('cue', 'rt')

See also

If you’re filtering based on a single criterion, you can consider using pooltool.events.filter_type(), pooltool.events.filter_ball(), pooltool.events.filter_time(), etc.

filter_time(events: list[Event], t: float, after: bool = True) → list[Event][source]¶

Filter events with respect to a time cutoff.

Parameters:

events : list[Event]

A list of chronological events.
t : float

The cutoff time for filtering events.
after : bool

If True, return events after time t (non-inclusive). If False, return events before time t (non-inclusive).

Returns:

A filtered event list containing only events before or after the cutoff time, non-inclusive.

Return type:

List[Event]

See also

If you’re filtering based on multiple criteria, you can (and should!) use pooltool.events.filter_events().

filter_type(events: list[Event], types: EventType | list[EventType]) → list[Event][source]¶

Filter events based on event type.

Parameters:

events : list[Event]

A list of chronological events.
types : EventType | list[EventType]

Event type(s) you want to include in your result. All others will be filtered.

Returns:

A filtered event list containing only events matching the passed event type(s).

Return type:

List[Event]

See also

If you’re filtering based on multiple criteria, you can (and should!) use pooltool.events.filter_events().

pooltool.events¶

Classes¶

Functions¶

`pooltool.events`¶