API documentation for the `core_components` module#

This submodule contains a dataclass used to generate core common components required by models. It is used as input to the BaseModel, allowing single instances of these components to be cascaded down to individual model subclass instances via the __init__ method of the base model..

Classes:

`CoreComponents`(config)	Core model components.
`DisturbanceTiming`(model_timing[, run_at, ...])	Implement the timing for disturbance models.
`LayerStructure`(config, n_cells, ...)	Vertical layer structure of the Virtual Ecosystem.
`ModelTiming`(config)	Model timing details.

class virtual_ecosystem.core.core_components.CoreComponents(config: InitVar[CoreConfiguration])[source]#

Core model components.

This dataclass takes a validated model configuration and uses it to generate a set of core model attributes, populated via the __init__ method of BaseModel and hence inherited by the specific model subclasses.

Methods:

__post_init__(config)

Populate the core components from the config.

Attributes:

`config`	A validated model configuration.
`core_constants`	The core constant definitions for the simulation.
`grid`	A grid structure for the simulation.
`layer_structure`	The vertical layer structure for the simulation.
`model_timing`	The model timing details for the simulation.

__post_init__(config: CoreConfiguration) → None[source]#: Populate the core components from the config.

config: InitVar[CoreConfiguration]#: A validated model configuration.

core_constants: CoreConstants#: The core constant definitions for the simulation.

grid: Grid#: A grid structure for the simulation.

layer_structure: LayerStructure#: The vertical layer structure for the simulation.

model_timing: ModelTiming#: The model timing details for the simulation.

class virtual_ecosystem.core.core_components.DisturbanceTiming(model_timing: ModelTiming, run_at: int | tuple[int, ...] = (), run_every: tuple[int, ...] = ())[source]#

Implement the timing for disturbance models.

Methods:

check_run(time_index)

Check if the disturbance needs to be run.

check_run(time_index) → bool[source]#

Check if the disturbance needs to be run.

Parameters:: time_index – The index of the time to check.
Returns:: True if the disturbance must be run, False otherwise.

class virtual_ecosystem.core.core_components.LayerStructure(config: InitVar[LayersConfiguration], n_cells: InitVar[int], max_depth_of_microbial_activity: float)[source]#

Vertical layer structure of the Virtual Ecosystem.

This class defines the structure of the vertical dimension of a simulation using the Virtual Ecosystem. The vertical dimension is divided into a series of layers, ordered from above the canopy to the bottom of the soil, that perform different roles in the simulation. The configuration of the layer structure is defined in the virtual_ecosystem.core.model_config.LayersConfiguration class.

The layer structure is shown below, along with the default configured height values in metres relative to ground level.

Index	Role	Description	Set by	Default
0	above	Above canopy conditions	`above_ground_canopy_offset`	+2 m
1	canopy	Height of first canopy layer	`PlantsModel`	–
…	canopy	Height of other canopy layers	`PlantsModel`	–
10	canopy	Height of the last canopy layer	`PlantsModel`	–
11	surface	Near surface conditions	`surface_layer_height`	0.1 m
12	topsoil	Top soil layer depth	`soil_layers`	-0.25 m
13	subsoil	First subsoil layer depth	`soil_layers`	-1.00 m

Additional Roles:

The following additional roles and attributes are also defined when the instance is created and are constant through the runtime of the model.

The active_soil role indicates soil layers that fall even partially above the configured max_depth_of_microbial_activity. The soil_layer_thickness attribute provides the thickness of each soil layer - including both top- and sub-soil layers - and the soil_layer_active_thickness records the thickness of biologically active soil within each layer. Note that the soil_layers provides the sequence of depths of soil horizons relative to the surface and these values provide the thickness of individual layers: the default soil_layers values of [-0.25, -1.00] give thickness values of [0.25, 0.75].
The all_soil role is the combination of the topsoil and subsoil layers.
The atmosphere role is the combination of above, canopy and surface layers.

Dynamic roles:

The following roles are set when the instance is initialised but are can be updated during the model run using the set_filled_canopy() method.

The filled_canopy role indicates canopy layers that contain any canopy across all of the grid cells. No grid cell contains actual canopy in any of the canopy layers below the filled canopy layers. This is initialised to show no filled canopy layers.

2, The filled_atmosphere role includes the above canopy layer, all filled canopy layer indices and the surface layer.

The flux_layers role includes the filled canopy layers, understorey, and
the topsoil layer.

In addition, the lowest_canopy_filled attribute provides an array giving the vertical index of the lowest filled canopy layer in each grid cell. It contains np.nan when there is no canopy in a grid cell and is initialised as an array of np.nan values.

Getting layer indices:

The _role_indices_bool and _role_indices_int attributes contain dictionaries keyed by role name of the boolean or integer indices of the different defined roles. However, all of the role indices should be accessed using the specific instance properties e.g. index_above.

Note that the standard index properties like index_above will return an array index, which extracts a two dimensional slice of the vertical structure. It is sometimes more convenient to extract a 1 dimensional slice across cells, dropping the vertical dimension. This only makes sense for the role layers that are by definition a single layer thick (above, surface and topsoil), and for these three layers, additional properties (e.g. index_above_scalar) are defined that will return a scalar index that extracts a one-dimensional slice.

Methods overview:

from_template(): this returns an empty DataArray with the standard vertical layer structure and grid cell dimensions used across the Virtual Ecosystem models.

set_filled_canopy(): this method is used to update the filled_canopy role indices, the related filled_atmosphere and flux_layers roles, and the lowest_canopy_filled attribute.

Raises:: ConfigurationError – If the configuration elements are incorrect for defining the layer structure.

Methods:

`__post_init__`(config, n_cells)	Populate the `LayerStructure` instance.
`from_template`([array_name])	Get a DataArray with the simulation vertical structure.
`set_filled_canopy`(canopy_heights)	Set the dynamic canopy indices and attributes.

Attributes:

`_role_indices_bool`	A dictionary of boolean layer role indices within the vertical structure.
`_role_indices_int`	A dictionary of integer layer role indices within the vertical structure.
`above_canopy_height_offset`	The height above the canopy of the provided reference climate variables.
`config`	A configuration object instance.
`index_above`	Layer indices for the above layer.
`index_above_scalar`	Layer indices for the above canopy layer.
`index_active_soil`	Layer indices for microbially active soil layers.
`index_all_soil`	Layer indices for all soil layers.
`index_atmosphere`	Layer indices for all atmospheric layers.
`index_canopy`	Layer indices for the above canopy layers.
`index_filled_atmosphere`	Layer indices for the filled atmospheric layers.
`index_filled_canopy`	Layer indices for the filled canopy layers.
`index_flux_layers`	Layer indices for the flux layers.
`index_subsoil`	Layer indices for the subsoil layers.
`index_surface`	Layer indices for the surface layer.
`index_surface_scalar`	Layer indices for the surface layer.
`index_topsoil`	Layer indices for the topsoil layer.
`index_topsoil_scalar`	Layer indices for the topsoil layer.
`layer_indices`	An array of the integer indices of the vertical layers in the model.
`layer_roles`	An array of vertical layer role names from top to bottom.
`lowest_canopy_filled`	An integer index showing the lowest filled canopy layer for each grid cell
`max_depth_of_microbial_activity`	The maximum soil depth of significant microbial activity.
`n_canopy_layers`	The maximum number of canopy layers.
`n_canopy_layers_filled`	The current number of filled canopy layers across grid cells
`n_cells`	The number of grid cells in the simulation.
`n_layers`	The total number of vertical layers in the model.
`n_soil_layers`	The number of soil layers.
`soil_layer_active_thickness`	Thickness of the microbially active soil in each soil layer (m)
`soil_layer_depths`	A list of the depths of soil layer boundaries.
`soil_layer_thickness`	Thickness of each soil layer (m)
`surface_layer_height`	The height above ground used to represent surface conditions.

__post_init__(config: LayersConfiguration, n_cells: int) → None[source]#

Populate the LayerStructure instance.

This method populates the LayerStructure attributes from the dataclass init arguments.

Parameters:

config – A Config instance.
n_cells – The number of grid cells in the simulation.

_role_indices_bool: dict[str, ndarray[tuple[Any, ...], dtype[bool]]]#: A dictionary of boolean layer role indices within the vertical structure.

_role_indices_int: dict[str, ndarray[tuple[Any, ...], dtype[int64]]]#: A dictionary of integer layer role indices within the vertical structure.

above_canopy_height_offset: float#: The height above the canopy of the provided reference climate variables.

config: InitVar[LayersConfiguration]#: A configuration object instance.

from_template(array_name: str | None = None) → DataArray[source]#

Get a DataArray with the simulation vertical structure.

This method returns two dimensional xarray.DataArray with coordinates set to match the layer roles and number of grid cells for the current simulation. The array is filled with np.nan values and the array name is set if a name is provided.

Parameters:: array_name – An optional variable name to assign to the returned data array.

property index_above: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for the above layer.

property index_above_scalar: int#: Layer indices for the above canopy layer.

property index_active_soil: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for microbially active soil layers.

property index_all_soil: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for all soil layers.

property index_atmosphere: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for all atmospheric layers.

property index_canopy: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for the above canopy layers.

property index_filled_atmosphere: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for the filled atmospheric layers.

property index_filled_canopy: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for the filled canopy layers.

property index_flux_layers: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for the flux layers.

property index_subsoil: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for the subsoil layers.

property index_surface: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for the surface layer.

property index_surface_scalar: int#: Layer indices for the surface layer.

property index_topsoil: ndarray[tuple[Any, ...], dtype[bool]]#: Layer indices for the topsoil layer.

property index_topsoil_scalar: int#: Layer indices for the topsoil layer.

layer_indices: ndarray[tuple[Any, ...], dtype[int64]]#: An array of the integer indices of the vertical layers in the model.

layer_roles: ndarray[tuple[Any, ...], dtype[str_]]#: An array of vertical layer role names from top to bottom.

lowest_canopy_filled: ndarray[tuple[Any, ...], dtype[int64]]#: An integer index showing the lowest filled canopy layer for each grid cell

max_depth_of_microbial_activity: float#: The maximum soil depth of significant microbial activity.

n_canopy_layers: int#: The maximum number of canopy layers.

n_canopy_layers_filled: int#: The current number of filled canopy layers across grid cells

n_cells: InitVar[int]#: The number of grid cells in the simulation.

n_layers: int#: The total number of vertical layers in the model.

n_soil_layers: int#: The number of soil layers.

set_filled_canopy(canopy_heights: ndarray[tuple[Any, ...], dtype[floating]]) → None[source]#

Set the dynamic canopy indices and attributes.

The layer structure includes a fixed number of canopy layers but these layers are not all necessarily occupied. This method takes an array of canopy heights across the grid cells of the simulation and populates the “filled_canopy” indices, which are the canopy layers that contain at least one filled canopy layer. It also populates the “lowest_canopy_filled” attribute.

Parameters:: canopy_heights – A n_canopy_layers by n_grid_cells array of canopy layer heights.

soil_layer_active_thickness: ndarray[tuple[Any, ...], dtype[floating]]#: Thickness of the microbially active soil in each soil layer (m)

soil_layer_depths: ndarray[tuple[Any, ...], dtype[floating]]#: A list of the depths of soil layer boundaries.

soil_layer_thickness: ndarray[tuple[Any, ...], dtype[floating]]#: Thickness of each soil layer (m)

surface_layer_height: float#: The height above ground used to represent surface conditions.

class virtual_ecosystem.core.core_components.ModelTiming(config: InitVar[TimingConfiguration])[source]#

Model timing details.

This data class defines the timing of a Virtual Ecosystem simulation from the {class}`~virtual_ecosystem.core.model_config.TimingConfiguration` section of a validated model configuration.

The end time is calculated from the previously extracted timing information. This end time will always be the largest whole multiple of the update interval that exceeds or equal the configured run_length.

Methods:

__post_init__(config)

Populate the ModelTiming instance.

Attributes:

`config`	A validated model configuration.
`end_time`	The calculated end time of the simulation.
`n_updates`	The total number of model updates in the configured run.
`reconciled_run_length`	The difference between start and calculated end time.
`run_length`	The configured run length.
`run_length_quantity`	The configured run length.
`start_time`	The start time of the simulation.
`update_datestamps`	The date of the start of each update interval.
`update_interval`	The configured update interval.
`update_interval_quantity`	The configured update interval.
`update_interval_seconds`	The configured update interval in seconds.
`updates_per_year`	The number of updates per year based on update_interval.

__post_init__(config: TimingConfiguration) → None[source]#

Populate the ModelTiming instance.

This method populates the ModelTiming attributes from the provided TimingConfiguration instance.

Parameters:: config – A TimingConfiguration instance.

config: InitVar[TimingConfiguration]#: A validated model configuration.

end_time: datetime64#: The calculated end time of the simulation.

n_updates: int#: The total number of model updates in the configured run.

reconciled_run_length: timedelta64#: The difference between start and calculated end time.

run_length: timedelta64#: The configured run length.

run_length_quantity: Quantity#: The configured run length.

start_time: datetime64#: The start time of the simulation.

update_datestamps: ndarray[tuple[Any, ...], dtype[datetime64]]#: The date of the start of each update interval.

update_interval: timedelta64#: The configured update interval.

update_interval_quantity: Quantity#: The configured update interval.

update_interval_seconds: float#: The configured update interval in seconds.

updates_per_year: float64#: The number of updates per year based on update_interval.

API documentation for the core_components module#

API documentation for the `core_components` module#