Plant structures for the `plants` module#

This page documents submodules of the plants module used to support the central plants_model module:

The plant functional types (PFTs) that make up the flora used in a simulation.
The plant community structures, describing the cohorts of stems of different PFTs with different diameters at breast height within a grid cell.
The canopy structure generated in a grid cell by the plant community.
The constants definitions required to run the model

The plant `functional_types` module#

The functional_types submodule provides functionality to load plant functional type definitions from the model configuration and generate a Flora object for use in simulation.

Classes:

ExtraTraitsPFT(traits)

A dataclass to hold additional traits for a plant functional type.

Functions:

get_flora_from_config(config)

Generate a Flora object from a Virtual Ecosystem configuration.

class virtual_ecosystem.models.plants.functional_types.ExtraTraitsPFT(traits: dict[str, dict[str, float]])[source]#

A dataclass to hold additional traits for a plant functional type.

This class is used to store traits that are not part of the standard PFT definition in Pyrealm, but are used in the Virtual Ecosystem. Each instance of this class maps to one PFT, keyed by the PFT name. The structure is:

{‘pft_name’: {‘trait_name’: trait_value, …},: ‘pft_name_2’: {‘trait_name’: trait_value, …}, …}

Attributes:

array_attrs

Additional array attributes accepted by the ExtraTraitsPFT class.

Methods:

from_df(df)

Load additional traits from a DataFrame.

array_attrs: ClassVar[tuple[str, ...]] = ('deadwood_c_n_ratio', 'deadwood_c_p_ratio', 'leaf_turnover_c_n_ratio', 'leaf_turnover_c_p_ratio', 'plant_reproductive_tissue_turnover_c_n_ratio', 'plant_reproductive_tissue_turnover_c_p_ratio', 'root_turnover_c_p_ratio', 'root_turnover_c_n_ratio', 'foliage_c_n_ratio', 'foliage_c_p_ratio', 'c_mass_fruit_flesh', 'c_mass_per_fruit_seed', 'seeds_per_fruit')#: Additional array attributes accepted by the ExtraTraitsPFT class.

classmethod from_df(df) → ExtraTraitsPFT[source]#

Load additional traits from a DataFrame.

Parameters:: df – A pandas DataFrame containing additional traits.
Returns:: An instance of ExtraTraitsPFT with the loaded traits.

virtual_ecosystem.models.plants.functional_types.get_flora_from_config(config: PlantsConfiguration) → tuple[Flora, ExtraTraitsPFT][source]#

Generate a Flora object from a Virtual Ecosystem configuration.

Parameters:: config – A validated PlantsConfiguration instance.
Returns:: A tuple containing a populated pyrealm.demography.flora.Flora instance and an ExtraTraitsPFT instance.

The plants `communities` module#

The communities submodule provides the PlantCommunities class. This provides a dictionary mapping each grid cell id to the plant community growing within the cell.

There is a one-to-one mapping of grid cells to plant communities, with the individual community for a grid cell being represented as a pyrealm.demography.community.Community instance. The community is then made up of size-structured plant cohorts using pyrealm.demography.community.Cohorts instances.

Classes:

PlantCommunities(cohort_data, flora, grid)

Records the plant community with each grid cell across a simulation.

class virtual_ecosystem.models.plants.communities.PlantCommunities(cohort_data: DataFrame, flora: Flora, grid: Grid)[source]#

Records the plant community with each grid cell across a simulation.

A PlantCommunities instance provides a dictionary mapping each grid cell onto a single pyrealm.demography.community.Community instance, containing a set of pyrealm.demography.community.Cohorts instances.

A class instance must be initialised using pandas.DataFrame instance containing the required cohort data. Each row in the data frame defines a cohort located in one of the cells, so required data frame fields are:

the cell id in which the cohort is located (plant_cohorts_cell_id),
the plant functional type of the cohort (plant_cohorts_pft),
the number of individuals within the cohort (plant_cohorts_n), and
the diameter at breast height of the individuals (plant_cohorts_dbh).

The data are validated and then compiled into lists of cohorts keyed by grid cell id. The class is a subclass of dictionary, so has the __get_item__ method, allowing access to the community for a given cell id using plants_inst[cell_id].

Todo

This function will need updating if the grid cell area implementation is changed to allow variable cell area .

Parameters:

cohort_data – A data frame containing the initial cohort data.
flora – A flora containing the plant functional types used in the cohorts.
grid – The grid for the simulation, providing the area of the grid cells and the expected cell ids.

The plants `canopy` module#

The canopy submodule provides functionality to initialise the canopy layer data held in the simulation Data instance and to generate Canopy instances from the plant community data within each grid cell.

Functions:

`calculate_canopies`(communities, ...)	Calculate the canopy structure of communities.
`initialise_canopy_layers`(data, layer_structure)	Initialise the canopy layer height and leaf area index data.

virtual_ecosystem.models.plants.canopy.calculate_canopies(communities: PlantCommunities, max_canopy_layers: int) → dict[int, Canopy][source]#

Calculate the canopy structure of communities.

This function takes a PlantCommunities object and calculates the canopy representation for each community, using the perfect plasticity approximation to calculate the closure heights of the canopy layers.

Parameters:

communities – The PlantCommunities object to convert
max_canopy_layers – The maximum number of permitted canopy layers

Returns:

A dictionary of pyrealm.demography.canopy.Canopy instances, keyed by grid cell id. There is a one-to-one mapping of canopy representations to grid cells.

virtual_ecosystem.models.plants.canopy.initialise_canopy_layers(data: Data, layer_structure: LayerStructure) → dict[str, DataArray][source]#

Initialise the canopy layer height and leaf area index data.

This function initialises the following 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 shortwave_absorption.

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

The plants `biomasses` module#

The biomasses module contains the class for managing plant cohort carbon biomass along with the biomasses of all elements being tracked stochiometrically within a simulation. The class contains representations of the carbon mass and element masses within individual tissues and provides methods to balance stoichiometric nutrients across tissues.

The theoretical tissue masses for individuals in a cohort are derived from the T Model predictions for the stem and the elemental masses are currently populated using the ideal ratio of those elements for each tissue. Growth is modelled using allocation of NPP from the T Model. However, the actual realised masses of different tissues can differ from the theory due to herbivory and fruit production, so this class is used to track the actual carbon masses realised by individuals through the simulation.

The module define a base class for tissues and then currently four tissue types.

FoliageBiomass:

# Has different ratios in turnover mass

biomass: foliage_mass turnover_biomass: foliage_turnover growth_biomass: delta_foliage_mass

ideal_ratio: foliage_c_{elem.lower()}_ratio turnover_ratio: leaf_turnover_c_{elem.lower()}_ratio

TODO - check to make sure turnover foliage doesn’t get relatively _enriched_ if the: plant is severely nutrient depleted.

ReproductiveBiomass:

# Same ratios; has turnover

biomass: reproductive_tissue_mass turnover_biomass: reproductive_tissue_turnover growth_biomass: foliage_tissue * p_foliage_for_reproductive_tissue

ideal_ratio: not defined - identical to turnover ratio turnover_ratio: plant_reproductive_tissue_turnover_c_{elem.lower()}_ratio

RootBiomass:

# Same ratios; has turnover

biomass: fine_root_mass turnover_biomass: fine_root_turnover growth_biomass: delta_foliage_mass * zeta * sla

ideal_ratio: not defined - identical to turnover ratio turnover_ratio: root_turnover_c_{elem.lower()}_ratio

StemBiomass

# No turnover at present, so same ratios doesn’t really make sense, but if there was: turnover it probably would be at these ratios.

biomass: stem_mass turnover_biomass: not defined, no stem turnover growth_biomass: delta_stem_mass

ideal_ratio: deadwood_c_{elem.lower()}_ratio turnover_ratio: not defined (because there is no turnover)

TODO - factor out mass accessor functions (get_biomass etc) as in the lists above and

then make those limited functions the abstract methods so that all the logic can be shared in base class methods.

TODO - make this all run on 2D CNP arrays (remove Element?) Have single arrays giving

biomasses and ideal and turnover ratios.

Classes:

`BiomassTissueABC`(community, ...)	A dataclass to hold tissue stoichiometry biomasses for a set of plant cohorts.
`Biomasses`(tissues, community, extra_pft_traits)	A class holding biomasses for a set of plant cohorts and tissues.
`Element`(name, ideal_ratio, ...)	Stochiometric elemental masses for cohorts in a community.
`FoliageBiomass`(community, extra_pft_traits, ...)	A class to hold foliage stoichiometry data for a set of plant cohorts.
`FruitBiomass`(community, extra_pft_traits, ...)	Holds fruit tissue stoichiometry data for a set of plant cohorts.
`ReproductiveBiomass`(community, ...)	Holds reproductive tissue stoichiometry data for a set of plant cohorts.
`RootBiomass`(community, extra_pft_traits, ...)	A class to hold root stoichiometry data for a set of plant cohorts.
`SeedBiomass`(community, extra_pft_traits, ...)	Holds fruit tissue stoichiometry data for a set of plant cohorts.
`StemBiomass`(community, extra_pft_traits, ...)	A class to hold stem stoichiometry data for a set of plant cohorts.

class virtual_ecosystem.models.plants.biomasses.BiomassTissueABC(community: Community, extra_pft_traits: ExtraTraitsPFT, carbon_mass: ndarray[tuple[Any, ...], dtype[floating]], element_masses: dict[str, Element])[source]#

A dataclass to hold tissue stoichiometry biomasses for a set of plant cohorts.

This class holds the current quantity of a given element (generally N or P) for a specific plant tissue type (generally foliage, wood, roots or reproductive tissue). The class also holds the ideal ratio of the element for that tissue type. They hold an entry for each cohort in the data class.

Attributes:

`Cx_ratio`	Get the carbon to element ratio for the tissue type.
`carbon_mass`	An 1D array of tissue carbon mass for each stem in cohorts in the community.
`community`	The community object that the tissue is associated with.
`deficit`	Calculate the element deficit (ideal mass - actual mass) for the tissue.
`element_masses`	A dictionary of Elements containing nutrient masses each stem in cohorts in the community.
`get_elemental_masses`	Get the current element masses for the tissue.
`tissue_name`	A tissue name for derived classes.

Methods:

`add_elemental_masses`(masses)	Return the current element masses for the tissue.
`append`(other)	Add new tissue data representing new cohorts.
`apply_growth`(allocation)	Increase tissue biomasses following growth allocation for the tissue.
`apply_herbivory`(herbivory_array)	Remove biomass from a tissue to account for herbiivory.
`as_array`([deficit, with_carbon])	Utility method to return tissue masses as an array.
`from_pft_default_ratios`(community, ...)	Create a default instance of Tissue based on the PFT traits.
`get_relative_carbon_biomass_by_pft`()	Get the proportional carbon biomass of each cohort within PFTs for a tissue.
`get_turnover`(allocation)	Calculate the elemental losses to turnover for the tissue type.

property Cx_ratio: dict[str, ndarray[tuple[Any, ...], dtype[floating]]]#

Get the carbon to element ratio for the tissue type.

Returns:: The carbon to element ratio for the specified tissue.

add_elemental_masses(masses: dict[str, ndarray[tuple[Any, ...], dtype[floating]]]) → None[source]#

Return the current element masses for the tissue.

Returns:: The element deficit for the specified tissue.

append(other: BiomassTissueABC)[source]#: Add new tissue data representing new cohorts.

abstractmethod apply_growth(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Increase tissue biomasses following growth allocation for the tissue.

This method should adjust the carbon biomass following the allocation model and similarly increase nutrient biomasses following the ideal ratios. The method must then also return the nutrient biomass increases, so that subsequent nutrient balancing can account for deficits and excesses within the stem.

apply_herbivory(herbivory_array: DataArray)[source]#

Remove biomass from a tissue to account for herbiivory.

The input is expected to be a DataArray with a pft dimension matching the number of cohorts and then an element dimension containing C and then each element.

NOTE - if this class moves to an all array representation of biomasses, then it: we should be able just to subtract the incoming array from the current element masses. Note that np.array - xr.DataArray returns an xr.DataArray so need to reduce to numpy.

as_array(deficit: bool = False, with_carbon: bool = False) → ndarray[tuple[Any, ...], dtype[floating]][source]#

Utility method to return tissue masses as an array.

TODO: The internals of this class may switch over to array based, this is a: placeholder API for that change.

Parameters:

deficit – Return the deficit masses not the actual masses.
with_carbon – Should carbon mass be included in the array.

carbon_mass: ndarray[tuple[Any, ...], dtype[floating]]#: An 1D array of tissue carbon mass for each stem in cohorts in the community.

community: Community#: The community object that the tissue is associated with.

property deficit: dict[str, ndarray[tuple[Any, ...], dtype[floating]]]#

Calculate the element deficit (ideal mass - actual mass) for the tissue.

Returns:: The element deficit for the specified tissue.

element_masses: dict[str, Element]#: A dictionary of Elements containing nutrient masses each stem in cohorts in the community.

abstractmethod classmethod from_pft_default_ratios(community: Community, extra_pft_traits: ExtraTraitsPFT, with_elements: list[str])[source]#: Create a default instance of Tissue based on the PFT traits.

property get_elemental_masses: dict[str, ndarray[tuple[Any, ...], dtype[floating]]]#

Get the current element masses for the tissue.

Returns:: The element deficit for the specified tissue.

get_relative_carbon_biomass_by_pft() → ndarray[tuple[Any, ...], dtype[floating]][source]#

Get the proportional carbon biomass of each cohort within PFTs for a tissue.

This is used to distribute herbivory - which happens at the PFT level - back down to individual cohorts, assuming that herbivory is distributed between cohorts of the same PFT in proportion to the available biomass.

Parameters:: tissue_type – The type of tissue to retrieve (e.g., ‘foliage’, ‘wood’).
Returns:: An one-dimensional array with length equal to the number of cohorts giving the proportional carbon biomass of that cohort within the PFT.

abstractmethod get_turnover(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the elemental losses to turnover for the tissue type.

This method should return dictionary keyed by elements, including carbon. The values should be an array giving the per stem biomass within each cohort that is lost to turnover given the allocation.

tissue_name: ClassVar[str]#: A tissue name for derived classes.

class virtual_ecosystem.models.plants.biomasses.Biomasses(tissues: list[BiomassTissueABC], community: Community, extra_pft_traits: ExtraTraitsPFT)[source]#

A class holding biomasses for a set of plant cohorts and tissues.

This class holds the current ratios across tissue type for a community object, which in essence is a series of cohorts. It acts in parallel with StemAllometry, a class attribute of Community.

The class is designed to be element-agnostic, so it can be used for any element as required.

Methods:

`append`(other)	Append data from another Biomasses instance representing new cohorts.
`apply_growth`(allocation)	Distribute the carbon allocated to growth and required nutrients to tissues.
`apply_turnover`(allocation)	Apply the effects of turnover on whole stem nutrient balances.
`balance_elements`()	Redistribute elemental mass across tissues and element pool.
`default_init`(community, extra_pft_traits, ...)	Create an instance of StemStoichiometry from the PFT stoichiometry ratios.
`get_tissue`(tissue_type)	Get the tissue model for a specific tissue type.

Attributes:

`array_attrs`	Array attribute names for all biomass tissue and element data.
`community`	The community object that the stoichiometry is associated with.
`element_surpluses`	The surplus of the element per cohort.
`elements`	A list of the elements recorded in each tissue.
`extra_pft_traits`	Additional traits specific to the plant functional types.
`tissue_deficit`	Calculate the total element deficits for each cohort.
`tissue_names`	A list giving the name of each tissue.
`tissues`	Tissues for the associated cohorts.
`total_element_masses`	Calculate the total element mass for each cohort.

append(other: Biomasses)[source]#: Append data from another Biomasses instance representing new cohorts.

apply_growth(allocation: StemAllocation) → None[source]#

Distribute the carbon allocated to growth and required nutrients to tissues.

This method updates the actual biomasses for each tissue type based on the carbon allocation and elements needed for growth at ideal ratios, given that carbon biomass.

The nutrient allocation is debited from the whole stem nutrient balance and subsequent nutrient balancing is responsible for adjusting tissue values to reflect nutrient excesses or deficits at the whole stem level.

Parameters:: allocation – The allocation object containing the growth allocation data.

apply_turnover(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Apply the effects of turnover on whole stem nutrient balances.

This method takes a stem allocation object and returns an array per tissue of the carbon and nutrient biomasses of turnover from each pool.

The calls to the individual BiomassTissueABC.get_turnover methods do not alter the biomasses in the tissue pools:

The carbon biomass turnover explicitly models the maintenance of tissue carbon biomass by replacement - an equal carbon biomass is lost to the environment
Nutrient biomasses are lost to turnover according to the turnover ratios. If the tissues are at their ideal ratio, then the elemental masses will not change. However, if the nutrient inputs within a timestep are not sufficient to maintain the current ratios of replacement tissue, then the tissue elemental masses should decrease. This is handled by recording the lost elemental masses in the stem-wide element surplus pools and balancing the accumulated deficits and gains to those pools at the end of the allocation process.

TODO: This needs to account for herbivory - proportional to herbivory loss?

Returns:: A dictionary by tissue of turnover biomass arrays

array_attrs: ClassVar[tuple[str, ...]] = ('biomass_foliage_carbon_mass', 'biomass_foliage_n_actual_element_mass', 'biomass_foliage_p_actual_element_mass', 'biomass_fruit_carbon_mass', 'biomass_fruit_n_actual_element_mass', 'biomass_fruit_p_actual_element_mass', 'biomass_seed_carbon_mass', 'biomass_seed_n_actual_element_mass', 'biomass_seed_p_actual_element_mass', 'biomass_stem_carbon_mass', 'biomass_stem_n_actual_element_mass', 'biomass_stem_p_actual_element_mass', 'biomass_root_carbon_mass', 'biomass_root_n_actual_element_mass', 'biomass_root_p_actual_element_mass')#: Array attribute names for all biomass tissue and element data.

balance_elements() → None[source]#

Redistribute elemental mass across tissues and element pool.

This method calculates the elemental deficits and surpluses in each tissue and the central pool and then redistributes elemental masses to distribute whole stem deficits and surpluses down to the tissue level.

Typically the central biomass pools will be empty at the end of this process unless elemental surpluses exceed the masses needed to bring all of tissues up to their ideal ratio.

community: Community#: The community object that the stoichiometry is associated with.

classmethod default_init(community: Community, extra_pft_traits: ExtraTraitsPFT, with_elements: list[str], tissues: list[type[BiomassTissueABC]])[source]#

Create an instance of StemStoichiometry from the PFT stoichiometry ratios.

Parameters:

community – The community object that the stoichiometry is associated with.
extra_pft_traits – Additional traits specific to the plant functional type.
with_elements – The name of the elements to be used in the biomass representation.
tissues – A list of tissue models to be used.

Returns:

An instance of StemBiomasses with default tissues for the community.

element_surpluses: dict[str, ndarray[tuple[Any, ...], dtype[floating]]]#: The surplus of the element per cohort.

elements: tuple[str, ...]#: A list of the elements recorded in each tissue.

extra_pft_traits: ExtraTraitsPFT#: Additional traits specific to the plant functional types.

get_tissue(tissue_type: str) → BiomassTissueABC[source]#

Get the tissue model for a specific tissue type.

Parameters:: tissue_type – The type of tissue to retrieve (e.g., ‘foliage’, ‘wood’).
Returns:: The tissue model corresponding to the specified tissue type.

property tissue_deficit: dict[str, ndarray[tuple[Any, ...], dtype[floating]]]#

Calculate the total element deficits for each cohort.

Returns:: The element deficit for all cohorts.

tissue_names: list[str]#: A list giving the name of each tissue.

tissues: list[BiomassTissueABC]#: Tissues for the associated cohorts.

property total_element_masses: dict[str, ndarray[tuple[Any, ...], dtype[floating]]]#

Calculate the total element mass for each cohort.

Returns:: The total element mass for each cohort.

class virtual_ecosystem.models.plants.biomasses.Element(name: str, ideal_ratio: ndarray[tuple[Any, ...], dtype[floating]], actual_element_mass: ndarray[tuple[Any, ...], dtype[floating]], turnover_ratio: ndarray[tuple[Any, ...], dtype[floating]])[source]#

Stochiometric elemental masses for cohorts in a community.

Attributes:

`actual_element_mass`	The actual mass of the element for the tissue type.
`ideal_ratio`	The ideal ratio of the element for the tissue type.
`name`	The element name.
`turnover_ratio`	What to do with this on non-reclaiming tissues.

Methods:

append(other)

Appends new data representing new cohorts onto an element instance.

actual_element_mass: ndarray[tuple[Any, ...], dtype[floating]]#: The actual mass of the element for the tissue type.

append(other: Element) → None[source]#: Appends new data representing new cohorts onto an element instance.

ideal_ratio: ndarray[tuple[Any, ...], dtype[floating]]#: The ideal ratio of the element for the tissue type.

name: str#: The element name.

turnover_ratio: ndarray[tuple[Any, ...], dtype[floating]]#: What to do with this on non-reclaiming tissues.

class virtual_ecosystem.models.plants.biomasses.FoliageBiomass(community: Community, extra_pft_traits: ExtraTraitsPFT, carbon_mass: ndarray[tuple[Any, ...], dtype[floating]], element_masses: dict[str, Element])[source]#

A class to hold foliage stoichiometry data for a set of plant cohorts.

Methods:

`apply_growth`(allocation)	Increase the biomasses of foliage tissue given the allocation model.
`from_pft_default_ratios`(community, ...)	Create a default instance of FoliageBiomass based on the PFT traits.
`get_turnover`(allocation)	Calculate the element mass lost to turnover for foliage tissue.

Attributes:

tissue_name

A tissue name for derived classes.

apply_growth(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Increase the biomasses of foliage tissue given the allocation model.

Returns:: The increases in element quantities needed to support growth at the ideal ratio for the tissue.

carbon_mass: ndarray[tuple[Any, ...], dtype[floating]]#: An 1D array of tissue carbon mass for each stem in cohorts in the community.

community: Community#: The community object that the tissue is associated with.

element_masses: dict[str, Element]#: A dictionary of Elements containing nutrient masses each stem in cohorts in the community.

classmethod from_pft_default_ratios(community: Community, extra_pft_traits: ExtraTraitsPFT, with_elements: list[str])[source]#: Create a default instance of FoliageBiomass based on the PFT traits.

get_turnover(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the element mass lost to turnover for foliage tissue.

Returns:: The element quantity lost to turnover for foliage tissue.

tissue_name: ClassVar[str] = 'foliage'#: A tissue name for derived classes.

class virtual_ecosystem.models.plants.biomasses.FruitBiomass(community: Community, extra_pft_traits: ExtraTraitsPFT, carbon_mass: ndarray[tuple[Any, ...], dtype[floating]], element_masses: dict[str, Element])[source]#

Holds fruit tissue stoichiometry data for a set of plant cohorts.

Methods:

`apply_growth`(allocation)	Increase the biomasses of reproductive tissue given the allocation model.
`from_pft_default_ratios`(community, ...)	Create a default instance of FoliageBiomass based on the PFT traits.
`get_turnover`(allocation)	Calculate the element mass lost to turnover for reproductive tissue.

Attributes:

tissue_name

A tissue name for derived classes.

apply_growth(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Increase the biomasses of reproductive tissue given the allocation model.

Returns:: The increases in element quantities needed to support growth at the ideal ratio for the tissue.

carbon_mass: ndarray[tuple[Any, ...], dtype[floating]]#: An 1D array of tissue carbon mass for each stem in cohorts in the community.

community: Community#: The community object that the tissue is associated with.

element_masses: dict[str, Element]#: A dictionary of Elements containing nutrient masses each stem in cohorts in the community.

classmethod from_pft_default_ratios(community: Community, extra_pft_traits: ExtraTraitsPFT, with_elements: list[str])[source]#: Create a default instance of FoliageBiomass based on the PFT traits.

get_turnover(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the element mass lost to turnover for reproductive tissue.

Returns:: The element quantity lost to turnover for reproductive tissue.

tissue_name: ClassVar[str] = 'fruit'#: A tissue name for derived classes.

class virtual_ecosystem.models.plants.biomasses.ReproductiveBiomass(community: Community, extra_pft_traits: ExtraTraitsPFT, carbon_mass: ndarray[tuple[Any, ...], dtype[floating]], element_masses: dict[str, Element])[source]#

Holds reproductive tissue stoichiometry data for a set of plant cohorts.

Methods:

`apply_growth`(allocation)	Increase the biomasses of reproductive tissue given the allocation model.
`from_pft_default_ratios`(community, ...)	Create a default instance of FoliageBiomass based on the PFT traits.
`get_turnover`(allocation)	Calculate the element mass lost to turnover for reproductive tissue.

Attributes:

tissue_name

A tissue name for derived classes.

apply_growth(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Increase the biomasses of reproductive tissue given the allocation model.

Returns:: The increases in element quantities needed to support growth at the ideal ratio for the tissue.

carbon_mass: ndarray[tuple[Any, ...], dtype[floating]]#: An 1D array of tissue carbon mass for each stem in cohorts in the community.

community: Community#: The community object that the tissue is associated with.

element_masses: dict[str, Element]#: A dictionary of Elements containing nutrient masses each stem in cohorts in the community.

classmethod from_pft_default_ratios(community: Community, extra_pft_traits: ExtraTraitsPFT, with_elements: list[str])[source]#: Create a default instance of FoliageBiomass based on the PFT traits.

get_turnover(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the element mass lost to turnover for reproductive tissue.

Returns:: The element quantity lost to turnover for reproductive tissue.

tissue_name: ClassVar[str] = 'plant_reproductive_tissue'#: A tissue name for derived classes.

class virtual_ecosystem.models.plants.biomasses.RootBiomass(community: Community, extra_pft_traits: ExtraTraitsPFT, carbon_mass: ndarray[tuple[Any, ...], dtype[floating]], element_masses: dict[str, Element])[source]#

A class to hold root stoichiometry data for a set of plant cohorts.

Methods:

`apply_growth`(allocation)	Increase the biomasses of root tissue given the allocation model.
`from_pft_default_ratios`(community, ...)	Create a default instance of FoliageBiomass based on the PFT traits.
`get_turnover`(allocation)	Calculate the element mass lost to turnover for foliage tissue.

Attributes:

tissue_name

A tissue name for derived classes.

apply_growth(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Increase the biomasses of root tissue given the allocation model.

Returns:: The increases in element quantities needed to support growth at the ideal ratio for the tissue.

carbon_mass: ndarray[tuple[Any, ...], dtype[floating]]#: An 1D array of tissue carbon mass for each stem in cohorts in the community.

community: Community#: The community object that the tissue is associated with.

element_masses: dict[str, Element]#: A dictionary of Elements containing nutrient masses each stem in cohorts in the community.

classmethod from_pft_default_ratios(community: Community, extra_pft_traits: ExtraTraitsPFT, with_elements: list[str])[source]#: Create a default instance of FoliageBiomass based on the PFT traits.

get_turnover(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the element mass lost to turnover for foliage tissue.

Returns:: The element quantity lost to turnover for foliage tissue.

tissue_name: ClassVar[str] = 'root'#: A tissue name for derived classes.

class virtual_ecosystem.models.plants.biomasses.SeedBiomass(community: Community, extra_pft_traits: ExtraTraitsPFT, carbon_mass: ndarray[tuple[Any, ...], dtype[floating]], element_masses: dict[str, Element])[source]#

Holds fruit tissue stoichiometry data for a set of plant cohorts.

Methods:

`apply_growth`(allocation)	Increase the biomasses of reproductive tissue given the allocation model.
`from_pft_default_ratios`(community, ...)	Create a default instance of FoliageBiomass based on the PFT traits.
`get_turnover`(allocation)	Calculate the element mass lost to turnover for reproductive tissue.

Attributes:

tissue_name

A tissue name for derived classes.

apply_growth(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Increase the biomasses of reproductive tissue given the allocation model.

Returns:: The increases in element quantities needed to support growth at the ideal ratio for the tissue.

carbon_mass: ndarray[tuple[Any, ...], dtype[floating]]#: An 1D array of tissue carbon mass for each stem in cohorts in the community.

community: Community#: The community object that the tissue is associated with.

element_masses: dict[str, Element]#: A dictionary of Elements containing nutrient masses each stem in cohorts in the community.

classmethod from_pft_default_ratios(community: Community, extra_pft_traits: ExtraTraitsPFT, with_elements: list[str])[source]#: Create a default instance of FoliageBiomass based on the PFT traits.

get_turnover(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the element mass lost to turnover for reproductive tissue.

Returns:: The element quantity lost to turnover for reproductive tissue.

tissue_name: ClassVar[str] = 'seed'#: A tissue name for derived classes.

class virtual_ecosystem.models.plants.biomasses.StemBiomass(community: Community, extra_pft_traits: ExtraTraitsPFT, carbon_mass: ndarray[tuple[Any, ...], dtype[floating]], element_masses: dict[str, Element])[source]#

A class to hold stem stoichiometry data for a set of plant cohorts.

Methods:

`apply_growth`(allocation)	Increase the biomasses of woody tissue given the allocation model.
`from_pft_default_ratios`(community, ...)	Create a default instance of WoodBiomass based on the PFT traits.
`get_turnover`(allocation)	Calculate the element mass lost to turnover for foliage tissue.

Attributes:

tissue_name

A tissue name for derived classes.

apply_growth(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Increase the biomasses of woody tissue given the allocation model.

Returns:: The increases in element quantities needed to support growth at the ideal ratio for the tissue.

carbon_mass: ndarray[tuple[Any, ...], dtype[floating]]#: An 1D array of tissue carbon mass for each stem in cohorts in the community.

community: Community#: The community object that the tissue is associated with.

element_masses: dict[str, Element]#: A dictionary of Elements containing nutrient masses each stem in cohorts in the community.

classmethod from_pft_default_ratios(community: Community, extra_pft_traits: ExtraTraitsPFT, with_elements: list[str])[source]#: Create a default instance of WoodBiomass based on the PFT traits.

get_turnover(allocation: StemAllocation) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the element mass lost to turnover for foliage tissue.

Returns:: The element quantity lost to turnover for foliage tissue.

tissue_name: ClassVar[str] = 'stem'#: A tissue name for derived classes.

The plants `subcanopy` module#

The subcanopy module provides a representation of subcanopy biomass as two pools. The first is a pool of subcanopy vegetation, implemented as layer of pure leaf tissue in the surface layer of the model vertical structure. The second is a pool of subcanopy seedbank biomass.

Both pools use a simplified stiochiometric system: this is defined independently of the virtual_ecosystem.models.plants.biomasses module, as that class explicitly handles communities of cohorts with multiple tissue types. The subcanopy has much simpler structure with two stoichiometric masses per grid cell and so the dynamics are more easily handled by a separate implementation.

The module implements the following classes:

The Nutrient class provides a representation of nutrient masses per grid cell.
The SubcanopyBiomass class then tracks the carbon mass and an associated set of nutrient masses for a given pool.
The Subcanopy then maintains subcanopy biomass pools for the vegetation and seedbank and provides methods to update the light gathering and ecological dynamics of the subcanopy at each update step.

TODO - lot more overlap between the SubcanopyBiomass and Biomasses classes than there: used to be with the old stoichiometry module - can we replace the code here with a new tissue? The problem is the lack of a community object to initialise.

Classes:

`Nutrient`(name, ideal_ratio, masses)	Dataclass for subcanopy elemental nutrient details.
`Subcanopy`(data, pyrealm_core_constants, ...)	Representation of the subcanopy biomasses.
`SubcanopyBiomass`(carbon_mass, nutrients)	A stochiometric biomass class for Subcanopy vegetation.

class virtual_ecosystem.models.plants.subcanopy.Nutrient(name: str, ideal_ratio: float, masses: ndarray[tuple[Any, ...], dtype[floating]])[source]#

Dataclass for subcanopy elemental nutrient details.

Parameters:

name – The elemental nutrient name
ideal_ratio – The ideal ratio for subcanopy tissue of the nutrient
values – An array of per-grid-cell values

Methods:

from_constants(tissue_name, element, ...)

Factory method for Nutrient instances from the ideal ratio in constants.

classmethod from_constants(tissue_name: str, element: str, constants: PlantsConstants, masses: ndarray[tuple[Any, ...], dtype[floating]]) → Nutrient[source]#

Factory method for Nutrient instances from the ideal ratio in constants.

Parameters:

tissue_name – The tissue name used in the plant constants
element – The element name
constants – A PlantConstants instance
masses – The carbon biomasses of cells for the tissue.

class virtual_ecosystem.models.plants.subcanopy.Subcanopy(data: Data, pyrealm_core_constants: CoreConst, model_constants: PlantsConstants, layer_index: int, model_timing: ModelTiming, data_object_template: DataArray)[source]#

Representation of the subcanopy biomasses.

This class maintains the representation of the subcanopy vegetation across grid cells within the Plants Model. The class maintains two biomass pools within each cell, the subcanopy vegetation and the seedbank for that vegetation, and tracks the carbon, nitrogen and phosphorous masses present in each pool.

The class provides methods:

to calculate the leaf area index and fAPAR associated with the with the subcanopy, and
to calculate the dynamics of the subcanopy vegetation at each time step.

Parameters:

data – The model Data instance
pyrealm_core_constants – The PModel core constants for the simulation.
model_constants – The PlantModel constants for the simulation
layer_index – The layer index of the surface layer in the vertical layer axis.
model_timing – The core ModelTiming instance for the simulation.
data_object_template – A template for creating CNP element arrays.

Methods:

`calculate_dynamics`(lue, iwue, swd)	Estimate the dynamics of subcanopy vegetation.
`set_light_capture`(below_canopy_light_fraction)	Calculate the leaf area index and absorption of subcanopy vegetation.

Attributes:

elements

The set of nutrient elements currently tracked within the simulation.

calculate_dynamics(lue: ndarray[tuple[Any, ...], dtype[floating]], iwue: ndarray[tuple[Any, ...], dtype[floating]], swd: ndarray[tuple[Any, ...], dtype[floating]]) → None[source]#

Estimate the dynamics of subcanopy vegetation.

This method models the biomass dynamics with the subcanopy vegetation and subcanopy seedbank pools during a model update.

A fraction of the biomass in each pool is allocated to turnover, and passed into litter pools. The stoichiometric ratios of turnover biomass are identical to the pool biomasses.
The predicted light use and intrinsic water use efficiencies (LUE and iWUE) in the surface layer are taken from the P Model and used to estimate gross primary productivity (GPP) and transpiration. GPP is reduced by respiration and yield to give net primary productivity NPP, which is added as new carbon biomass to the subcanopy vegetation. The soil dissolved nitrate, ammonium and phosphorous concentrations are then used to calculate the nutrient uptake associated with the transpiration volume and these are added to the subcanopy vegetation pool.
A fraction of the subcanopy vegetation biomass is then removed to represent reproductive output to the seedbank pool. The stochiometric ratio of the reproductive biomass is initially identical to the vegetation biomass but any excess nitrogen and phosphorous above the configured ideal ratios is also transferred to the seedbank to represent seed provisioning.
Lastly, new vegetative biomass is added from sprouting from the seedbank. The initial amount of sprouting biomass is set by the subcanopy_sprout_rate constant but the contribution to subcanopy biomass is reduced using the subcanopy_sprout_yield constant. The remainder of the sprouting biomass is allocated to litter.

Todo

Timing of turnover The timing of turnover is going to affect growth patterns - it is currently placed right at the start of the dynamics, but it might be better to calculate an average biomass to spread turnover through the update period.

elements: tuple[str, ...] = ('n', 'p')#: The set of nutrient elements currently tracked within the simulation.

set_light_capture(below_canopy_light_fraction: ndarray[tuple[Any, ...], dtype[_ScalarT]]) → None[source]#

Calculate the leaf area index and absorption of subcanopy vegetation.

The subcanopy vegetation is represented as pure leaf biomass (\(M_{SC}\), kg m-2), with an associated extinction coefficient (\(k\)) and specific leaf area (\(\sigma\), kg m-2) set in the model constants. These can be used to calculate the leaf area index (\(L\)) and hence the absorption fraction (\(f_{a}\)) of the subcanopy vegetation layer via the Beer-Lambert law:

\[ \begin{align*} L &= M_{SC} \sigma \\ f_a = e^{-kL} \end{align*} \]

class virtual_ecosystem.models.plants.subcanopy.SubcanopyBiomass(carbon_mass: ndarray[tuple[Any, ...], dtype[floating]], nutrients: SubcanopyNutrients)[source]#

A stochiometric biomass class for Subcanopy vegetation.

The class tracks the carbon and elemental nutrient masses across an array of grid cells and provides properties to report the nutrient ratios. It also provides methods to add and remove masses from the class and to remove excess nutrients above ideal ratios.

Methods:

`add_mass`(source)	Add biomass to a SubcanopyBiomass instance.
`c_x_ratio`(nutrient)	Return the current CN ratio for the biomass.
`from_constants`(tissue_name, elements, ...)	Factory method to generate a SubcanopyBiomass object from constants.
`get_excess_nutrients`()	Extract excess nutrients.
`remove_mass_fraction`(mass_fraction)	Remove a proportion of the biomass.

add_mass(source: SubcanopyBiomass | SubcanopyNutrients)[source]#

Add biomass to a SubcanopyBiomass instance.

The method adds carbon and nutrient biomasses (source is of type SubcanopyBiomass) or just nutrient biomasses (source is of type SubcanopyNutrients) to the calling instance.

Parameters:

source – The source SubcanopyBiomass or SubcanopyNutrients
instance.

c_x_ratio(nutrient: str) → ndarray[tuple[Any, ...], dtype[floating]][source]#: Return the current CN ratio for the biomass.

classmethod from_constants(tissue_name: str, elements: tuple[str, ...], constants: PlantsConstants, masses: ndarray[tuple[Any, ...], dtype[floating]]) → SubcanopyBiomass[source]#

Factory method to generate a SubcanopyBiomass object from constants.

The returned instance uses the provided carbon masses and initialises the named element masses at the ideal ratios set in the constants.

get_excess_nutrients() → SubcanopyNutrients[source]#

Extract excess nutrients.

This method calculates the excess nitrogen and phosphorous biomass in a SubcanopyBiomass instance, given the provided ideal ratios. The method returns a SubcanopyNutrients instance containing excess nutrient masses: these will be be zero where the source biomass in a cell is at or below the ideal ratio.

remove_mass_fraction(mass_fraction: float | ndarray[tuple[Any, ...], dtype[floating]]) → SubcanopyBiomass[source]#

Remove a proportion of the biomass.

This function returns a new SubcanopyBiomass object containing the requested fraction of the carbon biomass. The removed carbon biomass is removed from the parent instance. The nitrogen and phosphorous masses are split using the same fraction to maintain the same CN and CP ratios.

Parameters:: mass_fraction – The proportion of mass to remove from each cell in the instance.

The plant `exporter` module#

The exporter module provides the CommunityDataExporter, which is used to control the output of plant community data at each time step. An instance of the class is required by the PlantsModel, which calls the dump() method within the setup and update steps to export data continuously during the model run.

The exporter can be configured to write three different levels of data: cohort level data and canopy structure data at both the community and individual stem levels. The data being exported is best structured as data frames and is highly ragged across cells, so is less well suited for export through the central data object.

Classes:

CommunityDataExporter(output_directory[, ...])

The CommunityDataExporter class.

class virtual_ecosystem.models.plants.exporter.CommunityDataExporter(output_directory: Path, required_data: set[str] = set(), cohort_attributes: set[str] = set(), community_canopy_attributes: set[str] = set(), stem_canopy_attributes: set[str] = set(), float_format: str = '%0.5f')[source]#

The CommunityDataExporter class.

The class is used to export detailed plant community data from inside a PlantsModel instance to CSV files. The community data is split across three output files:

cohort data: details about the stems in each cohort, including the stem allometry and the GPP allocation of the stem. The stem GPP allocation is not defined during the model setup, so these attributes are set to np.nan for the initial output.
community canopy data: community wide data on the canopy structure, such as the heights of the canopy layers and the light transmission profile.
stem canopy data: details of contribution in leaf area and fAPAR from each stem to the community canopy model.

The data are written to standard file names in the provided output directory, which will typically be the output directory used by the Virtual Ecosystem model run. The required_data attribute is used to set which data to export by providing a set of values from: cohorts, community_canopy and stem_canopy.

In addition, the attribute arguments can be used to specify a subset of data attributes to be exported. If an empty attribute set is provided (which is the default) then the exporter will write all attributes, otherwise the exported data will be reduced to just the named attributes.

Parameters:

output_directory – The output directory for the files
required_data – A set of the required data outputs.
cohort_attributes – An optional subset of cohort attributes to export
community_canopy_attributes – An optional subset of community canopy attributes to export
stem_canopy_attributes – An optional subset of stem canopy attributes to export
float_format – A float format string used when writing data.

Attributes:

`available_attributes`	Class variable of the available attributes that can be exported for each export option.
`cohort_attributes`	A subset of cohort attribute names to export.
`community_canopy_attributes`	A subset of community canopy attribute names to export.
`float_format`	The float format for data export.
`output_directory`	The directory in which to save plant community data.
`required_data`	The set of plant community data types to be exported.
`stem_canopy_attributes`	A subset of community canopy attribute names to export.

Methods:

`dump`(communities, biomasses, canopies, ...)	Export plant community data to file.
`from_config`(output_directory, config)	Factory class to create a CommunityDataExporter from configuration data.

available_attributes: ClassVar[dict[str, set[str]]] = {'cohort_attributes': {'biomass_foliage_carbon_mass', 'biomass_foliage_n_actual_element_mass', 'biomass_foliage_p_actual_element_mass', 'biomass_fruit_carbon_mass', 'biomass_fruit_n_actual_element_mass', 'biomass_fruit_p_actual_element_mass', 'biomass_root_carbon_mass', 'biomass_root_n_actual_element_mass', 'biomass_root_p_actual_element_mass', 'biomass_seed_carbon_mass', 'biomass_seed_n_actual_element_mass', 'biomass_seed_p_actual_element_mass', 'biomass_stem_carbon_mass', 'biomass_stem_n_actual_element_mass', 'biomass_stem_p_actual_element_mass', 'cell_id', 'cohort_id', 'crown_area', 'crown_fraction', 'crown_r0', 'crown_z_max', 'dbh', 'dbh_values', 'delta_dbh', 'delta_foliage_mass', 'delta_stem_mass', 'fine_root_respiration', 'fine_root_turnover', 'foliage_mass', 'foliage_turnover', 'foliar_respiration', 'n_individuals', 'npp', 'pft_names', 'reproductive_tissue_mass', 'reproductive_tissue_respiration', 'reproductive_tissue_turnover', 'sapwood_mass', 'sapwood_respiration', 'stem_height', 'stem_mass', 'time', 'whole_crown_gpp'}, 'community_canopy_attributes': {'average_layer_absorption', 'average_layer_fapar', 'average_layer_lai', 'canopy_layer_index', 'cell_id', 'heights', 'time', 'transmission_profile'}, 'stem_canopy_attributes': {'canopy_layer_index', 'cell_id', 'cohort_id', 'fapar', 'stem_leaf_area', 'time'}}#: Class variable of the available attributes that can be exported for each export option.

cohort_attributes: set[str]#: A subset of cohort attribute names to export.

community_canopy_attributes: set[str]#: A subset of community canopy attribute names to export.

dump(communities: PlantCommunities, biomasses: dict[int, Biomasses] | None, canopies: dict[int, Canopy], stem_allocations: dict[int, StemAllocation], time: datetime64, time_index: int) → None[source]#

Export plant community data to file.

The method accepts the main community components of the PlantsModel as arguments and compiles and writes the output data requested in the instance setup to file.

Parameters:

communities – A PlantCommunities instance.
biomasses – A dictionary of biomass data keyed by cell id.
canopies – A dictionary of Canopy instances, keyed by cell id.
stem_allocations – A dictionary of StemAllocations, also keyed by cell id
time – A datetime to be used as a timestamp in the output files.
time_index – The index of the datatime within the model updates.

float_format#: The float format for data export.

classmethod from_config(output_directory: Path, config: PlantsExportConfig) → CommunityDataExporter[source]#

Factory class to create a CommunityDataExporter from configuration data.

See the documentation of PlantsExportConfig for details of the configuration settings for this method.

Parameters:

output_directory – The path to the output directory for the files
config – An instance of PlantsExportConfig

output_directory: Path#: The directory in which to save plant community data.

required_data: set[str]#: The set of plant community data types to be exported.

stem_canopy_attributes: set[str]#: A subset of community canopy attribute names to export.

Plant structures for the plants module#

The plant functional_types module#

The plants communities module#

The plants canopy module#

The plants biomasses module#

The plants subcanopy module#

The plant exporter module#

Plant structures for the `plants` module#

The plant `functional_types` module#

The plants `communities` module#

The plants `canopy` module#

The plants `biomasses` module#

The plants `subcanopy` module#

The plant `exporter` module#