How the Virtual Ecosystem works#
The main workflow of the Virtual Ecosystem (Fig. 4) has the following steps:
Users provide a set of configuration files that define how a particular simulation should run.
That configuration is validated and compiled into configuration object that is shared across the rest of the simulation.
The configuration is then used to create several core components: the spatial grid, the core constants, the vertical layer structure and the model timing. These components are also shared across the simulation.
The configuration also sets the locations of the initial input data. These variables are then loaded into the core data store, with validation to check that the data are compatible with the model configuration.
The configuration also defines a set of science models that should be used in the simulation. These are now configured, checking that any configurations settings specific to each science model are valid.
The configured models are then initialised, checking that the data store contains all required initial data for the model and carrying out any calculations for the initial model state.
The system now iterates forward over the configured time steps. At each time step, there is an update step for each science model. The model execution order is defined by the set of variables required for each model, to ensure that all required variables are updated before being used.
Fig. 4 The workflow of a Virtual Ecosystem simulation (click to zoom).#
Configuration files#
The configuration files use the TOML format to provide all of
the details for running a simulation: the spatial layout, the locations of the initial
input data, everything.
Core Components#
The Virtual Ecosystem uses several core components to validate and coordinate shared configuration settings and to initialise model structures. The components are listed below but also see the description of how the simulation core works for more detail:
The Config object, containing the validated configuration.
The Grid object, containing the shared spatial structure of the simulation.
The LayerStructure object, which is used to coordinate the vertical structure of the simulation from the top of the canopy down to the lowest soil layer.
The CoreConstants object, which is used to provide fixed constant values that are shared across science models. Each model will have a separate model constants object that is used to set model-specific constants.
The ModelTiming object, which is used to validate the runtime and update frequency of the simulation.
The Data object, which is used to store data in array format. This is initially populated using all of the initial input data that is provided in array format (e.g. not the animal cohort data). As the simulation progresses, new variables are added and the value of existing variables are updated so that the object tracks the current state of the simulation. Because of this, the Data object is the primary way that information is passed between the different models.
Data#
The Virtual Ecosystem primarily expects data to be imported from files in NetCDF format. This is not the easiest format to work with but the datasets in the Virtual Ecosystem are commonly multi-dimensional arrays (e.g. space and time), and the NetCDF format supports this kind of data, as well as providing critical metadata for data validation.
The Virtual Ecosystem has a large number of variables that are used to set up the simulation and then update the model state through time. The configuration files need to provide the locations of the variables required to initialise each science model.
Science models#
The science models in the Virtual Ecosystem all share a common framework, which is used to coordinate the initialisation and update processes within each model. Each model has an implementation page describing the initialisation and update stages and required data, but the science model overview page provides a quick summary of the models and how they work.
The current suite of science models are:
the simple abiotic model,
the hydrology model,
the animal model,
the plants model,
the soil model, and
the litter model.
New models can be added to the Virtual Ecosystem, although this requires reasonable programming expertise.