Plant structures for the plants module

This page documents three submodules of the plants module:

  1. The plant functional types (PFTs) that make up the flora used in a simulation.

  2. The plant community structures, describing the cohorts of stems of different PFTs with different diameters at breast height within a grid cell.

  3. The canopy structure generated in a grid cell by the plant community.

The plant functional_types module

Initial definition of plant functional type classes.

These are likely to become part of pyrealm.

Classes:

Flora(pfts)

Defines the flora used in a virtual_ecosystem model.

PlantFunctionalType(pft_name, max_height)

Data class containing plant functional type definitions.
class virtual_ecosystem.models.plants.functional_types.Flora(pfts: list[PlantFunctionalType])

Defines the flora used in a virtual_ecosystem model.

The flora is the set of plant functional types used within a particular simulation and this class provides dictionary-like access to a defined set of PlantFunctionalType instances.

Instances of this class should not be altered during model fitting, at least until the point where plant evolution is included in the modelling process.

Parameters:

pfts – A list of PlantFunctionalType instances, which must not have duplicated pft_name attributes.

Methods:

from_config(config)

Factory method to generate a Flora instance from a configuration.
classmethod from_config(config: Config) → Flora

Factory method to generate a Flora instance from a configuration.

Parameters:

config – A validated Virtual Ecosystem model configuration object.

Returns:

A populated Flora instance

class virtual_ecosystem.models.plants.functional_types.PlantFunctionalType(pft_name: str, max_height: float)

Data class containing plant functional type definitions.

Attributes:

max_height

The maximum stem height of the plant functional type.

pft_name

The name of the plant functional type.
max_height: float

The maximum stem height of the plant functional type.

pft_name: str

The name of the plant functional type.

The plants community module

The community submodule provides a simple dataclass to hold plant cohort information and then the PlantCommunities class that is used to hold list of plant cohorts by grid cell and generate those lists from variables provided in the data object.

NOTE - much of this will be outsourced to pyrealm.

Classes:

PlantCohort(pft, dbh, n)

A dataclass describing a plant cohort.

PlantCommunities(data, flora)

A dictionary of plant cohorts keyed by grid cell id.
class virtual_ecosystem.models.plants.community.PlantCohort(pft: PlantFunctionalType, dbh: float, n: int)

A dataclass describing a plant cohort.

The cohort is defined by the plant functional type, the number of individuals in the cohort and the diameter at breast height for the cohort.

Instances also have a canopy_area and gpp attributes that are used to track the canopy structure of a cohort within the wider community and record gross primary productivity. These should not be updated by users.

Attributes:

canopy_area

The canopy area within canopy layers of each individual.

dbh

The diameter at breast height (m) of cohort members.

gpp

The gross primary productivity for each individual.

n

The number of individuals in the cohort.

pft

The plant functional type of the cohort.
canopy_area: ndarray[Any, dtype[float32]]

The canopy area within canopy layers of each individual.

dbh: float

The diameter at breast height (m) of cohort members.

gpp: float = 0

The gross primary productivity for each individual.

n: int

The number of individuals in the cohort.

pft: PlantFunctionalType

The plant functional type of the cohort.

class virtual_ecosystem.models.plants.community.PlantCommunities(data: Data, flora: Flora)

A dictionary of plant cohorts keyed by grid cell id.

An instance of this class is initialised from a Data object that must contain the variables plant_cohorts_cell_id, plant_cohorts_pft, plant_cohorts_n and plant_cohorts_dbh. These are required to be equal length, one-dimensional arrays that provide the data to initialise each plant cohort. The data are validated and then compiled into lists of cohorts keyed by grid cell id. The class provides a __getitem__ method to allow the list of cohorts for a grid cell to be accessed using plants_inst[cell_id].

Parameters:

  • data – A data instance containing the required plant cohort data.

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

The plants canopy module

The canopy submodule provides the core functions used to estimate the canopy model.

NOTE - much of this will be outsourced to pyrealm.

Functions:

build_canopy_arrays(communities, n_canopy_layers)

Converts the PlantCommunities data into canopy layer data arrays.

generate_canopy_model(community)

Generate the canopy structure for a plant community.

initialise_canopy_layers(data, layer_structure)

Initialise the canopy layer height and leaf area index data.
virtual_ecosystem.models.plants.canopy.build_canopy_arrays(communities: PlantCommunities, n_canopy_layers: int) → tuple[ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]]]

Converts the PlantCommunities data into canopy layer data arrays.

This function takes a list of plant cohorts present in a community and uses the T Model to estimate the heights and crown areas of the individuals. It then uses the perfect plasticity approximation to calculate the closure heights of the canopy layers and the leaf area indices of each layer.

Parameters:

  • communities – The PlantCommunities object to convert

  • n_canopy_layers – The maximum number of permitted canopy layers.

Returns:

A tuple of two dimensional numpy arrays giving the canopy layer heights and then leaf area indices, \(f_{APAR}\) and leaf mass by cell id.

virtual_ecosystem.models.plants.canopy.generate_canopy_model(community: list[PlantCohort]) → tuple[ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]]]

Generate the canopy structure for a plant community.

This function takes a list of plant cohorts present in a community and uses the T Model to estimate the heights and crown areas of the individuals. It then uses the perfect plasticity approximation to calculate the closure heights of the canopy layers and the leaf area indices of each layer. The last step is then to use the Beer-Lambert law to estimate the fraction of absorbed photosynthetically active radiation (fapar, \(f_{APAR}\)) for the canopy.

This function also updates the input community data, by setting the canopy_area attribute of each PlantCohort object to the area of canopy for that cohort within each of the canopy layers. These are then used to calculate the gross primary productivity of each cohort within the community.

Warning

This function defines the API for generating canopy models but currently returns constant values for all inputs.

Parameters:

community – A list of plant cohorts.

Returns:

A tuple of one dimensional numpy arrays giving the layer heights along with the leaf area indices, \(f_{APAR}\) and leaf masses from the canopy model.

virtual_ecosystem.models.plants.canopy.initialise_canopy_layers(data: Data, layer_structure: LayerStructure) → Data

Initialise the canopy layer height and leaf area index data.

This function initialises four data arrays describing the plant canopy structure and soil layer structure within a Data object: layer_heights, leaf_area_index, layer_fapar, layer_leaf_mass and layer_absorbed_irradiation.

Parameters:

  • data – A Data object to update.

  • layer_structure – A layer structure object containing the layer configuration

Returns:

A data object with the layers added.

Raises:

InitialisationError – if the layers already exist in the data object