Merge pull request #1199 from CLIMADA-project/feature/impact-computation-strategies

Risk Trajectory Split 3 : Impact Computation Strategies

Author: spjuhel

climada/trajectories/impact_calc_strat.py

@@ -0,0 +1,114 @@
+"""
+This file is part of CLIMADA.
+
+Copyright (C) 2017 ETH Zurich, CLIMADA contributors listed in AUTHORS.
+
+CLIMADA is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free
+Software Foundation, version 3.
+
+CLIMADA is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with CLIMADA. If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+This modules implements the impact computation strategy objects for risk
+trajectories.
+
+"""
+
+from abc import ABC, abstractmethod
+
+from climada.engine.impact import Impact
+from climada.engine.impact_calc import ImpactCalc
+from climada.entity.exposures.base import Exposures
+from climada.entity.impact_funcs.impact_func_set import ImpactFuncSet
+from climada.hazard.base import Hazard
+
+__all__ = ["ImpactCalcComputation"]
+
+
+# The following is acceptable.
+# We design a pattern, and currently it requires only to
+# define the compute_impacts method.
+# pylint: disable=too-few-public-methods
+class ImpactComputationStrategy(ABC):
+    """
+    Interface for impact computation strategies.
+
+    This abstract class defines the contract for all concrete strategies
+    responsible for calculating and optionally modifying with a risk transfer,
+    the impact computation, based on a set of inputs (exposure, hazard, vulnerability).
+
+    It revolves around a `compute_impacts()` method that takes as arguments
+    the three dimensions of risk (exposure, hazard, vulnerability) and return an
+    Impact object.
+    """
+
+    @abstractmethod
+    def compute_impacts(
+        self,
+        exp: Exposures,
+        haz: Hazard,
+        vul: ImpactFuncSet,
+    ) -> Impact:
+        """
+        Calculates the total impact, including optional risk transfer application.
+
+        Parameters
+        ----------
+        exp : Exposures
+            The exposure data.
+        haz : Hazard
+            The hazard data (e.g., event intensity).
+        vul : ImpactFuncSet
+            The set of vulnerability functions.
+
+        Returns
+        -------
+        Impact
+            An object containing the computed total impact matrix and metrics.
+
+        See Also
+        --------
+        ImpactCalcComputation : The default implementation of this interface.
+        """
+
+
+class ImpactCalcComputation(ImpactComputationStrategy):
+    r"""
+    Default impact computation strategy using the core engine of climada.
+
+    This strategy first calculates the raw impact using the standard
+    :class:`ImpactCalc` logic.
+
+    """
+
+    def compute_impacts(
+        self,
+        exp: Exposures,
+        haz: Hazard,
+        vul: ImpactFuncSet,
+    ) -> Impact:
+        """
+        Calculates the impact.
+
+        Parameters
+        ----------
+        exp : Exposures
+            The exposure data.
+        haz : Hazard
+            The hazard data.
+        vul : ImpactFuncSet
+            The set of vulnerability functions.
+
+        Returns
+        -------
+        Impact
+            The final impact object.
+        """
+        return ImpactCalc(exposures=exp, impfset=vul, hazard=haz).impact()

climada/trajectories/test/test_impact_calc_strat.py

@@ -0,0 +1,97 @@
+"""
+This file is part of CLIMADA.
+
+Copyright (C) 2017 ETH Zurich, CLIMADA contributors listed in AUTHORS.
+
+CLIMADA is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free
+Software Foundation, version 3.
+
+CLIMADA is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with CLIMADA. If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+Tests for impact_calc_strat
+
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from climada.engine import Impact
+from climada.entity import ImpactFuncSet
+from climada.entity.exposures import Exposures
+from climada.hazard import Hazard
+from climada.trajectories import Snapshot
+from climada.trajectories.impact_calc_strat import (
+    ImpactCalcComputation,
+    ImpactComputationStrategy,
+)
+
+# --- Fixtures ---
+
+
+@pytest.fixture
+def mock_snapshot():
+    """Provides a snapshot with mocked exposure, hazard, and impact functions."""
+    snap = MagicMock(spec=Snapshot)
+    snap.exposure = MagicMock(spec=Exposures)
+    snap.hazard = MagicMock(spec=Hazard)
+    snap.impfset = MagicMock(spec=ImpactFuncSet)
+    return snap
+
+
+@pytest.fixture
+def strategy():
+    """Provides an instance of the ImpactCalcComputation strategy."""
+    return ImpactCalcComputation()
+
+
+# --- Tests ---
+def test_interface_compliance(strategy):
+    """Ensure the class correctly inherits from the Abstract Base Class."""
+    assert isinstance(strategy, ImpactComputationStrategy)
+    assert isinstance(strategy, ImpactCalcComputation)
+
+
+def test_compute_impacts(strategy, mock_snapshot):
+    """Test that compute_impacts calls the pre-transfer method correctly."""
+    mock_impacts = MagicMock(spec=Impact)
+
+    # We patch the ImpactCalc within trajectories
+    with patch("climada.trajectories.impact_calc_strat.ImpactCalc") as mock_ImpactCalc:
+        mock_ImpactCalc.return_value.impact.return_value = mock_impacts
+        result = strategy.compute_impacts(
+            exp=mock_snapshot.exposure,
+            haz=mock_snapshot.hazard,
+            vul=mock_snapshot.impfset,
+        )
+        mock_ImpactCalc.assert_called_once_with(
+            exposures=mock_snapshot.exposure,
+            impfset=mock_snapshot.impfset,
+            hazard=mock_snapshot.hazard,
+        )
+        mock_ImpactCalc.return_value.impact.assert_called_once()
+        assert result == mock_impacts
+
+
+def test_cannot_instantiate_abstract_base_class():
+    """Ensure ImpactComputationStrategy cannot be instantiated directly."""
+    with pytest.raises(TypeError, match="Can't instantiate abstract class"):
+        ImpactComputationStrategy()  # type: ignore
+
+
+@pytest.mark.parametrize("invalid_input", [None, 123, "string"])
+def test_compute_impacts_type_errors(strategy, invalid_input):
+    """
+    Smoke test: Ensure that if ImpactCalc raises errors due to bad input,
+    the strategy correctly propagates them.
+    """
+    with pytest.raises(AttributeError):
+        strategy.compute_impacts(invalid_input, invalid_input, invalid_input)

doc/api/climada/climada.trajectories.impact_calc_strat.rst

@@ -0,0 +1,7 @@
+climada\.trajectories\.impact_calc_strat module
+----------------------------------------
+
+.. automodule:: climada.trajectories.impact_calc_strat
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/api/climada/climada.trajectories.rst

@@ -5,4 +5,5 @@ climada\.trajectories module
 .. toctree::
 
    climada.trajectories.snapshot
+   climada.trajectories.impact_calc_strat
    climada.trajectories.interpolation