API documentation for the chemistry module#

The models.litter.chemistry module tracks the chemistry of the litter pools. This involves both the polymer content (i.e. lignin content of the litter), as well as the litter stoichiometry (i.e. nitrogen and phosphorus content).

The amount of lignin in both the structural pools and the dead wood pool is tracked, but not for the metabolic pool because by definition it contains no lignin. Nitrogen and phosphorus content are tracked for every pool.

Nitrogen and phosphorus contents do not have an explicit impact on decay rates, instead these contents determine how input material is split between pools (see inputs), which indirectly captures the impact of N and P stoichiometry on litter decomposition rates. By contrast, the impact of lignin on decay rates is directly calculated.

Classes:

LitterChemistry(data)

This class handles the chemistry of litter pools.

Functions:

calculate_litter_chemistry_factor(...)

Calculate the effect that litter chemistry has on litter decomposition rates.

calculate_updated_nutrient_pools(...)

Calculate the updated nutrient masses for all litter pools.

calculate_updated_pool_lignin_proportion(...)

Calculate the change in the lignin proportion of a particular litter pool.
class virtual_ecosystem.models.litter.chemistry.LitterChemistry(data: Data)[source]#

This class handles the chemistry of litter pools.

This class contains methods to calculate the changes in the litter pool chemistry based on the contents of the data object, as well as method to calculate total mineralisation based on litter pool decay rates.

Methods:

calculate_new_lignin_proportions(...)

Calculate the new lignin proportions for the relevant litter pools.

calculate_new_pool_chemistries(...)

Method to calculate the updated chemistry of each litter pool.
calculate_new_lignin_proportions(litter_inputs: LitterInputs, input_chemistries: InputChemistries, litter_losses: LitterLosses, original_pools: dict[str, DataArray], update_interval: float) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the new lignin proportions 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:

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

  • input_chemistries – The chemical compositions of the input to each litter pool

  • litter_losses – An LitterInputs instance containing the total loss of carbon, nitrogen, phosphorus and lignin from each litter pool.

  • original_pools – The size of each litter pool after animal consumption, but before litter inputs and decay [kg{C} m^-2].

  • update_interval – The update interval for the litter model [days]

Returns:

Dictionary containing the updated lignin proportions for the 3 relevant litter pools (above ground structural, dead wood, and below ground structural) [kg{lignin C} kg{C}^-1]

calculate_new_pool_chemistries(litter_inputs: LitterInputs, litter_losses: LitterLosses, input_chemistries: InputChemistries, original_pools: dict[str, DataArray], update_interval: float) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Method to calculate the updated chemistry of each litter pool.

All pools contain nitrogen and phosphorus, so this is updated for every pool. Only the structural (above and below ground) pools and the woody pools contain lignin, so it is only updated for those pools.

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.

  • litter_losses – An LitterLosses instance containing the total loss of carbon, nitrogen and carbon from each litter pool.

  • input_chemistries – An InputChemistries instance containing the chemical compositions of the input to each litter pool

  • original_pools – The size of each litter pool after animal consumption, but before litter inputs and decay [kg{C} m^-2].

  • update_interval – The update interval for the litter model [days]

virtual_ecosystem.models.litter.chemistry.calculate_litter_chemistry_factor(lignin_proportion: ndarray[tuple[Any, ...], dtype[floating]], lignin_inhibition_factor: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

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 litter pool carbon that is held in the form of lignin (or similar polymers) [kg{lignin C} kg{C}^-1]

  • 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.chemistry.calculate_updated_nutrient_pools(input_chemistries: InputChemistries, litter_losses: LitterLosses, original_pools: dict[str, DataArray], update_interval: float) → dict[str, ndarray[tuple[Any, ...], dtype[floating]]][source]#

Calculate the updated nutrient masses for all litter pools.

This function calculates the total change over the entire time step, so cannot be used in an integration process.

Parameters:

  • input_chemistries – The chemical compositions of the input to each litter pool

  • litter_losses – An LitterInputs instance containing the total loss of carbon, nitrogen and phosphorus from each litter pool.

  • original_pools – The size of each litter pool after animal consumption, but before litter inputs and decay [kg{C} m^-2]

  • update_interval – The update interval for the litter model [days]

Returns:

Dictionary containing the updated carbon nitrogen ratios for all of the litter pools [unitless]

virtual_ecosystem.models.litter.chemistry.calculate_updated_pool_lignin_proportion(initial_carbon: ndarray[tuple[Any, ...], dtype[floating]], input_carbon_rate: ndarray[tuple[Any, ...], dtype[floating]], carbon_loss: ndarray[tuple[Any, ...], dtype[floating]], initial_lignin_proportion: ndarray[tuple[Any, ...], dtype[floating]], input_lignin_proportion: ndarray[tuple[Any, ...], dtype[floating]], lignin_loss: ndarray[tuple[Any, ...], dtype[floating]], update_interval: float) → ndarray[tuple[Any, ...], dtype[floating]][source]#

Calculate the change in the lignin proportion of a particular litter pool.

The lignin proportion of the pool after the update is found by calculating the total amounts of carbon (in any form) and lignin carbon, and then dividing to find the proportion.

Parameters:

  • initial_carbon – The total carbon mass of the litter pool before inputs and decay [kg{C} m^-2]

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

  • carbon_loss – Total loss of carbon from the litter pool due to decay [kg{C} m^-2]

  • initial_lignin_proportion – The lignin proportion of the litter pool at the start of the update interval [kg{lignin C} kg{C}^-1]

  • input_lignin_proportion – The lignin proportion of the input biomass [kg{lignin C} kg{C}^-1]

  • lignin_loss – Total loss of lignin from the litter pool due to decay [kg{lignin C} m^-2]

  • update_interval – The update interval for the litter model [days]

Returns:

The new lignin proportion at the end of the update interval [kg{lignin C} kg{C}^-1]