Merge pull request #894 from ImperialCollegeLondon/887-animal-model---handling-starvation-during-ontogeny

887 animal model   handling starvation during ontogeny

Author: TaranRallings

tests/models/animals/test_animal_cohorts.py

@@ -3097,3 +3097,45 @@ def test_get_litter_pools(
         result = cohort.get_litter_pools(test_litter_pools)
 
         assert len(result) == expected
+
+    @pytest.mark.parametrize(
+        "carbon, nitrogen, phosphorus, initial_largest_mass, expected_largest_mass",
+        [
+            # Grows, still under adult mass
+            (6.0, 1.0, 0.5, 5.0, 7.5),
+            # Grows past adult mass, should cap
+            (50.0, 10.0, 5.0, 20.0, "cap_to_adult"),
+            # No growth, mass lower than previous largest
+            (4.0, 0.5, 0.2, 10.0, 10.0),
+        ],
+    )
+    def test_update_largest_mass(
+        self,
+        herbivore_cohort_instance,
+        carbon,
+        nitrogen,
+        phosphorus,
+        initial_largest_mass,
+        expected_largest_mass,
+    ):
+        """Test update_largest_mass."""
+
+        # Set up current mass via mass_cnp
+        herbivore_cohort_instance.mass_cnp.carbon = carbon
+        herbivore_cohort_instance.mass_cnp.nitrogen = nitrogen
+        herbivore_cohort_instance.mass_cnp.phosphorus = phosphorus
+
+        # Set initial largest_mass_achieved
+        herbivore_cohort_instance.largest_mass_achieved = initial_largest_mass
+
+        # Call update
+        herbivore_cohort_instance.update_largest_mass()
+
+        # Determine expected value
+        if expected_largest_mass == "cap_to_adult":
+            expected = herbivore_cohort_instance.functional_group.adult_mass
+        else:
+            expected = expected_largest_mass
+
+        # Assertion
+        assert herbivore_cohort_instance.largest_mass_achieved == expected

tests/models/animals/test_animal_model.py

@@ -165,8 +165,8 @@ def test_update_method_sequence(self, mocker, prepared_animal_model_instance):
             "metamorphose_community",
             "metabolize_community",
             "inflict_non_predation_mortality_community",
-            "remove_dead_cohort_community",
-            "increase_age_community",
+            "update_community_bookkeeping",
+            "update_cohort_bookkeeping",
         ]
 
         # Setup mock methods using spy on the prepared_animal_model_instance itself
@@ -2164,3 +2164,65 @@ def test_create_new_cohort_routing(
         else:
             assert cohort.id in animal_model_instance.active_cohorts
             spy_occ.assert_called_once_with(cohort, 0)
+
+    def test_update_community_bookkeeping(self, mocker, prepared_animal_model_instance):
+        """Test update_community_bookkeeping."""
+
+        # Spy on the three submethods
+        mocker.spy(prepared_animal_model_instance, "update_migrated_and_aquatic")
+        mocker.spy(prepared_animal_model_instance, "reintegrate_community")
+        mocker.spy(prepared_animal_model_instance, "remove_dead_cohort_community")
+
+        # Call the bookkeeping method
+        prepared_animal_model_instance.update_community_bookkeeping(
+            dt=np.timedelta64(1, "D")
+        )
+
+        # Assert each method was called exactly once
+        assert (
+            prepared_animal_model_instance.update_migrated_and_aquatic.call_count == 1
+        )
+        assert prepared_animal_model_instance.reintegrate_community.call_count == 1
+        assert (
+            prepared_animal_model_instance.remove_dead_cohort_community.call_count == 1
+        )
+
+    def test_update_cohort_bookkeeping(self, mocker, prepared_animal_model_instance):
+        """Test that update_cohort_bookkeeping calls both age and ontogeny methods."""
+
+        # Spy on the model-level methods
+        mocker.spy(prepared_animal_model_instance, "increase_age_community")
+        mocker.spy(prepared_animal_model_instance, "handle_ontogeny")
+
+        # Call the method
+        prepared_animal_model_instance.update_cohort_bookkeeping(
+            dt=np.timedelta64(1, "M")
+        )
+
+        # Assert both were called once
+        assert prepared_animal_model_instance.increase_age_community.call_count == 1
+        assert prepared_animal_model_instance.handle_ontogeny.call_count == 1
+
+    def test_handle_ontogeny_calls_update_on_immature_cohorts(
+        self, mocker, prepared_animal_model_instance
+    ):
+        """Test handle_ontogeny."""
+
+        # Create two mock cohorts
+        mock_mature = mocker.Mock()
+        mock_mature.is_mature = True
+        mock_immature = mocker.Mock()
+        mock_immature.is_mature = False
+
+        # Add them to active_cohorts
+        prepared_animal_model_instance.active_cohorts = {
+            "mature": mock_mature,
+            "immature": mock_immature,
+        }
+
+        # Call the method
+        prepared_animal_model_instance.handle_ontogeny()
+
+        # Assert that only the immature cohort's update_largest_mass was called
+        mock_immature.update_largest_mass.assert_called_once()
+        mock_mature.update_largest_mass.assert_not_called()

virtual_ecosystem/models/animal/animal_cohorts.py

@@ -109,6 +109,8 @@ def __init__(
         self.reproductive_mass_cnp = CNP(0.0, 0.0, 0.0)
         """The reproductive mass of each stoichiometric element found in the animal
           cohort, {"carbon": value, "nitrogen": value, "phosphorus": value}."""
+        self.largest_mass_achieved: float = mass
+        """The largest body-mass ever achieved by this cohort [kg]."""
 
     @property
     def mass_current(self) -> float:
@@ -120,6 +122,19 @@ def reproductive_mass(self) -> float:
         """Dynamically calculate the current reproductive mass from CNP object."""
         return self.reproductive_mass_cnp.total
 
+    def update_largest_mass(self) -> 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.
+
+        """
+
+        if self.mass_current > self.largest_mass_achieved:
+            self.largest_mass_achieved = min(
+                self.mass_current, self.functional_group.adult_mass
+            )
+
     def get_territory_cells(self, centroid_key: int) -> list[int]:
         """This calls bfs_territory to determine the scope of the territory.
 
@@ -1472,7 +1487,7 @@ def inflict_non_predation_mortality(
 
         t_to_maturity = self.time_to_maturity
         t_since_maturity = self.time_since_maturity
-        mass_max = self.functional_group.adult_mass  # this might not be only solution
+        mass_max = self.largest_mass_achieved  # growth to adult_mass
 
         u_bg = sf.background_mortality(
             self.constants.u_bg

virtual_ecosystem/models/animal/animal_model.py

@@ -363,9 +363,6 @@ def _update(self, time_index: int, **kwargs: Any) -> None:
         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.
 
-        TODO: update so that it just cycles through the community methods, each of those
-        will cycle through all cohorts in the model
-
         Args:
             time_index: The index representing the current time step in the data object.
             **kwargs: Further arguments to the update method.
@@ -382,10 +379,8 @@ def _update(self, time_index: int, **kwargs: Any) -> None:
         self.migrate_external_community()
         self.metabolize_community(self.update_interval_timedelta)
         self.inflict_non_predation_mortality_community(self.update_interval_timedelta)
-        self.update_migrated_and_aquatic(self.update_interval_timedelta)
-        self.reintegrate_community()
-        self.remove_dead_cohort_community()
-        self.increase_age_community(self.update_interval_timedelta)
+        self.update_community_bookkeeping(self.update_interval_timedelta)
+        self.update_cohort_bookkeeping(self.update_interval_timedelta)
 
         # Now that communities have been updated information required to update the
         # soil and litter models can be extracted
@@ -401,6 +396,35 @@ def _update(self, time_index: int, **kwargs: Any) -> None:
         # Update population densities
         self.update_population_densities()
 
+    def update_community_bookkeeping(self, dt: timedelta64) -> None:
+        """Perform status updates and cleanup at the community level.
+
+        This includes:
+        - Updating timers for migrated or aquatic cohorts
+        - Reintegration of previously inactive cohorts
+        - Removal of dead cohorts
+
+        Args:
+            dt: Time step duration [days].
+        """
+
+        self.update_migrated_and_aquatic(dt)
+        self.reintegrate_community()
+        self.remove_dead_cohort_community()
+
+    def update_cohort_bookkeeping(self, dt: timedelta64) -> None:
+        """Perform lifecycle-related updates for each cohort.
+
+        This includes:
+        - Increasing age
+        - Updating largest mass achieved
+
+        Args:
+            dt: Time step duration [days].
+        """
+        self.increase_age_community(dt)
+        self.handle_ontogeny()
+
     def cleanup(self) -> None:
         """Placeholder function for animal model cleanup."""
 
@@ -1139,6 +1163,16 @@ def increase_age_community(self, dt: timedelta64) -> None:
         for cohort in self.active_cohorts.values():
             cohort.increase_age(dt)
 
+    def handle_ontogeny(self) -> None:
+        """Update largest body mass achieved for immature cohorts.
+
+        This is used to support ontogeny-aware starvation calculations.
+        """
+
+        for cohort in self.active_cohorts.values():
+            if not cohort.is_mature:
+                cohort.update_largest_mass()
+
     def inflict_non_predation_mortality_community(self, dt: timedelta64) -> None:
         """This handles natural mortality for all cohorts in a community.