API for the animal_model module

The animal_model module creates a AnimalModel class as a child of the BaseModel class. At present a lot of the abstract methods of the parent class (e.g. setup() and spinup()) are overwritten using placeholder functions that don’t do anything. This will change as the Virtual Ecosystem model develops. The factory method from_config() exists in a more complete state, and unpacks a small number of parameters from our currently pretty minimal configuration dictionary. These parameters are then used to generate a class instance. If errors crop up here when converting the information from the config dictionary to the required types (e.g. timedelta64) they are caught and then logged, and at the end of the unpacking an error is thrown. This error should be caught and handled by downstream functions so that all model configuration failures can be reported as one.

Classes:

AnimalModel(data, core_components, ...[, ...])

A class describing the animal model.

class virtual_ecosystem.models.animals.animal_model.AnimalModel(data: Data, core_components: CoreComponents, functional_groups: list[FunctionalGroup], model_constants: AnimalConsts = AnimalConsts(), **kwargs: Any)

A class describing the animal model.

Describes the specific functions and attributes that the animal module should possess.

Parameters:

• data – The data object to be used in the model.

• core_components – The core components used across models.

• functional_groups – The list of animal functional groups present in the simulation.

• model_constants – Set of constants for the animal model.

Methods:

calculate_density_for_cohort(cohort)	Calculate the population density for a cohort within a specific community.
calculate_litter_additions()	Calculate the how much animal matter should be transferred to the litter.
cleanup()	Placeholder function for animal model cleanup.
from_config(data, core_components, config)	Factory function to initialise the animal model from configuration.
get_community_by_key(key)	Function to return the AnimalCommunity present in a given grid square.
setup()	Method to setup the animal model specific data variables.
spinup()	Placeholder function to spin up the animal model.
update(time_index, **kwargs)	Function to step the animal model through time.
update_population_densities()	Updates the densities for each functional group in each community.

Attributes:

communities	Set empty dict for populating with communities.
functional_groups	List of functional groups in the model.
model_constants	Animal constants.
update_interval_timedelta	Convert pint update_interval to timedelta64 once during initialization.

calculate_density_for_cohort(cohort: AnimalCohort) → float

Calculate the population density for a cohort within a specific community.

TODO: This will need to be modified for multi-grid occupancy.

Parameters:

• cohort – The AnimalCohort object for which to calculate the density.

• community_id – The identifier for the community where the cohort resides.

Returns:

The population density of the cohort within the community (individuals/m2).

calculate_litter_additions() → dict[str, DataArray]

Calculate the how much animal matter should be transferred to the litter.

cleanup() → None

Placeholder function for animal model cleanup.

communities: dict[int, AnimalCommunity]

Set empty dict for populating with communities.

core_constants: CoreConsts

The core constants used in the model.

data: Data

A Data instance providing access to the shared simulation data.

classmethod from_config(data: Data, core_components: CoreComponents, config: Config) → AnimalModel

Factory function to initialise the animal model from configuration.

This function unpacks the relevant information from the configuration file, and then uses it to initialise the model. If any information from the config is invalid rather than returning an initialised model instance None is returned.

Parameters:

• data – A Data instance.

• core_components – The core components used across models.

• config – A validated Virtual Ecosystem model configuration object.

functional_groups

List of functional groups in the model.

get_community_by_key(key: int) → AnimalCommunity

Function to return the AnimalCommunity present in a given grid square.

This function exists principally to provide a callable for AnimalCommunity.

Parameters:

key – The specific grid square integer key associated with the community.

Returns:

The AnimalCommunity object in that grid square.

layer_structure: LayerStructure

The LayerStructure details used in the model.

model_constants

Animal constants.

model_timing: ModelTiming

The ModelTiming details used in the model.

model_update_bounds: tuple[pint.Quantity, pint.Quantity] = (<Quantity(1, 'day')>, <Quantity(1, 'month')>)

Bounds on model update frequencies.

This class attribute defines two time intervals that define a lower and upper bound on the update frequency that can reasonably be used with a model. Models updated more often than the lower bound may fail to capture transient dynamics and models updated more slowly than the upper bound may fail to capture important temporal patterns.

required_init_vars: tuple[tuple[str, tuple[str, ...]], ...] = ()

Required variables for model initialisation.

This class property defines a set of variable names that must be present in the Data instance used to initialise an instance of this class. It is a tuple containing zero or more tuples, each providing a variable name and then a tuple of zero or more core axes that the variable must map onto.

For example: (('temperature', ('spatial', 'temporal')),)

setup() → None

Method to setup the animal model specific data variables.

spinup() → None

Placeholder function to spin up the animal model.

update(time_index: int, **kwargs: Any) → None

Function to step the animal model through time.

Temporary solution.

This method sets the order of operations for the animal module. In nature, these events would be simultaneous. The ordering within the method is less a question of the science and more a question of computational logic and stability.

Parameters:

time_index – The index representing the current time step in the data object.

update_interval_timedelta

Convert pint update_interval to timedelta64 once during initialization.

update_population_densities() → None

Updates the densities for each functional group in each community.

vars_updated: tuple[str, ...] = ('decomposed_excrement', 'decomposed_carcasses', 'total_animal_respiration')

Variables that are updated by the model.

At the moment, this tuple is used to decide which variables to output from the Data object, i.e. every variable updated by a model used in the specific simulation. In future, this could also be used to prevent multiple models from updating the same variable and similar problems.