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.

property current_time: Timestamp | datetime | Number

Returns the current simulation time.

setup()

step(step_size=None)

Advance the simulation one step.

Parameters:

step_size (Timedelta | timedelta | Number) – 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.

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.

Return type:

int

run_for(duration, with_logging=True)

Run the simulation for the given time duration.

Parameters:

• duration (Timedelta | timedelta | Number) – 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.

Return type:

int

run_until(end_time, with_logging=True)

Run the simulation until the provided end time.

Parameters:

• end_time (Timestamp | datetime | Number) – 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.

Return type:

int

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

Run the simulation for the given number of steps.

Parameters:

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

• step_size (Timedelta | timedelta | Number) – 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.

Parameters:

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

Return type:

DataFrame

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.

Parameters:

value_pipeline_name (str) –

Return type:

Pipeline

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().

Parameters:

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

Return type:

Dict[int, List[Callable]]

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.

Return type:

Callable

list_components()

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

Returns:

A dictionary mapping component names to components.

Return type:

Dict[str, Any]

get_component(name)

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

Parameters:

name (str) – A component name.

Return type:

A component that has the name name else None.

print_initializer_order()

Print the order in which population initializers are called.

print_lifecycle_order()

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