API for the `decay` module#

The decay module contains pools which are still potentially forageable by animals but are in the process of microbial decomposition. This includes excrement and carcasses that are tracked solely in the animal module. This also includes plant litter which is mainly tracked in the litter module, but is made available for animal consumption.

Classes:

`CarcassPool`(scavengeable_cnp, ...)	This class stores information about the carcass biomass in each grid cell.
`ExcrementPool`(scavengeable_cnp, ...)	This class stores information about the amount of excrement in each grid cell.
`FungalFruitPool`(cell_id, data, cell_area, ...)	A class to track the mass of fungal fruiting bodies in each grid cell.
`HerbivoryWaste`(plant_matter_type)	A class to track the amount of waste generated by each form of herbivory.
`ScavengeableMixin`()	Mixin for nutrient pools that can be scavenged by animal cohorts.
`SoilPool`(pool_name, cell_id, data, ...)	Interface between litter model variables in `Data` and the animal module.

Functions:

find_decay_consumed_split(...)

Find fraction of biomass that is assumed to decay rather than being scavenged.

class virtual_ecosystem.models.animal.decay.CarcassPool(scavengeable_cnp: ~virtual_ecosystem.models.animal.cnp.CNP = <factory>, decomposed_cnp: ~virtual_ecosystem.models.animal.cnp.CNP = <factory>, cell_id: int = -1, vertical_occupancy: ~virtual_ecosystem.models.animal.animal_traits.VerticalOccupancy = <VerticalOccupancy.GROUND: 2>)[source]#

This class stores information about the carcass biomass in each grid cell.

Methods:

`add_carcass`(C, N, P)	Add carcass mass to the pool based on the provided mass.
`decomposed_nutrient_per_area`(nutrient, ...)	Convert decomposed carcass nutrient content to mass per area units.
`reset`()	Reset tracking of the nutrients associated with decomposed carcasses.

Attributes:

`cell_id`	Grid position of carcass pool.
`decomposed_cnp`	A CNP object storing decomposed nutrients in the carcass pool.
`mass_current`	Total scavengeable carcass mass (kg).
`scavengeable_cnp`	A CNP object storing animal-accessible nutrients in the carcass pool.
`vertical_occupancy`	Vertical position of carcass pool.

add_carcass(C: float, N: float, P: float) → None[source]#

Add carcass mass to the pool based on the provided mass.

Parameters:

C (float) – The mass of carbon to add.
N (float) – The mass of nitrogen to add.
P (float) – The mass of phosphorus to add.

Raises:

ValueError – If any input mass is negative.

cell_id: int = -1#: Grid position of carcass pool.

decomposed_cnp: CNP#: A CNP object storing decomposed nutrients in the carcass pool.

decomposed_nutrient_per_area(nutrient: str, grid_cell_area: float) → float[source]#

Convert decomposed carcass nutrient content to mass per area units.

Parameters:

nutrient (str) – The name of the nutrient to calculate for.
grid_cell_area (float) – The size of the grid cell [m^2].

Raises:

ValueError – If a nutrient other than carbon, nitrogen, or phosphorus is chosen.

Returns:

The nutrient content of the decomposed carcasses on a per area basis: [kg m^-2].

Return type:

float

property mass_current: float#: Total scavengeable carcass mass (kg).

reset() → None[source]#

Reset tracking of the nutrients associated with decomposed carcasses.

This function sets the decomposed carbon, nitrogen, and phosphorus to zero. It should only be called after transfers to the soil model due to decomposition have been calculated.

scavengeable_cnp: CNP#: A CNP object storing animal-accessible nutrients in the carcass pool.

vertical_occupancy: VerticalOccupancy = 2#: Vertical position of carcass pool.

class virtual_ecosystem.models.animal.decay.ExcrementPool(scavengeable_cnp: ~virtual_ecosystem.models.animal.cnp.CNP = <factory>, decomposed_cnp: ~virtual_ecosystem.models.animal.cnp.CNP = <factory>, cell_id: int = -1, vertical_occupancy: ~virtual_ecosystem.models.animal.animal_traits.VerticalOccupancy = <VerticalOccupancy.GROUND: 2>)[source]#

This class stores information about the amount of excrement in each grid cell.

Methods:

`add_excrement`(C, N, P)	Add excrement mass to the pool based on the provided input mass.
`decomposed_nutrient_per_area`(nutrient, ...)	Convert decomposed excrement nutrient content to mass per area units.
`reset`()	Reset tracking of the nutrients associated with decomposed excrement.

Attributes:

`cell_id`	Grid position of carcass pool.
`decomposed_cnp`	A CNP object storing decomposed nutrients in the excrement pool.
`mass_current`	Total scavengeable excrement mass (kg).
`scavengeable_cnp`	A CNP object storing animal-accessible nutrients in the excrement pool.
`vertical_occupancy`	Vertical position of carcass pool.

add_excrement(C: float, N: float, P: float) → None[source]#

Add excrement mass to the pool based on the provided input mass.

Parameters:

C (float) – The mass of carbon to add.
N (float) – The mass of nitrogen to add.
P (float) – The mass of phosphorus to add.

Raises:

ValueError – If any input mass is negative.

cell_id: int = -1#: Grid position of carcass pool.

decomposed_cnp: CNP#: A CNP object storing decomposed nutrients in the excrement pool.

decomposed_nutrient_per_area(nutrient: str, grid_cell_area: float) → float[source]#

Convert decomposed excrement nutrient content to mass per area units.

Parameters:

nutrient (str) – The name of the nutrient to calculate for.
grid_cell_area (float) – The size of the grid cell [m^2].

Raises:

ValueError – If a nutrient other than carbon, nitrogen, or phosphorus is chosen.

Returns:

The nutrient content of the decomposed excrement on a per area basis: [kg m^-2].

Return type:

float

property mass_current: float#: Total scavengeable excrement mass (kg).

reset() → None[source]#

Reset tracking of the nutrients associated with decomposed excrement.

This function sets the decomposed carbon, nitrogen, and phosphorus to zero. It should only be called after transfers to the soil model due to decomposition have been calculated.

scavengeable_cnp: CNP#: A CNP object storing animal-accessible nutrients in the excrement pool.

vertical_occupancy: VerticalOccupancy = 2#: Vertical position of carcass pool.

class virtual_ecosystem.models.animal.decay.FungalFruitPool(cell_id: int, data: Data, cell_area: float, c_n_ratio: float, c_p_ratio: float)[source]#

A class to track the mass of fungal fruiting bodies in each grid cell.

TODO - A proper explanation as I add stuff

Methods:

`apply_decay`(decay_constant, time_period)	Apply exponential decay to the fungal fruiting bodies pool.
`get_eaten`(consumed_mass, detritivore)	Remove biomass when a cohort consumes fungal fruiting bodies.

Attributes:

`mass_current`	Return current carbon mass in the pool [kg].
`vertical_occupancy`	Vertical position of fungal fruiting pool.

apply_decay(decay_constant: float, time_period: float) → float[source]#

Apply exponential decay to the fungal fruiting bodies pool.

Parameters:

decay_constant – The rate constant for fungal fruiting body decay [day^-1].
time_period – The time period over which decay occurs [day].

Returns:

The total amount of fungal fruiting bodies that decayed in this specific grid cell (in carbon terms) [kg]

get_eaten(consumed_mass: float, detritivore: Consumer) → tuple[dict[str, float], dict[str, float]][source]#

Remove biomass when a cohort consumes fungal fruiting bodies.

Parameters:

consumed_mass – Target wet-mass to consume after mechanical efficiency is applied (kg). Any attempt to over-consume is automatically capped.
detritivore – The cohort that is feeding used only to obtain mechanical efficiency.

Returns:

Dictionary of element masses actually assimilated, keys C, N, P (kg).

property mass_current: float#: Return current carbon mass in the pool [kg].

vertical_occupancy: VerticalOccupancy = 2#: Vertical position of fungal fruiting pool.

class virtual_ecosystem.models.animal.decay.HerbivoryWaste(plant_matter_type: str)[source]#

A class to track the amount of waste generated by each form of herbivory.

This is used as a temporary storage location before the wastes are added to the litter model. As such it is not made available for animal consumption.

The litter model splits its plant matter into four classes: wood, leaves, roots, and reproductive tissues (fruits and flowers). A separate instance of this class should be used for each of these groups.

Parameters:: pool_name – Type of plant matter this waste pool contains.
Raises:: ValueError – If initialised for a plant matter type that the litter model doesn’t accept.

Methods:

add_waste(input_mass_cnp)

Add waste to the pool based on the provided stoichiometric mass.

Attributes:

`lignin_proportion`	Proportion of the herbivory waste pool carbon that is lignin [unitless].
`mass_cnp`	The mass of each stoichiometric element found in the plant resources, {"C": value, "N": value, "P": value}.
`plant_matter_type`	Type of plant matter this waste pool contains.

add_waste(input_mass_cnp: dict[str, float]) → None[source]#

Add waste to the pool based on the provided stoichiometric mass.

Parameters:: input_mass_cnp – Dictionary specifying the mass of each element in the waste {“C”: value, “N”: value, “P”: value}.
Raises:: ValueError – If the input dictionary is missing required elements or contains negative values.

lignin_proportion#: Proportion of the herbivory waste pool carbon that is lignin [unitless].

mass_cnp: dict[str, float]#: The mass of each stoichiometric element found in the plant resources, {“C”: value, “N”: value, “P”: value}.

plant_matter_type#: Type of plant matter this waste pool contains.

class virtual_ecosystem.models.animal.decay.ScavengeableMixin[source]#

Mixin for nutrient pools that can be scavenged by animal cohorts.

Methods:

get_eaten(consumed_mass, scavenger)

Remove biomass from the scavengeable pool and return stoichiometric gain.

get_eaten(consumed_mass: float, scavenger: Consumer) → tuple[dict[str, float], dict[str, float]][source]#

Remove biomass from the scavengeable pool and return stoichiometric gain.

Parameters:

consumed_mass – Wet-mass the scavenger tries to eat [kg].
scavenger – The animal cohort consuming the material.

Returns:

Dict with keys "C", "N", "P" giving the mass of each element actually ingested, and a second empty dict.

Raises:

ValueError – If consumed_mass is negative.

class virtual_ecosystem.models.animal.decay.SoilPool(pool_name: str, cell_id: int, data: Data, cell_area: float, max_depth_microbial_activity: float, c_n_p_ratios: dict[str, dict[str, float]])[source]#

Interface between litter model variables in Data and the animal module.

One SoilPool instance now represents one soil pool type *in one grid cell*.

Methods:

get_eaten(consumed_mass, detritivore)

Remove biomass when a cohort consumes this soil pool.

Attributes:

`mass_current`	Return current carbon mass in the pool [kg].
`vertical_occupancy`	Vertical position of soil pool.

get_eaten(consumed_mass: float, detritivore: Consumer) → tuple[dict[str, float], dict[str, float]][source]#

Remove biomass when a cohort consumes this soil pool.

In contrast to the LitterPool case, for soil pools mechanical efficiency is assumed to be 100% so does not factor into this calculation.

Parameters:

consumed_mass – Target wet-mass to consume (kg). Any attempt to over-consume is automatically capped.
detritivore – The cohort that is feeding, this is only needed to maintain same function signature as SoilPool case

Returns:

Dictionary of element masses actually assimilated, keys C, N, P (kg).

property mass_current: float#: Return current carbon mass in the pool [kg].

vertical_occupancy: VerticalOccupancy = 1#: Vertical position of soil pool.

virtual_ecosystem.models.animal.decay.find_decay_consumed_split(microbial_decay_rate: float, animal_scavenging_rate: float)[source]#

Find fraction of biomass that is assumed to decay rather than being scavenged.

This should be calculated separately for each relevant biomass type (excrement and carcasses). This function should could be replaced in future by something that incorporates more of the factors determining this split (e.g. temperature).

Parameters:

microbial_decay_rate – Rate at which biomass type decays due to microbes [day^-1]
animal_scavenging_rate – Rate at which biomass type is scavenged due to animals [day^-1]

API for the decay module#

API for the `decay` module#