Simulation Entry Points
vivarium provides a single main entry point, the
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
engine houses the
vivarium object for running and interacting with simulations.
It is the top-level manager for all state information in
simulations are created by a call to the
__init__ of the
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
vivariumsimulation formatted as a yaml file. As an argument ot the
SimulationContext, it can be provided as a path to a file (either as 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
vivariumsimulation. 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
ConfigTreerepresentation 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
vivariumsimulation. It may be provided as a dictionary or
ConfigTreerepresentation. See the concept note for more information.
Plugins represent core functionality and subsystems of a
vivariumsimulation. 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
ConfigTreeand are parsed into objects by the
PluginManager. This is an advanced feature and almost never necessary.
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
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
also available in the
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.
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.
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
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
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
vivarium.interface.interactive module provides the
(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
package and its associated