API documentation for the `variables` module#

Variable validation and model checking.

Variables are defined in the data_variables.toml file in the root folder of virtual_ecosystem . When the model runs, this data is loaded into the Data.known_variables attribute, using the load_known_variables() function is this module. The attribute provides a dictionary, keyed by variable name, of VariableMetadata instances, which hold the metadata loaded from file. That data is used to:

Check that only known variables are added to the Data instance.

Check that variable axes are defined correctly.

Add variable metadata, such as units and description, to output files.

The VariableMetadata instances also have attributes that are used to track which variables appear in the various var_... attributes of the set of running models. This is used to build up a dictionary of variables used by a particular simulation run (runtime variables) that tracks variable usage during runtime:

What variables are initialised from data or by models, and are they uniquely initialised.

Are variables required by models initialised by other models?

Are there running orders for both model initialisation and update that avoid circular variable dependencies.

To add a new variable, simply edit the data_variables.toml file and add the variable as:

[[variable]]
name = "variable_name"
description = "Description of the variable."
unit = "Unit of the variable."
variable_type = "Type of the variable."
axis = ["axis1", "axis2"]

where axis1 and axis2 are the name of axis validators defined on axes.

Classes:

`VariableMetadata`(name, description, unit, ...)	Variable metadata class.
`VariablesFile`(*[, variable])	Validation class for a variable definitions file.

Functions:

`get_model_order`(stage, runtime_variables)	Get the order of running the models during init or update.
`load_known_variables`([variable_file])	Loads variables from a TOML variable database file.
`setup_variables`(models, data_vars, ...)	Generate the runtime variables dictionary.

class virtual_ecosystem.core.variables.VariableMetadata(name: str, description: str, unit: str, variable_type: str, axis: list[str])[source]#

Variable metadata class.

This class is used to both validate entries loaded from a variables metadata file and to provide attributes that are used to track how each variable is used by the different models at runtime. The axis attribute has additional validation applied after loading to check that it values are unique and valid.

Attributes:

`axis`	Axes the variable is defined on.
`description`	Description of what the variable represents.
`name`	Name of the variable.
`related_models`	Get all models that are related to the variable.
`unit`	Units the variable should be represented in.
`variable_type`	Type of the variable.
`vars_populated_by_first_update`	Used at runtime to track which model initialises the variable during the update stage.
`vars_populated_by_init`	Used at runtime to track whether the variable is initialised from input data or during the initialisation stage of one of the models.
`vars_required_by_init`	Used at runtime to track which models require the variable to be initialised.
`vars_required_by_update`	Used at runtime to track which models use the variable.
`vars_updated`	Used at runtime to track which models update the variable.

Methods:

unique_axes(value, info)

Check axis list entries are unique and known.

axis: list[str]#: Axes the variable is defined on.

description: str#: Description of what the variable represents.

name: str#: Name of the variable. Must be unique.

property related_models: set[str]#

Get all models that are related to the variable.

Returns:: The set of all models related to the variable.

classmethod unique_axes(value: list[str], info: ValidationInfo) → list[str][source]#: Check axis list entries are unique and known.

unit: str#: Units the variable should be represented in.

variable_type: str#: Type of the variable.

vars_populated_by_first_update: list[str] = []#: Used at runtime to track which model initialises the variable during the update stage.

vars_populated_by_init: list[str] = []#: Used at runtime to track whether the variable is initialised from input data or during the initialisation stage of one of the models.

vars_required_by_init: list[str] = []#: Used at runtime to track which models require the variable to be initialised.

vars_required_by_update: list[str] = []#: Used at runtime to track which models use the variable.

vars_updated: list[str] = []#: Used at runtime to track which models update the variable.

class virtual_ecosystem.core.variables.VariablesFile(*, variable: list[VariableMetadata] = [])[source]#

Validation class for a variable definitions file.

This validator loads a variable definitions file, following the format used in data_variables.toml, applying validation to each entry, and then checks that the file does not contain duplicate variable definitions.

virtual_ecosystem.core.variables.get_model_order(stage: str, runtime_variables: dict[str, VariableMetadata]) → list[str][source]#

Get the order of running the models during init or update.

This order is based on the dependencies of initialisation and update of the variables.

Parameters:

stage – The stage of the simulation to get the order for. It must be either “init” or “update”.
runtime_variables – A dictionary of variables being used in this runtime

Returns:

The order of initialisation of the variables.

virtual_ecosystem.core.variables.load_known_variables(variable_file: str | None = None) → dict[str, VariableMetadata][source]#

Loads variables from a TOML variable database file.

The contents of the file are loaded using tomllib and then passed to the VariablesFile validation class, which in turn applies the VariableMetadata validation class to each entry.

Parameters:: variable_file – The path to a variables file.
Returns:: A dictionary, keyed by variable name, of validated VariableMetadata instances.

virtual_ecosystem.core.variables.setup_variables(models: list[type[BaseModel]], data_vars: list[str], known_variables: dict[str, VariableMetadata]) → dict[str, VariableMetadata][source]#

Generate the runtime variables dictionary.

This function takes the data variables provided by the initial data and a list of requested science models and populates a dictionary of runtime variables. The function then:

Checks that all variables provided in the data or appearing in model definitions appear in the dictionary of known variables.
Populates the model usage attributes of the variables being used at runtime, including initial checking that:
- variables are uniquely initialised,
- required variables have been initialised by a model or from data,

Note that the called functions all update the runtime_variables dictionary by reference. This is used because - in addition to adding new variables - the functions are updating attributes of existing runtime variables. It is much more concise to update by reference here rather than passing update information back to this function.

Parameters:

models – The list of models to setup variables for.
data_vars – The list of variables defined in the data object.
known_variables – A dictionary of known variables

Raises:

ValueError – If: a variable required by a model is not in the known variables; a variable is required but not populated; a variable is initialised more than once.

API documentation for the variables module#

API documentation for the `variables` module#