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.engine.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 | str) – The length of time to run the simulation for. Should be compatible with the simulation clock’s step size (usually a pandas Timedelta). If a string is provided, it will be passed to pandas.Timedelta to be converted.

• 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(attributes, query='', include_untracked=False)

Get a copy of the population state table.

Parameters:

• attributes (str | list[str] | tuple[str, ...]) – The attribute pipelines to include in the returned table.

• query (str) – Additional conditions used to filter the index.

• include_untracked (bool) – Whether to include untracked simulants.

Returns:

The current state of requested population attributes.

Return type:

pd.Series[Any] | pd.DataFrame

get_attribute_names()

List all attributes in the population state table.

Return type:

list[str]

list_values()

List the names of all value 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_name)

Get all listeners of a particular type of event.

Available events can be found by calling InteractiveContext.list_events().

Return type:

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

Parameters:

event_name (str) – The name of the 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_name)

Get the callable that emits the given type of events.

Available events can be found by calling InteractiveContext.list_events().

Parameters:

event_name (str) – The name of the 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