Fix tests and algo, update example notebook

Author: brynpickering

docs/examples/modes.py

@@ -160,6 +160,29 @@ def plot_capacity(results: xr.Dataset, **plotly_kwargs) -> go.Figure:
     return fig
 
 
+# %% [markdown]
+# ### Using different `spores` scoring algorithms.
+#
+# We make a number of scoring algorithms accessible out-of-the-box, based on those we present in [Lombardi et al. (2023)](https://doi.org/10.1016/j.apenergy.2023.121002).
+# You can call them on solving the model.
+# Here, we'll compare the result on `flow_cap` from running each.
+
+# %%
+# We subset to the same time range as operate/plan mode
+model_spores = calliope.examples.national_scale(
+    scenario="spores", time_subset=["2005-01-01", "2005-01-10"]
+)
+model_spores.build()
+
+spores_results = []
+for algorithm in ["integer", "evolving_average", "random", "relative_deployment"]:
+    model_spores.solve(**{"spores.scoring_algorithm": algorithm}, force=True)
+    spores_results.append(model_spores.results.expand_dims(algorithm=[algorithm]))
+
+spores_results_da = xr.concat(spores_results, dim="algorithm")
+
+spores_results_da.flow_cap.to_series().dropna().unstack("spores")
+
 # %% [markdown]
 # ## `plan` vs `operate`
 # Here, we compare flows over the 10 days.
@@ -188,3 +211,17 @@ def plot_capacity(results: xr.Dataset, **plotly_kwargs) -> go.Figure:
 # %%
 fig_flows_spores = plot_capacity(model_spores.results, facet_col="spores")
 fig_flows_spores.update_layout(title="SPORES mode capacities")
+
+# %% [markdown]
+# ## Comparing `spores` scoring algorithms
+# Here, we compare installed capacities between the different SPORES runs.
+
+# %%
+fig_flows_spores = plot_capacity(
+    spores_results_da, facet_col="spores", facet_row="algorithm"
+)
+fig_flows_spores.update_layout(
+    title="SPORES mode capacities using different scoring algorithms",
+    autosize=False,
+    height=800,
+)

src/calliope/model.py

@@ -5,7 +5,6 @@
 from __future__ import annotations
 
 import logging
-import random
 from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -612,6 +611,9 @@ def _solve_spores(self, solver_config: config_schema.Solve) -> xr.Dataset:
         # We store the results from each iteration in the `results_list` to later concatenate into a single dataset.
         results_list: list[xr.Dataset] = [baseline_results]
         spore_range = range(1, spores_config.number + 1)
+        LOGGER.info(
+            f"Optimisation model | Running SPORES with `{spores_config.scoring_algorithm}` scoring algorithm."
+        )
         for spore in spore_range:
             LOGGER.info(f"Optimisation model | Running SPORE {spore}.")
             self._spores_update_model(baseline_results, results_list, spores_config)
@@ -639,8 +641,21 @@ def _spores_update_model(
         all_previous_results: list[xr.Dataset],
         spores_config: config_schema.SolveSpores,
     ):
+        """Assign SPORES scores for the next iteration of the model run.
+
+        Algorithms applied are based on those introduced in <https://doi.org/10.1016/j.apenergy.2023.121002>.
+
+        Args:
+            baseline_results (xr.Dataset): The initial results (before applying SPORES scoring)
+            all_previous_results (list[xr.Dataset]):
+                A list of all previous iterations.
+                 This includes the baseline results, which will be the first item in the list.
+            spores_config (config_schema.SolveSpores):
+                The SPORES configuration.
+        """
+
         def _score_integer() -> xr.DataArray:
-            # Look at capacity deployment in the previous iteration
+            """Integer scoring algorithm."""
             previous_cap = latest_results["flow_cap"].where(spores_techs)
 
             # Make sure that penalties are applied only to non-negligible deployments of capacity
@@ -658,36 +673,33 @@ def _score_integer() -> xr.DataArray:
             return new_score
 
         def _score_relative_deployment() -> xr.DataArray:
-            # Look at capacity deployment in the previous iteration
+            """Relative deployment scoring algorithm."""
             previous_cap = latest_results["flow_cap"].where(spores_techs)
-
-            # Look at capacity deployment in the previous iteration
             relative_cap = previous_cap / self.inputs["flow_cap_max"].where(
                 spores_techs
             )
 
-            # Make sure that penalties are applied only to non-negligible deployments of capacity
-            min_relevant_size = spores_config.score_threshold_factor * relative_cap
-
             new_score = (
-                # Where capacity was deployed more than the minimal relevant size, assign the relative deployment as a penalty (score)
-                relative_cap.where(previous_cap > min_relevant_size)
+                # Make sure that penalties are applied only to non-negligible relative capacities
+                relative_cap.where(relative_cap > spores_config.score_threshold_factor)
                 .fillna(0)
                 .where(spores_techs)
             )
-            return new_score.to_pandas()
+            return new_score
 
         def _score_random() -> xr.DataArray:
+            """Random scoring algorithm."""
             previous_cap = latest_results["flow_cap"].where(spores_techs)
             new_score = (
                 previous_cap.fillna(0)
-                .where(previous_cap.isnull(), other=lambda x: random.random())
+                .where(previous_cap.isnull(), other=np.random.rand(*previous_cap.shape))
                 .where(spores_techs)
             )
 
             return new_score
 
         def _score_evolving_average() -> xr.DataArray:
+            """Evolving average scoring algorithm."""
             previous_cap = latest_results["flow_cap"]
             evolving_average = sum(
                 results["flow_cap"] for results in all_previous_results
@@ -700,17 +712,21 @@ def _score_evolving_average() -> xr.DataArray:
                 new_score = _score_integer()
             else:
                 # If capacity is exactly the same as the average, we give the relative difference an arbitrarily small value
-                relative_change = (
-                    relative_change.clip(min=0.001)
-                    .where(relative_change != np.inf, other=0)
-                    .where(spores_techs)
+                # which will give it a _large_ score since we take the reciprocal of the change.
+                cleaned_relative_change = (
+                    relative_change.clip(min=0.001).fillna(0).where(spores_techs)
+                )
+                # Any zero values that make their way through to the scoring are kept as zero after taking the reciprocal.
+                new_score = (cleaned_relative_change**-1).where(
+                    cleaned_relative_change > 0, other=0
                 )
-                new_score = relative_change**-1
 
             return new_score
 
         latest_results = all_previous_results[-1]
-        allowed_methods: dict[str, Callable[[], xr.DataArray]] = {
+        allowed_methods: dict[
+            config_schema.SPORES_SCORING_OPTIONS, Callable[[], xr.DataArray]
+        ] = {
             "integer": _score_integer,
             "relative_deployment": _score_relative_deployment,
             "random": _score_random,

src/calliope/schemas/config_schema.py

@@ -14,6 +14,10 @@
 
 LOGGER = logging.getLogger(__name__)
 
+SPORES_SCORING_OPTIONS = Literal[
+    "integer", "relative_deployment", "random", "evolving_average"
+]
+
 
 class Init(CalliopeBaseModel):
     """All configuration options used when initialising a Calliope model."""
@@ -131,10 +135,11 @@ class SolveSpores(CalliopeBaseModel):
 
     model_config = {"title": "Model solve SPORES mode configuration"}
 
-    scoring_algorithm: Literal[
-        "integer", "relative_deployment", "random", "evolving_average"
-    ] = "integer"
-    """Algorithm to apply to update the SPORES score between iterations."""
+    scoring_algorithm: SPORES_SCORING_OPTIONS = "integer"
+    """
+    Algorithm to apply to update the SPORES score between iterations.
+    For more information on each option, see [Lombardi et al. (2023)](https://doi.org/10.1016/j.apenergy.2023.121002).
+    """
 
     number: int = Field(default=3)
     """SPORES mode number of iterations after the initial base run."""

tests/test_core_model.py

@@ -237,12 +237,15 @@ def spores_model_save_per_spore_and_log(self, tmp_path_factory, request):
 
         return model, log
 
-    @pytest.fixture(scope="class")
-    def spores_model_with_tracker(self):
+    @pytest.fixture(
+        scope="class",
+        params=["integer", "relative_deployment", "random", "evolving_average"],
+    )
+    def spores_model_with_tracker(self, request):
         """Iterate 2 times in SPORES mode with a SPORES score tracking parameter."""
         model = build_model({}, "spores,spores_tech_tracking,investment_costs")
         model.build(mode="spores")
-        model.solve()
+        model.solve(**{"spores.scoring_algorithm": request.param})
 
         return model
 
@@ -264,36 +267,47 @@ def test_spores_mode_success(self, spores_model_and_log_algorithms):
         spores_model, _ = spores_model_and_log_algorithms
         assert spores_model.results.attrs["termination_condition"] == "optimal"
 
-    def test_spores_mode_3_results(self, spores_model_and_log):
+    def test_spores_mode_3_results(self, spores_model_and_log_algorithms):
         """Solving in spores mode should lead to 3 sets of results."""
-        spores_model, _ = spores_model_and_log
+        spores_model, _ = spores_model_and_log_algorithms
         assert not set(spores_model.results.spores.values).symmetric_difference(
             ["baseline", 1, 2]
         )
 
-    def test_spores_scores(self, spores_model_and_log):
+    def test_spores_scores(self, spores_model_and_log_algorithms):
         """All techs should have a spores score defined."""
-        spores_model, _ = spores_model_and_log
+        spores_model, _ = spores_model_and_log_algorithms
         fill_gaps = ~spores_model._model_data.definition_matrix
         assert (
             spores_model._model_data.spores_score_cumulative.notnull() | fill_gaps
         ).all()
 
-    def test_spores_caps(self, spores_model_and_log):
+    def test_spores_caps(self, spores_model_and_log_algorithms):
         """There should be some changes in capacities between SPORES."""
-        spores_model, _ = spores_model_and_log
+        spores_model, _ = spores_model_and_log_algorithms
         cap_diffs = spores_model.results.flow_cap.diff(dim="spores")
         assert (cap_diffs != 0).any()
 
-    def test_spores_scores_never_decrease(self, spores_model_and_log):
-        """SPORES scores can never decrease."""
+    def test_spores_algo_log(self, spores_model_and_log_algorithms):
+        """The scoring algorithm being used should be logged correctly."""
+        model, log = spores_model_and_log_algorithms
+        assert (
+            f"Running SPORES with `{model.config.solve.spores.scoring_algorithm}` scoring algorithm."
+            in log
+        )
+
+    def test_spores_scores_never_decrease_integer_algo(self, spores_model_and_log):
+        """SPORES scores can never decrease.
+
+        This is not true for all algorithms (e.g. random scoring) so we test with integer scoring.
+        """
         spores_model, _ = spores_model_and_log
         assert (
             spores_model._model_data.spores_score_cumulative.fillna(0).diff("spores")
             >= 0
         ).all()
 
-    def test_spores_scores_increasing_with_cap(self, spores_model_and_log):
+    def test_spores_scores_increasing_with_cap_integer_algo(self, spores_model_and_log):
         """SPORES scores increase when a tech has a finite flow_cap in the previous iteration."""
         spores_model, _ = spores_model_and_log
         has_cap = spores_model.results.flow_cap > 0