API documentation for the carbon module#

The models.litter.carbon module tracks the carbon content of 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.

Functions:

calculate_carbon_mineralised(carbon_loss, ...)

Calculate fraction of carbon loss that gets mineralised.

calculate_decay_rates(...)

Calculate the decay rate for all five of the litter pools.

calculate_final_pool_size(input_rate, ...)

Calculate the final size of a litter pool based on input and decay rates.

calculate_litter_decay_metabolic_above(...)

Calculate decay of above ground metabolic litter pool.

calculate_litter_decay_metabolic_below(...)

Calculate decay of below ground metabolic litter pool.

calculate_litter_decay_structural_above(...)

Calculate decay of above ground structural litter pool.

calculate_litter_decay_structural_below(...)

Calculate decay of below ground structural litter pool.

calculate_litter_decay_woody(...)

Calculate decay of the woody litter pool.

calculate_post_consumption_pools(...)

Calculates the size of the five litter pools after animal consumption.

calculate_total_C_mineralised(litter_losses, ...)

Calculate the total carbon mineralisation rate from all five litter pools.

calculate_updated_pools(...)

Calculate the updated mass of each litter pool.
virtual_ecosystem.models.litter.carbon.calculate_carbon_mineralised(carbon_loss: ndarray[tuple[Any, ...], dtype[floating]], carbon_use_efficiency: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

Calculate fraction of carbon loss that gets mineralised.

TODO - This function could also be used to track carbon respired, if/when we decide to track that.

Parameters:

  • carbon_loss – Total amount of carbon lost from the litter pool [kg{C} m^-2]

  • 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]

virtual_ecosystem.models.litter.carbon.calculate_decay_rates(lignin_above_structural: ndarray[tuple[Any, ...], dtype[floating]], lignin_woody: ndarray[tuple[Any, ...], dtype[floating]], lignin_below_structural: ndarray[tuple[Any, ...], dtype[floating]], air_temperatures: DataArray, soil_temperatures: DataArray, water_potentials: DataArray, layer_structure: LayerStructure, constants: LitterConstants) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the decay rate for all five of the litter pools.

Parameters:

  • lignin_above_structural – Proportion of above ground structural pool which is lignin [kg{lignin C} kg{C}^-1]

  • lignin_woody – Proportion of dead wood pool which is lignin [kg{lignin C} kg{C}^-1]

  • lignin_below_structural – Proportion of below ground structural pool which is lignin [kg{lignin C} kg{C}^-1]

  • air_temperatures – Air temperatures, for all above ground layers [Celsius]

  • soil_temperatures – Soil temperatures, for all soil layers [Celsius]

  • water_potentials – Water potentials, for all soil layers [kPa]

  • layer_structure – The LayerStructure instance for the simulation.

  • constants – Set of constants for the litter model

Decay rates depend on lignin proportions as well as a range of environmental factors. These environmental factors are calculated as part of this function.

Returns:

A dictionary containing the decay rate for each of the five litter pools.

virtual_ecosystem.models.litter.carbon.calculate_final_pool_size(input_rate: ndarray[tuple[Any, ...], dtype[floating]], decay_rate: ndarray[tuple[Any, ...], dtype[floating]], initial_pool: ndarray[tuple[Any, ...], dtype[floating]], update_interval: float)[source]#

Calculate the final size of a litter pool based on input and decay rates.

This function use an exact solution to the litter input and decay dynamics to find the pool size at the end of the update interval. This involves finding the equilibrium pool size based on the ratio of the input rate to the decay rate. The actual pool size exponentially decays from its initial size towards this equilibrium size with at the litter decay rate.

Parameters:

  • input_rate – The rate of input of carbon to the new pool [kg{C} m^-2 day^-1]

  • decay_rate – The rate at which the pool decays (in carbon terms) [kg{C} m^-2 day^-1]

  • initial_pool – The size of the pool at the start of the update interva [kg{C} m^-2]

  • update_interval – Interval that the litter pools are being updated for [days]

Returns:

The size of the pool at the end of the time step [kg{C} m^-2]

virtual_ecosystem.models.litter.carbon.calculate_litter_decay_metabolic_above(temperature_factor: ndarray[tuple[Any, ...], dtype[floating]], litter_decay_coefficient: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

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_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.carbon.calculate_litter_decay_metabolic_below(temperature_factor: ndarray[tuple[Any, ...], dtype[floating]], moisture_factor: ndarray[tuple[Any, ...], dtype[floating]], litter_decay_coefficient: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

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_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.carbon.calculate_litter_decay_structural_above(temperature_factor: ndarray[tuple[Any, ...], dtype[floating]], lignin_proportion: ndarray[tuple[Any, ...], dtype[floating]], litter_decay_coefficient: float, lignin_inhibition_factor: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

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]

  • lignin_proportion – The proportion of the above ground structural pool which is lignin [kg{lignin C} kg{C}^-1]

  • 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.carbon.calculate_litter_decay_structural_below(temperature_factor: ndarray[tuple[Any, ...], dtype[floating]], moisture_factor: ndarray[tuple[Any, ...], dtype[floating]], lignin_proportion: ndarray[tuple[Any, ...], dtype[floating]], litter_decay_coefficient: float, lignin_inhibition_factor: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

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]

  • lignin_proportion – The proportion of the below ground structural pool which is lignin [kg{lignin C} kg{C}^-1]

  • 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.carbon.calculate_litter_decay_woody(temperature_factor: ndarray[tuple[Any, ...], dtype[floating]], lignin_proportion: ndarray[tuple[Any, ...], dtype[floating]], litter_decay_coefficient: float, lignin_inhibition_factor: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

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]

  • lignin_proportion – The proportion of the woody litter pool which is lignin [kg{lignin C} kg{C}^-1]

  • 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.carbon.calculate_post_consumption_pools(above_metabolic: DataArray, above_structural: DataArray, woody: DataArray, below_metabolic: DataArray, below_structural: DataArray, consumption_above_metabolic: DataArray, consumption_above_structural: DataArray, consumption_woody: DataArray, consumption_below_metabolic: DataArray, consumption_below_structural: DataArray, cell_area: float) → dict[str, DataArray][source]#

Calculates the size of the five litter pools after animal consumption.

At present the Virtual Ecosystem gives animals priority for consumption of litter. And so only the litter not consumed by animals has a chance to decay. This is a major assumption that we may have to revisit in future.

This function calculates the change for all three nutrients (carbon, nitrogen and phosphorus) simultaneously, and also converts the animal consumption into density units.

Parameters:

  • above_metabolic – Above ground metabolic litter pool [kg m^-2]

  • above_structural – Above ground structural litter pool [kg m^-2]

  • woody – The woody litter pool [kg m^-2]

  • below_metabolic – Below ground metabolic litter pool [kg m^-2]

  • below_structural – Below ground structural litter pool [kg m^-2]

  • consumption_above_metabolic – Amount of above-ground metabolic litter that has been consumed by animals [kg]

  • consumption_above_structural – Amount of above-ground structural litter that has been consumed by animals [kg]

  • consumption_woody – Amount of woody litter that has been consumed by animals [kg]

  • consumption_below_metabolic – Amount of below-ground metabolic litter that has been consumed by animals [kg]

  • consumption_below_structural – Amount of below-ground structural litter that has been consumed by animals [kg]

  • cell_area – The area of each cell. [m^2]

Returns:

A dictionary containing the size of each litter pool after the mass consumed by animals has been removed [kg m^-2].

virtual_ecosystem.models.litter.carbon.calculate_total_C_mineralised(litter_losses: LitterLosses, model_constants: LitterConstants, core_constants: CoreConstants, update_interval: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

Calculate the total carbon mineralisation rate from all five litter pools.

Parameters:

  • litter_losses – Dataclass containing the total nutrient loss from each litter pool

  • model_constants – Set of constants for the litter model

  • core_constants – Set of core constants shared between all models

  • update_interval – Interval that the litter pools are being updated for [days]

Returns:

Rate of carbon mineralisation from litter into soil [kg{C} m^-3 day^-1].

virtual_ecosystem.models.litter.carbon.calculate_updated_pools(post_consumption_pools: dict[str, DataArray], decay_rates: dict[str, ndarray[tuple[Any, ...], dtype[floating]]], litter_inputs: LitterInputs, update_interval: float) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

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:

  • post_consumption_pools – The five litter pools after animal consumption has been subtracted [kg{C} m^-2]

  • decay_rates – Dictionary containing the rates of decay for all 5 litter pools [kg{C} m^-2 day^-1]

  • 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.

  • 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]