Event Manager

vivarium constructs and manages the flow of time through the emission of regularly scheduled events. The tools in this module manage the relationships between event emitters and listeners.

The EventManager maintains a mapping between event types and channels. Each event type (and event types must be unique so event type is equivalent to event name, e.g., time_step_prepare) corresponds to an EventChannel, which tracks listeners to that event in prioritized levels and passes on the event to those listeners when emitted.

For more information, see the associated event concept note.

class vivarium.engine.framework.event.manager.Event(name, index, user_data, time, step_size)

An Event object represents the context of an event.

Events themselves are just a bundle of data. They must be emitted along an EventChannel in order for other simulation components to respond to them.

Parameters:

• name (str)

• index (pd.Index[int])

• user_data (dict[str, Any])

• time (ClockTime)

• step_size (ClockStepSize)

name: str

The name of the event. Typically a lifecycle state.

index: pd.Index[int]

An index into the population table containing all simulants affected by this event.

user_data: dict[str, Any]

Any additional data provided by the user about the event.

time: ClockTime

The simulation time at which this event will resolve. The current simulation size plus the current time step size.

step_size: ClockStepSize

The current step size at the time of the event.

split(new_index)

Creates a copy of this event with a new index.

This function should be used to emit an event in a new EventChannel in response to an event emitted from a different channel.

Parameters:

new_index (pd.Index[int]) – An index into the population table containing all simulants affected by this event.

Returns:

The new event.

Return type:

Event

class vivarium.engine.framework.event.manager.EventChannel(manager, event_name)

A named subscription channel that passes events to event listeners.

Parameters:

• manager (EventManager)

• event_name (str)

emit(index, user_data=None)

Notifies all listeners to this channel that an event has occurred.

Events are emitted to listeners in order of priority (with order 0 being first and order 9 last), with no ordering within a particular priority level guaranteed.

Parameters:

• index (pd.Index[int]) – An index into the population table containing all simulants affected by this event.

• user_data (dict[str, Any] | None) – Any additional data provided by the user about the event.

Return type:

Event

class vivarium.engine.framework.event.manager.EventManager

The configuration for the event system.

Notes

Client code should never need to interact with this class except through the decorators in this module and the emitter function exposed on the builder during the setup phase.

property name: str

The name of this component.

get_channel(event_name)

Return type:

EventChannel

Parameters:

event_name (str)

setup(builder)

Performs this component’s simulation setup.

Return type:

None

Parameters:

builder (Builder) – Object giving access to core framework functionality.

on_post_setup(event)

Return type:

None

Parameters:

event (Event)

get_emitter(event_name)

Gets an emitter function for the named event.

Parameters:

• name – The name of the event.

• event_name (str)

Returns:

A function that accepts an index and optional user data. This function creates and timestamps an Event and distributes it to all interested listeners

Return type:

Callable[[pd.Index[int], dict[str, Any] | None], Event]

register_listener(event_name, listener, priority=5)

Registers a new listener to the named event.

Return type:

None

Parameters:

• name – The name of the event.

• listener (Callable[[Event], None]) – The consumer of the named event.

• priority (int) – Number in range(10) used to assign the ordering in which listeners process the event.

• event_name (str)

get_listeners(event_name)

Gets all listeners registered for the named event.

Return type:

dict[int, list[Callable[[Event], None]]]

Parameters:

• name – The name of the event.

• event_name (str)

Returns:

A dictionary that maps each priority level of the named event’s listeners to a list of listeners at that level.

list_events()

Lists all event names known to the event system.

Return type:

list[str]

Returns:

A list of all known events names.

Notes

This value can change after setup if components dynamically create new event labels.