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.
LayerStructure(config)	Simulation vertical layer structure.
ModelTiming(config)	Model timing details.

class virtual_ecosystem.core.core_components.CoreComponents(config: InitVar[Config])

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 constants definitions for the simulation
layer_structure	The vertical layer structure for the simulation.
model_timing	The model timing details for the simulation.

__post_init__(config: Config) → None

Populate the core components from the config.

config: InitVar[Config]

A validated model configuration.

core_constants: CoreConsts

The core constants definitions 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.LayerStructure(config: InitVar[Config])

Simulation vertical layer structure.

This class defines the structure of the vertical dimension of the Virtual Ecosystem from a model configuration. Five values from the core.layers configuration section are used to define a set of vertical layers and their heights (or relative heights): canopy_layers, soil_layers, above_canopy_height_offset, surface_layer_height and``subcanopy_layer_height``. These values are validatated and then assigned to attributes of this class. The n_layers and layer_roles attributes report the total number of layers in the vertical dimension and a tuple of the role of each layer within that dimension.

The layer structure is shown below, along with values from the default configuration. All heights are in metres relative to ground level and the canopy layer heights are defined dynamically by the PlantsModel.

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	subcanopy	Subcanopy height	subcanopy_layer_height	1.5 m
12	surface	Near surface conditions	surface_layer_height	0.1 m
13	soil	Upper soil layer depth	soil_layers	-0.25 m
14	soil	Lower soil layer depth	soil_layers	-1.25 m

Raises:

ConfigurationError – If the configuration elements are incorrect for defining the model timing.

Methods:

__post_init__(config)

Populate the LayerStructure instance.

Attributes:

above_canopy_height_offset	The height above the canopy of the provided reference climate variables.
canopy_layers	The maximum number of canopy layers.
config	A validated model configuration.
layer_roles	An tuple of the roles of the vertical layers within the model from top to bottom.
n_layers	The total number of vertical layers in the model.
soil_layers	A list of the depths of soil layer boundaries.
subcanopy_layer_height	The height above ground used to represent subcanopy conditions.
surface_layer_height	The height above ground used to represent surface conditions.

__post_init__(config: Config) → None

Populate the LayerStructure instance.

This method populates the LayerStructure attributes from the provided Config instance.

Parameters:

config – A Config instance.

above_canopy_height_offset: float

The height above the canopy of the provided reference climate variables.

canopy_layers: int

The maximum number of canopy layers.

config: InitVar[Config]

A validated model configuration.

layer_roles: list[str]

An tuple of the roles of the vertical layers within the model from top to bottom.

n_layers: int

The total number of vertical layers in the model.

soil_layers: list[float]

A list of the depths of soil layer boundaries.

subcanopy_layer_height: float

The height above ground used to represent subcanopy conditions.

surface_layer_height: float

The height above ground used to represent surface conditions.

class virtual_ecosystem.core.core_components.ModelTiming(config: InitVar[Config])

Model timing details.

This data class defines the timing of a Virtual Ecosystem simulation from the core.timing section of a validated model configuration. The start time, run length and update interval are all extracted from the configuration and validated.

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.

Raises:

ConfigurationError – If the timing configuration details are incorrect.

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 as a pint Quantity.
start_time	The start time of the simulation.
update_interval	The configured update interval.
update_interval_quantity	The configured update interval as a pint Quantity.

__post_init__(config: Config) → None

Populate the ModelTiming instance.

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

Parameters:

config – A Config instance.

config: InitVar[Config]

A validated model configuration.

end_time: np.datetime64

The calculated end time of the simulation.

n_updates: int

The total number of model updates in the configured run.

reconciled_run_length: np.timedelta64

The difference between start and calculated end time.

run_length: np.timedelta64

The configured run length.

run_length_quantity: Quantity

The configured run length as a pint Quantity.

start_time: np.datetime64

The start time of the simulation.

update_interval: np.timedelta64

The configured update interval.

update_interval_quantity: Quantity

The configured update interval as a pint Quantity.