Add documentation for commodity price calculations

[tsmbland]

Description

Adds documentation describing the approach for calculating commodity prices. Includes the example laid out in #1128 (comment)

Fixes #1034

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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.68%. Comparing base (651b4e2) to head (58b0ec6).
⚠️ Report is 46 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1362      +/-   ##
==========================================
- Coverage   89.75%   89.68%   -0.07%     
==========================================
  Files          58       58              
  Lines        8529     8406     -123     
  Branches     8529     8406     -123     
==========================================
- Hits         7655     7539     -116     
+ Misses        561      550      -11     
- Partials      313      317       +4     

☔ 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 a new user-facing documentation page describing how MUSE2 calculates commodity prices after dispatch, including an end-to-end worked example for full-cost pricing (per the referenced issues).

Changes:

• Add a new “Commodity Prices” page under the Model Description section.
• Document pricing strategies, cost component breakdowns, ordering logic (including cycles), and a worked example.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/SUMMARY.md	Adds the new “Commodity Prices” page to the mdBook table of contents.
docs/model/prices.md	New documentation page describing pricing strategies and worked examples for commodity price calculation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dc2917]

A couple of minor suggestions but otherwise looks good to me

[alexdewar]

Looks good! A useful resource. I've put some comments.

Maybe you could link to this page from the docs for src/simulation/prices.rs? (Though bear in mind the URL may change soon, see: #1366 (comment)).

I spotted one place where we are using a different name for the variable elsewhere in the docs from what's here (there may be more), but your naming scheme is at least internally consistent, so I think that's better. We have a bit of a mix of single letters, snake case and Pascal case in equations. Not sure if we should do something about that.

[alexdewar]

Side note: I think this option might be misnamed. I had it in mind it removes the effect of scarcity from prices. scarcity_adjusted or something might be clearer.

[tsmbland]

I spotted one place where we are using a different name for the variable elsewhere in the docs from what's here (there may be more), but your naming scheme is at least internally consistent, so I think that's better. We have a bit of a mix of single letters, snake case and Pascal case in equations. Not sure if we should do something about that.

I admittedly didn't make much of an attempt to make it consistent with the rest of the docs. Probably should be long run, but I think we'd need to agree upon a proper naming scheme before embarking on that.

[tsmbland]

Maybe you could link to this page from the docs for src/simulation/prices.rs? (Though bear in mind the URL may change soon, see: #1366 (comment)).

Done, although linkchecker will fail until this is merged

[alexdewar]

LGTM! Tried it locally and it renders nicely.

I spotted one place where we are using a different name for the variable elsewhere in the docs from what's here (there may be more), but your naming scheme is at least internally consistent, so I think that's better. We have a bit of a mix of single letters, snake case and Pascal case in equations. Not sure if we should do something about that.

I admittedly didn't make much of an attempt to make it consistent with the rest of the docs. Probably should be long run, but I think we'd need to agree upon a proper naming scheme before embarking on that.

Agreed! I think this is fine for now.

Maybe you could link to this page from the docs for src/simulation/prices.rs? (Though bear in mind the URL may change soon, see: #1366 (comment)).

Done, although linkchecker will fail until this is merged

👍 Feel free to bypass and merge as long as there are no other failures.

@AdrianDAlessandro This is another link that will need updating for #1366.

[alexdewar]

Ah ok! My bad. This is fine then