Add Units and Dimensions page to documentation

[tsmbland]

Description

Adds a page to the documentation describing how units work in MUSE. Hopefully this should be a useful guide for anyone building a model or interpreting results.

To help explain how monetary quantities work, and to serve as a useful record, I've added a currency field to the model.toml file so that users can record the currency used for all monetary quantities. We have something similar in MUSE1. This isn't actually used by the model, but it helps to stress that monetary quantities should follow some consistent scheme, and is referred to a lot in the documentation to explain how monetary quantities work. Together with the units column in commodities.csv, all prices and costs in the input/output data can now be interpreted in terms of real world units (e.g a price of 0.5 for a commodity measured in PJ, in a model with currency MUSD2020 -> price = $500,000/PJ). Without this parameter, it would be up to the modeller to remember the currency or document it independently, and share it alongside the results.

Whilst capacities don't have a defined unit of measurement in the input data, this can be figured out in a slightly roundabout way using the commodity units and the capacity_to_activity factor. Similarly, together with currency, capital costs can be resolved (e.g. 1.5 might mean $1,500,000/GW). It's a conscious decision not to include capacity units in the input data, because it wouldn't necessarily be correct unless the modeller has done their unit conversions properly, and could lead to a false sense of security. This is not such a worry for commodity units and currency, as these are orthogonal concepts.

(Note, "capacity units" is a distinct concept to "asset units", which very confusingly uses the same word. I've proposed #1502 to change the terminology around asset units to reduce confusion.)

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.30%. Comparing base (a332ac1) to head (9a28da5).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1503      +/-   ##
==========================================
+ Coverage   90.29%   90.30%   +0.01%     
==========================================
  Files          60       60              
  Lines        8645     8658      +13     
  Branches     8645     8658      +13     
==========================================
+ Hits         7806     7819      +13     
  Misses        525      525              
  Partials      314      314              

☔ 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 documentation page explaining MUSE2’s unit conventions (commodity units, activity, capacity, and monetary quantities), and introduces an optional currency label in model.toml as metadata to help users interpret monetary inputs/outputs consistently.

Changes:

• Add currency: Option<String> to ModelParameters, update the input schema, and add a deserialisation test confirming it is optional metadata.
• Add a new “Units and Dimensions” documentation page and link it from the model docs and SUMMARY.
• Populate currency = "MUSD2020" in the example model.toml files to demonstrate/document the convention.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/model/parameters.rs	Adds optional currency field, defaulting to None, plus a test verifying backwards-compatible TOML deserialisation.
schemas/input/model.yaml	Documents the new optional currency property in the model parameters schema.
examples/two_regions/model.toml	Adds currency metadata to the example configuration.
examples/two_outputs/model.toml	Adds currency metadata to the example configuration.
examples/simple/model.toml	Adds currency metadata to the example configuration.
examples/muse1_default/model.toml	Adds currency metadata to the example configuration.
examples/missing_commodity/model.toml	Adds currency metadata to the example configuration.
examples/circularity/model.toml	Adds currency metadata to the example configuration.
docs/SUMMARY.md	Links the new “Units and Dimensions” page in the documentation sidebar.
docs/model/units_and_dimensions.md	New page describing how MUSE2 interprets unit labels and relates activity/capacity/flows/costs.
docs/model/README.md	Adds a short pointer to the new units/dimensions documentation.
docs/model/prices.md	Clarifies that SED/SVD output “unit” consistency is based on label matching (no conversion).

---

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

[tsmbland]

@ahawkes FYI. Hopefully this is all correct and clear!

[ahawkes]

Looks good, thanks!

…

________________________________ From: Tom Bland ***@***.***> Sent: Friday, 21 August 2026 16:25:25 To: EnergySystemsModellingLab/MUSE2 ***@***.***> Cc: Hawkes, Adam D ***@***.***>; Mention ***@***.***> Subject: Re: [EnergySystemsModellingLab/MUSE2] Add Units and Dimensions page to documentation (PR #1503) CAUTION: This message came from outside Imperial. Do not click links or open attachments unless you recognise the sender and were expecting this email. [https://avatars.githubusercontent.com/u/23723407?s=20&v=4]tsmbland left a comment (EnergySystemsModellingLab/MUSE2#1503)<#1503 (comment)> @ahawkes<https://github.com/ahawkes> FYI. Hopefully this is all correct and clear! — Reply to this email directly, view it on GitHub<#1503?email_source=notifications&email_token=AC37JLLXRPPETFTQBKLBVQL5LBEULA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZXGAZTKMJWGEY2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5370351611>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AC37JLJYJEG2SBVFN7RBDGT5LBEULAVCNFSNUABFKJSXA33TNF2G64TZHM3TSMBYGA4TIOJTHNEXG43VMU5TKMRRGQYTSNBRGM42C5QC>. You are receiving this because you were mentioned.Message ID: ***@***.***>