diff --git a/docs/source/virtual_ecosystem/implementation/animal_implementation.md b/docs/source/virtual_ecosystem/implementation/animal_implementation.md index 08dc48073..7125f578f 100644 --- a/docs/source/virtual_ecosystem/implementation/animal_implementation.md +++ b/docs/source/virtual_ecosystem/implementation/animal_implementation.md @@ -1,15 +1,205 @@ --- -jupyter: - jupytext: - cell_metadata_filter: all,-trusted - main_language: python - notebook_metadata_filter: settings,mystnb,language_info - text_representation: - extension: .md - format_name: markdown - format_version: '1.3' - jupytext_version: 1.16.4 +jupytext: + formats: md:myst + main_language: python + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.16.4 +kernelspec: + display_name: Python 3 (ipykernel) + language: python + name: python3 +language_info: + codemirror_mode: + name: ipython + version: 3 + file_extension: .py + mimetype: text/x-python + name: python + nbconvert_exporter: python + pygments_lexer: ipython3 + version: 3.11.9 --- +# Animal Model Implementation -# The Animal Model implementation +## Model Overview + +The animal model in the Virtual Ecosystem platform represents the dynamics of animal +communities. The implementation is structured +around three core classes, each playing a distinct role in managing animal agents, their +traits, and their interactions with the ecosystem. Together, these classes facilitate a +flexible and scalable approach to simulating complex animal processes across spatial +grids. + +- [Functional Group](https://virtual-ecosystem.readthedocs.io/en/latest/api/models/animal/functional_group.html) + - the organismal type and its traits +- [Animal Cohort](https://virtual-ecosystem.readthedocs.io/en/latest/api/models/animal/animal_cohorts.html) + - the agent, a group of identical individuals of the same functional group and age +- [Animal Model](https://virtual-ecosystem.readthedocs.io/en/latest/api/models/animal/animal_model.html#virtual_ecosystem.models.animal.animal_model.AnimalModel) + - the structural class, orchestrating the interactions between cohorts and their environment. + +### Core Classes + +#### **1. FunctionalGroup** + +The `FunctionalGroup` class encapsulates the fixed traits of an organism, defining its +ecological role and life-history strategy. These traits include metabolic type, diet, +taxonomic classification, reproductive strategy, and developmental type. Functional +groups serve as templates for constructing animal cohorts and ensuring consistent trait +inheritance across simulations. + +Key responsibilities: + +- Encodes fixed traits shared by cohorts within the group. +- Provides scaling factors that scale processes like territory size and prey selection + to the mass of individuals within a cohort +- Defines dietary and physiological constraints that influence cohort behavior. + +#### **2. AnimalCohort** + +The `AnimalCohort` class represents a group of identically sized individual animal agents +from a single functional group: a cohort. Each cohort is age-specific, meaning all +individuals in the cohort were produced in the same reproductive event and share the same +age. The class tracks dynamic state variables such as mass, age, reproductive biomass, + and territory occupancy. + +Key attributes: + +- **Dynamic state variables**: Mass, age, individuals, reproductive mass, and more. +- **Territory management**: Tracks the spatial extent of a cohort's interactions with + resources and other cohorts. +- **Lifecycle processes**: Handles maturity, mortality, and metamorphosis. + +#### **3. AnimalModel** + +The `AnimalModel` class orchestrates the animal community at the spatial grid level. +It contains methods for initialization, setup, and updating of the animal model as well as +communication with the core data object. The animal +model provides methods that loop over all cohorts in the simulation to simulate community +processes, along with methods to handle cohort movement, creation and death. + +Key responsibilities: + +- **Cohort management**: Initializes, updates, and removes animal cohorts. +- **Spatial dynamics**: Tracks cohort occupancy across grid cells and handles migration. +- **Community-level processes**: Foraging, mortality, birth, metamorphosis, and more. + +### Code Structure + +The `AnimalModel` is a subclass of `BaseModel`, integrating into the broader +Virtual Ecosystem framework. It extends the base functionality to include animal-specific +methods and attributes, ensuring compatibility with other ecosystem modules such as +vegetation, litter, and soil. + +Key components: + +- **Initialization**: Sets up the grid structure for animal movement, functional groups, + and resource pools for excrement, carcasses, and leaf waste. +- **Cohort-level methods**: Implements functions to handle cohort-specific processes + (e.g., `birth`, `metamorphose`, `forage`). +- **Community-level methods**: Manages collective processes for all cohorts in a grid cell + (e.g., `migrate_community`, `metabolize_community`, `remove_dead_cohort_community`). +- **State updates**: Updates population densities, litter consumption, and nutrient + contributions to the soil. + +## Sequence of Operations in the Animal Model + +The animal model follows a sequence of operations designed to simulate the dynamic +interactions of animal cohorts with their environment. The ordering of events may be +revised in the future. + +1. **Initialize Litter Pools** + Litter pools accessible to animals for consumption are populated using the + `populate_litter_pools` method. These pools are referenced during foraging and + consumption calculations. + +2. **Foraging** + Animal cohorts forage for resources within their communities using the + `forage_community` method. Resource consumption is determined by cohort traits and + resource availability. + +3. **Migration** + Cohorts migrate between grid cells based on birth events and resource + availability using the `migrate_community` method. Migration updates the spatial + distribution of cohorts. + +4. **Birth** + New cohorts are generated through reproduction using the `birth_community` method. + Parent cohorts allocate biomass from their reproductive mass to create new cohorts. + +5. **Metamorphosis** + Larval cohorts transition into adult cohorts using the `metamorphose_community` + method. This transition updates the cohort's traits and functional role. + +6. **Metabolism** + Cohorts metabolize consumed resources, processing consumed matter into waste and + fueling internal processes. This is handled by the `metabolize_community` method, + which considers the update interval duration. + +7. **Mortality** + Non-predation mortality is applied to cohorts using the + `inflict_non_predation_mortality_community` method. Mortality may be caused by + starvation, disease, aging, or background mortality. + +8. **Remove Dead Cohorts** + Cohorts that have no remaining individuals are removed from the simulation using the + `remove_dead_cohort_community` method. Their biomass contributes to excrement or + carcass pools. + +9. **Increase Cohort Age** + Cohorts are aged by the simulation time step using the `increase_age_community` + method. This tracks the progression of cohorts toward maturity and mortality. + +10. **Calculate Additions to Soil and Litter** + The contributions of animal activities to the soil and litter models are calculated: + - **Soil Additions**: Biomass from excrement, carcasses, and waste is transferred to + the soil using the `calculate_soil_additions` method. + - **Litter Consumption**: The total animal consumption of litter pools is calculated + using the `calculate_total_litter_consumption` method. + - **Litter Additions**: Biomass from herbivory (e.g., unconsumed plant material) is + added to litter pools using the `calculate_litter_additions_from_herbivory` method. + +11. **Update Simulation State** + Updates to soil and litter pools are recorded in the data object. Population densities + for each functional group in each grid cell are updated using the + `update_population_densities` method. + +This sequence allows the animal model to dynamically interact with other ecosystem +modules, such as soil and vegetation, while maintaining an organized computational flow. +The modular structure ensures that individual processes can be refined without disrupting +the overall simulation. + +## Model Variables + +### Initialisation, Generated, and Updated Variables + +The following tables show the variables required to initialise and update the animal +model, the variables generated during the first update, and the variables updated at +each model step. + +```{code-cell} ipython3 +--- +mystnb: + markdown_format: myst +tags: [remove-input] +--- +from IPython.display import display_markdown +from var_generator import generate_variable_table + +# Variables required for initialisation and update +display_markdown( + generate_variable_table("AnimalModel", ["vars_required_for_update"]), + raw=True, +) + +# Variables generated during the first update +display_markdown( + generate_variable_table("AnimalModel", ["vars_populated_by_first_update"]), raw=True +) + +# Variables updated at each model step +display_markdown(generate_variable_table("AnimalModel", ["vars_updated"]), raw=True) +``` diff --git a/docs/source/virtual_ecosystem/theory/animals/animal_theory.md b/docs/source/virtual_ecosystem/theory/animals/animal_theory.md index 2bce1e515..9dd5837b1 100644 --- a/docs/source/virtual_ecosystem/theory/animals/animal_theory.md +++ b/docs/source/virtual_ecosystem/theory/animals/animal_theory.md @@ -23,12 +23,205 @@ language_info: version: 3.11.9 --- -# Theory of the animals +# Theory of the Animal Model + +This page outlines the theoretical basis for the animal model within the Virtual +Ecosystem. It details the representation of functional groups and cohorts, +the processes governing their interactions with the environment, and their contributions +to ecosystem-level dynamics. The page also highlights the key state variables tracked +for each cohort and the links between animal processes and other ecosystem modules. :::{admonition} In progress 🛠️ -This is a high level landing page from animal theory, that will be filled out at a later -date. +Much of the Animal Model follows the logic of the Madingley Model {cite}`harfoot_madingley_2014` +with modifications made for differences in spatial and temporal scale, trophic +resolution, multi-grid cell occupancy, and ecological stoichiometry. + +The theoretical framework for animal stoichiometric cycling and water balance is still +being refined. As such, some sections are relatively brief and will be expanded as the +model evolves. + +::: + +## Functional Groups + +Instead of modeling species individually, the animal model uses **functional groups** +to define cohort types. Functional groups aggregate species based on shared ecological +roles and traits, enabling scalable simulations while maintaining ecological fidelity. + +This approach has several advantages: + +- **Trait-based generalization**: Functional groups are defined by traits such as body +size, diet, metabolic rate, reproductive strategy, and excretory type, rather than +specific taxonomic identity. +- **Scalability**: Simplifies the representation of biodiversity, allowing the model to +simulate large ecosystems with diverse communities without overwhelming computational +resources. +- **Focus on ecosystem function**: Prioritizes the ecological roles of organisms (e.g., +herbivores, scavengers, predators) and their impacts on ecosystem dynamics over +species-specific details. + +### Traits Defining Functional Groups + +Functional groups in the animal model are constructed based on a combination of core +traits that capture the diversity of ecological roles and physiological strategies. These +traits include: + +#### **Metabolic Type** + +The primary strategy for thermoregulation: + +- **Endothermic**: Animals that regulate their body temperature internally (e.g., mammals, + birds). +- **Ectothermic**: Animals whose body temperature is influenced by the external environment + (e.g., reptiles, amphibians, insects). + +#### **Diet Type** + +The primary dietary habits: + +- **Herbivore**: Consumes plant material as the primary food source. +- **Carnivore**: Consumes other animals as the primary food source. + +Additional dietary categories under development: + +- **Scavenger**: Consumes dead animals or carrion as a primary food source. +- **Omnivore**: Consumes a mix of plant and animal materials. +- **Detritivore**: Consumes decomposing organic material, including soil. +- **Coprophage**: Consumes feces as a significant food source. +- **Ectoparasite**: Feeds on the external surfaces of a host organism. + +#### **Taxa Type** + +A broad classification based on taxonomic group: + +- **Mammal** +- **Bird** +- **Insect** + +Additional taxa categories under development: + +- **Reptile** +- **Amphibian** + +#### **Reproductive Type** + +The reproductive strategy: + +- **Semelparous**: Reproduces once in a lifetime, often producing many offspring (e.g., some + insects, salmon). +- **Iteroparous**: Reproduces multiple times over a lifetime, typically with fewer offspring + per event. +- **Nonreproductive**: Does not engage in reproduction (e.g., non-reproductive life stages). + +#### **Development Type** + +The path of development: + +- **Direct**: Development involves no major morphological transformation; juveniles resemble + adults (e.g., mammals, birds). +- **Indirect**: Development involves significant morphological changes (e.g., metamorphosis + in insects or amphibians). + +#### **Development Status** + +The life stage of the cohort: + +- **Larval**: Juvenile stage, morphologically distinct from the adult form in indirect +developers. +- **Adult**: Mature stage, typically capable of reproduction. + +#### **Excretion Type** + +The strategy for nitrogen waste excretion: + +- **Ureotelic**: Excretes nitrogen primarily as urea (e.g., mammals). +- **Uricotelic**: Excretes nitrogen primarily as uric acid (e.g., birds, reptiles). + +## Representation of Animal Cohorts + +In the animal model, **cohorts** represent groups of individuals within a functional group +that are of the same age and were produced in the same reproductive event by a parent +cohort. This age-specific approach simplifies tracking population dynamics while +maintaining biological realism. + +### Key Features of Animal Cohorts + +Animal cohorts are the fundamental agents in the animal model, designed to simulate the +growth, movement, reproduction, and survival of populations. Each cohort tracks a set of +state variables that evolve through ecological processes: + +- **Functional Group**: Each cohort belongs to a functional group, which defines its + ecological role, such as herbivore or carnivore, along with its physiological and + behavioral traits. +- **Mass**: Represents the average body mass of individuals in the cohort (in kilograms), + which changes dynamically as individuals grow or lose biomass. +- **Age**: Tracks the cohort's age in days. +- **Number of Individuals**: The population size of the cohort. +- **Reproductive Mass**: A dedicated biomass pool for reproduction, which accumulates as + individuals allocate resources to reproductive efforts. +- **Location and Territory**: Cohorts occupy specific territories on the simulation grid, + interacting with local resources and environmental conditions. Their **territory size** + is determined by their functional group’s traits, such as adult body mass. +- **Occupancy Proportion**: Tracks how much of a cohort occupies a specific grid cell + within its territory. + +## Key Animal Processes + +The animal model incorporates several processes that determine cohort dynamics and their +influence on the ecosystem: + +### Foraging and Consumption + +- **Diet specificity**: Determines what resources a cohort consumes (e.g., plants, other +animals, detritus). +- **Mass and stoichiometry**: Tracks the intake of carbon, nitrogen, and phosphorus and +their allocation to different pools (e.g., body mass, reproductive mass). + +### Metabolism and Maintenance + +- **Energy and nutrient use**: Models the metabolic cost of maintaining body functions. +- **Waste production**: Generates excretory and respiratory byproducts, linking animal +processes to soil nutrient dynamics. + +### Growth and Reproduction + +- **Somatic growth**: Simulates the conversion of consumed resources into body mass. +- **Reproductive allocation**: Tracks resource allocation to offspring production, with +reproduction resulting in new cohorts. + +### Mortality and Carcass Dynamics + +- **Mortality causes**: Includes predation, background mortality, starvation, and old age. +- **Carcass generation**: Links the fate of animal biomass to scavenger activity, +decomposition, and soil nutrient inputs. + +### Migration and Movement + +- **Resource tracking**: Animals move across grid cells based on resource availability +and reproductive events. +- **Home range dynamics**: Simulates spatial patterns of movement and habitat use. + +## Links to Ecosystem Dynamics + +The animal model is tightly integrated with other modules in the Virtual Ecosystem +platform: + +- **Vegetation**: Herbivores affect plant biomass directly through consumption and +indirectly through nutrient cycling. +- **Litter**: Animals contribute to litter through unconsumed plant material produced +during foraging. +- **Soil**: Animal wastes and carcasses feed into soil pools through decomposition. +- **Microclimate**: Animal metabolic rates are influenced by local microclimates. + +## Scaling and Challenges + +- **Scaling individual processes to ecosystems**: Balancing fine-scale detail with +computational efficiency for large landscapes. +- **Trait diversity**: Representing the wide range of animal functional traits within a +cohesive framework. +- **Temporal and spatial dynamics**: Capturing short-term behaviors and long-term +ecosystem impacts within the same model. :::