Simulation Entry Points

vivarium provides a single main entry point, the SimulationContext, that is then wrapped for use on the command line and in interactive settings. This document describes the main entry point and the wrappers and gives an indication about how you might parallelize the simulations to run on multiple CPUs. The purpose here is to describe architecture and guarantees. For tutorials on running simulations, see the tutorials section.

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. All simulations are created by a call to the __init__ of the SimulationContext at some level and wrappers around the context should try to be as thin as possible around simulation creation.

The context accepts four arguments:


The model specification is a complete representation of a vivarium simulation formatted as a yaml file. As an argument ot the SimulationContext, it can be provided as a path to a file (either as a str or a pathlib.Path) or as a ConfigTree, the internal representation of configuration information used by vivarium. The model specification contains three pieces, each represented by the next three arguments. For more information about model specifications and their formatting, see the associated concept note.


Components provide the logical structure of a vivarium simulation. They are python classes that interact with the framework via the builder. Components may be provided to the context as a list of instantiated objects, as a dictionary representation of their import paths, or as a ConfigTree representation of their import paths. The latter two representations are treated as prefix trees when they are parsed into objects. This behavior is controlled by the ComponentConfigurationParser. More information about components is available in the component concept note.


The configuration is the set of variable model parameters in a vivarium simulation. It may be provided as a dictionary or ConfigTree representation. See the concept note for more information.


Plugins represent core functionality and subsystems of a vivarium simulation. Users may wish to extend the functionality of the framework by writing their own plugins. The framework then needs to be notified of their names and where they are located. Plugins may be specified as either a dictionary or ConfigTree and are parsed into objects by the PluginManager. This is an advanced feature and almost never necessary.

The configuration and plugins arguments are treated as overrides for anything provided in the model_specification. This allows easy modification of a simulation defined in a model specification file.


If you provide components as a dict or ConfigTree, these will also be treated as overrides, though this is almost never the intended use case, so tread cautiously.

By intention, the context exposes a very simple interface for managing the simulation lifecycle. The combination of initializing and running the simulation is encapsulated in the run_simulation command also available in the engine.

The simulation Builder is also part of the engine. It 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 it exposes here.

Public Interfaces

Functionality in the the vivarium.framework.engine serves as the lowest level entry point into the simulation, but common use cases demand more usability. In the vivarium.interface subpackage we have two public interfaces for interacting with the simulation.

The vivarium.interface.cli module provides the simulate command and sub-commands for running and profiling simulations from the command line. A complete tutorial is available here. simulate restricts the user to work only with model specification files and so is primarily useful in a workflow where the user is modifying that file directly to run simulations. Results are deposited in the ~/vivarium_results folder by default, though a command line flag allows the user to specify different output directories.

During model development and debugging, it is frequently more useful to work in an interactive setting like a jupyter notebook or a Python REPL. For this sort of work, the vivarium.interface.interactive module provides the InteractiveContext (also available as a top-level import from vivarium). Details about the many ways to initialize and run a simulation using the interactive context are available in the interactive tutorial.

vivarium itself does not provide tools for running simulations in a distributed system, mostly because each cluster is unique. However, many common simulation tasks will require running many variations of the same simulation (parameter searches, intervention analysis, uncertainty analysis, etc.). For an example of a distributed system built on top of vivarium, see the vivarium_cluster_tools package and its associated documentation.