API documentation for the plants model

The plants module provides a plants model for use in the Virtual Ecosystem. The submodules provide:

• The plants_model submodule provides the PlantsModel class as the main API for interacting with the plants model.

• The constants submodule provides dataclasses containing constants used in the model.

• The community submodule provides the PlantCohort dataclass that records the details of an individual cohort and the PlantCommunities class that records list of plant cohorts by grid cell.

The plants_model module

The plants_model module creates PlantsModel class as a child of the BaseModel class.

Classes:

PlantsModel(data, core_components, flora[, ...])

A class defining the plants model.

class virtual_ecosystem.models.plants.plants_model.PlantsModel(data: Data, core_components: CoreComponents, flora: Flora, model_constants: PlantsConsts = PlantsConsts(), **kwargs: Any)

A class defining the plants model.

This is currently a basic placeholder to define the main interfaces between the plants model and other models.

When a model instance is created, the model attributes are validated and set. The initial canopy structure for each grid cell is then generated from provided plant cohort data using the update_canopy_layers() method. This includes the irradiance absorbed within each canopy layer and reaching ground level, which at present is estimated using the first time step of the provided photosynthetic photon flux density (PPFD).

When the model is updated, the P Model will be used to calculate the light use efficiency given the conditions within canopy layers, and the PPFD at the top of the canopy and the canopy layer extinction profile is used to estimate gross primary productivity across plant cohorts. An allocation model is then used to estimate growth and then update the canopy model.

Required Variables:

The following variables must be provided in the data instance to initialise an instance of this model:

• plant_cohorts_cell_id: The grid cell id containing the cohort

• plant_cohorts_pft: The plant functional type of the cohort

• plant_cohorts_n: The number of individuals in the cohort

• plant_cohorts_dbh: The diameter at breast height of the individuals in metres.

• photosynthetic_photon_flux_density: The above canopy photosynthetic photon flux density in µmol m-2 s-1.

Warning

The current implementation defines the main interfaces between the plants model and other models and accesses and updates the expected data to be used in the full model. The actual predictions of the model are placeholder values.

Parameters:

• data – The data object to be used in the model.

• core_components – The core components used across models.

• flora – A Flora instance of the plant functional types to be used in the model.

• model_constants – Set of constants for the plants model.

Methods:

allocate_gpp()	Calculate the allocation of GPP to growth and respiration.
cleanup()	Placeholder function for plants model cleanup.
estimate_gpp(time_index)	Estimate the gross primary productivity within plant cohorts.
from_config(data, core_components, config)	Factory function to initialise a plants model from configuration.
set_absorbed_irradiance(time_index)	Set the absorbed irradiance across the canopy.
setup()	Placeholder function to set up the plants model.
spinup()	Placeholder function to spin up the plants model.
update(time_index, **kwargs)	Update the plants model.
update_canopy_layers()	Update the canopy structure for the plant communities.

Attributes:

communities	Initialise the plant communities from the data object.
data	A reference to the global data object.
flora	A flora containing the plant functional types used in the plants model.
model_constants	Set of constants for the plants model

allocate_gpp() → None

Calculate the allocation of GPP to growth and respiration.

This method will use the T Model to estimate the allocation of plant gross primary productivity to respiration, growth, maintenance and turnover costs.

Warning

At present, this asserts a constant fixed increment in diameter at breast height, rather than calculating the actual predictions of the T Model.

cleanup() → None

Placeholder function for plants model cleanup.

communities

Initialise the plant communities from the data object.

core_constants: CoreConsts

The core constants used in the model.

data: Data

A reference to the global data object.

estimate_gpp(time_index: int) → None

Estimate the gross primary productivity within plant cohorts.

This method uses the P Model to estimate the light use efficiency of leaves in gC mol-1, given the environment (temperate, atmospheric pressure, vapour pressure deficit and atmospheric CO2 concentration) within each canopy layer. This is multiplied by the absorbed irradiance within each canopy layer to predict the gross primary productivity (GPP, µg C m-2 s-1) for each canopy layer.

The GPP for each cohort is then estimated by mutiplying the cohort canopy area within each layer by GPP and the time elapsed in seconds since the last update.

Warning

At present this method checks that the required forcing variables exist, but asserts a constant fixed light use efficiency rather than using the P Model.

Parameters:

time_index – The index along the time axis of the forcing data giving the time step to be used to estimate GPP.

Raises:

ValueError – if any of the P Model forcing variables are not defined.

flora

A flora containing the plant functional types used in the plants model.

classmethod from_config(data: Data, core_components: CoreComponents, config: Config) → PlantsModel

Factory function to initialise a plants model from configuration.

This function returns a PlantsModel instance based on the provided configuration and data, raising an exception if the configuration is invalid.

Parameters:

• data – A Data instance.

• core_components – The core components used across models.

• config – A validated Virtual Ecosystem model configuration object.

layer_structure: LayerStructure

The LayerStructure details used in the model.

model_constants

Set of constants for the plants model

model_timing: ModelTiming

The ModelTiming details used in the model.

model_update_bounds: tuple[pint.Quantity, pint.Quantity] = (<Quantity(1, 'day')>, <Quantity(1, 'year')>)

Bounds on model update frequencies.

This class attribute defines two time intervals that define a lower and upper bound on the update frequency that can reasonably be used with a model. Models updated more often than the lower bound may fail to capture transient dynamics and models updated more slowly than the upper bound may fail to capture important temporal patterns.

required_init_vars: tuple[tuple[str, tuple[str, ...]], ...] = (('plant_cohorts_cell_id', ()), ('plant_cohorts_pft', ()), ('plant_cohorts_n', ()), ('plant_cohorts_dbh', ()), ('photosynthetic_photon_flux_density', ('spatial',)))

Required variables for model initialisation.

This class property defines a set of variable names that must be present in the Data instance used to initialise an instance of this class. It is a tuple containing zero or more tuples, each providing a variable name and then a tuple of zero or more core axes that the variable must map onto.

For example: (('temperature', ('spatial', 'temporal')),)

set_absorbed_irradiance(time_index: int) → None

Set the absorbed irradiance across the canopy.

This method takes the photosynthetic photon flux density at the top of the canopy for a particular time index and uses the layer_fapar data calculated by the canopy model to estimate the irradiance absorbed by each layer and the remaining irradiance at ground level.

setup() → None

Placeholder function to set up the plants model.

spinup() → None

Placeholder function to spin up the plants model.

update(time_index: int, **kwargs: Any) → None

Update the plants model.

This method first updates the canopy layers, so that growth in any previous update is reflected in the canopy structure. It then estimates the absorbed irradiance through the canopy and calculates the per cohort gross primary productivity, given the position in the canopy and canopy area of each individual in the cohort. This then increments the diameter of breast height within the cohort.

Parameters:

time_index – The index representing the current time step in the data object.

update_canopy_layers() → None

Update the canopy structure for the plant communities.

This method calculates the canopy structure from the current state of the plant cohorts across grid cells and then updates four canopy layer variables in the the data object:

• the layer closure heights (layer_heights),

• the layer leaf area indices (leaf_area_index),

• the fraction of absorbed photosynthetically active radation in each layer (layer_fapar), and

• the whole canopy leaf mass within the layers (layer_leaf_mass), and

• the absorbed irradiance in each layer, including the remaining incident radation at ground level (layer_absorbed_irradiation).

vars_updated: tuple[str, ...] = ('leaf_area_index', 'layer_heights', 'layer_fapar', 'layer_leaf_mass', 'layer_absorbed_irradiation', 'evapotranspiration')

Variables that are updated by the model.

At the moment, this tuple is used to decide which variables to output from the Data object, i.e. every variable updated by a model used in the specific simulation. In future, this could also be used to prevent multiple models from updating the same variable and similar problems.

The plants constants module

This submodule contains a set of dataclasses containing constants used in the plants module.

Classes:

PlantsConsts([placeholder])

Constants for the plants model.

class virtual_ecosystem.models.plants.constants.PlantsConsts(placeholder: float = 1.0)

Constants for the plants model.

Attributes:

placeholder

Placeholder constant.

placeholder: float = 1.0

Placeholder constant.