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.

Functions:

initialise_models(config, data, ...)

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

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

Perform a Virtual Ecosystem simulation.
virtual_ecosystem.main.initialise_models(config: Config, data: Data, core_components: CoreComponents, models: dict[str, Any]) → dict[str, Any]

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

Parameters:

  • config – A validated Virtual Ecosystem model configuration object.

  • data – A Data instance.

  • core_components – A CoreComponents instance.

  • modules – A dictionary of models to be configured.

Raises:

InitialisationError – If one or more models cannot be properly configured

virtual_ecosystem.main.ve_run(cfg_paths: str | Path | Sequence[str | Path] = [], cfg_strings: str | list[str] = [], override_params: dict[str, Any] = {}, logfile: Path | None = None, progress: bool = False) → None

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

  • override_params – Extra parameters provided by the user

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

  • progress – A logical switch to turn on simple progress reporting, mostly for visual confirmation of progress when the log is not printed to the console.

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_command_line_params(params_str, ...)

Parse extra parameters provided with command-line arguments.

_parse_param_str(s)

Parse a single parameter string into a dict.

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_command_line_params(params_str: Sequence[str], override_params: dict[str, Any]) → None

Parse extra parameters provided with command-line arguments.

Parameters:

  • params_str – Extra parameters in string format (e.g. my.parameter=0.2)

  • override_params – Dictionary to be appended to with additional parameters

Raises:

ConfigurationError – Invalid format for parameters or conflicting values supplied

virtual_ecosystem.entry_points._parse_param_str(s: str) → dict[str, Any]

Parse a single parameter string into a dict.

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

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

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 the log will be written to the console. If the log is being redirected to a file, then the –progress option can be used to print a simple progress report to the standard output.

The resolved complete configuration will then be written to a single consolidated config file in the output path with a default name of vr_full_model_configuration.toml. This can be disabled by setting the core.data_output_options.save_merged_config option to false.

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)