Vivarium Interactive Tools

This module provides an interface for interactive simulation usage. The main part is the InteractiveContext, a sub-class of the main simulation object in vivarium that has been extended to include convenience methods for running and exploring the simulation in an interactive setting.

See the associated tutorials for running and exploring for more information.

class vivarium.interface.interactive.InteractiveContext(*args, setup=True, **kwargs)

A simulation context with helper methods for running simulations interactively.

Parameters:

• args (Any)

• setup (bool)

• kwargs (Any)

property current_time: Timestamp | datetime | int

Returns the current simulation time.

setup()

Return type:

None

step(step_size=None)

Advance the simulation one step.

Return type:

None

Parameters:

step_size (Timedelta | timedelta | int | None) – An optional size of step to take. Must be compatible with the simulation clock’s step size (usually a pandas.Timedelta).

run(with_logging=True)

Run the simulation for the duration specified in the configuration.

Return type:

None

Parameters:

with_logging (bool) – Whether or not to log the simulation steps. Only works in an ipython environment.

Returns:

The number of steps the simulation took.

run_for(duration, with_logging=True)

Run the simulation for the given time duration.

Return type:

None

Parameters:

• duration (Timedelta | timedelta | int) – The length of time to run the simulation for. Should be compatible with the simulation clock’s step size (usually a pandas Timedelta).

• with_logging (bool) – Whether or not to log the simulation steps. Only works in an ipython environment.

Returns:

The number of steps the simulation took.

run_until(end_time, with_logging=True)

Run the simulation until the provided end time.

Return type:

None

Parameters:

• end_time (Timestamp | datetime | int) – The time to run the simulation until. The simulation will run until its clock is greater than or equal to the provided end time. Must be compatible with the simulation clock’s step size (usually a pandas.Timestamp)

• with_logging (bool) – Whether or not to log the simulation steps. Only works in an ipython environment.

Returns:

The number of steps the simulation took.

take_steps(number_of_steps=1, step_size=None, with_logging=True)

Run the simulation for the given number of steps.

Return type:

None

Parameters:

• number_of_steps (int) – The number of steps to take.

• step_size (Timedelta | timedelta | int | None) – An optional size of step to take. Must be compatible with the simulation clock’s step size (usually a pandas.Timedelta).

• with_logging (bool) – Whether or not to log the simulation steps. Only works in an ipython environment.

get_population(untracked=False)

Get a copy of the population state table.

Return type:

DataFrame

Parameters:

untracked (bool) – Whether or not to return simulants who are no longer being tracked by the simulation.

Returns:

The population state table.

list_values()

List the names of all pipelines in the simulation.

Return type:

list[str]

get_value(value_pipeline_name)

Get the value pipeline associated with the given name.

Return type:

Pipeline

Parameters:

value_pipeline_name (str)

list_events()

List all event types registered with the simulation.

Return type:

list[str]

get_listeners(event_type)

Get all listeners of a particular type of event.

Available event types can be found by calling InteractiveContext.list_events().

Return type:

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

Parameters:

event_type (str) – The type of event to grab the listeners for.

Returns:

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

get_emitter(event_type)

Get the callable that emits the given type of events.

Available event types can be found by calling InteractiveContext.list_events().

Parameters:

event_type (str) – The type of event to grab the listeners for.

Returns:

The callable that emits the named event.

Return type:

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

list_components()

Get a mapping of component names to components currently in the simulation.

Return type:

dict[str, Any]

Returns:

A dictionary mapping component names to components.

get_component(name)

Get the component in the simulation that has name, if present. Names are guaranteed to be unique.

Return type:

Any

Parameters:

name (str) – A component name.

Returns:

A component that has the name name else None.

print_initializer_order()

Print the order in which population initializers are called.

Return type:

None

print_lifecycle_order()

Print the order of lifecycle events (including user event handlers).

Return type:

None