API documentation for the litter_pools module
The models.litter.litter_pools module simulates the litter pools for the Virtual
Ecosystem. Pools are divided into above and below ground pools, with below ground pools
affected by both soil moisture and temperature, and above ground pools just affected by
soil surface temperatures. The pools are also divided based on the recalcitrance of
their inputs, dead wood is given a separate pool, and all other inputs are divided
between metabolic and structural pools. Recalcitrant litter contains hard to break down
compounds, principally lignin. The metabolic litter pool contains the non-recalcitrant
litter and so breaks down quickly. Whereas, the structural litter contains the
recalcitrant litter.
We consider 5 pools rather than 6, as it’s not really possible to parametrise the below ground dead wood pool. So, all dead wood gets included in the above ground woody litter pool.
The amount of lignin in both the structural pools and the dead wood pool is tracked. This is tracked because litter chemistry is a major determinant of litter decay rates.
Functions:
Calculate fraction of litter decay that gets mineralised. |
|
|
Calculate the change in the lignin concentration of a particular litter pool. |
Calculate changes for all the litter variables (pool sizes and chemistries). |
|
|
Calculate the decay rate for all five of the litter pools. |
Calculate the impact of the environment has on litter decay across litter layers. |
|
Calculate the changes in lignin proportion for the relevant litter pools. |
|
Calculate the effect that litter chemistry has on litter decomposition rates. |
|
Calculate decay of above ground metabolic litter pool. |
|
Calculate decay of below ground metabolic litter pool. |
|
Calculate decay of above ground structural litter pool. |
|
Calculate decay of below ground structural litter pool. |
|
Calculate decay of the woody litter pool. |
|
Calculate the effect that soil moisture has on litter decomposition rates. |
|
Calculate the effect that temperature has on litter decomposition rates. |
|
|
Calculate the total carbon mineralisation rate from all five litter pools. |
|
Calculate the updated mass of each litter pool. |
- virtual_ecosystem.models.litter.litter_pools.calculate_carbon_mineralised(litter_decay_rate: ndarray[Any, dtype[float32]], carbon_use_efficiency: float) ndarray[Any, dtype[float32]]
Calculate fraction of litter decay that gets mineralised.
TODO - This function could also be used to track carbon respired, if/when we decide to track that.
- Parameters:
litter_decay_rate – Rate at which litter pool is decaying [kg C m^-2 day^-1]
carbon_use_efficiency – Carbon use efficiency of litter pool [unitless]
- Returns:
Rate at which carbon is mineralised from the litter pool [kg C m^-2 day^-1]
- virtual_ecosystem.models.litter.litter_pools.calculate_change_in_lignin(input_carbon: float | ndarray[Any, dtype[float32]], updated_pool_carbon: ndarray[Any, dtype[float32]], input_lignin: float | ndarray[Any, dtype[float32]], old_pool_lignin: ndarray[Any, dtype[float32]]) ndarray[Any, dtype[float32]]
Calculate the change in the lignin concentration of a particular litter pool.
This change is found by calculating the difference between the previous lignin concentration of the pool and the lignin concentration of the inputs. This difference is then multiplied by the ratio of the mass of carbon added to pool and the final (carbon) mass of the pool.
- Parameters:
input_carbon – The total carbon mass of inputs to the litter pool [kg C m^-2]
updated_pool_carbon – The total carbon mass of the litter pool after inputs and decay [kg C m^-2]
input_lignin – The proportion of the input carbon that is lignin [unitless]
old_pool_lignin – The proportion of the carbon mass of the original litter pool that was lignin [unitless]
- Returns:
The total change in the lignin concentration of the pool over the full time step [unitless]
- virtual_ecosystem.models.litter.litter_pools.calculate_change_in_litter_variables(surface_temp: ndarray[Any, dtype[float32]], topsoil_temp: ndarray[Any, dtype[float32]], water_potential: ndarray[Any, dtype[float32]], above_metabolic: ndarray[Any, dtype[float32]], above_structural: ndarray[Any, dtype[float32]], woody: ndarray[Any, dtype[float32]], below_metabolic: ndarray[Any, dtype[float32]], below_structural: ndarray[Any, dtype[float32]], lignin_above_structural: ndarray[Any, dtype[float32]], lignin_woody: ndarray[Any, dtype[float32]], lignin_below_structural: ndarray[Any, dtype[float32]], decomposed_excrement: ndarray[Any, dtype[float32]], decomposed_carcasses: ndarray[Any, dtype[float32]], update_interval: float, model_constants: LitterConsts, core_constants: CoreConsts) dict[str, ndarray[Any, dtype[float32]]]
Calculate changes for all the litter variables (pool sizes and chemistries).
- Parameters:
surface_temp – Temperature of soil surface, which is assumed to be the same temperature as the above ground litter [C]
topsoil_temp – Temperature of topsoil layer, which is assumed to be the same temperature as the below ground litter [C]
water_potential – Water potential of the topsoil layer [kPa]
above_metabolic – Above ground metabolic litter pool [kg C m^-2]
above_structural – Above ground structural litter pool [kg C m^-2]
woody – The woody litter pool [kg C m^-2]
below_metabolic – Below ground metabolic litter pool [kg C m^-2]
below_structural – Below ground structural litter pool [kg C m^-2]
lignin_above_structural – Proportion of above ground structural pool which is lignin [unitless]
lignin_woody – Proportion of dead wood pool which is lignin [unitless]
lignin_below_structural – Proportion of below ground structural pool which is lignin [unitless]
decomposed_excrement – Input rate of excrement from the animal model [kg C m^-2 day^-1]
decomposed_carcasses – Input rate of (partially) decomposed carcass biomass from the animal model [kg C m^-2 day^-1]
update_interval – Interval that the litter pools are being updated for [days]
model_constants – Set of constants for the litter model
core_constants – Set of core constants shared between all models
- Returns:
The new value for each of the litter pools, and the total mineralisation rate.
- virtual_ecosystem.models.litter.litter_pools.calculate_decay_rates(above_metabolic: ndarray[Any, dtype[float32]], above_structural: ndarray[Any, dtype[float32]], woody: ndarray[Any, dtype[float32]], below_metabolic: ndarray[Any, dtype[float32]], below_structural: ndarray[Any, dtype[float32]], lignin_above_structural: ndarray[Any, dtype[float32]], lignin_woody: ndarray[Any, dtype[float32]], lignin_below_structural: ndarray[Any, dtype[float32]], environmental_factors: dict[str, ndarray[Any, dtype[float32]]], constants: LitterConsts) dict[str, ndarray[Any, dtype[float32]]]
Calculate the decay rate for all five of the litter pools.
- Parameters:
above_metabolic – Above ground metabolic litter pool [kg C m^-2]
above_structural – Above ground structural litter pool [kg C m^-2]
woody – The woody litter pool [kg C m^-2]
below_metabolic – Below ground metabolic litter pool [kg C m^-2]
below_structural – Below ground structural litter pool [kg C m^-2]
lignin_above_structural – Proportion of above ground structural pool which is lignin [unitless]
lignin_woody – Proportion of dead wood pool which is lignin [unitless]
lignin_below_structural – Proportion of below ground structural pool which is lignin [unitless]
environmental_factors – Factors capturing the effect that the physical environment (soil water + temperature) has on litter decay rates [unitless].
constants – Set of constants for the litter model
- Returns:
A dictionary containing the decay rate for each of the five litter pools.
- virtual_ecosystem.models.litter.litter_pools.calculate_environmental_factors(surface_temp: ndarray[Any, dtype[float32]], topsoil_temp: ndarray[Any, dtype[float32]], water_potential: ndarray[Any, dtype[float32]], constants: LitterConsts) dict[str, ndarray[Any, dtype[float32]]]
Calculate the impact of the environment has on litter decay across litter layers.
For the above ground layer the impact of temperature is calculated, and for the below ground layer the effect of temperature and soil water potential are considered.
- Parameters:
surface_temp – Temperature of soil surface, which is assumed to be the same temperature as the above ground litter [C]
topsoil_temp – Temperature of topsoil layer, which is assumed to be the same temperature as the below ground litter [C]
water_potential – Water potential of the topsoil layer [kPa]
constants – Set of constants for the litter model
- Returns:
A dictionary containing three environmental factors, one for the effect of temperature on above ground litter decay, one for the effect of temperature on below ground litter decay, and one for the effect of soil water potential on below ground litter decay.
- virtual_ecosystem.models.litter.litter_pools.calculate_lignin_updates(lignin_above_structural: ndarray[Any, dtype[float32]], lignin_woody: ndarray[Any, dtype[float32]], lignin_below_structural: ndarray[Any, dtype[float32]], updated_pools: dict[str, ndarray[Any, dtype[float32]]], update_interval: float, constants: LitterConsts) dict[str, ndarray[Any, dtype[float32]]]
Calculate the changes in lignin proportion for the relevant litter pools.
The relevant pools are the two structural pools, and the dead wood pool. This function calculates the total change over the entire time step, so cannot be used in an integration process.
- Parameters:
lignin_above_structural – Proportion of above ground structural pool which is lignin [unitless]
lignin_woody – Proportion of dead wood pool which is lignin [unitless]
lignin_below_structural – Proportion of below ground structural pool which is lignin [unitless]
updated_pools – Dictionary containing the updated pool densities for all 5 litter pools [kg C m^-2]
update_interval – Interval that the litter pools are being updated for [days]
constants – Set of constants for the litter model
- Returns:
Dictionary containing the updated lignin proportions for the 3 relevant litter pools (above ground structural, dead wood, and below ground structural) [kg C m^-2]
- virtual_ecosystem.models.litter.litter_pools.calculate_litter_chemistry_factor(lignin_proportion: ndarray[Any, dtype[float32]], lignin_inhibition_factor: float) ndarray[Any, dtype[float32]]
Calculate the effect that litter chemistry has on litter decomposition rates.
This expression is taken from Kirschbaum and Paul (2002).
- Parameters:
lignin_proportion – The proportion of the polymers in the litter pool that are lignin (or similar) [unitless]
lignin_inhibition_factor – An exponential factor expressing the extent to which lignin inhibits the breakdown of litter [unitless]
- Returns:
A factor that captures the impact of litter chemistry on litter decay rates
- virtual_ecosystem.models.litter.litter_pools.calculate_litter_decay_metabolic_above(temperature_factor: ndarray[Any, dtype[float32]], litter_pool_above_metabolic: ndarray[Any, dtype[float32]], litter_decay_coefficient: float) ndarray[Any, dtype[float32]]
Calculate decay of above ground metabolic litter pool.
This function is taken from Kirschbaum and Paul (2002).
- Parameters:
temperature_factor – A multiplicative factor capturing the impact of temperature on litter decomposition [unitless]
litter_pool_above_metabolic – The size of the above ground metabolic litter pool [kg C m^-2]
litter_decay_coefficient – The decay coefficient for the above ground metabolic litter pool [day^-1]
- Returns:
Rate of decay of the above ground metabolic litter pool [kg C m^-2 day^-1]
- virtual_ecosystem.models.litter.litter_pools.calculate_litter_decay_metabolic_below(temperature_factor: ndarray[Any, dtype[float32]], moisture_factor: ndarray[Any, dtype[float32]], litter_pool_below_metabolic: ndarray[Any, dtype[float32]], litter_decay_coefficient: float) ndarray[Any, dtype[float32]]
Calculate decay of below ground metabolic litter pool.
This function is taken from Kirschbaum and Paul (2002).
- Parameters:
temperature_factor – A multiplicative factor capturing the impact of temperature on litter decomposition [unitless]
moisture_factor – A multiplicative factor capturing the impact of soil moisture on litter decomposition [unitless]
litter_pool_below_metabolic – The size of the below ground metabolic litter pool [kg C m^-2]
litter_decay_coefficient – The decay coefficient for the below ground metabolic litter pool [day^-1]
- Returns:
Rate of decay of the below ground metabolic litter pool [kg C m^-2 day^-1]
- virtual_ecosystem.models.litter.litter_pools.calculate_litter_decay_structural_above(temperature_factor: ndarray[Any, dtype[float32]], litter_pool_above_structural: ndarray[Any, dtype[float32]], lignin_proportion: ndarray[Any, dtype[float32]], litter_decay_coefficient: float, lignin_inhibition_factor: float) ndarray[Any, dtype[float32]]
Calculate decay of above ground structural litter pool.
This function is taken from Kirschbaum and Paul (2002).
- Parameters:
temperature_factor – A multiplicative factor capturing the impact of temperature on litter decomposition [unitless]
litter_pool_above_structural – The size of the above ground structural litter pool [kg C m^-2]
lignin_proportion – The proportion of the above ground structural pool which is lignin [unitless]
litter_decay_coefficient – The decay coefficient for the above ground structural litter pool [day^-1]
lignin_inhibition_factor – An exponential factor expressing the extent to which lignin inhibits the breakdown of litter [unitless]
- Returns:
Rate of decay of the above ground structural litter pool [kg C m^-2 day^-1]
- virtual_ecosystem.models.litter.litter_pools.calculate_litter_decay_structural_below(temperature_factor: ndarray[Any, dtype[float32]], moisture_factor: ndarray[Any, dtype[float32]], litter_pool_below_structural: ndarray[Any, dtype[float32]], lignin_proportion: ndarray[Any, dtype[float32]], litter_decay_coefficient: float, lignin_inhibition_factor: float) ndarray[Any, dtype[float32]]
Calculate decay of below ground structural litter pool.
This function is taken from Kirschbaum and Paul (2002).
- Parameters:
temperature_factor – A multiplicative factor capturing the impact of temperature on litter decomposition [unitless]
moisture_factor – A multiplicative factor capturing the impact of soil moisture on litter decomposition [unitless]
litter_pool_below_structural – The size of the below ground structural litter pool [kg C m^-2]
lignin_proportion – The proportion of the below ground structural pool which is lignin [unitless]
litter_decay_coefficient – The decay coefficient for the below ground structural litter pool [day^-1]
lignin_inhibition_factor – An exponential factor expressing the extent to which lignin inhibits the breakdown of litter [unitless]
- Returns:
Rate of decay of the below ground structural litter pool [kg C m^-2 day^-1]
- virtual_ecosystem.models.litter.litter_pools.calculate_litter_decay_woody(temperature_factor: ndarray[Any, dtype[float32]], litter_pool_woody: ndarray[Any, dtype[float32]], lignin_proportion: ndarray[Any, dtype[float32]], litter_decay_coefficient: float, lignin_inhibition_factor: float) ndarray[Any, dtype[float32]]
Calculate decay of the woody litter pool.
This function is taken from Kirschbaum and Paul (2002).
- Parameters:
temperature_factor – A multiplicative factor capturing the impact of temperature on litter decomposition [unitless]
litter_pool_woody – The size of the woody litter pool [kg C m^-2]
lignin_proportion – The proportion of the woody litter pool which is lignin [unitless]
litter_decay_coefficient – The decay coefficient for the woody litter pool [day^-1]
lignin_inhibition_factor – An exponential factor expressing the extent to which lignin inhibits the breakdown of litter [unitless]
- Returns:
Rate of decay of the woody litter pool [kg C m^-2 day^-1]
- virtual_ecosystem.models.litter.litter_pools.calculate_moisture_effect_on_litter_decomp(water_potential: ndarray[Any, dtype[float32]], water_potential_halt: float, water_potential_opt: float, moisture_response_curvature: float) ndarray[Any, dtype[float32]]
Calculate the effect that soil moisture has on litter decomposition rates.
This function is only relevant for the below ground litter pools. Its functional form is taken from Moyano et al. (2013).
- Parameters:
water_potential – Soil water potential [kPa]
water_potential_halt – Water potential at which all microbial activity stops [kPa]
water_potential_opt – Optimal water potential for microbial activity [kPa]
moisture_response_curvature – Parameter controlling the curvature of the moisture response function [unitless]
- Returns:
A multiplicative factor capturing the impact of moisture on below ground litter decomposition [unitless]
- virtual_ecosystem.models.litter.litter_pools.calculate_temperature_effect_on_litter_decomp(temperature: ndarray[Any, dtype[float32]], reference_temp: float, offset_temp: float, temp_response: float) ndarray[Any, dtype[float32]]
Calculate the effect that temperature has on litter decomposition rates.
This function is taken from Kirschbaum and Paul (2002).
- Parameters:
temperature – The temperature of the litter layer [C]
reference_temp – The reference temperature for changes in litter decomposition rates with temperature [C]
offset_temp – Temperature offset [C]
temp_response – Factor controlling response strength to changing temperature [unitless]
- Returns:
A multiplicative factor capturing the impact of temperature on litter decomposition [unitless]
- virtual_ecosystem.models.litter.litter_pools.calculate_total_C_mineralised(decay_rates: dict[str, ndarray[Any, dtype[float32]]], model_constants: LitterConsts, core_constants: CoreConsts) ndarray[Any, dtype[float32]]
Calculate the total carbon mineralisation rate from all five litter pools.
- Parameters:
decay_rates – Dictionary containing the rates of decay for all 5 litter pools [kg C m^-2 day^-1]
model_constants – Set of constants for the litter model
core_constants – Set of core constants shared between all models
- Returns:
Rate of carbon mineralisation from litter into soil [kg C m^-3 day^-1].
- virtual_ecosystem.models.litter.litter_pools.calculate_updated_pools(above_metabolic: ndarray[Any, dtype[float32]], above_structural: ndarray[Any, dtype[float32]], woody: ndarray[Any, dtype[float32]], below_metabolic: ndarray[Any, dtype[float32]], below_structural: ndarray[Any, dtype[float32]], decomposed_excrement: ndarray[Any, dtype[float32]], decomposed_carcasses: ndarray[Any, dtype[float32]], decay_rates: dict[str, ndarray[Any, dtype[float32]]], update_interval: float, constants: LitterConsts) dict[str, ndarray[Any, dtype[float32]]]
Calculate the updated mass of each litter pool.
This function is not intended to be used continuously, and returns the new value for each pool after the update interval, rather than a rate of change to be integrated.
- Parameters:
above_metabolic – Above ground metabolic litter pool [kg C m^-2]
above_structural – Above ground structural litter pool [kg C m^-2]
woody – The woody litter pool [kg C m^-2]
below_metabolic – Below ground metabolic litter pool [kg C m^-2]
below_structural – Below ground structural litter pool [kg C m^-2]
decomposed_excrement – Input rate of excrement from the animal model [kg C m^-2 day^-1]
decomposed_carcasses – Input rate of (partially) decomposed carcass biomass from the animal model [kg C m^-2 day^-1]
decay_rates – Dictionary containing the rates of decay for all 5 litter pools [kg C m^-2 day^-1]
update_interval – Interval that the litter pools are being updated for [days]
constants – Set of constants for the litter model
- Returns:
Dictionary containing the updated pool densities for all 5 litter pools (above ground metabolic, above ground structural, dead wood, below ground metabolic, and below ground structural) [kg C m^-2]