Static models#

Advanced usage

Running models in static mode is very much advanced usage of the Virtual Ecosystem, and should only be attempted if you feel that you have a strong grasp of the science underlying the model for which you want to provide static inputs to.

A case for which particular care is required is when a static model removes biomass from a non-static model (e.g. the plants model is being updated, but the herbivory rate is generated by the static animal model). In this case, the rate of removal cannot vary based on the resource availability, so even if the biomass drops to zero it continues to be removed, causing (clearly nonsensical) negative biomasses to be observed. This is one of the reasons why significant care needs to be taken when interpreting the results of simulation runs involving static models.

When a model is included in a Virtual Ecosystem simulation, it runs a sequence of data variable creation and updating:

All data needed by the model to set up is read in.
The initial model setup adds new variables provided by the model.
When the model is first updated it creates additional new variables.
At each time step, it then updates a set of variables.

This sequence of changing data drives the interactions between models and leads to complex ecological behaviour. However, this complexity can be problematic and it can be useful to set some models to keep their data in a static state. For example:

In development this could be used for debugging, by keeping all models but one static in order to isolate and assess changes.
It could also be used to explore individual models or combinations of models to understand the interactions without running the entire complex model.

To implement this, all models (except core) accept a boolean configuration option, static, that indicates if the model data should be held static. Changing the default configuration static=false to static=true puts a model into static mode. For an example of this in use, see this tutorial.

However, even when the model is run in static mode the model constants and variables need to be populated, for use by any models that are not in static mode. Because of this, you still need to provide any model configuration and data. You do have some choices for providing data that give increasingly fine control on what values are passed to the other models.

Warning

The second and third options described below are currently bugged, and trying to use them will result in the simulation failing on initialisation.

However, if you want to implement the third option, you can do this by removing the model you wish to hold static entirely from the simulation configuration. Then, in order to get the other models to run, you will have to provide any variables generated by the removed model that are used by other models (i.e. anything in the removed model’s vars_populated_by_init or vars_populated_by_first_update that is used by another model).

You must provide all the required data to initialise the model. The list of required variables is stored in the model’s vars_required_for_init attribute: see for example the plant model required variables.

If you only provide the required variables, then the model will take this data and run the setup and first update steps and then go into static mode.
You can additionally provide all of the variables created by the model initial setup. The list of these variables is stored in the model’s vars_populated_by_init attribute: see for example the plant model generated variables.

If you only provide the setup generated variables, then the model will skip the setup steps and use your provided values to run the first update step before going into static mode.
Finally, you can additionally provide all of the variables created by the model first update. The list of these variables is stored in the model’s vars_populated_by_first_update attribute: again, see for example the plant model generated variables.

If you provide the first update variables as well, then there is nothing left for the model to calculate for itself, and it will go into static mode without running setup or the first update.

This approach allows you to dictate every value provided by your static model to the rest of the simulation. This is powerful but it is very demanding to get the details right. A good start could be to run a full simulation for a single time step and then use and modify the model outputs from that run as inputs to a static model configuration.

These different scenarios are identified automatically when the simulation starts by comparing the different sets of required variables to what has been loaded into the Data object from the configuration. In addition, note that:

Providing some but not all of the variables required in steps 2 or 3 above will result in an error.
The stages above form a hierarchy - you cannot just provide the first update variables without providing the initial data.

In summary,

Static	Setup data provided	First update data provided	Behaviour
No	—	—	Default model behaviour
Yes	No	No	Model sets up and runs first update from initial data
Yes	Yes	No	Model skips setup and runs first update
Yes	Yes	Yes	Model skips setup and first update
Yes	No	Yes	Improper configuration, will not run