API documentation for the inputs module#
The models.litter.inputs module handles the partitioning of plant matter into the
various pools of the litter model. This plant matter comes from both natural tissue
death as well as from mechanical inefficiencies in herbivory.
Classes:
|
Dataclass containing the chemistry for the input to each litter pool. |
|
The full set input flows to the litter model. |
Functions:
|
Calculate the chemistries of the input to each litter pool. |
Calculate the concentration of lignin for each plant biomass to litter flow. |
|
Calculate the nutrient mass for each plant biomass to litter flow. |
|
Calculate the proportion of each input type that flows to the metabolic pool. |
|
|
Calculate the split of nutrients between metabolic and structural litter pools. |
|
Combine the plant death and herbivory inputs into a single total input. |
Helper function to convert input masses to rates per area. |
|
Function to find the split of input nutrients between litter pools. |
|
Function to partition input biomass between the various litter pools. |
|
Calculate the split of input biomass between metabolic and structural pools. |
- class virtual_ecosystem.models.litter.inputs.InputChemistries(above_metabolic_nitrogen: DataArray, above_structural_nitrogen: DataArray, woody_nitrogen: DataArray, below_metabolic_nitrogen: DataArray, below_structural_nitrogen: DataArray, above_metabolic_phosphorus: DataArray, above_structural_phosphorus: DataArray, woody_phosphorus: DataArray, below_metabolic_phosphorus: DataArray, below_structural_phosphorus: DataArray, above_structural_lignin: DataArray, woody_lignin: DataArray, below_structural_lignin: DataArray)[source]#
Dataclass containing the chemistry for the input to each litter pool.
Attributes:
Nitrogen input rate to the aboveground metabolic pool [kg{N} m^-2 day^-1]
Phosphorus input rate to the aboveground metabolic pool [kg{P} m^-2 day^-1]
Lignin proportion of input to the aboveground structural pool.
Nitrogen input rate to the aboveground structural pool [kg{N} m^-2 day^-1]
Phosphorus input rate to the aboveground structural pool [kg{P} m^-2 day^-1]
Nitrogen input rate to the belowground metabolic pool [kg{N} m^-2 day^-1]
Phosphorus input rate to the belowground metabolic pool [kg{P} m^-2 day^-1]
Lignin proportion of input to the belowground structural pool.
Nitrogen input rate to the belowground structural pool [kg{N} m^-2 day^-1]
Phosphorus input rate to the belowground structural pool [kg{P} m^-2 day^-1]
Lignin proportion of input to the woody pool [kg{lignin C} kg{C}^-1]
Nitrogen input rate to the woody pool [kg{N} m^-2 day^-1]
Phosphorus input rate to the woody pool [kg{P} m^-2 day^-1]
- above_metabolic_nitrogen: DataArray#
Nitrogen input rate to the aboveground metabolic pool [kg{N} m^-2 day^-1]
- above_metabolic_phosphorus: DataArray#
Phosphorus input rate to the aboveground metabolic pool [kg{P} m^-2 day^-1]
- above_structural_lignin: DataArray#
Lignin proportion of input to the aboveground structural pool.
Units of [kg{lignin C} kg{C}^-1]
- above_structural_nitrogen: DataArray#
Nitrogen input rate to the aboveground structural pool [kg{N} m^-2 day^-1]
- above_structural_phosphorus: DataArray#
Phosphorus input rate to the aboveground structural pool [kg{P} m^-2 day^-1]
- below_metabolic_nitrogen: DataArray#
Nitrogen input rate to the belowground metabolic pool [kg{N} m^-2 day^-1]
- below_metabolic_phosphorus: DataArray#
Phosphorus input rate to the belowground metabolic pool [kg{P} m^-2 day^-1]
- below_structural_lignin: DataArray#
Lignin proportion of input to the belowground structural pool.
Units of [kg{lignin C} kg{C}^-1]
- below_structural_nitrogen: DataArray#
Nitrogen input rate to the belowground structural pool [kg{N} m^-2 day^-1]
- class virtual_ecosystem.models.litter.inputs.LitterInputs(leaf_mass: DataArray, root_mass: DataArray, deadwood_mass: DataArray, subcanopy_mass: DataArray, herbivore_waste_above_mass: DataArray, herbivore_waste_below_mass: DataArray, leaf_lignin: DataArray, root_lignin: DataArray, stem_lignin: DataArray, subcanopy_lignin: DataArray, herbivore_waste_above_lignin: DataArray, herbivore_waste_below_lignin: DataArray, leaf_meta_split: DataArray, root_meta_split: DataArray, subcanopy_meta_split: DataArray, herbivore_waste_above_meta_split: DataArray, herbivore_waste_below_meta_split: DataArray, woody: DataArray, above_metabolic: DataArray, above_structural: DataArray, below_metabolic: DataArray, below_structural: DataArray)[source]#
The full set input flows to the litter model.
Attributes:
Total input rate to the above ground metabolic litter pool [kg{C} m^-2 day^-1]
Total input rate to the above ground structural litter pool [kg{C} m^-2 day^-1]
Total input rate to the below ground metabolic litter pool [kg{C} m^-2 day^-1]
Total input rate to the below ground structural litter pool [kg{C} m^-2 day^-1]
Total deadwood input rate to litter of each nutrient [kg m^-2 day^-1]
Lignin proportion of above-ground herbivore waste input [kg{lignin C} kg{C}^-1]
Total input rate due to mechanical inefficiency of above-ground herbivores [kg m^-2 day^-1]
Fraction of above-ground herbivore waste input that goes to metabolic litter [unitless]
Lignin proportion of below-ground herbivore waste input [kg{lignin C} kg{C}^-1]
Total input rate due to mechanical inefficiency of below-ground herbivores [kg m^-2 day^-1]
Fraction of below-ground herbivore waste input that goes to metabolic litter [unitless]
Lignin proportion of leaf input [kg{lignin C} kg{C}^-1]
Total leaf input rate to litter of each nutrient [kg m^-2 day^-1]
Fraction of leaf input that goes to metabolic litter [unitless]
Lignin proportion of root input [kg{lignin C} kg{C}^-1]
Total root input rate to litter of each nutrient [kg m^-2 day^-1]
Fraction of leaf input that goes to metabolic litter [unitless]
Lignin proportion of deadwood input [kg{lignin C} kg{C}^-1]
Lignin proportion of sub-canopy vegetation input [kg{lignin C} kg{C}^-1]
Total input rate from sub-canopy vegetation (per nutrient) [kg m^-2 day^-1]
Fraction of subcanopy vegetation input that goes to metabolic litter [unitless]
Total input rate to the woody litter pool [kg{C} m^-2 day^-1]
Methods:
create_from_data(data, constants, ...)Factory method to populate the various litter input flows.
- above_metabolic: DataArray#
Total input rate to the above ground metabolic litter pool [kg{C} m^-2 day^-1]
- above_structural: DataArray#
Total input rate to the above ground structural litter pool [kg{C} m^-2 day^-1]
- below_metabolic: DataArray#
Total input rate to the below ground metabolic litter pool [kg{C} m^-2 day^-1]
- below_structural: DataArray#
Total input rate to the below ground structural litter pool [kg{C} m^-2 day^-1]
- classmethod create_from_data(data: Data, constants: LitterConstants, update_interval: float) LitterInputs[source]#
Factory method to populate the various litter input flows.
This method first combines the two different input streams for dead plant matter (plant tissue death and herbivory waste) to find the total input of each plant biomass type. This is then used to find the split between metabolic and structural litter pools for each plant matter class (expect deadwood). Finally, the total rate of flow to each litter pool is calculated.
- Parameters:
data – The Data object to be used to populate the litter input details.
constants – Set of constants for the litter model.
update_interval – The length of time over which the input is being added over [days]
- Returns:
An LitterInputs instance containing the total input of each plant biomass type, the proportion of the input that goes to the relevant metabolic pool for each input type (expect deadwood) and the total input into each litter pool.
- herbivore_waste_above_lignin: DataArray#
Lignin proportion of above-ground herbivore waste input [kg{lignin C} kg{C}^-1]
- herbivore_waste_above_mass: DataArray#
Total input rate due to mechanical inefficiency of above-ground herbivores [kg m^-2 day^-1]
- herbivore_waste_above_meta_split: DataArray#
Fraction of above-ground herbivore waste input that goes to metabolic litter [unitless]
- herbivore_waste_below_lignin: DataArray#
Lignin proportion of below-ground herbivore waste input [kg{lignin C} kg{C}^-1]
- herbivore_waste_below_mass: DataArray#
Total input rate due to mechanical inefficiency of below-ground herbivores [kg m^-2 day^-1]
- herbivore_waste_below_meta_split: DataArray#
Fraction of below-ground herbivore waste input that goes to metabolic litter [unitless]
- subcanopy_lignin: DataArray#
Lignin proportion of sub-canopy vegetation input [kg{lignin C} kg{C}^-1]
- subcanopy_mass: DataArray#
Total input rate from sub-canopy vegetation (per nutrient) [kg m^-2 day^-1]
- virtual_ecosystem.models.litter.inputs.calculate_input_chemistries(litter_inputs: LitterInputs, meta_to_struct_nitrogen_ratio: float, meta_to_struct_phosphorus_ratio: float) InputChemistries[source]#
Calculate the chemistries of the input to each litter pool.
- Parameters:
litter_inputs – An LitterInputs instance containing the total input of each plant biomass type, the proportion of the input that goes to the relevant metabolic pool for each input type (expect deadwood) and the total input into each litter pool.
meta_to_struct_nitrogen_ratio – Ratio of nitrogen concentrations for inputs to the metabolic and structural litter pools [unitless]
meta_to_struct_phosphorus_ratio – Ratio of phosphorus concentrations for inputs to the metabolic and structural litter pools [unitless]
- Returns:
An InputChemistries instance containing the input chemistry for each litter pool
- virtual_ecosystem.models.litter.inputs.calculate_litter_input_lignin_concentrations(litter_inputs: LitterInputs) dict[str, DataArray][source]#
Calculate the concentration of lignin for each plant biomass to litter flow.
By definition the metabolic litter pools do not contain lignin, so all input lignin flows to the structural and woody pools. As the input biomass gets split between pools, the lignin concentration of the input to the structural pools will be higher than it was in the input biomass.
For the woody litter there’s no structural-metabolic split so the lignin concentration of the litter input is the same as that of the dead wood production. For the structural litter pools, the total lignin content of the input is found (by summing the contributions from the relevant input pathways), and then converted back into a proportion by dividing by the total input mass.
- Parameters:
litter_inputs – An LitterInputs instance containing the total input of each plant biomass type, the proportion of the input that goes to the relevant metabolic pool for each input type (expect deadwood) and the total input into each litter pool.
- Returns:
Dictionary containing the lignin concentration of the input to each of the three lignin containing litter pools (woody, above and below ground structural) [kg{lignin C} kg{C}^-1]
- virtual_ecosystem.models.litter.inputs.calculate_litter_input_nutrient_masses(litter_inputs: LitterInputs, meta_to_struct_nutrient_ratio: float, nutrient: str) dict[str, DataArray][source]#
Calculate the nutrient mass for each plant biomass to litter flow.
Input to the woody litter pool just matches the nutrient masses of the deadwood input. For the other pools, the split of nutrient flows from root/leaf/subcanopy turnover and herbivore waste between the metabolic and structural pools is calculated.
- Parameters:
litter_inputs – An LitterInputs instance containing the total input of each plant biomass type, the proportion of the input that goes to the relevant metabolic pool for each input type (expect deadwood) and the total input into each litter pool.
meta_to_struct_nutrient_ratio – Ratio of the nutrient concentrations (relative to carbon mass) for the inputs to the metabolic and structural litter pools [unitless]
nutrient – Nutrient to calculate flows for (options are nitrogen and phosphorus)
- Returns:
Dictionary containing input rates of the nutrients (nitrogen or phosphorus) into each of the pools [kg{nutrient} m^-2 day^-1]
- virtual_ecosystem.models.litter.inputs.calculate_metabolic_proportions_of_input(total_input: dict[str, DataArray], constants: LitterConstants) dict[str, DataArray][source]#
Calculate the proportion of each input type that flows to the metabolic pool.
This function is used for roots, leaves, subcanopy biomass, and above- and below-ground herbivory waste, but not for deadwood because all deadwood goes into a single woody litter pool.
- Parameters:
total_input – The total amount of carbon in each input pools [kg{C} m^-3], as well as the nitrogen content [kg{N} m^-3], phosphorus content [kg{P} m^-3] and lignin proportions [kg{lignin C} kg{C}^-1] of each of these pools.
constants – Set of constants for the litter model.
- Returns:
A dictionary containing the proportion of the input that goes to the relevant metabolic pool. This is for five input types: leaves, roots, sub-canopy biomass, above-ground herbivore waste and below-ground herbivore waste [unitless]
- virtual_ecosystem.models.litter.inputs.calculate_nutrient_split(carbon_input_meta: DataArray, carbon_input_struct: DataArray, input_nutrient_rate: DataArray, meta_to_struct_nutrient_ratio: float) tuple[DataArray, DataArray][source]#
Calculate the split of nutrients between metabolic and structural litter pools.
The calculation of this split derives from Kirschbaum and Paul (2002), and assumes that the nutrient concentrations of inputs to the structural and metabolic litter pools are in a fixed proportion.
- Parameters:
carbon_input_meta – Rate of carbon input to the metabolic pool [kg{C} m^-2 day^-1]
carbon_input_struct – Rate of carbon input to the structural pool [kg{C} m^-2 day^-1]
input_nutrient_rate – Total rate of nutrient input [kg{nutrient} m^-2 day^-1]
meta_to_struct_nutrient_ratio – Ratio of the nutrient concentrations (relative to carbon mass) for the inputs to the metabolic and structural litter pools [unitless]
- Returns:
A tuple containing the rate of nutrient flow to the metabolic and structural litter pools, respectively [kg{nutrient} m^-2 day^-1]
- virtual_ecosystem.models.litter.inputs.combine_input_sources(data: Data, update_interval: float) dict[str, DataArray][source]#
Combine the plant death and herbivory inputs into a single total input.
The total input for each plant matter type is returned, the chemical concentration of each of these new pools is also calculated.
This function also converts the plant inputs from total inputs (over the model time step), to the (per area) input rates needed by the litter model.
- Parameters:
data – The Data object to be used to populate the litter input streams.
update_interval – The length of time over which the input is being added over [days]
- Returns:
A dictionary containing the combined rate at which each input pools is added to for each nutrient [kg{nutrient} m^-2 day^-1] and lignin proportions [kg{lignin C} kg{C}^-1] of each of these pools.
- virtual_ecosystem.models.litter.inputs.convert_to_input_masses_to_rates_per_area(input_mass: DataArray, cell_area: float, update_interval: float) DataArray[source]#
Helper function to convert input masses to rates per area.
The plant model stores plant biomass in units of mass (kg) per grid square, whereas in the litter model we need everything as input rates per area.
- Parameters:
input_mass – The mass of the input [kg]
cell_area – The size of the grid cell [m^2]
update_interval – The length of time over which the input is being added over [days]
- Returns:
The input as a per area input rate [kg m^-2 day^-1]
- virtual_ecosystem.models.litter.inputs.find_nutrient_split_between_litter_pools(input_carbon_rate: DataArray, input_nutrient_rate: DataArray, metabolic_split: DataArray, meta_to_struct_nutrient_ratio: float) tuple[DataArray, DataArray][source]#
Function to find the split of input nutrients between litter pools.
Following Kirschbaum and Paul (2002), we assume that the nutrient concentrations of inputs to the structural and metabolic litter pools are in a fixed proportion. This ratio can vary between nutrients but doesn’t vary between above and below ground pools. This simplifying assumption allows us to capture litter mineralisation dynamics for specific elements without having to build (and parametrise) a model where every nutrient effects decay rate of every pool.
This function explicitly handle the edge case where there is no carbon flow to structural litter. How this is done depends on whether there is a carbon flow to metabolic litter. If there is, then all nutrient flow goes to the metabolic litter. If there isn’t, then there is no nutrient flow to either pool.
- Parameters:
input_carbon_rate – Rate of carbon input [kg{C} m^-2 day^-1]
input_nutrient_rate – Rate of nutrient input [kg{nutrient} m^-2 day^-1]
metabolic_split – Proportion of organic matter input that flows to the metabolic litter pool [unitless]
meta_to_struct_nutrient_ratio – Ratio of the nutrient concentrations (relative to carbon mass) for the inputs to the metabolic and structural litter pools [unitless]
- Returns:
A tuple containing the nutrient input rate to the metabolic and structural litter pools [kg{nutrient} m^-2 day^-1], in that order.
- virtual_ecosystem.models.litter.inputs.partion_plant_inputs_between_pools(total_input: dict[str, DataArray], metabolic_splits: dict[str, DataArray]) dict[str, DataArray][source]#
Function to partition input biomass between the various litter pools.
All deadwood is added to the woody litter pool. Leaf biomass is split between the above ground metabolic and structural pools based on lignin concentration and carbon nitrogen ratios. Root biomass is split between the below ground metabolic and structural pools based on lignin concentration and carbon nitrogen ratios. Sub-canopy biomass is considered to not be woody, so is treated the same as (canopy) leaf biomass (i.e. split between the above ground metabolic and structural pools). Herbivore waste is split between the metabolic and structural litter pools of the strata the waste belongs to.
- Parameters:
total_input – The the total pool size for each input pools for each nutrient [kg{nutrient} m^-3], as lignin proportions [kg{lignin C} kg{C}^-1] of each of these pools.
metabolic_splits – Dictionary containing the proportion of each input that goes to the relevant metabolic pool. This is for five input types: leaves, roots, subcanopy biomass, above-ground herbivore waste and below-ground herbivore waste [unitless]
- Returns:
A dictionary containing the rate of biomass flow into each of the five litter pools (woody, above ground metabolic, above ground structural, below ground metabolic and below ground structural) [kg{C} m^-2 day^-1]
- virtual_ecosystem.models.litter.inputs.split_pool_into_metabolic_and_structural_litter(input_masses: DataArray, lignin_proportion: DataArray, max_metabolic_fraction: float, split_sensitivity_nitrogen: float, split_sensitivity_phosphorus: float)[source]#
Calculate the split of input biomass between metabolic and structural pools.
This division depends on the lignin, nitrogen and phosphorus contents of the input biomass, the functional form is taken from Parton et al. (1988).
- Parameters:
input_masses – Mass of each nutrient in the input biomass [kg{C} m^-2]
lignin_proportion – Proportion of input biomass carbon that is lignin [kg{lignin C} kg{C}^-1]
max_metabolic_fraction – Fraction of pool that becomes metabolic litter for the easiest to breakdown case, i.e. no lignin, ample nitrogen [unitless]
split_sensitivity_nitrogen – Sets how rapidly the split changes in response to changing lignin and nitrogen contents [unitless]
split_sensitivity_phosphorus – Sets how rapidly the split changes in response to changing lignin and phosphorus contents [unitless]
- Raises:
ValueError – If any values of lignin proportion are not between zero and one (which breaks the logic of this function)
- Returns:
The fraction of the biomass that goes to the metabolic pool [unitless]