Add documentation for commodity price calculations by tsmbland · Pull Request #1362 · EnergySystemsModellingLab/MUSE2

tsmbland · 2026-06-22T15:25:46Z

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 · 2026-06-22T15:30:12Z

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1362      +/-   ##
==========================================
+ Coverage   89.75%   89.80%   +0.05%     
==========================================
  Files          58       58              
  Lines        8529     8524       -5     
  Branches     8529     8524       -5     
==========================================
  Hits         7655     7655              
+ Misses        561      556       -5     
  Partials      313      313

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

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

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 · 2026-06-25T14:02:39Z

+highest-cost active asset producing the commodity.
+- **`shadow`**: Prices are taken directly from the shadow prices (dual values) of the commodity
+balance constraints in the dispatch optimisation.
+- **`scarcity`**: Prices are set to the shadow price plus the highest activity dual of the assets


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.

alexdewar · 2026-06-25T14:03:01Z

+balance constraints in the dispatch optimisation.
+- **`scarcity`**: Prices are set to the shadow price plus the highest activity dual of the assets
+producing the commodity in that region and time slice.
+- **`unpriced`**: No prices are calculated for the commodity.


Worth mentioning that for OTH-type prices, you have to use this option?

alexdewar · 2026-06-25T14:04:31Z

+
+**Supply Equals Demand (SED):**: An SED commodity is a type of commodity that is both consumed and
+produced by processes in the system. In fully resolved systems, supply of these commodities is
+constrained to be equal to or greater than demand.


Would it also be worth mentioning OTH commodities here? The abbreviation isn't very self-explanatory

alexdewar · 2026-06-25T14:09:28Z

+The generic activity cost comprises all operating expenditures, input purchases, and flow costs/levies
+not associated with specific SED/SVD outputs:
+\\[
+\text{GenericActivityCost} = \text{VariableOperatingCost} + \text{InputPurchases} + \sum \text{GenericFlowCosts}


Just noting that we use $cost_{var}$ to mean variable operating cost in the dispatch docs. I think it would probably be confusing to use that here though.

You could abbreviate "operating cost" to "opex" though, as you use that below anyway:

Suggested change

\text{GenericActivityCost} = \text{VariableOperatingCost} + \text{InputPurchases} + \sum \text{GenericFlowCosts}

\text{GenericActivityCost} = \text{VariableOpex} + \text{InputPurchases} + \sum \text{GenericFlowCosts}

alexdewar · 2026-06-25T14:11:31Z

+*Note: this only works if all output commodities are measured in the same energy units (e.g. PJ).
+For this reason, MUSE2 disallows processes that have output commodities with differing units.*


I'd put this in a box:

Suggested change

*Note: this only works if all output commodities are measured in the same energy units (e.g. PJ).

For this reason, MUSE2 disallows processes that have output commodities with differing units.*

> Note: this only works if all output commodities are measured in the same energy units (e.g. PJ).

> For this reason, MUSE2 disallows processes that have output commodities with differing units.

alexdewar · 2026-06-25T14:25:39Z

+
+### GASPRD
+
+In this scenario, GASPRD is produced by a single GASDRV asset. This asset produces 1 unit of GASPRD


Is the reader likely to know what GASPRD refers to, i.e. is it a common abbreviation? I always assumed these names were MUSE-isms.

If so, should we maybe have a list spelling out what they mean? Alternatively we could just use longer names.

alexdewar · 2026-06-25T14:33:29Z

+\\[
+\text{CRF} = 0.11016807219
+\\]
+
+\\[
+\text{AnnualFixedCostPerCapacity} = (10 \times 0.11016807219 + 0.3) = 1.4016807219
+\\]


How about aligning these on the = signs?

Suggested change

\\[

\text{CRF} = 0.11016807219

\\]

\\[

\text{AnnualFixedCostPerCapacity} = (10 \times 0.11016807219 + 0.3) = 1.4016807219

\\]

\\[

\begin{aligned}

\text{CRF} &= 0.11016807219

\text{AnnualFixedCostPerCapacity} &= (10 \times 0.11016807219 + 0.3) = 1.4016807219

\end{aligned}

\\]

You might even be able to get the equations below to line up by keeping the whole lot in a math block or something, but, even if not, I think it's nicer to have these aligned.

alexdewar · 2026-06-25T14:34:18Z

+\\[
+\text{CO2Levy} = 2.5565 \times 0.04 = 0.10226
+\\]
+
+\\[
+\text{InputPurchases} = 8.9477554044 \times 1.05 = 9.39514317462
+\\]
+
+\\[
+\text{MarginalCost}_{\text{GASNAT}} = 0.10226 + 0.5 + 9.39514317462 = 9.99740317462
+\\]


As above:

Suggested change

\\[

\text{CO2Levy} = 2.5565 \times 0.04 = 0.10226

\\]

\\[

\text{InputPurchases} = 8.9477554044 \times 1.05 = 9.39514317462

\\]

\\[

\text{MarginalCost}_{\text{GASNAT}} = 0.10226 + 0.5 + 9.39514317462 = 9.99740317462

\\]

\\[

\begin{aligned}

\text{CO2Levy} &= 2.5565 \times 0.04 = 0.10226

\text{InputPurchases} &= 8.9477554044 \times 1.05 = 9.39514317462

\text{MarginalCost}_{\text{GASNAT}} &= 0.10226 + 0.5 + 9.39514317462 = 9.99740317462

\end{aligned}

\\]

alexdewar · 2026-06-25T14:34:50Z

+\\[
+\text{CRF} = 0.11016807219
+\\]
+
+\\[
+\text{AnnualFixedCostPerCapacity} = (7 \times 0.11016807219 + 0.21) = 0.98117650533
+\\]


Suggested change

\\[

\text{CRF} = 0.11016807219

\\]

\\[

\text{AnnualFixedCostPerCapacity} = (7 \times 0.11016807219 + 0.21) = 0.98117650533

\\]

\\[

\begin{aligned}

\text{CRF} &= 0.11016807219

\text{AnnualFixedCostPerCapacity} &= (7 \times 0.11016807219 + 0.21) = 0.98117650533

\end{aligned}

\\]

alexdewar · 2026-06-25T14:38:34Z

+\[
+\text{AnnualFixedCostPerOutput} = \frac{4.6836756722}{1} = 4.6836756722
+\]


This didn't render for me:

Suggested change

\[

\text{AnnualFixedCostPerOutput} = \frac{4.6836756722}{1} = 4.6836756722

\]

\\[

\text{AnnualFixedCostPerOutput} = \frac{4.6836756722}{1} = 4.6836756722

\\]

tsmbland added 2 commits June 22, 2026 16:25

Add documentation for commodity price calculations

a98c2cc

Rename section

d297ee2

tsmbland added 5 commits June 22, 2026 16:35

Fix link

01473c0

Clarification about assets with zero activity

e90ae4e

Link to input file docs

365929d

Clearer wording

47d80d7

Add example

5c499e7

tsmbland marked this pull request as ready for review June 23, 2026 14:24

Copilot AI review requested due to automatic review settings June 23, 2026 14:24

Copilot started reviewing on behalf of tsmbland June 23, 2026 14:24 View session

Copilot AI reviewed Jun 23, 2026

View reviewed changes

Comment thread docs/model/prices.md Outdated

Comment thread docs/model/prices.md Outdated

Comment thread docs/model/prices.md Outdated

Comment thread docs/model/prices.md Outdated

tsmbland and others added 5 commits June 23, 2026 15:30

Potential fix for pull request finding

2686346

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

f445870

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

d7bf930

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

3c9c53c

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Lint fix (sorry for all the commits 😂)

019e9e3

tsmbland requested review from AdrianDAlessandro, alexdewar and dc2917 June 23, 2026 14:35

Clarify annual utilisation statement

d14b36f

dc2917 approved these changes Jun 25, 2026

View reviewed changes

Comment thread docs/model/prices.md

Comment thread docs/model/prices.md Outdated

Comment thread docs/model/prices.md Outdated

Comment thread docs/model/prices.md Outdated

tsmbland added 2 commits June 25, 2026 09:04

Add note to glossary about SED/SVD

4560c47

@dc2917 suggestions

f4c9118

alexdewar requested changes Jun 25, 2026

View reviewed changes

	\text{GenericActivityCost} = \text{VariableOperatingCost} + \text{InputPurchases} + \sum \text{GenericFlowCosts}
	\text{GenericActivityCost} = \text{VariableOpex} + \text{InputPurchases} + \sum \text{GenericFlowCosts}

		*Note: this only works if all output commodities are measured in the same energy units (e.g. PJ).
		For this reason, MUSE2 disallows processes that have output commodities with differing units.*


		### GASPRD

		In this scenario, GASPRD is produced by a single GASDRV asset. This asset produces 1 unit of GASPRD

-\\[
-\text{CRF} = 0.11016807219
-\\]
-\\[
-\text{AnnualFixedCostPerCapacity} = (10 \times 0.11016807219 + 0.3) = 1.4016807219
-\\]
+\\[
+\begin{aligned}
+\text{CRF} &= 0.11016807219
+\text{AnnualFixedCostPerCapacity} &= (10 \times 0.11016807219 + 0.3) = 1.4016807219
+\end{aligned}
+\\]

Uh oh!

Conversation

tsmbland commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Key checklist

Further checks

Uh oh!

codecov Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dc2917 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexdewar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tsmbland commented Jun 22, 2026 •

edited

Loading

codecov Bot commented Jun 22, 2026 •

edited

Loading