The Vivarium Event Framework

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 and provide an interface for user components to register themselves as emitters or listeners to particular events.

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.

The EventInterface is exposed off the builder and provides two methods: get_emitter, which returns a callable emitter for the given event type and register_listener, which adds the given listener to the event channel for the given event. This is the only part of the event framework with which client code should interact.

For more information, see the associated event concept note.

class vivarium.framework.event.Event[source]

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.


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


Any additional data provided by the user about the event.


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


The current step size at the time of the event.


Alias for field number 0


Alias for field number 1


Alias for field number 2


Alias for field number 3


Create 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 (Index) – An index into the population table containing all simulants affected by this event.
Return type:The new event.
class vivarium.framework.event.EventManager[source]

The configuration for the event system.


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.


The name of this component.


Performs this component’s simulation setup.

Parameters:builder – Object giving access to core framework functionality.

Get an emitter function for the named event.

Parameters:name (str) – The name of the event.
Return type:Callable[[Index, Optional[Dict[~KT, ~VT]]], Event]
  • A function that accepts an index and optional user data. This function
  • creates and timestamps an Event and distributes it to all interested
  • listeners
register_listener(name, listener, priority=5)[source]

Registers a new listener to the named event.

  • name (str) – The name of the event.
  • listener (Callable) – The consumer of the named event.
  • priority (int) – Number in range(10) used to assign the ordering in which listeners process the event.

Get all listeners registered for the named event.

Parameters:name (str) – The name of the event.
Return type:Dict[int, List[Callable]]
  • A dictionary that maps each priority level of the named event’s
  • listeners to a list of listeners at that level.

List all event names known to the event system.

Return type:A list of all known event names.


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

class vivarium.framework.event.EventInterface(manager)[source]

The public interface for the event system.


Gets an emitter for a named event.

Parameters:name (str) – The name of the event the requested emitter will emit. Users may provide their own named events by requesting an emitter with this function, but should do so with caution as it makes time much more difficult to think about.
Return type:Callable[[Index, Optional[Dict[~KT, ~VT]]], Event]
  • An emitter for the named event. The emitter should be called by
  • the requesting component at the appropriate point in the simulation
  • lifecycle.
register_listener(name, listener, priority=5)[source]

Registers a callable as a listener to a events with the given name.

The listening callable will be called with a named Event as its only argument any time the event emitter is invoked from somewhere in the simulation.

The framework creates the following events and emits them at different points in the simulation:

  • At the end of the setup phase: post_setup
  • Every time step: - time_step__prepare - time_step - time_step__cleanup - collect_metrics
  • At simulation end: simulation_end
  • name (str) – The name of the event to listen for.
  • listener (Callable[[Event], None]) – The callable to be invoked any time an Event with the given name is emitted.
  • priority ({0, 1, 2, 3, 4, 5, 6, 7, 8, 9}) – An indication of the order in which event listeners should be called. Listeners with smaller priority values will be called earlier. Listeners with the same priority have no guaranteed ordering. This feature should be avoided if possible. Components should strive to obey the Markov property as they transform the state table (the state of the simulation at the beginning of the next time step should only depend on the current state of the system).
Return type: