API documentation for the plants model

The plants_model module

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

Classes:

PlantsModel(data, core_components, exporter, ...)

Representation of plants in the Virtual Ecosystem.

class virtual_ecosystem.models.plants.plants_model.PlantsModel(data: Data, core_components: CoreComponents, exporter: CommunityDataExporter, flora: Flora, cohort_data: DataFrame, extra_pft_traits: ExtraTraitsPFT, model_constants: PlantsConstants = PlantsConstants(), pyrealm_config: PyrealmConfig = PyrealmConfig(), static: bool = False)

Representation of plants in the Virtual Ecosystem.

The plants model is initialised using data from three sources:

1. The flora object contains a set of plant functional types, associating unique PFT names with sets of required traits for each PFT.

2. A data frame defining the initial cohort inventories for each grid cell. Each row in the data frame defines a cohort in one of the grid cells and the fields set:

   • plant_cohorts_pft: The PFT of the cohort, matching an entry in the flora

   • plant_cohorts_cell_id: The grid cell id containing 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.

These data are used to setup the plant communities within each grid cell, using the PlantCommunities class to maintain a lookup dictionary of communities by grid cell.

The model setup then initialises the canopy layer data within the virtual_ecosystem.core.data.Data instance for the simulation and populates these data layers with the calculated community canopy structure for each grid cell. The community canopy representation is calculated using the perfect plasticticy approximation, implemented in the pyrealm package. The canopy variables populated at this stage are:

• the canopy layer closure heights (layer_heights),

• the canopy layer leaf area indices (leaf_area_index),

• the fraction of absorbed photosynthetically active radiation in each canopy layer

  (layer_fapar), and

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

The model update process filters the photosynthetic photon flux density at the top of canopy through the community canopy representation. This allows the gross primary productivity (GPP) within canopy layers to be estimated, giving the total expected GPP for individual stems within cohorts. The predicted GPP is then allocated between plant respiration, turnover and growth and the resulting allocation to growth is used to predict the change in stem diameter expected during the update interval.

Parameters:

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

• core_components – The core components used across models.

• exporter – An instance of the CommunityDataExporter class used to export plant community data for each time step.

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

• cohort_data – A data frame containing the initial cohort data.

• extra_pft_traits – Additional traits for each plant functional type, keyed by PFT name.

• model_constants – Set of constants for the plants model.

• pyrealm_config – Configuration options to the pyrealm package.

• static – Boolean flag indicating if the model should run in static mode.

Methods:

allocate_gpp()	Calculate the allocation of GPP to growth and respiration.
apply_herbivory()	Applies herbivory effects on the plants model.
apply_mortality()	Apply mortality to plant cohorts.
apply_recruitment()	Apply recruitment to plant cohorts.
calculate_light_use_efficiency()	Calculate the light use efficiency across vertical layers.
calculate_nutrient_uptake()	Calculate uptake of soil nutrients by the plant community.
calculate_turnover()	Calculate turnover of each plant biomass pool.
check_init_data()	Check the init data contains the required variables.
cleanup()	Placeholder function for plants model cleanup.
convert_to_litter_units(input_mass)	Helper function to convert plant quantities into litter model units.
convert_to_soil_units(input_mass)	Helper function to convert plant quantities into soil model units.
estimate_gpp(time_index)	Estimate the gross primary productivity within plant cohorts.
from_config(data, configuration, core_components)	Factory function to initialise a plants model from configuration.
reset_update_vars()	Resets specified variables in the data object before each update.
set_canopy_top_radiation(time_index)	Set the current canopy top shortwave downwelling radiation.
set_shortwave_absorption()	Set the shortwave radiation absorption across the vertical layers.
spinup()	Placeholder function to spin up the plants model.
update(time_index, **kwargs)	Function to update the model.
update_allometry()	Update the T model allometry of cohorts.
update_canopy_layers()	Update the canopy structure for the plant communities.

Attributes:

allocations	A dictionary keyed by cell id giving the allocation of each community.
below_canopy_light_fraction	The fraction of light transmitted through the canopy.
biomass_tissues	A list of types of biomass subclasses that sets the tissues to be modelled within the simulation.
biomasses	A dictionary keyed by cell id of the carbon and nutrient biomass of each community.
canopies	A dictionary giving the canopy structure of each grid cell.
canopy_top_radiation	The downwelling radiation at the canopy top for the current time step.
communities	An instance of PlantCommunities providing dictionary access keyed by cell id to PlantCommunity instances for each cell.
core_constants	The core constants used in the model.
data	A Data instance providing access to the shared simulation data.
data_object_templates	DataArray templates for the data object.
exporter	A CommunityDataExporter instance providing configuration and methods for export of community data.
extra_pft_traits	The extra traits for each plant functional type, keyed by PFT name.
filled_canopy_mask	A boolean array showing which layers contain canopy by cell.
flora	A flora containing the plant functional types used in the plants model.
grid	The Grid details used in the model.
ground_incident_light_fraction	The fraction of light reaching the ground through the canopy and subcanopy vegetation.
initial_cohort_data	A dataframe providing the initial cohort data.
layer_structure	The LayerStructure details used in the model.
model_constant	Set of constants for the plants model
model_timing	The ModelTiming details used in the model.
model_update_bounds	Bounds on model update frequencies.
per_stem_gpp	A dictionary keyed by cell id giving the GPP values over the course of a model update for each stem within the cohorts in the community (µg C).
per_stem_transpiration	A dictionary keyed by cell id giving an array of per stem transpiration values in for each cohort in the cell community (mm H2O)
per_update_interval_stem_mortality_probability	The rate of stem mortality per update interval.
pmodel	A P Model instance providing estimates of light use efficiency through the canopy and across cells.
pyrealm_core_consts	Core constants used by pyrealm.
pyrealm_pmodel_consts	PModel constants used by pyrealm.
stem_allocations	A dictionary giving the stem allocation of GPP for the community in each grid cell.
subcanopy	Representation of the subcanopy vegetation.
vars_populated_by_first_update	Variables that are initialised by the model during the first update.
vars_populated_by_init	Variables that are initialised by the model during the setup.
vars_required_for_init	Required variables for model initialisation.
vars_required_for_update	Variables that are required by the update method of the model.
vars_updated	Variables that are updated by the model.

allocate_gpp() → None

Calculate the allocation of GPP to growth and respiration.

This method uses the T Model to estimate the allocation of plant gross primary productivity to respiration, growth, maintenance and turnover costs. The method then simulates growth by increasing dbh and calculates leaf and root turnover values.

allocations: dict[int, StemAllocation]

A dictionary keyed by cell id giving the allocation of each community.

apply_herbivory() → None

Applies herbivory effects on the plants model.

Herbivory removes biomass from the biomass tissues. In the case of foliage herbivory, this also impacts the light gathering of the canopy and effects the allocation of carbon to replacing lost leaves, assuming the plant prioritises the maintenance of canopy area during allocation of GPP.

The impacts on light gathering are modelled by decreasing the LAI of the cohort to reflect the decrease in expected foliage mass (\(W_f\)) given the mass of foliage removed by herbivory (\(H_f\)). The model assumes a constant rate of herbivory, such that the average realised leaf mass over a time step is:

\[\tilde{W_f} = W_f - H_f / 2\]

The original expected foliage mass is calculated, given the crown area (\(A_c\)), LAI (\(L\)) and specific leaf area (\(\sigma\)) as:

\[W_f = (A_c L) / \sigma\]

Hence the realised LAI given herbivory can be calculated as:

\[\tilde{L} = (\tilde{W_f} \sigma) / A_c\]

The increased carbon cost of leaf replacement can be rolled into the standard foliage turnover costs by increasing the foliage turnover rate (\(\tau_f\)). This increases turnover costs and hence reduces the amount of carbon available for stem growth.

\[\tilde{\tau_f} = \frac{W_f \tau_f}{H_f \tau_f + W_f}\]

Todo

There is a timing issue here - the effects of herbivory in the last time step are being used to modify the light gathering and leaf turnover costs for the current plants timestep.

apply_mortality() → None

Apply mortality to plant cohorts.

This function applies the basic annual mortality rate to plant cohorts. The mortality rate is currently a constant value for all cohorts. The function calculates the number of individuals that have died in each cohort and updates the cohort data accordingly.

The function then transfers the biomasses of dead stems into tissue turnover pools.

apply_recruitment() → None

Apply recruitment to plant cohorts.

This function applies recruitment to plant cohorts, currently using a single recruitment rate across all plant functional types.

below_canopy_light_fraction: NDArray[np.floating]

The fraction of light transmitted through the canopy.

biomass_tissues: list[type[BiomassTissueABC]]

A list of types of biomass subclasses that sets the tissues to be modelled within the simulation.

biomasses: dict[int, Biomasses]

A dictionary keyed by cell id of the carbon and nutrient biomass of each community.

calculate_light_use_efficiency() → None

Calculate the light use efficiency across vertical layers.

This method uses the P Model to estimate the light use efficiency within vertical layers, given the environmental conditions through the canopy structure.

calculate_nutrient_uptake() → None

Calculate uptake of soil nutrients by the plant community.

This function calculates the amount of inorganic nutrients(ammonium, nitrate, and labile phosphorus) taken up by plants from the soil, through transpiration. The function then assigns the N/P uptake values to the respective community through the Biomass class.

calculate_turnover() → None

Calculate turnover of each plant biomass pool.

This function calculates the lignin concentration, carbon nitrogen ratio, and carbon phosphorus ratio of each turnover flow. It also returns the rate at which plants supply carbon to their nitrogen fixing symbionts in the soil and the rate at which they exude carbohydrates into the soil more generally.

Warning

At present, this function literally just returns constant values for lignin and carbon fixation.

canopies: dict[int, Canopy]

A dictionary giving the canopy structure of each grid cell.

canopy_top_radiation: NDArray[np.floating]

The downwelling radiation at the canopy top for the current time step.

check_init_data() → None

Check the init data contains the required variables.

This method is used to check that the set of variables defined in the vars_required_for_init class attribute are present in the Data instance used to create a new instance of the class.

Raises:

ValueError – If the Data instance does not contain all the required variables or if those variables do not map onto the required axes.

cleanup() → None

Placeholder function for plants model cleanup.

communities: PlantCommunities

An instance of PlantCommunities providing dictionary access keyed by cell id to PlantCommunity instances for each cell.

convert_to_litter_units(input_mass: DataArray) → DataArray

Helper function to convert plant quantities into litter model units.

The plant model records the plant biomass in units of mass (kg) per grid square, whereas the litter model expects litter inputs as kg per m^2.

Parameters:

input_mass – The mass (of carbon) being passed from the plant model to the litter model [kg/g]

Returns:

The input mass converted to the density units that the litter model uses [kg m^-2]

convert_to_soil_units(input_mass: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[floating]]

Helper function to convert plant quantities into soil model units.

The plant model records the GPP allocations (summed over stems) in units of mass (g), whereas the soil model expects inputs into the soil to be expressed as rate per area units (i.e. kg m^-2 day^-1). As well as converting to per area and rate units this function also converts from g to kg.

Parameters:

input_mass – The mass (of carbon) being passed from the plant model to the soil model [g]

Returns:

The input mass converted to the density rate units that the soil model uses [kg m^-2 day^-1]

core_constants: CoreConstants

The core constants used in the model.

data: Data

A Data instance providing access to the shared simulation data.

data_object_templates: dict[str, xr.DataArray]

DataArray templates for the data object.

estimate_gpp(time_index: int) → None

Estimate the gross primary productivity within plant cohorts.

This method uses estimated light use efficiency from the P Model to estimate the light use efficiency of leaves in gC mol-1, given the environment (temperature, 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.

This method requires that the calculate_light_use_efficiency method has been run to populate the pmodel attribute.

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

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.

exporter: CommunityDataExporter

A CommunityDataExporter instance providing configuration and methods for export of community data.

extra_pft_traits: ExtraTraitsPFT

The extra traits for each plant functional type, keyed by PFT name.

filled_canopy_mask: NDArray[np.bool_]

A boolean array showing which layers contain canopy by cell.

flora: Flora

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

classmethod from_config(data: Data, configuration: CompiledConfiguration, core_components: CoreComponents) → 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.

• configuration – A validated Virtual Ecosystem model configuration object.

• core_components – The core components used across models.

grid: Grid

The Grid details used in the model.

ground_incident_light_fraction: NDArray[np.floating]

The fraction of light reaching the ground through the canopy and subcanopy vegetation.

initial_cohort_data: DataFrame

A dataframe providing the initial cohort data.

layer_structure: LayerStructure

The LayerStructure details used in the model.

model_constant: PlantsConstants

Set of constants for the plants model

model_timing: ModelTiming

The ModelTiming details used in the model.

model_update_bounds: tuple[Quantity, 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.

per_stem_gpp: dict[int, NDArray[np.floating]]

A dictionary keyed by cell id giving the GPP values over the course of a model update for each stem within the cohorts in the community (µg C).

per_stem_transpiration: dict[int, NDArray[np.floating]]

A dictionary keyed by cell id giving an array of per stem transpiration values in for each cohort in the cell community (mm H2O)

per_update_interval_stem_mortality_probability: np.float64

The rate of stem mortality per update interval.

pmodel: PModel

A P Model instance providing estimates of light use efficiency through the canopy and across cells.

pyrealm_core_consts: CoreConst

Core constants used by pyrealm.

pyrealm_pmodel_consts: PModelConst

PModel constants used by pyrealm.

reset_update_vars() → None

Resets specified variables in the data object before each update.

set_canopy_top_radiation(time_index: int) → None

Set the current canopy top shortwave downwelling radiation.

set_shortwave_absorption() → None

Set the shortwave radiation absorption across the vertical layers.

This method takes the shortwave radiation at the top of the canopy for a particular time index and uses the layer_fapar data calculated by the canopy and subcanopy models to estimate the amount of radiation absorbed by each canopy layer and the remaining radiation absorbed by the top soil layer.

The method requires that the canopy_top_radiation attribute has been set with the SWD values for the current time step.

Todo

• With the full canopy model, this could be partitioned into sunspots and shade.

spinup() → None

Placeholder function to spin up the plants model.

stem_allocations: dict[int, StemAllocation]

A dictionary giving the stem allocation of GPP for the community in each grid cell. The dictionary is only populated by the update method - before that the dictionary will be empty.

subcanopy: Subcanopy

Representation of the subcanopy vegetation.

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

Function to update the model.

If the model is static, the inner update method, self._update will only run once, at most.

Parameters:

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

• **kwargs – Further arguments to the update method.

update_allometry() → None

Update the T model allometry of cohorts.

This method is used to update the theoretical expectation of the stem allometry under the T model given any changes to the DBH of cohorts from growth. It also handles resetting LAI and foliage turnover rates - which may have been altered in the apply_herbivory method - to the default values for the PFT for each cohort.

update_canopy_layers() → None

Update the canopy structure for the plant communities.

This method updates the following canopy layer variables in the data object from the current state of the canopies attribute:

• the layer closure heights (layer_heights),

• the layer leaf area indices (leaf_area_index),

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

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

• the proportion of shortwave radiation absorbed, including both by leaves in canopy layers and by light reaching the topsoil (shortwave_absorption).

vars_populated_by_first_update: tuple[str, ...] = ('plant_ammonium_uptake', 'plant_nitrate_uptake', 'plant_phosphorus_uptake', 'plant_reproductive_tissue_lignin', 'plant_symbiote_carbon_supply', 'root_carbohydrate_exudation', 'root_lignin', 'senesced_leaf_lignin', 'stem_lignin', 'transpiration', 'subcanopy_seedbank_litter_lignin', 'subcanopy_vegetation_litter_lignin', 'subcanopy_ammonium_uptake', 'subcanopy_nitrate_uptake', 'subcanopy_phosphorus_uptake')

Variables that are initialised by the model during the first update.

These are the variables that are initialised by the model and stored in the data object when running the update method for the first time. They will be available for other models to use in their update methods but not in the setup methods.

vars_populated_by_init: tuple[str, ...] = ('layer_fapar', 'layer_heights', 'layer_leaf_mass', 'leaf_area_index', 'shortwave_absorption', 'subcanopy_seedbank_litter_cnp', 'subcanopy_vegetation_litter_cnp', 'subcanopy_vegetation_cnp', 'subcanopy_seedbank_cnp', 'fallen_seeds_cnp', 'fallen_fruit_cnp', 'fallen_seeds_per_fruit', 'fallen_fruit_n', 'canopy_seed_cnp', 'canopy_fruit_cnp', 'canopy_seeds_per_fruit', 'canopy_fruit_n', 'canopy_foliage_cnp', 'stem_turnover_cnp', 'foliage_turnover_cnp', 'root_turnover_cnp', 'seed_turnover_cnp', 'fruit_turnover_cnp', 'subcanopy_vegetation_cnp_consumed', 'subcanopy_seedbank_cnp_consumed', 'canopy_foliage_cnp_consumed', 'canopy_seed_cnp_consumed', 'canopy_fruit_cnp_consumed', 'foliage_turnover_cnp_consumed', 'seed_turnover_cnp_consumed', 'fruit_turnover_cnp_consumed')

Variables that are initialised by the model during the setup.

These are the variables that are initialised by the model and stored in the data object when running the setup method and that will be available for other models to use in their own setup or update methods.

vars_required_for_init: tuple[str, ...] = ('downward_shortwave_radiation', 'plant_pft_propagules', 'subcanopy_seedbank_biomass', 'subcanopy_vegetation_biomass')

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')),)

vars_required_for_update: tuple[str, ...] = ('air_temperature', 'atmospheric_co2', 'atmospheric_pressure', 'dissolved_ammonium', 'dissolved_nitrate', 'dissolved_phosphorus', 'downward_shortwave_radiation', 'plant_pft_propagules', 'subcanopy_seedbank_biomass', 'subcanopy_vegetation_biomass', 'vapour_pressure_deficit', 'arbuscular_mycorrhizal_n_supply', 'arbuscular_mycorrhizal_p_supply', 'ectomycorrhizal_n_supply', 'ectomycorrhizal_p_supply')

Variables that are required by the update method of the model.

These variables should have been initialised by another model or loaded from external sources, but in either case they will be available in the data object.

vars_updated: tuple[str, ...] = ('stem_turnover_cnp', 'foliage_turnover_cnp', 'root_turnover_cnp', 'seed_turnover_cnp', 'fruit_turnover_cnp', 'canopy_fruit_n', 'canopy_fruit_cnp', 'canopy_seeds_per_fruit', 'canopy_seed_cnp', 'fallen_fruit_n', 'fallen_fruit_cnp', 'fallen_seeds_per_fruit', 'fallen_seeds_cnp', 'canopy_foliage_cnp', 'subcanopy_seedbank_litter_cnp', 'subcanopy_vegetation_litter_cnp', 'subcanopy_vegetation_cnp', 'subcanopy_seedbank_cnp', 'layer_fapar', 'layer_heights', 'layer_leaf_mass', 'leaf_area_index', 'plant_ammonium_uptake', 'plant_nitrate_uptake', 'plant_phosphorus_uptake', 'plant_reproductive_tissue_lignin', 'plant_symbiote_carbon_supply', 'root_carbohydrate_exudation', 'root_lignin', 'senesced_leaf_lignin', 'shortwave_absorption', 'stem_lignin', 'subcanopy_seedbank_biomass', 'subcanopy_vegetation_biomass', 'transpiration', 'subcanopy_seedbank_litter_lignin', 'subcanopy_vegetation_litter_lignin', 'subcanopy_ammonium_uptake', 'subcanopy_nitrate_uptake', 'subcanopy_phosphorus_uptake')

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. It is also be used warn if multiple models will be updating the same variable and to verify that these variables are indeed initialised by another model, and therefore will be available.