The Model Specification
A model specification is a complete representation
of a vivarium
simulation formatted as a yaml file.
A model specification file contains three distinct blocks:
Plugins
Components
Configuration
Each of these blocks is delineated by a top-level key in the yaml file:
plugins
, components
, or configuration
, respectively.
You can find a short intro to yaml basics here.
The Components Block
The components block of the model specification file contains the information necessary to identify the components that should be included in the model. Each component in this block maps to an object that will be managed by the simulation to add some functionality.
In the model specification, these components should be specified in either a list or a hierarchical format, as the following examples illustrate:
A flat list:
components:
vivarium_examples.disease_model.population.BasePopulation()
vivarium_examples.disease_model.population.Mortality()
vivarium_examples.disease_model.disease.SIS_DiseaseModel("diarrhea")
and a hierchical format:
components:
vivarium_examples:
disease_model:
population:
- BasePopulation()
- Mortality()
disease:
- SIS_DiseaseModel("diarrhea")
When the model specification is loaded in, we need some way of transforming the
string representation of the components into the actual component objects that
the simulation can use. The exact process of that mapping between the model
specification item and the fully instantiated object is the domain of the
ComponentConfigurationParser
.
The ComponentConfigurationParser
is responsible for taking a list or hierarchical ConfigTree
of components derived from a model
specification file and turning it into a list of instantiated component objects.
The get_components
method of the parser is used anytime a simulation is initialized from a
model specification file. This method is responsible for the following three
steps that comprise the transformation process:
Parsing the model specification’s components
Validating the arguments and prepping each component
Importing and instantiating the actual components
To illustrate this process, the result of a get_components
call on either of the above yaml components block examples would be a list
containing three instantiated objects: a population object, a mortality object,
and a diarrhea disease model.