API for the animal_cohorts module

The ‘’animal’’ module provides animal module functionality.

Classes:

AnimalCohort(functional_group, mass, age, ...)

This is a class of animal cohorts.

class virtual_ecosystem.models.animal.animal_cohorts.AnimalCohort(functional_group: FunctionalGroup, mass: float, age: float, individuals: int, centroid_key: int, grid: Grid, constants: AnimalConstants = AnimalConstants(), core_constants: CoreConstants = CoreConstants())

This is a class of animal cohorts.

Methods:

F_i_j_individual(target_cohort, ...)	Method to determine instantaneous predation rate on cohort j.
F_i_k(resource, potential_biomass_consumed, ...)	Calculate the instantaneous consumption rate on a plant resource.
calculate_alpha()	Calculate search efficiency.
calculate_consumed_mass_predation(...)	Calculates the mass to be consumed from a prey cohort by the predator.
calculate_potential_prey_consumed(alpha, ...)	Calculate the potential number of prey consumed.
calculate_predation_search_rate(w_bar)	Calculate the search rate of the predator.
calculate_predation_success_probability(M_target)	Calculate the probability of a successful predation event.
calculate_theta_opt_i()	Calculate the optimal predation param based on predator-prey mass ratio.
calculate_total_handling_time_for_herbivory(...)	Calculate total handling time across all plant resources.
calculate_total_handling_time_for_predation(...)	Calculate the total handling time term for the predation functional response.
can_forage_on(resource)	Check if the cohort can forage on a given non-cohort resource pool.
can_prey_on(prey_cohort)	Check if the cohort can prey upon another cohort.
defecate(excrement_pools, mass_consumed)	Transfers unassimilated waste mass from an cohort to the excrement pools.
delta_mass_bacteriophagy(bacteria_list, ...)	Handle mass assimilation from soil bacteria.
delta_mass_carcass_scavenging(carcass_pools, ...)	Handle mass assimilation from carcass scavenging.
delta_mass_detritivory(litter_pools, adjusted_dt)	Handle mass assimilation from litter (detritivory).
delta_mass_excrement_scavenging(...)	Handle mass assimilation from excrement (coprophagy).
delta_mass_fruiting_fungivory(...)	Handle mass assimilation from fruiting body (mushroom) fungivory.
delta_mass_herbivory(plant_list, ...)	Handle mass assimilation from live plant herbivory.
delta_mass_pomivory(pom_list, adjusted_dt)	Handle mass assimilation from POM (particulate organic matter) foraging.
delta_mass_predation(animal_list, ...)	Handles mass assimilation from predation.
delta_mass_soil_fungivory(soil_fungi_list, ...)	Handle mass assimilation from soil fungi foraging.
die_individual(number_of_deaths, carcass_pools)	Handles the death of individuals in the cohort.
eat(mass_consumed, excrement_pools)	Handles the mass gain from consuming food and processes waste.
excrete(excreta_mass, excrement_pools)	Transfers metabolic wastes to the excrement pools.
find_intersecting_carcass_pools(...)	Find the carcass pools in the territorial overlap with another cohort.
forage_cohort(array_resource_list, ...)	Coordinate all resource consumption for a single cohort.
forage_resource_list(resources, adjusted_dt, ...)	Generic foraging function for all non-predation resources.
get_array_resources(array_resources)	Return array resources accessible within this cohort's territory.
get_bacteria_pools(soil_pools)	Return soil bacteria pools within the cohort's territory.
get_carcass_pools(carcass_pools)	Return carcass pools within the cohort's territory.
get_eaten(potential_consumed_mass, predator, ...)	Handles predation, removing individuals and distributing biomass.
get_excrement_pools(excrement_pools)	Return excrement pools within the cohort's territory.
get_fungal_fruit_pools(fungal_fruiting_bodies)	Return fungal fruiting-body pools within the cohort's territory.
get_herbivory_waste_pools(plant_waste)	Returns a list of herbivory waste pools in this territory.
get_mean_territory_climate(...)	Mean temperature and diurnal range across this cohort's full territory.
get_plant_resources(plant_resources)	Return plant resources accessible within this cohort's territory.
get_pom_pools(soil_pools)	Return soil POM pools within the cohort's territory.
get_prey(communities, prey_diet)	Collect suitable prey cohorts within the cohort's territory.
get_soil_fungi_pools(soil_pools)	Return soil fungi pools within the cohort's territory.
get_stratum_climate(cell_id, ...)	Mean temperature and diurnal range experienced by this cohort in a cell.
get_territory_cells(centroid_key)	This calls bfs_territory to determine the scope of the territory.
get_territory_intersection(other_cohort)	Find the overlapping cells and area between this cohort and another cohort.
grow(resource_intake)	Handles growth based on resource intake, enforcing stoichiometry.
increase_age(dt)	The function to modify cohort age as time passes and flag maturity.
inflict_non_predation_mortality(dt, ...)	Inflict combined background, senescence, and starvation mortalities.
is_below_mass_threshold(mass_threshold)	Check if cohort's total mass is below a certain threshold.
is_migration_season()	Handles determination of whether it is time to migrate.
match_vertical(resource_occupancy)	Check whether cohort vertical occupancy overlaps with a resource or prey.
metabolize(temperature, dt)	The function to reduce body carbon mass through metabolism.
migrate_juvenile_probability()	The probability that a juvenile cohort will migrate to a new grid cell.
record_trophic_transfer(resource_key, delta)	Accumulate a trophic mass transfer for the current timestep.
reset_trophic_record()	Reset the trophic transfer record for a new timestep.
respire(excreta_mass)	Transfers carbonaceous metabolic wastes to the atmosphere.
theta_i_j(animal_list, theta_opt, target_bin)	Cumulative density of prey within the same mass bin as the target prey.
update_activity_window(temperature, ...)	Update the activity window fraction and current temperature.
update_carcass_pool(C, N, P, carcass_pools)	Updates the carcass pools after deaths.
update_largest_mass()	Update the record of the largest body-mass achieved by this cohort.
update_territory(new_grid_cell_keys)	Update territory details at initialization and after migration.

Attributes:

age	The age of the animal cohort [days].
centroid_key	The centroid key of the cohort's territory.
cnp_proportions	The normalized stoichiometric proportions that constrains growth.
constants	Animal constants.
core_constants	Core constants.
current_temperature	Mean territory temperature [°C] last recorded by update_activity_window().
decay_fraction_carcasses	The fraction of carcass biomass which decays before it gets consumed.
decay_fraction_excrement	The fraction of excrement which decays before it gets consumed.
diet_category_count	The number of different diet categories consumed by the cohort.
functional_group	The functional group of the animal cohort which holds constants.
grid	The the grid structure of the simulation.
id	A unique identifier for the cohort.
individuals	The number of individuals in this cohort.
is_alive	Whether the cohort is alive [True] or dead [False].
is_mature	Whether the cohort has reached adult body-mass.
largest_mass_achieved	The largest body-mass ever achieved by this cohort [kg].
location_status	Location status of the cohort, active means present and participating.
mass_cnp	The mass of C, N, and P in the cohort, from total mass and proportions.
mass_current	Dynamically calculate the current total body mass from CNP object.
name	The functional type name of the animal cohort.
occupancy_proportion	The proportion of the cohort that is within a grid cell of territory.
prey_groups	The identification of usable food resources.
remaining_time_away	Remaining time that the cohort is frozen in a migrated or aquatic state.
reproductive_mass	Dynamically calculate the current reproductive mass from CNP object.
reproductive_mass_cnp	The reproductive mass of each stoichiometric element found in the animal cohort, {"C": value, "N": value, "P": value}.
sigma_f_t	The Activity window fraction in [0, 1].
territory	The list of grid cells currently occupied by the cohort.
territory_cells	The number of grid cells the cohort occupies.
territory_size	The size in m2 of the animal cohort's territory.
time_since_maturity	The amount of time [days] since reaching adult body-mass.
time_to_maturity	The amount of time [days] between birth and adult body-mass.
trophic_record	A record of the mass transfer from resource to consumer during the timestep.

F_i_j_individual(target_cohort: AnimalCohort, intersection_area: float, theta_opt: float, bin_densities: dict[int, float], total_handling_time: float) → float

Method to determine instantaneous predation rate on cohort j.

Implements the Holling type II functional response for predation. All encounter-level quantities (theta_opt, bin_densities, total_handling_time) are pre-computed once per encounter in delta_mass_predation and passed in to avoid redundant recomputation across prey.

Parameters:

• target_cohort – The prey cohort from which mass will be consumed.

• intersection_area – Pre-computed overlap area between predator and target territories in m2.

• theta_opt – This predator’s optimal prey-predator mass ratio, drawn once per encounter in delta_mass_predation.

• bin_densities – Pre-computed mapping of mass bin index to cumulative prey density, built once per encounter by _build_prey_bin_densities.

• total_handling_time – Pre-computed Holling type II denominator sum ∑(K_i,m · H_i,m), built once per encounter in delta_mass_predation.

Returns:

Float fraction of target cohort consumed per day.

F_i_k(resource: Resource | CellResource, potential_biomass_consumed: float, total_handling_t: float) → float

Calculate the instantaneous consumption rate on a plant resource.

Implements the Holling Type II functional response for herbivory.

Parameters:

• resource – The target plant resource being consumed.

• potential_biomass_consumed – Potential biomass eaten from the target resource in a day [g/day].

• total_handling_t – Pre-computed dimensionless handling time sum across all available resources, built once per foraging bout in forage_resource_list.

Returns:

The instantaneous consumption rate [1/day] of the target resource.

age

The age of the animal cohort [days].

calculate_alpha() → float

Calculate search efficiency.

This utilizes the alpha_i_k scaling function to determine the effective rate at which an individual herbivore searches its environment, factoring in the herbivore’s current mass.

TODO: update name

Returns:

A float representing the search efficiency rate in [m2/(day*g)].

calculate_consumed_mass_predation(target_cohort: AnimalCohort, adjusted_dt: timedelta64, intersection_area: float, theta_opt: float, bin_densities: dict[int, float], total_handling_time: float) → float

Calculates the mass to be consumed from a prey cohort by the predator.

This method utilizes the F_i_j_individual method to determine the rate at which the target cohort is consumed, and then calculates the actual mass to be consumed based on this rate and other model parameters.

Parameters:

• target_cohort – The prey cohort from which mass will be consumed.

• adjusted_dt – The amount of time (D) in the time-step available for foraging.

• intersection_area – Pre-computed overlap area between predator and target territories in m2.

• theta_opt – This predator’s optimal prey-predator mass ratio, drawn once per encounter in delta_mass_predation.

• bin_densities – Pre-computed mapping of mass bin index to cumulative prey density, built once per encounter by _build_prey_bin_densities.

• total_handling_time – Pre-computed Holling type II denominator sum ∑(K_i,m · H_i,m), built once per encounter in delta_mass_predation.

Returns:

The mass to be consumed from the target cohort by the predator (in kg).

calculate_potential_prey_consumed(alpha: float, theta_i_j: float, intersection_area: float) → float

Calculate the potential number of prey consumed.

Parameters:

• alpha – The predation search rate in m2/(day*g).

• theta_i_j – The cumulative density of organisms with a mass lying within the same predator specific mass bin.

• intersection_area – The overlapping area between predator and prey territories in m2.

Returns:

The potential number of prey items consumed.

calculate_predation_search_rate(w_bar: float) → float

Calculate the search rate of the predator.

Parameters:

w_bar – Probability of successfully capturing prey.

Returns:

A float value of the search rate in m2/day

calculate_predation_success_probability(M_target: float) → float

Calculate the probability of a successful predation event.

Parameters:

M_target – the body mass of the animal cohort being targeted for predation.

Returns:

A float value of the probability that a predation event is successful.

calculate_theta_opt_i() → float

Calculate the optimal predation param based on predator-prey mass ratio.

TODO: update name

Returns:

Float value of the optimal predation parameter for use in calculating the probability of a predation event being successful.

calculate_total_handling_time_for_herbivory(plant_list: list[Resource] | list[CellResource], alpha: float) → float

Calculate total handling time across all plant resources.

Computes the denominator sum Σ K_i,l · H_i,l from the Holling Type II functional response,

Parameters:

• plant_list – A list of plant resources available for consumption by the cohort.

• alpha – The search efficiency rate of the herbivore cohort.

Returns:

Dimensionless sum of handling time across all plant resources (days of handling per day of searching).

calculate_total_handling_time_for_predation(animal_list: list[AnimalCohort], theta_opt: float, bin_densities: dict[int, float], intersection_areas: dict[int, float]) → float

Calculate the total handling time term for the predation functional response.

Computes the denominator sum ∑(K_i,m · H_i,m) from Equations 28/29 of Harfoot et al. (2014), which represents the total time in days, per day spent searching, that would be taken to handle all potential prey items across all prey cohorts. This is dimensionless (days of handling per day of searching) and forms the saturation term in the Holling Type II denominator: 1 + ∑(K_i,m · H_i,m).

Parameters:

• animal_list – All prey cohorts available to the predator.

• theta_opt – The predator’s optimum prey-predator mass ratio for this encounter, drawn once per encounter in delta_mass_predation.

• bin_densities – Pre-computed mapping of mass bin index to cumulative prey density, built once per encounter by _build_prey_bin_densities.

• intersection_areas – Pre-computed mapping of prey cohort id to territory intersection area in m², built once per encounter in delta_mass_predation.

Returns:

Dimensionless sum of handling time across all prey cohorts (days of handling per day of searching).

can_forage_on(resource: Resource) → bool

Check if the cohort can forage on a given non-cohort resource pool.

This will soon be expanded to include more suitability checks.

Parameters:

resource – A non-cohort resource pool object implementing the Resource protocol.

Returns:

True if the cohort and resource share overlapping vertical occupancy, False otherwise.

can_prey_on(prey_cohort: AnimalCohort) → bool

Check if the cohort can prey upon another cohort.

Determines if another animal cohort is suitable prey based on the predator’s defined prey groups, prey body mass, and vertical occupancy.

Parameters:

prey_cohort – An animal cohort potentially being preyed upon.

Returns:

True if the prey cohort meets size, identity, and vertical occupancy

criteria, False otherwise.

centroid_key

The centroid key of the cohort’s territory.

cnp_proportions: dict[str, float]

The normalized stoichiometric proportions that constrains growth.

constants

Animal constants.

core_constants

Core constants.

current_temperature: float

Mean territory temperature [°C] last recorded by update_activity_window(). Seeded to the placeholder annual mean so that endotherms and any cohort that calls metabolize() before its first activity-window update receive a physically reasonable value.

decay_fraction_carcasses: float

The fraction of carcass biomass which decays before it gets consumed.

decay_fraction_excrement: float

The fraction of excrement which decays before it gets consumed.

defecate(excrement_pools: list[ExcrementPool], mass_consumed: dict[str, float]) → None

Transfers unassimilated waste mass from an cohort to the excrement pools.

Parameters:

• excrement_pools – List of excrement pools for waste distribution.

• mass_consumed – Dictionary specifying the mass of each element in the consumed food.

Raises:

ValueError – If mass_consumed is missing required keys or contains negative values.

delta_mass_bacteriophagy(bacteria_list: list[Resource], adjusted_dt: timedelta64) → dict[str, float]

Handle mass assimilation from soil bacteria.

Parameters:

• bacteria_list – List of soil bacteria resources.

• adjusted_dt – Time available for foraging.

Returns:

Stoichiometric mass gained by the cohort.

delta_mass_carcass_scavenging(carcass_pools: list[Resource], adjusted_dt: timedelta64) → dict[str, float]

Handle mass assimilation from carcass scavenging.

Parameters:

• carcass_pools – List of carcass pools available to the cohort.

• adjusted_dt – Time available for foraging.

Returns:

Stoichiometric mass gained by the cohort.

delta_mass_detritivory(litter_pools: list[CellResource], adjusted_dt: timedelta64) → dict[str, float]

Handle mass assimilation from litter (detritivory).

Parameters:

• litter_pools – List of litter pools available to the cohort.

• adjusted_dt – Time available for foraging.

Returns:

Stoichiometric mass gained by the cohort.

delta_mass_excrement_scavenging(excrement_pools: list[Resource], adjusted_dt: timedelta64) → dict[str, float]

Handle mass assimilation from excrement (coprophagy).

Parameters:

• excrement_pools – List of excrement pools available to the cohort.

• adjusted_dt – Time available for foraging.

Returns:

Stoichiometric mass gained by the cohort.

delta_mass_fruiting_fungivory(fungal_fruit_list: list[Resource], adjusted_dt: timedelta64, herbivory_waste_pools: dict[int, HerbivoryWaste]) → dict[str, float]

Handle mass assimilation from fruiting body (mushroom) fungivory.

Parameters:

• fungal_fruit_list – List of fungal fruiting resources.

• adjusted_dt – Time available for foraging.

• herbivory_waste_pools – Waste pools for unassimilated fungal matter.

Returns:

Stoichiometric mass gained by the cohort.

delta_mass_herbivory(plant_list: list[CellResource], adjusted_dt: timedelta64, herbivory_waste_pools: dict[int, HerbivoryWaste]) → dict[str, float]

Handle mass assimilation from live plant herbivory.

Parameters:

• plant_list – List of live plant resources.

• adjusted_dt – Time available for foraging.

• herbivory_waste_pools – Waste pools for unassimilated plant matter.

Returns:

Stoichiometric mass gained by the cohort.

delta_mass_pomivory(pom_list: list[Resource], adjusted_dt: timedelta64) → dict[str, float]

Handle mass assimilation from POM (particulate organic matter) foraging.

Parameters:

• pom_list – List of particulate organic matter soil resources.

• adjusted_dt – Time available for foraging.

Returns:

Stoichiometric mass gained by the cohort.

delta_mass_predation(animal_list: list[AnimalCohort], carcass_pools: dict[int, list[CarcassPool]], adjusted_dt: timedelta64) → dict[str, float]

Handles mass assimilation from predation.

This is Madingley’s delta_assimilation_mass_predation.

Pre-computes territory intersections, draws theta_opt once, and builds the prey bin density dict.

Parameters:

• animal_list – A list of animal cohorts that can be consumed by the predator.

• carcass_pools – The pools to which animal carcasses are delivered.

• adjusted_dt – The amount of time (D) in the time-step available for foraging.

Returns:

A dictionary representing the total change in mass (C, N, P) experienced by the predator: {“C”: value, “N”: value, “P”: value}.

Raises:

• ValueError – If animal_list or carcass_pools is None.

• ValueError – If prey_cohort.get_eaten() returns None.

• ValueError – If self.calculate_consumed_mass_predation() returns None.

delta_mass_soil_fungivory(soil_fungi_list: list[Resource], adjusted_dt: timedelta64) → dict[str, float]

Handle mass assimilation from soil fungi foraging.

Parameters:

• soil_fungi_list – List of soil fungi resources (distinct from fruiting bodies).

• adjusted_dt – Time available for foraging.

Returns:

Stoichiometric mass gained by the cohort.

die_individual(number_of_deaths: int, carcass_pools: list[CarcassPool]) → None

Handles the death of individuals in the cohort.

Transfers the biomass of dead individuals to the carcass pools, distributing mass between scavengeable and decomposed compartments.

Parameters:

• number_of_deaths (int) – Number of individuals dying in the cohort.

• carcass_pools (list[CarcassPool]) – Carcass pools receiving remains.

Raises:

ValueError – If number_of_deaths is invalid or exceeds the cohort size.

diet_category_count: int

The number of different diet categories consumed by the cohort.

eat(mass_consumed: dict[str, float], excrement_pools: list[ExcrementPool]) → None

Handles the mass gain from consuming food and processes waste.

This method updates the consumer’s mass based on the amount of food consumed in stoichiometric terms. It also handles waste by calling defecate with any excess nutrients after growth.

Parameters:

• mass_consumed – A dictionary representing the mass of each nutrient consumed by this consumer: {“C”: value, “N”: value, “P”: value}.

• excrement_pools – The ExcrementPool objects in the cohort’s territory in which waste is deposited.

Raises:

• ValueError – If mass_consumed contains negative values or missing keys.

• ValueError – If no excrement pools are provided.

excrete(excreta_mass: dict[str, float], excrement_pools: list[ExcrementPool]) → None

Transfers metabolic wastes to the excrement pools.

Parameters:

• excreta_mass – Mass of C, N, and P to be excreted as a dictionary.

• excrement_pools – List of excrement pools for distributing waste.

Raises:

ValueError – For invalid keys or negative values in excreta_mass.

find_intersecting_carcass_pools(other_cohort: AnimalCohort, carcass_pools: dict[int, list[CarcassPool]]) → list[CarcassPool]

Find the carcass pools in the territorial overlap with another cohort.

Parameters:

• other_cohort – The other cohort to find the territorial intersection with.

• carcass_pools – A dictionary mapping cell IDs to CarcassPool objects.

Returns:

A list of CarcassPools in the intersecting grid cells.

forage_cohort(array_resource_list: list[CellResource], animal_list: list[AnimalCohort], fungal_fruit_list: list[Resource], soil_fungi_list: list[Resource], pom_list: list[Resource], bacteria_list: list[Resource], excrement_pools: list[ExcrementPool], carcass_pool_map: dict[int, list[CarcassPool]], scavenge_carcass_pools: list[Resource], scavenge_excrement_pools: list[Resource], herbivory_waste_pools: dict[int, HerbivoryWaste], dt: timedelta64) → None

Coordinate all resource consumption for a single cohort.

This wrapper collects every resource class the cohort can exploit (plants, prey, litter, carcasses, excrement) and calls the specialised delta_mass_ helpers. It also passes the full deposition pools (excrement_pools, carcass_pool_map) so that waste and carcass remains are always routed correctly, even if the cohort is not actively scavenging.

Parameters:

• array_resource_list – Full set of resources available through the array resources interface, at present this consists of the living plants and dead plant detritus (litter).

• animal_list – Live prey cohorts available for predation.

• fungal_fruit_list – Live fungal fruiting bodies available for consumption.

• soil_fungi_list – Soil fungi pools (not fruiting bodies).

• pom_list – Soil particulate organic matter pools (POM).

• bacteria_list – Soil bacteria pools.

• excrement_pools – ExcrementPool objects used for defecation deposition.

• carcass_pool_map – Mapping cell_id → list[CarcassPool] that receives carcass remains created during predation.

• scavenge_carcass_pools – Subset of CarcassPool objects in the territory from which the cohort will attempt to scavenge.

• scavenge_excrement_pools – Subset of ExcrementPool objects in the territory that the cohort will consume via coprophagy.

• herbivory_waste_pools – Mapping cell_id → HerbivoryWaste for litter generated by partial plant consumption.

• dt – Time (D) in the time step.

forage_resource_list(resources: list[Resource] | list[CellResource], adjusted_dt: timedelta64, resource_kind: str, herbivory_waste_pools: dict[int, HerbivoryWaste] | None = None) → dict[str, float]

Generic foraging function for all non-predation resources.

Implements a Holling Type II functional response over a list of resources. Cohort-level quantities (search efficiency and total handling time) are precomputed once per foraging bout before the resource loop.

Elemental mass values returned by get_eaten are clamped to remove floating point noise before being passed to downstream validators. Values more negative than _ELEMENTAL_MASS_NOISE_TOLERANCE are left unchanged and will raise in record_trophic_transfer or add_waste.

Parameters:

• resources – List of foragable resources.

• adjusted_dt – Time available for foraging.

• resource_kind – A string label of the resource type, used as a key in trophic transfer records.

• herbivory_waste_pools – Optional mapping of cell_id to waste pool for unassimilated biomass. If None, mechanical losses are discarded.

Returns:

Stoichiometric mass gained by the cohort (kg of C, N, P).

functional_group

The functional group of the animal cohort which holds constants.

get_array_resources(array_resources: list[ResourcePool]) → list[CellResource]

Return array resources accessible within this cohort’s territory.

This method filters the array resources by territory and the cohort’s foraging capability (via can_forage_on).

Parameters:

array_resources – A list of ResourcePool instances.

Returns:

A list of CellResource objects that the cohort can forage on.

get_bacteria_pools(soil_pools: dict[int, dict[str, SoilPool]]) → list[Resource]

Return soil bacteria pools within the cohort’s territory.

Parameters:

soil_pools – Mapping from cell_id to SoilPool objects keyed by ‘fungi’, ‘pom’, and ‘bacteria’.

Returns:

List of bacterial Resource objects within the territory.

get_carcass_pools(carcass_pools: dict[int, list[CarcassPool]]) → list[CarcassPool]

Return carcass pools within the cohort’s territory.

This method returns all CarcassPool objects located in grid cells that the cohort occupies.

Parameters:

carcass_pools – A dictionary mapping cell IDs to lists of CarcassPool objects.

Returns:

A list of CarcassPool objects in the cohort’s territory.

get_eaten(potential_consumed_mass: float, predator: AnimalCohort, carcass_pools: dict[int, list[CarcassPool]]) → dict[str, float]

Handles predation, removing individuals and distributing biomass.

TODO: does mechanical efficiency need to be moved? not sure

Parameters:

• potential_consumed_mass – The mass intended to be consumed by the predator.

• predator – The predator consuming the cohort.

• carcass_pools – The pools to which remains of eaten individuals are delivered.

Returns:

A dictionary of the actual mass consumed by the predator in stoichiometric

terms.

get_excrement_pools(excrement_pools: dict[int, list[ExcrementPool]]) → list[ExcrementPool]

Return excrement pools within the cohort’s territory.

This method returns all ExcrementPool objects that are located in grid cells occupied by the cohort.

Parameters:

excrement_pools – A dictionary mapping cell IDs to lists of ExcrementPool objects.

Returns:

A list of ExcrementPool objects in the cohort’s territory.

get_fungal_fruit_pools(fungal_fruiting_bodies: dict[int, FungalFruitPool]) → list[Resource]

Return fungal fruiting-body pools within the cohort’s territory.

Parameters:

fungal_fruiting_bodies – The fungal fruiting pools the model.

Returns:

A list of fungal fruiting-body Resource objects available in the cohort’s territory.

get_herbivory_waste_pools(plant_waste: dict[int, HerbivoryWaste]) → list[HerbivoryWaste]

Returns a list of herbivory waste pools in this territory.

This method checks which grid cells are within this territory and returns a list of the herbivory waste pools available in those grid cells.

Parameters:

plant_waste – A dictionary of herbivory waste pools where keys are grid cell IDs.

Returns:

A list of HerbivoryWaste objects in this territory.

get_mean_territory_climate(canopy_temperature: ndarray[tuple[Any, ...], dtype[_ScalarT]], ground_temperature: ndarray[tuple[Any, ...], dtype[_ScalarT]], soil_temperature: ndarray[tuple[Any, ...], dtype[_ScalarT]], canopy_diurnal_range: ndarray[tuple[Any, ...], dtype[_ScalarT]], ground_diurnal_range: ndarray[tuple[Any, ...], dtype[_ScalarT]], soil_diurnal_range: ndarray[tuple[Any, ...], dtype[_ScalarT]]) → tuple[float, float]

Mean temperature and diurnal range across this cohort’s full territory.

Calls get_stratum_climate() for each cell in the cohort’s territory and returns the unweighted mean of both climate variables. Arrays should be pre-computed per-cell stratum means before calling — see update_activity_windows_community().

Parameters:

• canopy_temperature – 1-D array of per-cell mean filled canopy temperatures [°C], shape (n_cells,).

• ground_temperature – 1-D array of surface air temperatures [°C], shape (n_cells,).

• soil_temperature – 1-D array of topsoil temperatures [°C], shape (n_cells,).

• canopy_diurnal_range – 1-D array of per-cell mean filled canopy diurnal temperature ranges [°C], shape (n_cells,).

• ground_diurnal_range – 1-D array of surface diurnal temperature ranges [°C], shape (n_cells,).

• soil_diurnal_range – 1-D array of topsoil diurnal temperature ranges [°C], shape (n_cells,).

Returns:

A tuple of (temperature, diurnal_range), each the mean across all territory cells and occupied strata [°C].

get_plant_resources(plant_resources: dict[int, list[Resource]]) → list[Resource]

Return plant resources accessible within this cohort’s territory.

This method filters the plant resources by territory and the cohort’s foraging capability (via can_forage_on).

Parameters:

plant_resources – A dictionary mapping cell IDs to lists of plant resource objects.

Returns:

A list of plant Resource objects that the cohort can forage on.

get_pom_pools(soil_pools: dict[int, dict[str, SoilPool]]) → list[Resource]

Return soil POM pools within the cohort’s territory.

Parameters:

soil_pools – Mapping from cell_id to SoilPool objects keyed by ‘fungi’, ‘pom’, and ‘bacteria’.

Returns:

List of POM Resource objects within the territory.

get_prey(communities: dict[int, list[AnimalCohort]], prey_diet: DietType) → list[AnimalCohort]

Collect suitable prey cohorts within the cohort’s territory.

This method filters candidate prey by: 1) Spatial overlap (cohort territory), 2) Predation feasibility (can_prey_on), 3) Taxonomic category requested by prey_diet flags

Parameters:

• communities – Dictionary mapping cell IDs to lists of animal cohorts.

• prey_diet – Diet flags specifying which prey categories are allowed, e.g. DietType.VERTEBRATES, DietType.INVERTEBRATES, or both.

Returns:

List of animal cohorts that can be preyed upon.

get_soil_fungi_pools(soil_pools: dict[int, dict[str, SoilPool]]) → list[Resource]

Return soil fungi pools within the cohort’s territory.

Parameters:

soil_pools – Mapping from cell_id to SoilPool objects keyed by ‘fungi’, ‘pom’, and ‘bacteria’.

Returns:

List of soil-fungi Resource objects within the territory.

get_stratum_climate(cell_id: int, canopy_temperature: ndarray[tuple[Any, ...], dtype[_ScalarT]], ground_temperature: ndarray[tuple[Any, ...], dtype[_ScalarT]], soil_temperature: ndarray[tuple[Any, ...], dtype[_ScalarT]], canopy_diurnal_range: ndarray[tuple[Any, ...], dtype[_ScalarT]], ground_diurnal_range: ndarray[tuple[Any, ...], dtype[_ScalarT]], soil_diurnal_range: ndarray[tuple[Any, ...], dtype[_ScalarT]]) → tuple[float, float]

Mean temperature and diurnal range experienced by this cohort in a cell.

Averages both climate variables across all occupied vertical strata. The arrays should be pre-computed per-cell means for each stratum before calling — see update_activity_windows_community().

The stratum-to-array mapping is:

• CANOPY — mean of filled canopy layer values, one value per cell.

• GROUND — surface layer value, one value per cell.

• SOIL — topsoil layer value, one value per cell.

Parameters:

• cell_id – Index of the grid cell to evaluate.

• canopy_temperature – 1-D array of per-cell mean filled canopy temperatures [°C], shape (n_cells,).

• ground_temperature – 1-D array of surface air temperatures [°C], shape (n_cells,).

• soil_temperature – 1-D array of topsoil temperatures [°C], shape (n_cells,).

• canopy_diurnal_range – 1-D array of per-cell mean filled canopy diurnal temperature ranges [°C], shape (n_cells,).

• ground_diurnal_range – 1-D array of surface diurnal temperature ranges [°C], shape (n_cells,).

• soil_diurnal_range – 1-D array of topsoil diurnal temperature ranges [°C], shape (n_cells,).

Returns:

A tuple of (temperature, diurnal_range), each the mean across all occupied strata for the given cell [°C].

Raises:

ValueError – If the cohort’s vertical occupancy contains no recognised flags.

get_territory_cells(centroid_key: int) → list[int]

This calls bfs_territory to determine the scope of the territory.

Parameters:

centroid_key – The central grid cell key of the territory.

get_territory_intersection(other_cohort: AnimalCohort) → tuple[set[int], float]

Find the overlapping cells and area between this cohort and another cohort.

Parameters:

other_cohort – The prey cohort to find the territorial overlap with.

Returns:

A tuple of the set of overlapping cell IDs and the total intersection area in m2.

grid

The the grid structure of the simulation.

grow(resource_intake: dict[str, float]) → dict[str, float]

Handles growth based on resource intake, enforcing stoichiometry.

Parameters:

resource_intake – A dictionary of the mass of C, N, and P available for intake.

Returns:

A dictionary of the excess elements (waste) that could not be used for

growth.

id: UUID

A unique identifier for the cohort.

increase_age(dt: timedelta64) → None

The function to modify cohort age as time passes and flag maturity.

Parameters:

dt – The amount of time that should be added to cohort age.

individuals

The number of individuals in this cohort.

inflict_non_predation_mortality(dt: float, carcass_pools: list[CarcassPool]) → None

Inflict combined background, senescence, and starvation mortalities.

The number of deaths is drawn from a binomial distribution with trial size pop_size and per-individual death probability 1 - exp(-u_t * dt) where u_t is the sum of background, senescence, and starvation mortality rates.

Parameters:

• dt – The time passed in the timestep (days).

• carcass_pools – The local carcass pool to which dead individuals go.

is_alive: bool

Whether the cohort is alive [True] or dead [False].

is_below_mass_threshold(mass_threshold: float) → bool

Check if cohort’s total mass is below a certain threshold.

Currently used for thesholding: birth, dispersal, trophic flow to reproductive mass.

Parameters:

mass_threshold – a float value holding a threshold ratio of current total mass to standard adult mass.

Returns:

A bool of whether the current mass state is above the migration threshold.

is_mature: bool

Whether the cohort has reached adult body-mass.

is_migration_season() → bool

Handles determination of whether it is time to migrate.

Temporary probabilistic migration.

TODO: update when we have seasonality

Returns: A bool of whether it is time to migrate.

Notes

This method uses Python’s built-in random.random() function.

largest_mass_achieved: float

The largest body-mass ever achieved by this cohort [kg].

location_status: Literal['active', 'migrated', 'aquatic']

Location status of the cohort, active means present and participating.

mass_cnp

The mass of C, N, and P in the cohort, from total mass and proportions.

property mass_current: float

Dynamically calculate the current total body mass from CNP object.

match_vertical(resource_occupancy: VerticalOccupancy) → bool

Check whether cohort vertical occupancy overlaps with a resource or prey.

This method determines whether the vertical occupancy of the consumer cohort overlaps with the vertical occupancy of a resource (pool or cohort). Animals can only forage resources that share at least one overlapping vertical space.

Parameters:

resource_occupancy – The vertical occupancy trait of the potential resource or prey.

Returns:

True if the vertical occupancy overlaps; False otherwise.

metabolize(temperature: float, dt: timedelta64) → dict[str, float]

The function to reduce body carbon mass through metabolism.

This method reduces the carbon component of the cohort’s body mass through metabolic activity. Metabolism is a function of environmental temperature for ectotherms, while endotherms are unaffected by temperature changes.

TODO: Update with stoichiometry for nitrogen and phosphorus.

Parameters:

• temperature – Current air temperature (K).

• dt – Number of days over which the metabolic costs should be calculated.

Returns:

The total carbon mass metabolized by the cohort.

migrate_juvenile_probability() → float

The probability that a juvenile cohort will migrate to a new grid cell.

TODO: This does not hold for diagonal moves or non-square grids.

Following Madingley’s assumption that the probability of juvenile dispersal is equal to the proportion of the cohort individuals that would arrive in the neighboring cell after one full timestep’s movement.

Assuming cohort individuals are homogeneously distributed within a grid cell and that the move is non-diagonal, the probability is then equal to the ratio of dispersal speed to the side-length of a grid cell.

A homogeneously distributed cohort with a partial presence in a grid cell will have a proportion of its individuals in the new grid cell equal to the proportion the new grid cell that it occupies (A_new / A_cell). This proportion will be equal to the cohorts velocity (V) multiplied by the elapsed time (t) multiplied by the length of one side of a grid cell (L) (V*t*L) (t is assumed to be 1 here). The area of the square grid cell is the square of the length of one side. The proportion of individuals in the new cell is then: A_new / A_cell = (V * T * L) / (L * L) = ((L/T) * T * L) / (L * L ) = dimensionless [m2 / m2 = (m/d * d * m) / (m * m) = m / m = dimensionless]

Returns:

The probability of diffusive natal dispersal to a neighboring grid cell.

name

The functional type name of the animal cohort.

occupancy_proportion: float

The proportion of the cohort that is within a grid cell of territory.

prey_groups: dict[str, tuple[float, float]]

The identification of usable food resources.

record_trophic_transfer(resource_key: tuple[str, str], delta: CNP) → None

Accumulate a trophic mass transfer for the current timestep.

Values are stored as a simple dict of floats for easy export. This records the total CNP mass removed from a given resource by this cohort during the current timestep.

Parameters:

• resource_key – A tuple of (resource_kind, resource_id), where both elements are strings.

• delta – The CNP mass removed from the resource in a single feeding event.

Raises:

ValueError – If any element of delta is negative.

remaining_time_away: float

Remaining time that the cohort is frozen in a migrated or aquatic state.

property reproductive_mass: float

Dynamically calculate the current reproductive mass from CNP object.

reproductive_mass_cnp

The reproductive mass of each stoichiometric element found in the animal cohort, {“C”: value, “N”: value, “P”: value}.

reset_trophic_record() → None

Reset the trophic transfer record for a new timestep.

respire(excreta_mass: dict[str, float]) → float

Transfers carbonaceous metabolic wastes to the atmosphere.

This method processes the metabolic waste for carbon and returns the total mass respired to the atmosphere as a float. Currently, only carbon is affected.

TODO: This method needs to be properly fleshed out or it will produce a small error in carbon totals.

Parameters:

excreta_mass – A dictionary representing the mass of each nutrient excreted by the cohort: {“C”: value, “N”: value, “P”: value}.

Returns:

A float representing the total carbon mass respired to the atmosphere.

sigma_f_t: float

The Activity window fraction in [0, 1].

territory: list[int]

The list of grid cells currently occupied by the cohort.

territory_cells

The number of grid cells the cohort occupies.

territory_size

The size in m2 of the animal cohort’s territory.

theta_i_j(animal_list: list[AnimalCohort], theta_opt: float, target_bin: int) → float

Cumulative density of prey within the same mass bin as the target prey.

Implements Equation 38 of Harfoot et al. (2014). Sums the density of all prey cohorts that fall in the same predator-specific mass bin as the target cohort, where bin assignment follows Equation 39 (_mass_bin).

Parameters:

• animal_list – Prey cohorts available to this predator.

• theta_opt – This predator’s optimal prey-predator mass ratio for this foraging encounter, drawn once per encounter and passed in to ensure consistency with the w_bar_i_j calculation.

• target_bin – The bin index of the target prey cohort, computed by the caller via _mass_bin prior to this call.

Returns:

Cumulative prey density in individuals per m² within the matching bin.

time_since_maturity: float

The amount of time [days] since reaching adult body-mass.

time_to_maturity: float

The amount of time [days] between birth and adult body-mass.

trophic_record: dict[tuple[str, str], dict[str, float]]

A record of the mass transfer from resource to consumer during the timestep. tuple[“kind”, “id”] where kind is a str resource category and id is a uuid or a cell_id. Value example: {“C”: 1.2, “N”: 0.08, “P”: 0.01}

update_activity_window(temperature: float, diurnal_temp_range: float, annual_mean_temp: float, annual_temp_sd: float) → None

Update the activity window fraction and current temperature.

Delegates to activity_window() and stores the result in sigma_f_t. Should be called once per timestep, before both forage_cohort() and metabolize().

If the cohort’s functional group has t_opt, t_max_crit, and t_min_crit set from CSV input, those values are used directly. Otherwise the toy climate parameters from AnimalConstants are used to derive thermal tolerances.

Parameters:

• temperature – Monthly mean ambient temperature [°C].

• diurnal_temp_range – Monthly mean diurnal temperature range [°C].

• annual_mean_temp – Annual mean ambient temperature [°C].

• annual_temp_sd – Standard deviation of monthly temperatures across the climatological year [°C].

update_carcass_pool(C: float, N: float, P: float, carcass_pools: list[CarcassPool]) → None

Updates the carcass pools after deaths.

Distributes carcass mass among pools, dividing it into scavengeable and decomposed fractions.

Parameters:

• C (float) – The total carbon mass to be distributed.

• N (float) – The total nitrogen mass to be distributed.

• P (float) – The total phosphorus mass to be distributed.

• carcass_pools (list[CarcassPool]) – The carcass pools receiving the biomass.

Raises:

ValueError – If any input mass is negative or no carcass pools are provided.

update_largest_mass() → None

Update the record of the largest body-mass achieved by this cohort.

This provides a rough approximation of the development process. Once maturity is achieved, adult mass becomes the reference for starvation as normal.

update_territory(new_grid_cell_keys: list[int]) → None

Update territory details at initialization and after migration.

Parameters:

new_grid_cell_keys – The new list of grid cell keys the territory occupies.