API documentation for the carbon module

The models.soil.carbon module simulates the soil carbon cycle for the Virtual Ecosystem. At the moment five pools are modelled, these are low molecular weight carbon (LMWC), mineral associated organic matter (MAOM), microbial biomass, particulate organic matter (POM), and POM degrading enzymes.

Classes:

MicrobialBiomassLoss(maintenance_synthesis, ...)

A data class to store the various biomass losses from microbial biomass.

Functions:

calculate_carbon_use_efficiency(soil_temp, ...)

Calculate the (temperature dependant) carbon use efficiency.

calculate_enzyme_mediated_decomposition(...)

Calculate rate of a enzyme mediated decomposition process.

calculate_enzyme_turnover(enzyme_pool, ...)

Calculate the turnover rate of a specific enzyme class.

calculate_maintenance_biomass_synthesis(...)

Calculate microbial biomass synthesis rate required to offset losses.

calculate_microbial_carbon_uptake(...)

Calculate uptake and assimilation of labile carbon by microbes.

calculate_soil_carbon_updates(...)

Calculate net change for each carbon pool.

determine_microbial_biomass_losses(...)

Calculate all of the losses from the microbial biomass pool.
class virtual_ecosystem.models.soil.carbon.MicrobialBiomassLoss(maintenance_synthesis: ndarray[Any, dtype[float32]], pom_enzyme_production: ndarray[Any, dtype[float32]], maom_enzyme_production: ndarray[Any, dtype[float32]], necromass_decay_to_lmwc: ndarray[Any, dtype[float32]], necromass_decay_to_pom: ndarray[Any, dtype[float32]])

A data class to store the various biomass losses from microbial biomass.

Attributes:

maintenance_synthesis

Rate at which biomass must be synthesised to balance losses [kg C m^-3 day^-1].

maom_enzyme_production

Rate at which MAOM degrading enzymes are produced [kg C m^-3 day^-1].

necromass_decay_to_lmwc

Rate at which biomass is lost to the LMWC pool [kg C m^-3 day^-1].

necromass_decay_to_pom

Rate at which biomass is lost to the POM pool [kg C m^-3 day^-1].

pom_enzyme_production

Rate at which POM degrading enzymes are produced [kg C m^-3 day^-1].
maintenance_synthesis: ndarray[Any, dtype[float32]]

Rate at which biomass must be synthesised to balance losses [kg C m^-3 day^-1].

maom_enzyme_production: ndarray[Any, dtype[float32]]

Rate at which MAOM degrading enzymes are produced [kg C m^-3 day^-1].

necromass_decay_to_lmwc: ndarray[Any, dtype[float32]]

Rate at which biomass is lost to the LMWC pool [kg C m^-3 day^-1].

necromass_decay_to_pom: ndarray[Any, dtype[float32]]

Rate at which biomass is lost to the POM pool [kg C m^-3 day^-1].

pom_enzyme_production: ndarray[Any, dtype[float32]]

Rate at which POM degrading enzymes are produced [kg C m^-3 day^-1].

virtual_ecosystem.models.soil.carbon.calculate_carbon_use_efficiency(soil_temp: ndarray[Any, dtype[float32]], reference_cue: float, cue_reference_temp: float, cue_with_temperature: float) → ndarray[Any, dtype[float32]]

Calculate the (temperature dependant) carbon use efficiency.

TODO - This should be adapted to use an Arrhenius function at some point.

Parameters:

  • soil_temp – soil temperature for each soil grid cell [degrees C]

  • reference_cue – Carbon use efficiency at reference temp [unitless]

  • cue_reference_temp – Reference temperature [degrees C]

  • cue_with_temperature – Rate of change in carbon use efficiency with increasing temperature [degree C^-1]

Returns:

The carbon use efficiency (CUE) of the microbial community

virtual_ecosystem.models.soil.carbon.calculate_enzyme_mediated_decomposition(soil_c_pool: ndarray[Any, dtype[float32]], soil_enzyme: ndarray[Any, dtype[float32]], water_factor: ndarray[Any, dtype[float32]], pH_factor: ndarray[Any, dtype[float32]], clay_factor_saturation: ndarray[Any, dtype[float32]], soil_temp: ndarray[Any, dtype[float32]], reference_temp: float, max_decomp_rate: float, activation_energy_rate: float, half_saturation: float, activation_energy_sat: float) → ndarray[Any, dtype[float32]]

Calculate rate of a enzyme mediated decomposition process.

This function calculates various environmental factors that effect enzyme activity, then uses these to find environmental adjusted rate and saturation constants. These are then used to find the decomposition rate of the pool in question.

Parameters:

  • soil_c_pool – Size of organic matter pool [kg C m^-3]

  • soil_enzyme – Amount of enzyme class which breaks down the organic matter pool in question [kg C m^-3]

  • water_factor – A factor capturing the impact of soil water potential on microbial rates [unitless]

  • pH_factor – A factor capturing the impact of soil pH on microbial rates [unitless]

  • clay_factor_saturation – A factor capturing the impact of soil clay fraction on enzyme saturation constants [unitless]

  • soil_temp – soil temperature for each soil grid cell [degrees C]

  • reference_temp – The reference temperature that enzyme rates were determined relative to [degrees C]

  • max_decomp_rate – The maximum rate of substrate decomposition (at the reference temperature) [day^-1]

  • activation_energy_rate – Activation energy for maximum decomposition rate [J K^-1]

  • half_saturation – Half saturation constant for decomposition (at the reference temperature) [kg C m^-3]

  • activation_energy_sat – Activation energy for decomposition saturation [J K^-1]

Returns:

The rate of decomposition of the organic matter pool in question [kg C m^-3 day^-1]

virtual_ecosystem.models.soil.carbon.calculate_enzyme_turnover(enzyme_pool: ndarray[Any, dtype[float32]], turnover_rate: float) → ndarray[Any, dtype[float32]]

Calculate the turnover rate of a specific enzyme class.

Parameters:

  • enzyme_pool – The pool size for the enzyme class in question [kg C m^-3]

  • turnover_rate – The rate at which enzymes in the pool turnover [day^-1]

Returns:

The rate at which enzymes are lost from the pool [kg C m^-3 day^-1]

virtual_ecosystem.models.soil.carbon.calculate_maintenance_biomass_synthesis(soil_c_pool_microbe: ndarray[Any, dtype[float32]], soil_temp: ndarray[Any, dtype[float32]], constants: SoilConsts) → ndarray[Any, dtype[float32]]

Calculate microbial biomass synthesis rate required to offset losses.

In order for a microbial population to not decline it must synthesise enough new biomass to offset losses. These losses mostly come from cell death and protein decay, but also include loses due to extracellular enzyme excretion.

Parameters:

  • soil_c_pool_microbe – Microbial biomass (carbon) pool [kg C m^-3]

  • soil_temp – soil temperature for each soil grid cell [degrees C]

  • constants – Set of constants for the soil model.

Returns:

The rate of microbial biomass loss that must be matched to maintain a steady population [kg C m^-3 day^-1]

virtual_ecosystem.models.soil.carbon.calculate_microbial_carbon_uptake(soil_c_pool_lmwc: ndarray[Any, dtype[float32]], soil_c_pool_microbe: ndarray[Any, dtype[float32]], water_factor: ndarray[Any, dtype[float32]], pH_factor: ndarray[Any, dtype[float32]], soil_temp: ndarray[Any, dtype[float32]], constants: SoilConsts) → tuple[ndarray[Any, dtype[float32]], ndarray[Any, dtype[float32]]]

Calculate uptake and assimilation of labile carbon by microbes.

This function starts by calculating the impact that environmental factors have on the rate and saturation constants for microbial uptake. These constants are then used to calculate the rate of uptake of labile carbon. Carbon use efficiency is then calculated and used to find how much of this carbon ends up assimilated as biomass (rather than respired).

Parameters:

  • soil_c_pool_lmwc – Low molecular weight carbon pool [kg C m^-3]

  • soil_c_pool_microbe – Microbial biomass (carbon) pool [kg C m^-3]

  • water_factor – A factor capturing the impact of soil water potential on microbial rates [unitless]

  • pH_factor – A factor capturing the impact of soil pH on microbial rates [unitless]

  • soil_temp – soil temperature for each soil grid cell [degrees C]

  • constants – Set of constants for the soil model.

Returns:

A tuple containing the uptake rate of low molecular weight carbon (LMWC) by the soil microbial biomass, and the rate at which this causes microbial biomass to increase.

virtual_ecosystem.models.soil.carbon.calculate_soil_carbon_updates(soil_c_pool_lmwc: ndarray[Any, dtype[float32]], soil_c_pool_maom: ndarray[Any, dtype[float32]], soil_c_pool_microbe: ndarray[Any, dtype[float32]], soil_c_pool_pom: ndarray[Any, dtype[float32]], soil_enzyme_pom: ndarray[Any, dtype[float32]], soil_enzyme_maom: ndarray[Any, dtype[float32]], pH: ndarray[Any, dtype[float32]], bulk_density: ndarray[Any, dtype[float32]], soil_moisture: ndarray[Any, dtype[float32]], soil_water_potential: ndarray[Any, dtype[float32]], vertical_flow_rate: ndarray[Any, dtype[float32]], soil_temp: ndarray[Any, dtype[float32]], clay_fraction: ndarray[Any, dtype[float32]], mineralisation_rate: ndarray[Any, dtype[float32]], delta_pools_ordered: dict[str, ndarray[Any, dtype[float32]]], core_constants: CoreConsts, model_constants: SoilConsts) → ndarray[Any, dtype[float32]]

Calculate net change for each carbon pool.

This function calls lower level functions which calculate the transfers between pools. When all transfers have been calculated the net transfer is used to calculate the net change for each pool.

Parameters:

  • soil_c_pool_lmwc – Low molecular weight carbon pool [kg C m^-3]

  • soil_c_pool_maom – Mineral associated organic matter pool [kg C m^-3]

  • soil_c_pool_microbe – Microbial biomass (carbon) pool [kg C m^-3]

  • soil_c_pool_pom – Particulate organic matter pool [kg C m^-3]

  • soil_enzyme_pom – Amount of enzyme class which breaks down particulate organic matter [kg C m^-3]

  • soil_enzyme_maom – Amount of enzyme class which breaks down mineral associated organic matter [kg C m^-3]

  • pH – pH values for each soil grid cell [unitless]

  • bulk_density – bulk density values for each soil grid cell [kg m^-3]

  • soil_moisture – amount of water contained by each soil layer [mm]

  • soil_water_potential – Soil water potential for each grid cell [kPa]

  • soil_temp – soil temperature for each soil grid cell [degrees C]

  • clay_fraction – The clay fraction for each soil grid cell [unitless]

  • mineralisation_rate – Amount of litter mineralised into POM pool [kg C m^-3 day^-1]

  • delta_pools_ordered – Dictionary to store pool changes in the order that pools are stored in the initial condition vector.

  • core_constants – Set of constants shared between models.

  • model_constants – Set of constants for the soil model.

Returns:

A vector containing net changes to each pool. Order [lmwc, maom].

virtual_ecosystem.models.soil.carbon.determine_microbial_biomass_losses(soil_c_pool_microbe: ndarray[Any, dtype[float32]], soil_temp: ndarray[Any, dtype[float32]], clay_factor_decay: ndarray[Any, dtype[float32]], constants: SoilConsts) → MicrobialBiomassLoss

Calculate all of the losses from the microbial biomass pool.

Microbes need to synthesis new biomass at a certain rate just to maintain their current biomass. This function calculates this overall rate and the various losses that contribute to this rate. The main sources of this loss are the external excretion of enzymes, cell death, and protein degradation.

Parameters:

  • soil_c_pool_microbe – Microbial biomass (carbon) pool [kg C m^-3]

  • soil_temp – soil temperature for each soil grid cell [degrees C]

  • clay_factor_decay – A factor capturing the impact of soil clay fraction on necromass decay destination [unitless]

  • constants – Set of constants for the soil model.

Returns:

A dataclass containing all the losses from the microbial biomass pool.