The Vivarium Engine

The engine houses the SimulationContext – the key vivarium object for running and interacting with simulations. It is the top level manager for all state information in vivarium. By intention, it exposes a very simple interface for managing the simulation lifecycle.

Also included here is the simulation Builder, which is the main interface that components use to interact with the simulation framework. You can read more about how the builder works and what services is exposes here.

Finally, there are a handful of wrapper methods that allow a user or user tools to easily setup and run a simulation.

class vivarium.framework.engine.SimulationContext(model_specification=None, components=None, configuration=None, plugin_configuration=None, sim_name=None, logging_verbosity=1)[source]
Parameters:
  • model_specification (str | Path | LayeredConfigTree | None)

  • components (list[Component] | dict[str, Any] | LayeredConfigTree | None)

  • configuration (dict[str, Any] | LayeredConfigTree | None)

  • plugin_configuration (dict[str, Any] | LayeredConfigTree | None)

  • sim_name (str | None)

  • logging_verbosity (int)

property name: str
property current_time: Timestamp | datetime | int

Returns the current simulation time.

get_results()[source]

Return the formatted results.

Return type:

dict[str, DataFrame]

run_simulation()[source]

A wrapper method to run all steps of a simulation

Return type:

None

setup()[source]
Return type:

None

initialize_simulants()[source]
Return type:

None

step()[source]
Return type:

None

run(backup_path=None, backup_freq=None)[source]
Return type:

None

Parameters:
  • backup_path (Path | None)

  • backup_freq (int | float | None)

finalize()[source]
Return type:

None

report(print_results=True)[source]
Return type:

None

Parameters:

print_results (bool)

write_backup(backup_path)[source]
Return type:

None

Parameters:

backup_path (Path)

get_performance_metrics()[source]
Return type:

DataFrame

add_components(component_list)[source]

Adds new components to the simulation.

Return type:

None

Parameters:

component_list (list[Component])

get_population(untracked=True)[source]
Return type:

DataFrame

Parameters:

untracked (bool)

get_number_of_steps_remaining()[source]
Return type:

int

classmethod load_from_backup(backup_path)[source]

Load a simulation context from a backup file.

Return type:

SimulationContext

Parameters:

backup_path (Path)

class vivarium.framework.engine.Builder(configuration, plugin_manager)[source]

Toolbox for constructing and configuring simulation components.

This is the access point for components through which they are able to utilize a variety of interfaces to interact with the simulation framework.

Notes

A Builder should never be created directly. It will automatically be created during the initialization of a SimulationContext

Parameters:
  • configuration (LayeredConfigTree)

  • plugin_manager (PluginManager)

configuration

Provides access to the configuration

logging

Provides access to the logging system.

lookup

Provides access to simulant-specific data via the lookup table abstraction.

value

Provides access to computed simulant attribute values via the value pipeline system.

event

Provides access to event listeners utilized in the event system.

population

Provides access to simulant state table via the population system.

resources

Provides access to the resource system, which manages dependencies between components.

results

Provides access to the results system.

randomness

Provides access to the randomness system.

time: TimeInterface

Provides access to the simulation’s clock.

components

Provides access to the component management system, which maintains a reference to all managers and components in the simulation.

lifecycle

Provides access to the life-cycle system, which manages the simulation’s execution life-cycle.

data

Provides access to the simulation’s input data housed in the data artifact.