Simulation Entry Points

vivarium.engine 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.engine object for running and interacting with simulations. It is the top-level manager for all state information in vivarium.engine. 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.engine 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.engine. 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.engine 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.

configuration

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

plugins

Plugins represent core functionality and subsystems of a vivarium.engine 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.

Warning

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. 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.engine.framework.engine serves as the lowest level entry point into the simulation, but common use cases demand more usability. In the vivarium.engine.interface subpackage we have two public interfaces for interacting with the simulation.

The vivarium.engine.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.engine.interface.interactive module provides the InteractiveContext (also available as a top-level import from vivarium.engine). Details about the many ways to initialize and run a simulation using the interactive context are available in the interactive tutorial.

vivarium.engine 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.engine, see the vivarium_cluster_tools package and its associated documentation.