Added animal_implementation docs file.

docs/source/virtual_ecosystem/implementation/animal_implementation.md

@@ -1,15 +1,196 @@
 ---
-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.
+
+### 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 parameters for processes like territory size and prey selection.
+- Defines dietary and physiological constraints that influence cohort behavior.
+
+#### **2. AnimalCohort**
+
+The `AnimalCohort` class represents individual animal agents at the cohort level. 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 initializion, setup, and updating of the animal model as well as
+communication with the core data object. Cohort-facing methods found within the animal
+model are either community-level processes which loop over all cohorts in the simulation
+or are methods pertaining to the creation, destruction, or movement of animal chorts.
+
+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, 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
+   fueing 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)
+```

docs/source/virtual_ecosystem/theory/animals/animal_theory.md

@@ -156,12 +156,11 @@ state variables that evolve through ecological processes:
   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, ensuring that individuals in the same cohort
-  remain at the same life stage.
+- **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.
-- **Grid and Territory**: Cohorts occupy specific territories on the simulation grid,
+- **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
@@ -193,29 +192,27 @@ reproduction resulting in new cohorts.
 
 ### Mortality and Carcass Dynamics
 
-- **Mortality causes**: Includes predation, starvation, and old age.
+- **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 environmental conditions.
+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 and nutrient cycling through grazing
-and trampling.
-- **Litter**: Animals contribute to litter through unconsumed plant material and
-indirect interactions (e.g., breaking branches).
-- **Soil**: Excrement and carcasses provide nutrient inputs, while burrowing and
-trampling modify soil structure.
-- **Microclimate**: Animal behaviors (e.g., shading, burrowing) influence local
-microclimatic conditions.
+- **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