API reference for the main Virtual Ecosystem API#

This page documents the modules providing the main API for running the Virtual Ecosystem.

  • The main module provides the ve_run function and supporting functions.

  • The entry_points module provides a command line interface to running a Virtual Ecosystem model

The main module#

The main module defines the function used to run a full simulation of the model, along with helper functions to validate and configure the model.

Classes:

Progress(*values)

Integer enumeration to manage ve_run output verbosity.

Functions:

check_added_variables(before, after, ...)

Check the variables added to data during a model step.

initialise_disturbances(configuration, data, ...)

Initialise a set of disturbances for use in a virtual_ecosystem simulation.

initialise_models(configuration, data, ...)

Initialise a set of models for use in a virtual_ecosystem simulation.

sort_disturbances(configuration)

Sort disturbances based on priority and name.

ve_run([cfg_paths, cfg_strings, cli_config, ...])

Perform a Virtual Ecosystem simulation.
class virtual_ecosystem.main.Progress(*values)[source]#

Integer enumeration to manage ve_run output verbosity.

virtual_ecosystem.main.check_added_variables(before: list[str], after: list[str], claimed: tuple[str, ...], model: str, attr: str) → None[source]#

Check the variables added to data during a model step.

This function checks that the difference in the set of variable names added to data during a model step match the set of variables that the model var_ attributes claims for the model.

Parameters:

  • before – A list of data variable names from before the model method ran.

  • after – A list of data variable names from after the model method ran.

  • claimed – The model attribute describing the claimed set of variables added.

  • model – The name of the model being checked

  • attr – The variable attribute name being checked

Raises:

InitialisationError – if the actual changed variables do matched the variables configured in the model attributes.

virtual_ecosystem.main.initialise_disturbances(configuration: CompiledConfiguration, data: Data, core_components: CoreComponents, models: dict[str, BaseModel]) → dict[str, BaseDisturbance][source]#

Initialise a set of disturbances for use in a virtual_ecosystem simulation.

Parameters:

  • configuration – A validated Virtual Ecosystem configuration object containing the disturbance configuration.

  • data – A Data instance.

  • core_components – A CoreComponents instance.

  • models – A dictionary of initialised models.

Raises:

InitialisationError – If one or more disturbances cannot be properly configured

Returns:

Dictionary of initialised disturbances in the right execution order.

virtual_ecosystem.main.initialise_models(configuration: CompiledConfiguration, data: Data, core_components: CoreComponents, models: dict[str, type[BaseModel]]) → dict[str, BaseModel][source]#

Initialise a set of models for use in a virtual_ecosystem simulation.

Parameters:

  • configuration – A validated Virtual Ecosystem model configuration object.

  • config – A validated Virtual Ecosystem model configuration object.

  • data – A Data instance.

  • core_components – A CoreComponents instance.

  • models – A dictionary of models to be configured.

Raises:

InitialisationError – If one or more models cannot be properly configured

virtual_ecosystem.main.sort_disturbances(configuration: CompiledConfiguration) → list[str][source]#

Sort disturbances based on priority and name.

Parameters:

configuration – CompiledConfiguration object for disturbances.

Returns:

Tuple of disturbance model names in the order they need to be executed.

virtual_ecosystem.main.ve_run(cfg_paths: str | Path | Sequence[str | Path] = [], cfg_strings: str | list[str] = [], cli_config: dict[str, Any] = {}, cli_paths: dict[str, Path] = {}, logfile: Path | None = None, validate_only: bool = False, progress: Progress = Progress.FULL) → None[source]#

Perform a Virtual Ecosystem simulation.

This is a high-level function that runs a Virtual Ecosystem simulation. At the moment this involves validating an input configuration, and using this configuration to generate a set of configured model objects suitable for downstream use. Down the line this should be extended to encompass far more steps.

Parameters:

  • cfg_paths – Set of paths to configuration files

  • cfg_strings – An alternate string providing TOML formatted configuration data

  • cli_config – Configuration settings provided by the user at the command line, used to override configuration settings in files.

  • cli_paths – Configuration settings provided by the user at the command line, used to dynamically set paths to input data files.

  • logfile – An optional path to a log file, otherwise logging will print to the console.

  • validate_only – Should the command exit after config validation.

  • progress – A Progress enum instance setting the level of output to be printed to the console when ve_run is running.

The entry_points module#

The entry_points module defines the command line entry points to the virtual_ecosystem package. At the moment a single entry point is defined ve_run, which simply configures and runs a Virtual Ecosystem simulation based on a set of configuration files.

Functions:

_parse_cli_paths(cli_paths)

Parse command-line data input path substitutions.

_parse_command_line_config(config_strings)

Parse command-line configuration settings.

_parse_config_string(config_string)

Parse a single configuration string into a dictionary.

install_example_directory(install_dir)

Install the example directory to a location.

ve_run_cli([args_list])

Configure and run a Virtual Ecosystem simulation.
virtual_ecosystem.entry_points._parse_cli_paths(cli_paths: Sequence[str]) → dict[str, Path][source]#

Parse command-line data input path substitutions.

This function takes a list of strings containing path substitutions to the ve_run_cli entry points using the -p option. Each string should provide a file marker that can be referred to in a configuration file and a data path that should be used for that marker.

Parameters:

cli_paths – A list of strings containing configuration settings.

Returns:

A dictionary of markers and paths.

virtual_ecosystem.entry_points._parse_command_line_config(config_strings: Sequence[str]) → dict[str, Any][source]#

Parse command-line configuration settings.

This function takes a list of strings containing configuration settings passed to the ve_run_cli entry points using the --config option. Each string should be parseable TOML (e.g. plants.constants.value=0.4) and the function builds a partial configuration dictionary from the input strings.

Parameters:

config_strings – A list of strings containing configuration settings.

Returns:

A partial configuration dictionary containing parsed settings.

Raises:

ConfigurationError – Invalid format for parameters or conflicting values supplied

virtual_ecosystem.entry_points._parse_config_string(config_string: str) → dict[str, Any][source]#

Parse a single configuration string into a dictionary.

Parameters:

config_string – A string containing a TOML formatted configuration setting, for example: “hydrology.initial_soil_moisture=0.3”

Raises:

ConfigurationError – If the command-line parameters are not valid TOML

virtual_ecosystem.entry_points.install_example_directory(install_dir: Path) → int[source]#

Install the example directory to a location.

This function installs the example directory data files and configuration files provided within the package to a selected location. This allows users to look at the simulation directory structure and files more easily and avoids working with the original files inside the package tree.

The files are installed to a ve_example directory within the provided install location.

Parameters:

install_dir – the installation path.

Returns:

An integer indicating success (0) or failure (1).

virtual_ecosystem.entry_points.ve_run_cli(args_list: list[str] | None = None) → int[source]#

Configure and run a Virtual Ecosystem simulation.

This program sets up and runs a Virtual Ecosystem simulation. The program expects to be provided with paths to TOML formatted configuration files for the simulation. The configuration is modular: a directory path can be used to add all TOML configuration files in the directory, or individual file paths can be used to select specific combinations of configuration files. These are combined and validated and then used to initialise and run the model.

As an alternative to providing configuration paths, the –install-example option allows users to provide a location where a simple example set of datasets and configuration files provided with the Virtual Ecosystem package can be installed. This option will create a ve_example directory in the location, and users can examine the input files and run the simulation from that directory:

ve_run /provided/install/path/ve_example

The output directory for simulation results is typically set in the configuration files, but can be overwritten using the –outpath option. A log file path can be provided for logging output. If this is not provided then the log will be written to the console, but the logging is typically verbose and it is usually better to redirect the log to a file.

When logging is redirected to a file, a short progress report is written to stdout. By default, the command reports: the start and end of the simulation and log location; the completion of simulation stages; and a progress bar over the time steps of the model. The –quiet command can be used to incrementally mute this output: -q will remove the progress bar, -qq just prints the start and stop and -qqq mutes the report entirely.

The –config option can be used to override configuration settings provided in the file or to add additional settings. This is typically used to run a set of parallel simulations that vary configuration settings of interest around a central configuration setup, without the need to write a specific configuration file for each permutation.

The –data-path option can be used to dynamically set the location of data paths in the configuration. A file path in the config can be set as a path marker, which must be a string starting with a “$”, for example “$CLIMATE_DATA”. This option can then be used to substitute different files into that marker for different runs: –data-path CLIMATE_DATA=/path/to/file.nc.

The –validate-config-only flag can be used to only run the configuration validation part of the model setup and the exit before running any models.

The resolved complete configuration will then be written to a single consolidated config file in the output path with a default name of ve_full_model_configuration.toml. This can be disabled by setting the core.data_output_options.save_merged_config option to false. Note that the merged configuration automatically converts all file paths within the merged configurations to absolute file paths - this ties the merged configuration to the file system where the run is executed.

Parameters:

args_list – This is a developer and testing facing argument that is used to simulate command line arguments, allowing this function to be called directly. For example, ve_run --install-example /usr/abc can be replicated by calling ve_run_cli(['--install-example', '/usr/abc/']).

Returns:

An integer indicating success (0) or failure (1)