Introduce SPORES in v0.7.0 as a generalisable mode

[FLomb]

Fixes #431

Summary of changes in this pull request

• Introduces a spores scenario as part of the national-scale example model
• Introduces a custom math file in the national-scale example model, which is activated in the spores scenario to create a slack cost constraint
• It provides a dedicated notebook to generate SPORES iteratively based on the spores scenario overrides and a custom Python function for assigning penalties at each iteration.

Based on internal discussions, we have come to realise that there are many ongoing SPORES developments that may be hard to always reconduct to a monolithic run mode in the core code. Instead, it may be best to implement SPORES as a method that simply allows you to run a model in plan mode once, and then N number more times with some external function being applied between each run, with the user providing that function. This way, this mode could be used not only for SPORES but also for robustness analysis and other things.

This PR aims to show how SPORES can be indeed already used in v0.7.0 based on default software functionality plus a simple for-loop and a custom Python function to assign penalties for decision variables at each iteration of the loop. To move from this to the generalised mode described above, we would only need to decide how to make some bits of this code (such as the number of iterations, and the custom Python function) a default request for inputs to the user.

The new run-iteratively-with-a-function mode (a better name must be found, could also be spores-and-more if the main application remains SPORES), would essentially require the following three key inputs: 1) how many iterations to run; 2) what function to apply at each iteration; and 3) what backend parameter to updated based on the function.

Reviewer checklist

• Test(s) added to cover contribution
• Documentation updated
• Changelog updated
• Coverage maintained or improved

[FLomb]

I see that building the docs fails because I am using matplotlib, which isn't part of the default Calliope environment. I will remove the plotting part, for now. We can later re-implement it via a supported library, or just leave it out.

[FLomb]

I have no doubt that this function can be majorly shortened by someone with deeper experience of these data structures

[brynpickering]

@FLomb I've updated the approach to minimise the input requirements from the user. The main change is that there is now no longer a spores-specific cost class. Instead, the objective is changed in the math. Updating this objective with user-defined math would allow a user to update how the spores scores are translated to penalties in the optimisation problem.

The SPORES mode stuff is currently untested although you can see that it works in the example notebook.

I hope that some of the hardcoding of params in model.py can go away with the implementation of #712.

The SPORES mode stuff will also move out of model.py (initial work on that is also in #712). Hopefully, though, you can see that it is on the verge of being generalisable - there is an "iterative optimisation" controller that calls a model updater. My idea would be to scrub "spores" from this controller and just have it so that it can run with a supplied updater function, the SPORES mode one being one of them. This would allow for other iterative updaters (including custom SPORES algorithms) to be supplied by the user and managed by the controller.

[codecov]

Codecov Report

Attention: Patch coverage is 44.73684% with 42 lines in your changes missing coverage. Please review.

Project coverage is 95.14%. Comparing base (9f33ecb) to head (3e97ec8).

Files with missing lines	Patch %	Lines
src/calliope/model.py	6.66%	40 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #716      +/-   ##
==========================================
- Coverage   96.09%   95.14%   -0.95%     
==========================================
  Files          29       29              
  Lines        4067     4139      +72     
  Branches      584      596      +12     
==========================================
+ Hits         3908     3938      +30     
- Misses         68      108      +40     
- Partials       91       93       +2     

Files with missing lines	Coverage Δ
src/calliope/backend/backend_model.py	98.01% <100.00%> (+0.02%)	⬆️
src/calliope/backend/gurobi_backend_model.py	95.78% <100.00%> (+0.11%)	⬆️
src/calliope/backend/latex_backend_model.py	96.99% <100.00%> (+0.11%)	⬆️
src/calliope/backend/pyomo_backend_model.py	97.90% <100.00%> (+0.06%)	⬆️
src/calliope/backend/where_parser.py	98.18% <100.00%> (ø)
src/calliope/model.py	80.89% <6.66%> (-15.05%)	⬇️