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:
|
Average carbon to nutrient ratios weighted by their carbon content. |
|
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. |
|
Merge the lignin proportions of two input sources to the same litter pool. |
|
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, leaf_lignin: DataArray, root_lignin: DataArray, stem_lignin: DataArray, leaves_meta_split: DataArray, roots_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 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]
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.
- virtual_ecosystem.models.litter.inputs.average_nutrient_ratios(mass_1: ndarray[tuple[Any, ...], dtype[floating]], mass_2: ndarray[tuple[Any, ...], dtype[floating]], nutrient_ratio_1: ndarray[tuple[Any, ...], dtype[floating]], nutrient_ratio_2: ndarray[tuple[Any, ...], dtype[floating]])[source]#
Average carbon to nutrient ratios weighted by their carbon content.
- Parameters:
mass_1 – Total carbon mass of the first pool/input stream [kg{C} m^-2 or kg{C} m^-2]
mass_2 – Total carbon mass of the second pool/input stream [kg{C} m^-2 or kg{C} m^-2]
nutrient_ratio_1 – Carbon to nutrient ratio of the first pool/input stream [unitless]
nutrient_ratio_2 – Carbon to nutrient ratio of the second pool/input stream [unitless]
- Returns:
The nutrient ratio of the new combined pool/input stream [unitless]
- 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 below ground structural litter, the total lignin content of root input must be found, this is then converted back into a concentration relative to the input into the below structural litter pool. For the above ground structural litter pool, the same approach is taken using leaf lignin.
- 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 turnover 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 and reproductive tissue, but not deadwood because everything goes into a single woody litter pool. It is not used for animal inputs either as they all flow into just the metabolic 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 three input types: leaves, reproductive tissues and roots [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 (leaves, roots, deadwood) 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 [kg{C} m^-2 day^-1], as well as the carbon to nitrogen ratios [unitless], carbon to phosphorus ratios [unitless] 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.merge_input_lignin_proportions(turnover_mass: DataArray, herbivory_waste_mass: DataArray, total_mass: DataArray, turnover_lignin_proportion: DataArray, herbivory_waste_lignin_proportion: DataArray) DataArray[source]#
Merge the lignin proportions of two input sources to the same litter pool.
- Parameters:
turnover_mass – Input mass coming from the natural turnover of plant tissue [kg{C}]
herbivory_waste_mass – Input mass coming from the mechanical inefficiencies of herbivory [kg{C}]
total_mass – The combined mass of the two input sources [kg{C}]
turnover_lignin_proportion – Proportion of lignin in the input mass from natural plant turnover [unitless]
herbivory_waste_lignin_proportion – Proportion of lignin in the input mass from mechanical inefficiencies of herbivory [unitless]
- Returns:
The proportion of carbon that is lignin carbon in the total mass of the new combined input stream [kg{lignin C} kg{C}^-1]
- 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.
- Parameters:
total_input – The the total pool size for each input pools [kg{C} m^-3], as well as the carbon to nitrogen ratios [unitless], carbon to phosphorus ratios [unitless] and 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 three input types: leaves, reproductive tissues and roots [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]