API for the `animal_communities` module

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

Notes: - assume each grid = 1 km2 - assume each tick = 1 day (28800s) - damuth ~ 4.23*mass**(-3/4) indiv / km2

Classes:

AnimalCommunity(functional_groups, data, ...)

This is a class for the animal community of a grid cell.

class virtual_ecosystem.models.animals.animal_communities.AnimalCommunity(functional_groups: list[FunctionalGroup], data: Data, community_key: int, neighbouring_keys: list[int], get_destination: Callable[[int], AnimalCommunity], constants: AnimalConsts = AnimalConsts())

This is a class for the animal community of a grid cell.

This class manages the animal cohorts present in a grid cell and provides methods that need to loop over all cohorts, move cohorts to new grids, or manage an interaction between two cohorts.

Parameters:

functional_groups – A list of FunctionalGroup objects
data – The core data object
community_key – The integer key of the cell id for this community
neighbouring_keys – A list of cell id keys for neighbouring communities
get_destination – A function to return a destination AnimalCommunity for migration.

Attributes:

`all_animal_cohorts`	Get an iterable of all animal cohorts in the community.
`animal_cohorts`	A dictionary of lists of animal cohort keyed by functional group.
`carcass_pool`	A pool for animal carcasses within the community.
`community_key`	Integer designation of the community in the model grid.
`constants`	Animal constants.
`data`	A reference to the core data object.
`excrement_pool`	A pool for excrement within the community.
`functional_groups`	A list of all FunctionalGroup types in the model.
`get_destination`	Callable get_destination from AnimalModel.
`neighbouring_keys`	List of integer keys of neighbouring communities.

Methods:

`birth`(parent_cohort)	Produce a new AnimalCohort through reproduction.
`birth_community`()	This handles birth for all cohorts in a community.
`collect_prey`(consumer_cohort)	Collect suitable prey for a given consumer cohort.
`forage_community`()	This function organizes the foraging of animal cohorts.
`increase_age_community`(dt)	This handles age for all cohorts in a community.
`inflict_natural_mortality_community`(dt)	This handles natural mortality for all cohorts in a community.
`metabolize_community`(temperature, dt)	This handles metabolize for all cohorts in a community.
`migrate`(migrant, destination)	Function to move an AnimalCohort between AnimalCommunity objects.
`migrate_community`()	This handles migrating all cohorts in a community.
`populate_community`()	This function creates an instance of each functional group.
`remove_dead_cohort`(cohort)	Remove a dead cohort from a community.
`remove_dead_cohort_community`()	This handles remove_dead_cohort for all cohorts in a community.

property all_animal_cohorts: Iterable[AnimalCohort]

Get an iterable of all animal cohorts in the community.

This property provides access to all the animal cohorts contained within this community class.

Returns:: An iterable of AnimalCohort objects.
Return type:: Iterable[AnimalCohort]

animal_cohorts: dict[str, list[AnimalCohort]]: A dictionary of lists of animal cohort keyed by functional group.

birth(parent_cohort: AnimalCohort) → None

Produce a new AnimalCohort through reproduction.

A cohort can only reproduce if it has an excess of reproductive mass above a certain threshold. The offspring will be an identical cohort of adults with age 0 and mass=birth_mass.

The science here follows Madingley.

TODO: Implement juvenile dispersal. TODO: Check whether madingley discards excess reproductive mass

Parameters:

parent_cohort – The AnimalCohort instance which is producing a new
AnimalCohort. –

birth_community() → None: This handles birth for all cohorts in a community.

carcass_pool: CarcassPool: A pool for animal carcasses within the community.

collect_prey(consumer_cohort: AnimalCohort) → list[AnimalCohort]

Collect suitable prey for a given consumer cohort.

This is a helper function for forage_community to isolate the prey selection functionality. It was already getting confusing and it will get much more so as the Animal Module develops.

Parameters:: consumer_cohort – The AnimalCohort for which a prey list is being collected
Returns:: A list of AnimalCohorts that can be preyed upon.

community_key: Integer designation of the community in the model grid.

constants: Animal constants.

data: A reference to the core data object.

excrement_pool: ExcrementPool: A pool for excrement within the community.

forage_community() → None

This function organizes the foraging of animal cohorts.

It loops over every animal cohort in the community and calls the forage_cohort function with a list of suitable trophic resources. This action initiates foraging for those resources, with mass transfer details handled internally by forage_cohort and its helper functions. Future expansions may include functions for handling scavenging and soil consumption behaviors.

Cohorts with no remaining individuals post-foraging are marked for death.

functional_groups: A list of all FunctionalGroup types in the model.

get_destination: Callable get_destination from AnimalModel.

increase_age_community(dt: timedelta64) → None

This handles age for all cohorts in a community.

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

inflict_natural_mortality_community(dt: timedelta64) → None

This handles natural mortality for all cohorts in a community.

TODO Replace the number_of_days format with a passthrough of the initialized dt straight to the scaling function that sets the cohort rates.

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

metabolize_community(temperature: float, dt: timedelta64) → None

This handles metabolize for all cohorts in a community.

Parameters:

temperature – Current air temperature (K).
dt – Number of days over which the metabolic costs should be calculated.

migrate(migrant: AnimalCohort, destination: AnimalCommunity) → None

Function to move an AnimalCohort between AnimalCommunity objects.

This function should take a cohort and a destination community and then pop the cohort from this community to the destination.

Travel distance is not currently a function of body-size or locomotion for starvation dispersal.

TODO: Implement low-density trigger. [might not actually do this, requires: cohort merging.]

Parameters:

migrant – The AnimalCohort moving between AnimalCommunities.
destination – The AnimalCommunity the cohort is moving to.

migrate_community() → None

This handles migrating all cohorts in a community.

This migration method initiates migration for two reasons: 1) The cohort is starving and needs to move for a chance at resource access 2) An initial migration event immediately after birth.

neighbouring_keys: List of integer keys of neighbouring communities.

populate_community() → None

This function creates an instance of each functional group.

Currently, this is the simplest implementation of populating the animal model. In each AnimalCommunity one AnimalCohort of each FunctionalGroup type is generated. So the more functional groups that are made, the denser the animal community will be. This function will need to be reworked dramatically later on.

Currently, the number of individuals in a cohort is handled using Damuth’s Law, which only holds for mammals.

remove_dead_cohort(cohort: AnimalCohort) → None

Remove a dead cohort from a community.

Parameters:: cohort – The AnimalCohort instance that has lost all individuals.

remove_dead_cohort_community() → None: This handles remove_dead_cohort for all cohorts in a community.

API for the animal_communities module

API for the `animal_communities` module