API documentation for the utils module

The core.utils module contains functions that are used across the Virtual Ecosystem, but which don’t have a natural home in a specific module. Adding functions here can be a good way to reduce the amount boiler plate code generated for tasks that are repeated across modules.

Functions:

check_outfile(merge_file_path)	Check that final output file is not already in the output folder.
set_layer_roles([canopy_layers, soil_layers])	Create a list of layer roles.

virtual_ecosystem.core.utils.check_outfile(merge_file_path: Path) → None

Check that final output file is not already in the output folder.

Parameters:

merge_file_path – Path to save merged config file to (i.e. folder location + file name)

Raises:

ConfigurationError – If the path is invalid or the final output file already exists.

virtual_ecosystem.core.utils.set_layer_roles(canopy_layers: int = 10, soil_layers: list[float] = [-0.5, -1.0]) → list[str]

Create a list of layer roles.

This function creates a list of strings describing the layer roles for the vertical dimension of the Virtual Ecosystem. These roles are used with data arrays that have that vertical dimension: the roles then show what information is being captured at different heights through that vertical dimension. Within the model, ground level is at height 0 metres: above ground heights are positive and below ground heights are negative. At present, models are expecting two soil layers: the top layer being where microbial activity happens (usually around 0.5 metres below ground) and the second layer where soil temperature equals annual mean air temperature (usually around 1 metre below ground).

There are five layer roles capture data:

• above: at ~2 metres above the top of the canopy.

• canopy: within each canopy layer. The maximum number of canopy layers is set by the canopy_layers argument and is a configurable part of the model. The heights of these layers are modelled from the plant community data.

• subcanopy: at ~1.5 metres above ground level.

• surface: at ~0.1 metres above ground level.

• soil: at fixed depths within the soil. These depths are set in the soil_layers argument and are a configurable part of the model.

With the default values, this function gives the following layer roles.

Index	Role	Description
0	above	Canopy top height + 2 metres
1	canopy	Height of top of the canopy (1)
…	canopy	Height of canopy layer i
10	canopy	Height of the bottom canopy layer (10)
11	subcanopy	1.5 metres above ground level
12	surface	0.1 metres above ground level
13	soil	First soil layer at -0.5 metres
14	soil	First soil layer at -1.0 metres

Parameters:

• canopy_layers – the number of canopy layers

• soil_layers – a list giving the depth of each soil layer as a sequence of negative and strictly decreasing values.

Raises:

InitialisationError – If the number of canopy layers is not a positive integer or the soil depths are not a list of strictly decreasing, negative float values.

Returns:

A list of vertical layer role names