Implement commodity constraints

[tsmbland]

Description

Implements the commodity constraints in the dispatch. This is only a partial solution, included for testing purposes, and expected to fail in many/most cases - this is what Adam has asked for.

The reason it's only a partial solution is that we also need a way to constrain commodity consumption/production in the investment stage, and this is much harder. Without this, an agent may invest in assets to produce a commodity, then find that in the full system dispatch they can only produce that commodity up to a limit, at which point dispatch will fail. Similarly, they currently have no extra incentive to invest in assets producing commodities with minimum production constraints, but if they don't then dispatch will later fail. We don't currently have a solution for this problem, and it will need further thought/investigation.

In the meantime, I wanted to make sure the implementation is correct in the full system dispatch, and that error messages are clear in the case where it (inevitably) fails. I've made commodity constraints optional according to the caller (so we can exclude commodity constraints for partial system dispatch during investment). For the full system dispatch it will first run with commodity constraints (if provided), then run without commodity constraints if that fails, to see if the commodity constraints are responsible. I've reworked the diagnostics code a bit to make it easier to do multiple diagnostic runs (previously it was just the unmet demand diagnostic). We may want to think about more potential diagnostics, if useful.

I've gated commodity constraints behind the please_give_me_broken_results option so that casual users don't try to use this.

Other small changes:

• changed CommodityConstraint to store RegionID
• changed read_commodity_constraints_success to test read_commodity_constraints_from_iter rather than read_commodity_constraints, as the latter now requires changing please_give_me_broken_results which is difficult to do in tests
• added an integration test for a model expected to fail with commodity constraints
• updated the documentation

Fixes #1449

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

[codecov]

Codecov Report

❌ Patch coverage is 84.30493% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.82%. Comparing base (ae3839d) to head (88f21e3).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
src/simulation/optimisation.rs	75.00%	21 Missing and 3 partials ⚠️
src/simulation/optimisation/constraints.rs	72.97%	8 Missing and 2 partials ⚠️
src/input/commodity/constraints.rs	98.86%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1513      +/-   ##
==========================================
+ Coverage   90.35%   90.82%   +0.47%     
==========================================
  Files          61       61              
  Lines        8850     8996     +146     
  Branches     8850     8996     +146     
==========================================
+ Hits         7996     8171     +175     
+ Misses        529      506      -23     
+ Partials      325      319       -6     

☔ 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]

Pull request overview

Adds support for explicit commodity consumption/production constraints in the full-system dispatch optimisation, with diagnostic reruns to help pinpoint infeasibility causes, while intentionally excluding these constraints from partial dispatch during investment/cycle steps.

Changes:

• Implement commodity production/consumption constraint rows in dispatch optimisation (optional per dispatch run).
• Extend infeasibility diagnostics to separately test unmet demand vs. commodity-constraint-caused infeasibility and surface clearer error messages.
• Gate loading/usage of commodity_constraints.csv behind please_give_me_broken_results, and document the feature + add an integration test for the diagnostic messaging.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/model.rs	Adds an integration test asserting commodity-constraint infeasibility is diagnosed and reported clearly.
src/simulation/optimisation/constraints.rs	Adds commodity constraint rows to the HiGHS problem, toggled by a new flag.
src/simulation/optimisation.rs	Adds dispatch-run flag + diagnostic reruns for unmet demand and commodity constraints to improve infeasibility reporting.
src/simulation/market.rs	Disables commodity constraints for partial dispatch used during market/cycle selection.
src/simulation/investment.rs	Disables commodity constraints for partial dispatch used during investment.
src/input/commodity/constraints.rs	Reads optional commodity_constraints.csv, validates it, and enforces the experimental-feature gate.
src/commodity.rs	Refactors commodity constraint storage to be keyed by year and stores region on the constraint itself.
schemas/input/commodity_constraints.yaml	Documents the experimental nature and required please_give_me_broken_results setting.
docs/model/dispatch_optimisation.md	Documents commodity constraints and the new infeasibility diagnostic approach.

---

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