Rename "asset units" to "asset tranches"

[tsmbland]

Description

We use the term "unit" to mean too many things, so for clarity I decided it would be better to rename "asset units" to "asset tranches". See the issue for more discussion on this.

This PR goes through the codebase and renames variables in the code, updates comments and documentation. I did this the old-fashioned way (I didn't trust AI for this) - find and replace for terms like unit_size, num_units etc., and otherwise searching the codebase for "unit" and manually checking every single instance.

There are a few more substantial changes to the documentation to clarify what tranches are, but nothing too major

Since this renames some parameters, this has some breaking changes compared to v2.1.0, which are listed in upcoming.md and repeated here:

• The capacity_limit_factor parameter in model.toml has been renamed to capacity_tranche_fraction
• The unit_size parameter in processes.csv has been renamed to tranche_size
• The num_units parameter in the asset_capacities.csv output file has been renamed to num_tranches

Fixes #1502

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 99.30070% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 90.95%. Comparing base (035cdd7) to head (2052bb6).

Files with missing lines	Patch %	Lines
src/simulation/optimisation.rs	87.50%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1518   +/-   ##
=======================================
  Coverage   90.94%   90.95%           
=======================================
  Files          61       61           
  Lines        9045     9050    +5     
  Branches     9045     9050    +5     
=======================================
+ Hits         8226     8231    +5     
  Misses        500      500           
  Partials      319      319           

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

[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: 2052bb6	Previous: 849164f	Ratio
example_run/muse1_default example	409753390 ns	257200258.5 ns	1.59
select_best_assets_parallel/20	87172311.25 ns	66430136.16666667 ns	1.31
select_best_assets_sequential/01	9582967.654411765 ns	7215430.817307692 ns	1.33
select_best_assets_sequential/10	90261478.75 ns	69328321.66666666 ns	1.30
select_best_assets_sequential/15	135250523.5 ns	103927071 ns	1.30

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

[tsmbland]

⚠️ 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: 8da3dd0 Previous: 849164f Ratio
example_run/muse1_default example 391144426.5 ns 257200258.5 ns 1.52
example_run/two_regions example 642043028.5 ns 444982302.5 ns 1.44
select_best_assets_sequential/01 9397468.092982456 ns 7215430.817307692 ns 1.30
This comment was automatically generated by workflow using github-action-benchmark.

Clearly these changes will not affect performance, so it's concerning that this gets flagged

[Copilot]

🟡 Changes recommended

The release notes currently reference a non-existent process_capacities.csv and should accurately describe the input/output field renames introduced by this PR.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR standardises terminology by renaming “asset units” (discrete, independently mothballed/retained capacity portions) to “asset tranches” throughout the Rust codebase, input/output schemas, examples, and documentation, aligning implementation and docs with the clarified concept discussed in #1502.

Changes:

• Renamed core capacity concepts and APIs (unit_size → tranche_size, num_units → num_tranches, mothballing/retention terminology likewise) across simulation, assets, input parsing, and output writing.
• Updated schemas, example inputs, regression tests, and golden test CSV headers/data to match the new field names.
• Refreshed documentation (model/investment, glossary, architecture quickstart, release notes) to explain “tranches” and reflect the renamed config and file fields.

File summaries

File	Description
tests/regression.rs	Updates regression patch test name to simple_tranche_size.
tests/cli.rs	Updates CLI patch example constant to simple_tranche_size.
tests/data/two_regions/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/two_outputs/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/simple/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/simple_tranche_size/commodity_prices.csv	Adds new golden regression data for simple_tranche_size.
tests/data/simple_tranche_size/commodity_flows.csv	Adds new golden regression data for simple_tranche_size.
tests/data/simple_tranche_size/assets.csv	Adds new golden regression data for simple_tranche_size.
tests/data/simple_tranche_size/asset_capacities.csv	Adds tranche-header golden output for simple_tranche_size.
tests/data/simple_shadow/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/simple_npv/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/simple_mothball/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/simple_marginal/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/simple_marginal_average/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/simple_ironing_out/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/simple_full/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/muse1_default/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/missing_commodity/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/circularity/asset_capacities.csv	Renames output headers to tranche terminology.
tests/data/circularity_npv/asset_capacities.csv	Renames output headers to tranche terminology.
src/simulation/prices.rs	Updates process fixture construction to use tranche_size.
src/simulation/optimisation/constraints.rs	Updates limit scaling logic/comments and tidies test imports around MoneyPerActivity.
src/simulation/optimisation.rs	Renames optimisation capacity-variable semantics from units to tranches.
src/simulation/market.rs	Renames parameter capacity_limit_factor to capacity_tranche_fraction and updates candidate asset capacity logic/docs.
src/simulation/investment.rs	Renames retention/mothballing/investment selection logic to tranche semantics.
src/simulation.rs	Updates dispatch filtering for partially mothballed assets to tranche semantics.
src/process.rs	Renames unit_size to tranche_size and updates struct docs to match tranche behaviour.
src/output.rs	Renames asset capacity output columns/row fields to tranche terminology and updates tests/fixtures.
src/model/parameters.rs	Renames model parameter to capacity_tranche_fraction and updates docs/default/validation notes.
src/input/process.rs	Updates process input parsing/validation for tranche_size.
src/input/asset.rs	Updates asset input parsing/validation for num_tranches and tranche splitting logic; renames related tests.
src/fixture.rs	Renames multi_unit_asset fixture to multi_tranche_asset and updates process fixture field name.
src/example/patches.rs	Renames patch key to simple_tranche_size.
src/asset/pool.rs	Renames mothball/unretained/decommission logic and tests to tranche terminology.
src/asset/capacity.rs	Renames AssetCapacity internals and APIs from units to tranches and updates tests.
src/asset.rs	Renames asset mothballing/subsetting APIs and internal state from units to tranches; updates tests accordingly.
schemas/output/asset_capacities.yaml	Renames output schema fields to num_tranches / mothballed_tranches.
schemas/input/processes.yaml	Renames unit_size to tranche_size in the process input schema and notes.
schemas/input/model.yaml	Renames capacity_limit_factor to capacity_tranche_fraction in the model schema and notes.
schemas/input/assets.yaml	Renames num_units to num_tranches in the assets input schema and notes.
examples/simple/processes.csv	Renames header column unit_size to tranche_size.
docs/release_notes/upcoming.md	Updates release notes for tranche terminology and records breaking renames (one bullet needs correction).
docs/model/investment.md	Updates conceptual documentation from units to tranches (trial capacity/investment granularity).
docs/glossary.md	Replaces glossary entries for Asset Unit / Unit Size with Asset Tranche / Tranche Size.
docs/developer_guide/architecture_quickstart.md	Updates regression data regeneration command to use simple_tranche_size.
benches/assets.rs	Updates benchmark call site to use capacity_tranche_fraction.

Review details

• Files reviewed: 43/46 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.