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:
- model_specification
The model specification is a complete representation of a
vivarium
simulation formatted as a yaml file. As an argument ot theSimulationContext
, it can be provided as a path to a file (either as astr
or apathlib.Path
) or as aLayeredConfigTree
, the internal representation of configuration information used byvivarium
. 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
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 aLayeredConfigTree
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 theComponentConfigurationParser
. More information about components is available in the component concept note.- configuration
The configuration is the set of variable model parameters in a
vivarium
simulation. It may be provided as a dictionary orLayeredConfigTree
representation. See the concept note for more information.- plugins
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 orLayeredConfigTree
and are parsed into objects by thePluginManager
. 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.
Warning
If you provide components
as a dict
or
LayeredConfigTree
,
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. Once a context is instantiated,
all steps of running a simulation are encapsulated in the
run_simulation
method.
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.