Add seasonal/annual utilisation penalties to the appraisal mini-dispatch

[tsmbland]

Description

Adding seasonal/annual utilisation penalties to the appraisal mini-dispatch. These are nearly identical to the equivalent constraints used in the dispatch optimisation, but note the change of sign on the penalty as the appraisal optimisation is a MAX optimisation (whereas dispatch is MIN)

Fixes # (issue)

Type of change

• Bug fix (non-breaking change to fix an issue)
• New feature (non-breaking change to add functionality)
• Refactoring (non-breaking, non-functional change to improve maintainability)
• Optimization (non-breaking change to speed up the code)
• Breaking change (whatever its nature)
• Documentation (improve or add documentation)

Key checklist

• All tests pass: $ cargo test
• The documentation builds and looks OK: $ cargo doc
• Update release notes for the latest release if this PR adds a new feature or fixes a bug
  present in the previous release

Further checks

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.30.

Benchmark suite	Current: 48b24ec	Previous: 6a19604	Ratio
example_run/missing_commodity example	355397213 ns	271642953 ns	1.31
example_run/muse1_default example	478709176.5 ns	337702386.5 ns	1.42
example_run/two_outputs example	645487619 ns	485146523.5 ns	1.33
select_best_assets_parallel/01	13597854.149999999 ns	9132896.765151516 ns	1.49
select_best_assets_parallel/05	39025257.375 ns	26819628.777777776 ns	1.46
select_best_assets_parallel/10	66678746.66666667 ns	45113674.75 ns	1.48
select_best_assets_parallel/15	96846104.25 ns	65351435.33333333 ns	1.48
select_best_assets_parallel/20	127868620 ns	85097739.5 ns	1.50
select_best_assets_sequential/01	13611700.798076924 ns	9107675.635526314 ns	1.49
select_best_assets_sequential/05	65031033 ns	43859325.75 ns	1.48
select_best_assets_sequential/10	128887773 ns	87553632.5 ns	1.47
select_best_assets_sequential/15	193191512 ns	131658938.5 ns	1.47
select_best_assets_sequential/20	259427691.5 ns	175652280.5 ns	1.48

This comment was automatically generated by workflow using github-action-benchmark.

[Copilot]

🟡 Changes recommended

The regression test compares generated debug files without corresponding expected circularity debug fixtures.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds seasonal and annual utilisation penalties to the appraisal mini-dispatch, with signs adjusted for maximisation.

Changes:

• Adds peak variables and utilisation penalty constraints.
• Integrates the constraints into appraisal optimisation.
• Refreshes regression fixtures and updates documentation and release notes.

File summaries

File	Summary
tests/regression.rs	Updates regression coverage; the debug comparison lacks expected circularity debug fixtures.
tests/data/two_regions/commodity_prices.csv	Refreshes expected commodity prices.
tests/data/two_regions/assets.csv	Refreshes expected asset outputs.
tests/data/two_regions/asset_capacities.csv	Refreshes expected capacity outputs.
tests/data/simple/debug_appraisal_results.csv	Updates appraisal debug results.
tests/data/muse1_default/commodity_prices.csv	Refreshes expected commodity prices.
tests/data/muse1_default/commodity_flows.csv	Refreshes expected commodity flows.
tests/data/muse1_default/assets.csv	Refreshes expected asset outputs.
tests/data/muse1_default/asset_capacities.csv	Refreshes expected capacity outputs.
tests/data/missing_commodity/commodity_prices.csv	Refreshes expected commodity prices.
tests/data/missing_commodity/commodity_flows.csv	Refreshes expected commodity flows.
tests/data/missing_commodity/asset_capacities.csv	Refreshes expected capacity outputs.
tests/data/circularity/commodity_prices.csv	Refreshes expected commodity prices.
tests/data/circularity/commodity_flows.csv	Refreshes expected commodity flows.
tests/data/circularity/asset_capacities.csv	Refreshes expected capacity outputs.
tests/data/circularity_npv/commodity_prices.csv	Refreshes expected commodity prices.
tests/data/circularity_npv/commodity_flows.csv	Refreshes expected commodity flows.
tests/data/circularity_npv/asset_capacities.csv	Refreshes expected capacity outputs.
src/simulation/investment/appraisal/optimisation.rs	Integrates utilisation penalty constraints into appraisal optimisation.
src/simulation/investment/appraisal/constraints.rs	Adds seasonal and annual utilisation penalty constraints.
docs/release_notes/upcoming.md	Documents the new feature.
docs/model/investment.md	Documents appraisal utilisation penalties.

Review details

• Files reviewed: 23/24 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 96.84211% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.88%. Comparing base (22fbf4e) to head (48b24ec).

Files with missing lines	Patch %	Lines
src/simulation/investment/appraisal/constraints.rs	96.73%	1 Missing and 2 partials ⚠️

Additional details and impacted files

@@                     Coverage Diff                     @@
##           increase_annual_penalty    #1548      +/-   ##
===========================================================
+ Coverage                    90.83%   90.88%   +0.05%     
===========================================================
  Files                           61       61              
  Lines                         9019     9109      +90     
  Branches                      9019     9109      +90     
===========================================================
+ Hits                          8192     8279      +87     
- Misses                         508      509       +1     
- Partials                       319      321       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🔵 Needs a closer look

The change spans optimisation logic and numerous regenerated regression fixtures, warranting final human review.

Review details

• Files reviewed: 22/22 changed files
• Comments generated: 0 new
• Review effort level: Lite

[tsmbland]

Looks like there's a ~15-20% performance hit (local benchmarking). I think that's acceptable, and shouldn't be any worse for larger models