From cdc5702ed56f95496abd16013afa872f6b868028 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Wed, 2 Sep 2026 15:26:20 +0100 Subject: [PATCH 01/10] First draft for release notes --- docs/release_notes/upcoming.md | 94 --------------- docs/release_notes/v2.2.0.md | 213 +++++++++++++++++++++++++++++++++ 2 files changed, 213 insertions(+), 94 deletions(-) create mode 100644 docs/release_notes/v2.2.0.md diff --git a/docs/release_notes/upcoming.md b/docs/release_notes/upcoming.md index 1928f2dd6..0abd524f1 100644 --- a/docs/release_notes/upcoming.md +++ b/docs/release_notes/upcoming.md @@ -2,100 +2,6 @@ ## New features -- Users can now optionally pass [custom options][highs-opts-docs] to the HiGHS solver ([#1276]) -- Input files are now copied to the output folder for reference ([#1282], [#1303]) -- Implement a new appraisal approach for the LCOX objective type ([#1319]) -- Circular commodity markets can now use cost-based pricing strategies ([#1322]) -- The `max_decommission_year` column in `assets.csv` is now optional, defaulting to - `commission_year` plus the process's lifetime if not provided ([#1354]) -- Investment/commodity graphs (as generated by `muse2 save-graphs`) now include secondary - (non-primary) edges ([#1361]) -- Implement a new appraisal approach for the NPV objective type ([#1379]) -- Added a configurable `commodity_balance_epsilon` model parameter to help candidate assets dispatch - during investment appraisal ([#1387], [#1445]) -- New tranching approach for investment appraisal, sizing candidate asset capacities based on - annual demand rather than demand limiting capacity ([#1391], [#1395]) -- Added a fallback price to investment appraisal to reduce the risk of failed dispatch runs - ([#1420]) -- The execution time of key simulation steps (e.g. dispatch, agent investment) is now logged - ([#1421]) -- The `addition_limit` column in `process_investment_constraints.csv` is now optional ([#1427]) -- Memory usage and performance has been drastically improved for divisible assets with many tranches - ([#1464]) -- `asset_capacities.csv` now reports total and mothballed capacity and tranche counts ([#1461]) - ## Breaking changes -- Changed the default `pricing_strategy` for SED/SVD commodities from "shadow" to "full_average" ([#1281]) -- The individual tranches of divisible assets are no longer treated as separate assets and are instead - grouped under a single larger asset, affecting a number of output files. The `group_id` column has - been removed from all files. ([#1286], [#1302], [#1455]) -- The `agent_search_space.csv` input file has been renamed to `agent_search_spaces.csv` for - consistency ([#1293]) -- Due to an internal change, some options in CSV files are now case sensitive (e.g. you must put - `lcox` rather than `LCOX`). The error message you see if it does not match will now be more - informative, however. ([#1376]) -- Stricter input validation: `capacity_to_activity` must now be greater than zero. Previously, - `capacity_to_activity = 0` was permitted ([#1391]) -- The `capacity_limit_factor` parameter in `model.toml` has been renamed to - `capacity_tranche_fraction` ([#1502]) -- The `unit_size` parameter in `processes.csv` has been renamed to `tranche_size` ([#1502]) -- The `num_units` parameter in the `asset_capacities.csv` output file has been renamed to - `num_tranches` ([#1502]) - ## Bug fixes - -- Fix misleading warning message for assets decommissioned before simulation start ([#1259]) -- Avoid installing excessive candidate capacity during investment when there is little demand - remaining ([#1271]) -- Fix parsing and validation of agent search space file ([#1293]) -- Fix a bug in asset selection for circular commodity markets when agents in the same cycle have - different commodity shares ([#1323]) -- Fix demand limiting capacity calculations to account for seasonal/annual activity limits ([#1326]) -- Prevent commodities of type `OTH` from being specified in `agent_commodity_portions.csv` ([#1327]) -- Use shadow prices rather than market prices for appraisal optimisations and dispatch runs during - investment ([#1349]) -- Asset selection can now continue even if it runs out of options, giving dispatch a chance to still - meet demand, rather than failing immediately ([#1365]) -- Calculate commodity prices using the dispatch solution without candidate assets, so that they are - consistent with the flows reported in `commodity_flows.csv` ([#1389]) -- Fix price calculations to prioritise active assets over inactive ones when determining commodity - prices ([#1392]) -- The `unmet_demand.csv` output file is no longer created unless it is needed ([#1405]) -- Mothballed assets are now excluded from the main dispatch run ([#1458]) - -[highs-opts-docs]: ../developer_guide/custom_highs_options.md -[#1259]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1259 -[#1271]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1271 -[#1276]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1276 -[#1281]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1281 -[#1282]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1282 -[#1286]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1286 -[#1293]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1293 -[#1302]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1302 -[#1303]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1303 -[#1319]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1319 -[#1322]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1322 -[#1323]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1323 -[#1326]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1326 -[#1327]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1327 -[#1349]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1349 -[#1354]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1354 -[#1361]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1361 -[#1365]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1365 -[#1376]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1376 -[#1379]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1379 -[#1387]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1387 -[#1389]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1389 -[#1391]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1391 -[#1392]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1392 -[#1395]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1395 -[#1405]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1405 -[#1420]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1420 -[#1421]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1421 -[#1427]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1427 -[#1445]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1445 -[#1455]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1455 -[#1458]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1458 -[#1464]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1464 -[#1502]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1502 diff --git a/docs/release_notes/v2.2.0.md b/docs/release_notes/v2.2.0.md new file mode 100644 index 000000000..12633846a --- /dev/null +++ b/docs/release_notes/v2.2.0.md @@ -0,0 +1,213 @@ +# Release notes for MUSE2 v2.2.0 + +Please be aware that there are some breaking changes in this release, which may require you to +update the input files of any existing models. We have tried to outline these in the "Breaking +changes" section below, but please do get in touch if you have any issues adapting models to the new +version. + +Some of the new features in this release are still experimental, and will continue to be worked on +for future releases. In the meantime, any feedback on these features is very welcome. + +As always, you can keep track of upcoming changes for the next release in the +[upcoming release notes]. + +## New features + +### Total capacity limits + +Users can now add hard upper limits on the total amount of capacity that can exist for a certain +process at any one time, via the `total_capacity_limit` parameter in +[`process_investment_constraints.csv`] ([#1417], [#1496]). See [investment documentation] for more +details. + +Please note that these limits may be broken in models with circular commodity dependencies - this is +a known limitation ([#1498]), as circularities remain an experimental feature. + +### Investment appraisal + +This release fundamentally changes the investment appraisal approaches for both the LCOX and NPV +objectives. Appraisal now uses a more consistent approach across objectives, differing +between methods only in the calculation of the objective metric. All approaches now appraise a +capacity pre-calculated based on demand or input parameters (see "tranching" section below), optimise +dispatch of that capacity over remaining demand, and calculate an objective-specific metric based on +this dispatch ([#1319]). For LCOX, this replaces the previous approach that used dynamic capacity +variables and the Value of Lost Load parameter, which had a tendency to inflate capacities. The NPV +formulation has also changed to use SNAS (Specific Net Annualised Surplus) rather than Profitability +Index, which is more robust to assets with low/zero fixed costs ([#1379]). More details can be found +in the updated [investment documentation]. + +A further change is to introduce a fallback cost to the activity coefficient calculation, set by the +`fallback_pricing_strategy` parameter in `model.toml` ([#1420]). This reframes the optimisation +problem to consider the alternative cost of choosing _not_ to invest in a process, which encourages +investment in cases where there would otherwise lack an incentive to do so. This is also described +in more detail in the [investment documentation]. + +Casual users do not need to be concerned with the details of these changes, but may notice changes +in asset selection, better matching of capacities to demands, and less frequent occurrence of model +failures triggered by an absence of viable investment options. + +In addition, investment appraisal is now parallelised over candidate assets, which should result in +significant performance improvements for large models run on multi-core machines ([#1466]). + +### Divisible assets and tranching + +[v2.1.0] introduced the concept of asset groups as a proxy for modelling asset divisibility, i.e. +the idea that overall asset capacity may be made up of multiple discrete components, or _tranches_, +(e.g. a group of wind turbines in a wind farm) which can be mothballed and decommissioned +independently. This approach resulted in a (potentially large) number of `Asset`s (with distinct +`asset_id`s) linked together by a common `group_id`. + +Whilst this feature worked as intended, there were significant performance costs involved with +modelling these tranches as distinct `Asset` objects, and unnecessary complexity in the output file +format. The previous approach also limited asset divisibility to processes with a defined `unit_size`. + +v2.2.0 does away with asset groups, and instead expresses the capacity of each individual `Asset` as +a collection of tranches, each of which work in unison in dispatch, but can be independently +mothballed and decommissioned ([#1464], [#1483]). + +Tranches are __not__ reported individually in the output results. Rather, results files report +aggregate flows and capacities for the overall `Asset`, represented by a single `asset_id` +([#1455]). Since capacities for each `Asset` can now change over time, capacities are removed +from the fixed asset definition in [`assets.csv`], over to a new [`asset_capacities.csv`] file, +which reports capacity for each asset in each milestone year ([#1302]). + +The size of these tranches can be set on a per-process basis, either to a fixed pre-defined +capacity, or determined dynamically at the time of investment based on demand. There are several +new/renamed parameters to be aware of ([#1518]): + +- `tranche_size`: Replaces `unit_size` in [`processes.csv`]. An optional parameter to set a _fixed_ +tranche size for a process. +- `capacity_tranche_fraction`: A factor, defined in [`model.toml`], used to infer tranche sizes +at the time of investment for assets _without_ a defined `tranche_size` ([#1391], [#1395]). +See [investment documentation] for more details. +- `num_tranches`: The number of equal-capacity tranches making up an overall capacity. Reported with +overall capacities in [`asset_capacities.csv`], and can be used to split existing assets into +tranches in the [`assets.csv`] input file ([#1480]). + +As well as these parameter changes, and changes to the output format, users may notice performance +improvements compared to equivalent models in v2.1.0. It is worth emphasising, however, that asset +divisibility still comes with a performance cost, and that the `capacity_tranche_fraction`, +`num_tranches` and `tranche_size` parameters should be set at appropriate values to trade-off +performance against granularity. + +### Commodity constraints (experimental) + +Users can now add constraints on the total production and/or consumption of SED and OTH commodities +in a given region in a given year/season/time slice, via the [`commodity_constraints.csv`] file +([#1487], [#1513]). See the [dispatch documentation] for more details. + +Please note that this feature is currently experimental, and expected to cause conflicts in +otherwise working models, as these constraints are currently only considered in full-system +dispatch, and not factored in to the investment algorithm. Future releases will hopefully address +this, but for now, in order to use this feature, you must enable the `please_give_me_broken_results` +option in [`model.toml`]. + +### Dispatch optimisation + +Additional constraints and terms have been added to the dispatch optimisation problem to push +solutions towards a more intentional and consistent solution, without affecting the primary cost +objective. Two such additions, "Equal Utilisation of Equivalent Assets" ([#1477]) and +"Seasonal/Annual Utilisation Penalties" ([#1478]), are explained in more detail in the +[dispatch documentation]. + +Casual users do not need to concerned with the underlying model changes, but should be aware of the +implications. Firstly, users should notice more sensible and interpretable asset utilisation +patterns, away from arbitrary concentration of activity on certain assets and time slices, now +spreading utilisation evenly across equally good assets and time slices. In many cases this will +also have knock-on consequences for commodity prices. Secondly, results were previously sensitive to +differences between platforms and operating systems, as small floating point differences could push +the solver to a different convergence point in the under-constrained problem. With these added +constraints and terms, this should now no longer be the case. There may be some performance costs +associated with these additions, but these are expected to be small. + +## Other new features + +- Users can now optionally pass [custom options][highs-opts-docs] to the HiGHS solver ([#1276]) +- Input files are now copied to the output folder for reference ([#1282], [#1303]) +- Circular commodity markets can now use cost-based pricing strategies ([#1322]) +- Added a configurable `commodity_balance_epsilon` model parameter to help candidate assets dispatch + during investment appraisal ([#1387], [#1445]) +- The execution time of key simulation steps (e.g. dispatch, agent investment) is now logged + ([#1421]) + +## Breaking changes + +These changes may require users to update the input files for existing models developed using +previous versions of MUSE2. + +- Changed the default `pricing_strategy` for SED/SVD commodities from "shadow" to "full_average" ([#1281]) +- The `group_id` column has been removed from all output files ([#1286], [#1302], [#1455]) +- The `agent_search_space.csv` input file has been renamed to `agent_search_spaces.csv` for + consistency ([#1293]) +- Due to an internal change, some options in CSV files are now case sensitive (e.g. you must put + `lcox` rather than `LCOX`). The error message you see if it does not match will now be more + informative, however. ([#1376]) +- Stricter input validation: `capacity_to_activity` must now be greater than zero. Previously, + `capacity_to_activity = 0` was permitted ([#1391]) +- The `capacity_limit_factor` parameter in `model.toml` has been removed. Please use + `capacity_tranche_fraction` (see above) instead ([#1518]) +- The `unit_size` parameter in `processes.csv` has been renamed to `tranche_size` ([#1518]) + +## Bug fixes + +- Fix misleading warning message for assets decommissioned before simulation start ([#1259]) +- Fix parsing and validation of agent search space file ([#1293]) +- Fix a bug in asset selection for circular commodity markets when agents in the same cycle have + different commodity shares ([#1323]) +- Prevent commodities of type `OTH` from being specified in `agent_commodity_portions.csv` ([#1327]) +- Use shadow prices rather than market prices for appraisal optimisations and dispatch runs during + investment ([#1349]) +- Asset selection can now continue even if it runs out of options, giving dispatch a chance to still + meet demand, rather than failing immediately ([#1365]) +- Calculate commodity prices using the dispatch solution without candidate assets, so that they are + consistent with the flows reported in `commodity_flows.csv` ([#1389]) +- Fix price calculations to prioritise active assets over inactive ones when determining commodity + prices ([#1392]) +- The `unmet_demand.csv` output file is no longer created unless it is needed ([#1405]) +- Mothballed assets are now excluded from the main dispatch run ([#1458]) +- Disallow negative values for `capital_cost`, `fixed_operating_cost` and `variable_operating_cost` + ([#1485]) + +[#1259]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1259 +[#1276]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1276 +[#1281]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1281 +[#1282]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1282 +[#1286]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1286 +[#1293]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1293 +[#1302]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1302 +[#1303]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1303 +[#1319]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1319 +[#1322]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1322 +[#1323]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1323 +[#1327]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1327 +[#1349]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1349 +[#1365]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1365 +[#1376]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1376 +[#1379]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1379 +[#1387]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1387 +[#1389]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1389 +[#1391]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1391 +[#1392]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1392 +[#1395]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1395 +[#1405]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1405 +[#1420]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1420 +[#1421]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1421 +[#1445]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1445 +[#1455]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1455 +[#1458]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1458 +[#1464]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1464 +[#1485]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1485 +[#1518]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1502 + + + + +[upcoming release notes]: https://energysystemsmodellinglab.github.io/MUSE2/release_notes/upcoming.html + + +[v2.1.0]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/release_notes/v2.1.0.html + + +[investment documentation]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/model/investment.html +[dispatch documentation]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/model/dispatch_optimisation.html +[highs-opts-docs]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/developer_guide/custom_highs_options.html From d74e6cadcaacb1c51bb92d148b76ceff4e7ea068 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Wed, 2 Sep 2026 16:00:15 +0100 Subject: [PATCH 02/10] Add missing links --- docs/release_notes/v2.2.0.md | 58 +++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/docs/release_notes/v2.2.0.md b/docs/release_notes/v2.2.0.md index 12633846a..d7a355ee9 100644 --- a/docs/release_notes/v2.2.0.md +++ b/docs/release_notes/v2.2.0.md @@ -37,7 +37,7 @@ Index, which is more robust to assets with low/zero fixed costs ([#1379]). More in the updated [investment documentation]. A further change is to introduce a fallback cost to the activity coefficient calculation, set by the -`fallback_pricing_strategy` parameter in `model.toml` ([#1420]). This reframes the optimisation +`fallback_pricing_strategy` parameter in [`model.toml`] ([#1420]). This reframes the optimisation problem to consider the alternative cost of choosing _not_ to invest in a process, which encourages investment in cases where there would otherwise lack an incentive to do so. This is also described in more detail in the [investment documentation]. @@ -68,21 +68,21 @@ mothballed and decommissioned ([#1464], [#1483]). Tranches are __not__ reported individually in the output results. Rather, results files report aggregate flows and capacities for the overall `Asset`, represented by a single `asset_id` ([#1455]). Since capacities for each `Asset` can now change over time, capacities are removed -from the fixed asset definition in [`assets.csv`], over to a new [`asset_capacities.csv`] file, -which reports capacity for each asset in each milestone year ([#1302]). +from the fixed asset definition in the [`assets.csv` output file], over to a new +[`asset_capacities.csv`] file, which reports capacity for each asset in each milestone year ([#1302]). The size of these tranches can be set on a per-process basis, either to a fixed pre-defined capacity, or determined dynamically at the time of investment based on demand. There are several new/renamed parameters to be aware of ([#1518]): - `tranche_size`: Replaces `unit_size` in [`processes.csv`]. An optional parameter to set a _fixed_ -tranche size for a process. + tranche size for a process. - `capacity_tranche_fraction`: A factor, defined in [`model.toml`], used to infer tranche sizes -at the time of investment for assets _without_ a defined `tranche_size` ([#1391], [#1395]). -See [investment documentation] for more details. + at the time of investment for assets _without_ a defined `tranche_size` ([#1391], [#1395]). + See [investment documentation] for more details. - `num_tranches`: The number of equal-capacity tranches making up an overall capacity. Reported with -overall capacities in [`asset_capacities.csv`], and can be used to split existing assets into -tranches in the [`assets.csv`] input file ([#1480]). + overall capacities in [`asset_capacities.csv`], and can be used to split existing assets into + tranches in the [`assets.csv` input file] ([#1480]). As well as these parameter changes, and changes to the output format, users may notice performance improvements compared to equivalent models in v2.1.0. It is worth emphasising, however, that asset @@ -125,8 +125,8 @@ associated with these additions, but these are expected to be small. - Users can now optionally pass [custom options][highs-opts-docs] to the HiGHS solver ([#1276]) - Input files are now copied to the output folder for reference ([#1282], [#1303]) - Circular commodity markets can now use cost-based pricing strategies ([#1322]) -- Added a configurable `commodity_balance_epsilon` model parameter to help candidate assets dispatch - during investment appraisal ([#1387], [#1445]) +- Added a configurable `commodity_balance_epsilon` parameter in [`model.toml`] to help + candidate assets dispatch during investment appraisal ([#1387], [#1445]) - The execution time of key simulation steps (e.g. dispatch, agent investment) is now logged ([#1421]) @@ -137,16 +137,16 @@ previous versions of MUSE2. - Changed the default `pricing_strategy` for SED/SVD commodities from "shadow" to "full_average" ([#1281]) - The `group_id` column has been removed from all output files ([#1286], [#1302], [#1455]) -- The `agent_search_space.csv` input file has been renamed to `agent_search_spaces.csv` for +- The `agent_search_space.csv` input file has been renamed to [`agent_search_spaces.csv`] for consistency ([#1293]) - Due to an internal change, some options in CSV files are now case sensitive (e.g. you must put `lcox` rather than `LCOX`). The error message you see if it does not match will now be more informative, however. ([#1376]) - Stricter input validation: `capacity_to_activity` must now be greater than zero. Previously, `capacity_to_activity = 0` was permitted ([#1391]) -- The `capacity_limit_factor` parameter in `model.toml` has been removed. Please use +- The `capacity_limit_factor` parameter in [`model.toml`] has been removed. Please use `capacity_tranche_fraction` (see above) instead ([#1518]) -- The `unit_size` parameter in `processes.csv` has been renamed to `tranche_size` ([#1518]) +- The `unit_size` parameter in [`processes.csv`] has been renamed to `tranche_size` ([#1518]) ## Bug fixes @@ -154,19 +154,19 @@ previous versions of MUSE2. - Fix parsing and validation of agent search space file ([#1293]) - Fix a bug in asset selection for circular commodity markets when agents in the same cycle have different commodity shares ([#1323]) -- Prevent commodities of type `OTH` from being specified in `agent_commodity_portions.csv` ([#1327]) +- Prevent commodities of type `OTH` from being specified in [`agent_commodity_portions.csv`] ([#1327]) - Use shadow prices rather than market prices for appraisal optimisations and dispatch runs during investment ([#1349]) - Asset selection can now continue even if it runs out of options, giving dispatch a chance to still meet demand, rather than failing immediately ([#1365]) - Calculate commodity prices using the dispatch solution without candidate assets, so that they are - consistent with the flows reported in `commodity_flows.csv` ([#1389]) + consistent with the flows reported in [`commodity_flows.csv`] ([#1389]) - Fix price calculations to prioritise active assets over inactive ones when determining commodity prices ([#1392]) -- The `unmet_demand.csv` output file is no longer created unless it is needed ([#1405]) +- The [`unmet_demand.csv`] output file is no longer created unless it is needed ([#1405]) - Mothballed assets are now excluded from the main dispatch run ([#1458]) - Disallow negative values for `capital_cost`, `fixed_operating_cost` and `variable_operating_cost` - ([#1485]) + in [`process_parameters.csv`] ([#1485]) [#1259]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1259 [#1276]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1276 @@ -190,14 +190,24 @@ previous versions of MUSE2. [#1392]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1392 [#1395]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1395 [#1405]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1405 +[#1417]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1417 [#1420]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1420 [#1421]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1421 [#1445]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1445 [#1455]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1455 [#1458]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1458 [#1464]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1464 +[#1466]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1466 +[#1477]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1477 +[#1478]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1478 +[#1480]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1480 +[#1483]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1483 +[#1487]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1487 [#1485]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1485 -[#1518]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1502 +[#1496]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1496 +[#1498]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1498 +[#1513]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1513 +[#1518]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1518 @@ -211,3 +221,15 @@ previous versions of MUSE2. [investment documentation]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/model/investment.html [dispatch documentation]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/model/dispatch_optimisation.html [highs-opts-docs]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/developer_guide/custom_highs_options.html +[`model.toml`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/input_files.html#model-parameters-modeltoml +[`processes.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/input_files.html#processescsv +[`process_parameters.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/input_files.html#process_parameterscsv +[`process_investment_constraints.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/input_files.html#process-investment-constraintscsv +[`agent_search_spaces.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/input_files.html#agent-search-spacescsv +[`agent_commodity_portions.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/input_files.html#agent-commodity-portionscsv +[`commodity_constraints.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/input_files.html#commodity-constraintscsv +[`assets.csv` output file]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/output_files.html#assetscsv +[`assets.csv` input file]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/input_files.html#assetscsv +[`asset_capacities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/output_files.html#asset-capacitiescsv +[`commodity_flows.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/output_files.html#commodity-flowscsv +[`unmet_demand.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/output_files.html#unmet-demandcsv From c4098013846d657d1e7dd33bd0e86fc40451f106 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Wed, 2 Sep 2026 16:34:29 +0100 Subject: [PATCH 03/10] Small wording improvements --- docs/release_notes/v2.2.0.md | 47 ++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/release_notes/v2.2.0.md b/docs/release_notes/v2.2.0.md index d7a355ee9..8d834b058 100644 --- a/docs/release_notes/v2.2.0.md +++ b/docs/release_notes/v2.2.0.md @@ -43,11 +43,11 @@ investment in cases where there would otherwise lack an incentive to do so. This in more detail in the [investment documentation]. Casual users do not need to be concerned with the details of these changes, but may notice changes -in asset selection, better matching of capacities to demands, and less frequent occurrence of model -failures triggered by an absence of viable investment options. +in asset selection, better matching of capacities to demands, and fewer model failures triggered by +an absence of viable investment options. -In addition, investment appraisal is now parallelised over candidate assets, which should result in -significant performance improvements for large models run on multi-core machines ([#1466]). +In addition, investment appraisal is now parallelised over candidate assets, which may improve +performance, particularly for large models run on multi-core machines ([#1466]). ### Divisible assets and tranching @@ -57,10 +57,6 @@ the idea that overall asset capacity may be made up of multiple discrete compone independently. This approach resulted in a (potentially large) number of `Asset`s (with distinct `asset_id`s) linked together by a common `group_id`. -Whilst this feature worked as intended, there were significant performance costs involved with -modelling these tranches as distinct `Asset` objects, and unnecessary complexity in the output file -format. The previous approach also limited asset divisibility to processes with a defined `unit_size`. - v2.2.0 does away with asset groups, and instead expresses the capacity of each individual `Asset` as a collection of tranches, each of which work in unison in dispatch, but can be independently mothballed and decommissioned ([#1464], [#1483]). @@ -71,7 +67,7 @@ aggregate flows and capacities for the overall `Asset`, represented by a single from the fixed asset definition in the [`assets.csv` output file], over to a new [`asset_capacities.csv`] file, which reports capacity for each asset in each milestone year ([#1302]). -The size of these tranches can be set on a per-process basis, either to a fixed pre-defined +The size of these tranches can be set on a per-process basis, either to a fixed, predefined capacity, or determined dynamically at the time of investment based on demand. There are several new/renamed parameters to be aware of ([#1518]): @@ -84,11 +80,14 @@ new/renamed parameters to be aware of ([#1518]): overall capacities in [`asset_capacities.csv`], and can be used to split existing assets into tranches in the [`assets.csv` input file] ([#1480]). -As well as these parameter changes, and changes to the output format, users may notice performance -improvements compared to equivalent models in v2.1.0. It is worth emphasising, however, that asset -divisibility still comes with a performance cost, and that the `capacity_tranche_fraction`, -`num_tranches` and `tranche_size` parameters should be set at appropriate values to trade-off -performance against granularity. +Since _all_ assets can now be divided into tranches and partially decommissioned (not just those +with a defined `tranche_size`), this should allow capacity to be matched more closely to demand and +stale capacity to be removed more readily. + +These changes may bring performance improvements for equivalent models compared to v2.1.0. It is +worth emphasising, however, that asset divisibility still comes with a performance cost, and that +the `capacity_tranche_fraction`, `num_tranches` and `tranche_size` parameters therefore involve a +trade-off between performance and capacity granularity. ### Commodity constraints (experimental) @@ -104,21 +103,24 @@ option in [`model.toml`]. ### Dispatch optimisation -Additional constraints and terms have been added to the dispatch optimisation problem to push -solutions towards a more intentional and consistent solution, without affecting the primary cost -objective. Two such additions, "Equal Utilisation of Equivalent Assets" ([#1477]) and +Additional constraints and small objective penalties have been added to the dispatch optimisation +problem to push solutions towards a more intentional and consistent solution. The penalties are +deliberately kept small so that they primarily distinguish between otherwise equivalent solutions +while having negligible influence on the primary cost objective. Two such additions, "Equal +Utilisation of Equivalent Assets" ([#1477]) and "Seasonal/Annual Utilisation Penalties" ([#1478]), are explained in more detail in the [dispatch documentation]. -Casual users do not need to concerned with the underlying model changes, but should be aware of the +Casual users do not need to be concerned with the underlying model changes, but should be aware of the implications. Firstly, users should notice more sensible and interpretable asset utilisation patterns, away from arbitrary concentration of activity on certain assets and time slices, now spreading utilisation evenly across equally good assets and time slices. In many cases this will also have knock-on consequences for commodity prices. Secondly, results were previously sensitive to differences between platforms and operating systems, as small floating point differences could push -the solver to a different convergence point in the under-constrained problem. With these added -constraints and terms, this should now no longer be the case. There may be some performance costs -associated with these additions, but these are expected to be small. +the solver to a different convergence point in the under-constrained problem. These additions should +substantially reduce the sensitivity of results to small platform-dependent numerical differences, +although they cannot guarantee identical results across platforms. There may be some performance +costs associated with these additions, but these are expected to be small. ## Other new features @@ -163,7 +165,7 @@ previous versions of MUSE2. consistent with the flows reported in [`commodity_flows.csv`] ([#1389]) - Fix price calculations to prioritise active assets over inactive ones when determining commodity prices ([#1392]) -- The [`unmet_demand.csv`] output file is no longer created unless it is needed ([#1405]) +- The `debug_unmet_demand.csv` output file is no longer created unless it is needed ([#1405]) - Mothballed assets are now excluded from the main dispatch run ([#1458]) - Disallow negative values for `capital_cost`, `fixed_operating_cost` and `variable_operating_cost` in [`process_parameters.csv`] ([#1485]) @@ -232,4 +234,3 @@ previous versions of MUSE2. [`assets.csv` input file]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/input_files.html#assetscsv [`asset_capacities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/output_files.html#asset-capacitiescsv [`commodity_flows.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/output_files.html#commodity-flowscsv -[`unmet_demand.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/file_formats/output_files.html#unmet-demandcsv From f80a67dbc1a95c7bb9a82458ed04dcb8ca981367 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Wed, 2 Sep 2026 16:38:31 +0100 Subject: [PATCH 04/10] Link file --- docs/SUMMARY.md | 1 + docs/release_notes/README.md | 1 + docs/release_notes/v2.2.0.md | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 45e724747..911d74c86 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -27,4 +27,5 @@ - [Release notes](release_notes/README.md) - [MUSE2 v2.0.0 (October 14, 2025)](release_notes/v2.0.0.md) - [MUSE2 v2.1.0 (March 31, 2026)](release_notes/v2.1.0.md) + - [MUSE2 v2.2.0 (September 3, 2026)](release_notes/v2.2.0.md) - [Next unreleased version](release_notes/upcoming.md) diff --git a/docs/release_notes/README.md b/docs/release_notes/README.md index cf7b216c3..008fb3e8d 100644 --- a/docs/release_notes/README.md +++ b/docs/release_notes/README.md @@ -8,5 +8,6 @@ To see the list of changes for the current, in-progress version of MUSE2, [see h - [MUSE2 v2.0.0 (October 14, 2025)](./v2.0.0.md) - [MUSE2 v2.1.0 (March 31, 2026)](./v2.1.0.md) +- [MUSE2 v2.2.0 (September 3, 2026)](./v2.2.0.md) [GitHub releases page]: https://github.com/EnergySystemsModellingLab/MUSE2/releases diff --git a/docs/release_notes/v2.2.0.md b/docs/release_notes/v2.2.0.md index 8d834b058..c225b9285 100644 --- a/docs/release_notes/v2.2.0.md +++ b/docs/release_notes/v2.2.0.md @@ -1,4 +1,4 @@ -# Release notes for MUSE2 v2.2.0 +# Release notes for MUSE2 v2.2.0 (September 3, 2026) Please be aware that there are some breaking changes in this release, which may require you to update the input files of any existing models. We have tried to outline these in the "Breaking From d13d3ecaded6a2ac071a509772b79bda9efd4f2d Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Wed, 2 Sep 2026 16:56:15 +0100 Subject: [PATCH 05/10] More wording improvements --- docs/release_notes/v2.2.0.md | 71 ++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 39 deletions(-) diff --git a/docs/release_notes/v2.2.0.md b/docs/release_notes/v2.2.0.md index c225b9285..bf61827c7 100644 --- a/docs/release_notes/v2.2.0.md +++ b/docs/release_notes/v2.2.0.md @@ -13,22 +13,11 @@ As always, you can keep track of upcoming changes for the next release in the ## New features -### Total capacity limits - -Users can now add hard upper limits on the total amount of capacity that can exist for a certain -process at any one time, via the `total_capacity_limit` parameter in -[`process_investment_constraints.csv`] ([#1417], [#1496]). See [investment documentation] for more -details. - -Please note that these limits may be broken in models with circular commodity dependencies - this is -a known limitation ([#1498]), as circularities remain an experimental feature. - ### Investment appraisal This release fundamentally changes the investment appraisal approaches for both the LCOX and NPV -objectives. Appraisal now uses a more consistent approach across objectives, differing -between methods only in the calculation of the objective metric. All approaches now appraise a -capacity pre-calculated based on demand or input parameters (see "tranching" section below), optimise +objectives. Appraisal now uses a more consistent approach across objectives: all objectives now +appraise a capacity pre-determined capacity (see "tranching" section below), optimise dispatch of that capacity over remaining demand, and calculate an objective-specific metric based on this dispatch ([#1319]). For LCOX, this replaces the previous approach that used dynamic capacity variables and the Value of Lost Load parameter, which had a tendency to inflate capacities. The NPV @@ -42,9 +31,8 @@ problem to consider the alternative cost of choosing _not_ to invest in a proces investment in cases where there would otherwise lack an incentive to do so. This is also described in more detail in the [investment documentation]. -Casual users do not need to be concerned with the details of these changes, but may notice changes -in asset selection, better matching of capacities to demands, and fewer model failures triggered by -an absence of viable investment options. +Users may notice changes in asset selection, better matching of capacities to demands, and fewer +model failures triggered by an absence of viable investment options. In addition, investment appraisal is now parallelised over candidate assets, which may improve performance, particularly for large models run on multi-core machines ([#1466]). @@ -54,8 +42,8 @@ performance, particularly for large models run on multi-core machines ([#1466]). [v2.1.0] introduced the concept of asset groups as a proxy for modelling asset divisibility, i.e. the idea that overall asset capacity may be made up of multiple discrete components, or _tranches_, (e.g. a group of wind turbines in a wind farm) which can be mothballed and decommissioned -independently. This approach resulted in a (potentially large) number of `Asset`s (with distinct -`asset_id`s) linked together by a common `group_id`. +independently. This approach resulted in a (potentially large) number of `Asset`'s (with distinct +`asset_id`'s) linked together by a common `group_id`. v2.2.0 does away with asset groups, and instead expresses the capacity of each individual `Asset` as a collection of tranches, each of which work in unison in dispatch, but can be independently @@ -63,31 +51,37 @@ mothballed and decommissioned ([#1464], [#1483]). Tranches are __not__ reported individually in the output results. Rather, results files report aggregate flows and capacities for the overall `Asset`, represented by a single `asset_id` -([#1455]). Since capacities for each `Asset` can now change over time, capacities are removed -from the fixed asset definition in the [`assets.csv` output file], over to a new +([#1455]). Since capacities for each `Asset` can now change over time, capacities are moved +from the fixed asset definition in the [`assets.csv` output file] over to a new [`asset_capacities.csv`] file, which reports capacity for each asset in each milestone year ([#1302]). The size of these tranches can be set on a per-process basis, either to a fixed, predefined -capacity, or determined dynamically at the time of investment based on demand. There are several -new/renamed parameters to be aware of ([#1518]): +capacity, or determined dynamically at the time of investment based on demand. Investment appraisal +(see above) works on one tranche at a time. There are several new/renamed parameters to be aware of +([#1518]): - `tranche_size`: Replaces `unit_size` in [`processes.csv`]. An optional parameter to set a _fixed_ tranche size for a process. - `capacity_tranche_fraction`: A factor, defined in [`model.toml`], used to infer tranche sizes at the time of investment for assets _without_ a defined `tranche_size` ([#1391], [#1395]). See [investment documentation] for more details. -- `num_tranches`: The number of equal-capacity tranches making up an overall capacity. Reported with - overall capacities in [`asset_capacities.csv`], and can be used to split existing assets into - tranches in the [`assets.csv` input file] ([#1480]). +- `num_tranches`: The number of equal-capacity tranches making up an overall asset capacity. + Reported with overall capacities in [`asset_capacities.csv`], and can be used to split existing + assets into tranches in the [`assets.csv` input file] ([#1480]). Since _all_ assets can now be divided into tranches and partially decommissioned (not just those with a defined `tranche_size`), this should allow capacity to be matched more closely to demand and stale capacity to be removed more readily. -These changes may bring performance improvements for equivalent models compared to v2.1.0. It is -worth emphasising, however, that asset divisibility still comes with a performance cost, and that -the `capacity_tranche_fraction`, `num_tranches` and `tranche_size` parameters therefore involve a -trade-off between performance and capacity granularity. +### Total capacity limits + +Users can now add hard upper limits on the total amount of capacity that can exist for a certain +process at any one time, via the `total_capacity_limit` parameter in +[`process_investment_constraints.csv`] ([#1417], [#1496]). See [investment documentation] for more +details. + +Please note that these limits may be broken in models with circular commodity dependencies - this is +a known limitation ([#1498]), as circularities remain an experimental feature. ### Commodity constraints (experimental) @@ -111,16 +105,15 @@ Utilisation of Equivalent Assets" ([#1477]) and "Seasonal/Annual Utilisation Penalties" ([#1478]), are explained in more detail in the [dispatch documentation]. -Casual users do not need to be concerned with the underlying model changes, but should be aware of the -implications. Firstly, users should notice more sensible and interpretable asset utilisation +As a result of these changes, users should notice more sensible and interpretable asset utilisation patterns, away from arbitrary concentration of activity on certain assets and time slices, now -spreading utilisation evenly across equally good assets and time slices. In many cases this will -also have knock-on consequences for commodity prices. Secondly, results were previously sensitive to -differences between platforms and operating systems, as small floating point differences could push -the solver to a different convergence point in the under-constrained problem. These additions should -substantially reduce the sensitivity of results to small platform-dependent numerical differences, -although they cannot guarantee identical results across platforms. There may be some performance -costs associated with these additions, but these are expected to be small. +tending to spread utilisation evenly across equally good assets and time slices. In many cases, this +will also have knock-on consequences for commodity prices. Additionally, whereas results were +previously sensitive to differences between platforms and operating systems, as small floating point +differences could push the solver to a different convergence point, these additions constrain the +optimisation problem in a way that should substantially reduce the sensitivity of results to these +platform-dependent differences. That said, identical results cannot yet be guaranteed across all +platforms in all cases - this is an area of onging investigation. ## Other new features @@ -214,7 +207,7 @@ previous versions of MUSE2. -[upcoming release notes]: https://energysystemsmodellinglab.github.io/MUSE2/release_notes/upcoming.html +[upcoming release notes]: https://energysystemsmodellinglab.github.io/MUSE2/dev/release_notes/upcoming.html [v2.1.0]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/release_notes/v2.1.0.html From c02e76d740659ab2b7b8096e977f2e6ed3fcd30d Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Wed, 2 Sep 2026 17:30:58 +0100 Subject: [PATCH 06/10] Add intro --- docs/release_notes/v2.2.0.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/release_notes/v2.2.0.md b/docs/release_notes/v2.2.0.md index bf61827c7..26bd93e1a 100644 --- a/docs/release_notes/v2.2.0.md +++ b/docs/release_notes/v2.2.0.md @@ -1,5 +1,20 @@ # Release notes for MUSE2 v2.2.0 (September 3, 2026) +This release is the culmination of a huge effort from many [contributors] over the past 5 months. +Whilst there are only a handful of entirely new features (total capacity limits, commodity +constraints), the most significant changes in this release come from improvements and refinements to +existing features. Almost every aspect of the main algorithm, from investments to dispatch to +mothballing and decommissioning has been modified or fundamentally changed, in many cases to address +issues in the model formulation brought to light through rigorous testing and assessment of the +software in action. In many ways this is not just a software update, but a research update to what +is very much a live and evolving project. + +Along with changes to the core code, this release also brings significant improvements to the +user-facing documentation, bringing this up to date with the current state of the code. +In particular, see the [Model Description] and [Glossary]. In addition, the documentation site now +hosts permanent documentation versions for each release of MUSE2, which should serve as a useful +record as new MUSE2 versions are continually released. + Please be aware that there are some breaking changes in this release, which may require you to update the input files of any existing models. We have tried to outline these in the "Breaking changes" section below, but please do get in touch if you have any issues adapting models to the new @@ -163,6 +178,7 @@ previous versions of MUSE2. - Disallow negative values for `capital_cost`, `fixed_operating_cost` and `variable_operating_cost` in [`process_parameters.csv`] ([#1485]) +[contributors]: https://github.com/EnergySystemsModellingLab/MUSE2?tab=readme-ov-file#contributors- [#1259]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1259 [#1276]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1276 [#1281]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1281 @@ -213,6 +229,8 @@ previous versions of MUSE2. [v2.1.0]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/release_notes/v2.1.0.html +[Model Description]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/model/index.html +[Glossary]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/glossary.html [investment documentation]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/model/investment.html [dispatch documentation]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/model/dispatch_optimisation.html [highs-opts-docs]: https://energysystemsmodellinglab.github.io/MUSE2/v2.2.0/developer_guide/custom_highs_options.html From a462ca3c45b20e3e417074e62b4374f44aa64a26 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:40:19 +0000 Subject: [PATCH 07/10] [pre-commit.ci lite] apply automatic fixes --- benches/benchmark-data.json | 428 ++++++++++++++++++------------------ 1 file changed, 214 insertions(+), 214 deletions(-) diff --git a/benches/benchmark-data.json b/benches/benchmark-data.json index 5a20f9337..72c6634b4 100644 --- a/benches/benchmark-data.json +++ b/benches/benchmark-data.json @@ -1,216 +1,216 @@ { - "lastUpdate": 1788338865130, - "repoUrl": "https://github.com/EnergySystemsModellingLab/MUSE2", - "entries": { - "Benchmark": [ - { - "commit": { - "author": { - "email": "t.bland@imperial.ac.uk", - "name": "Tom Bland", - "username": "tsmbland" - }, - "committer": { - "email": "noreply@github.com", - "name": "GitHub", - "username": "web-flow" - }, - "distinct": true, - "id": "849164f50fd97a3388189aee2b020d8e4c594619", - "message": "Merge pull request #1516 from EnergySystemsModellingLab/allow_push_main\n\nUse PR instead of direct push to main", - "timestamp": "2026-09-01T10:45:49+01:00", - "tree_id": "f4e331cadaf5c3b9c48399c16a7484e673f3283e", - "url": "https://github.com/EnergySystemsModellingLab/MUSE2/commit/849164f50fd97a3388189aee2b020d8e4c594619" - }, - "date": 1788256182014, - "tool": "customSmallerIsBetter", - "benches": [ - { - "name": "example_run/circularity example", - "value": 414093669, - "unit": "ns" - }, - { - "name": "example_run/missing_commodity example", - "value": 224283879.25, - "unit": "ns" - }, - { - "name": "example_run/muse1_default example", - "value": 257200258.5, - "unit": "ns" - }, - { - "name": "example_run/simple example", - "value": 82232509.625, - "unit": "ns" - }, - { - "name": "example_run/two_outputs example", - "value": 397768111.5, - "unit": "ns" - }, - { - "name": "example_run/two_regions example", - "value": 444982302.5, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/01", - "value": 7184719.770833334, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/05", - "value": 21415495.111111112, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/10", - "value": 35291724, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/15", - "value": 51844114.66666667, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/20", - "value": 66430136.16666667, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/01", - "value": 7215430.817307692, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/05", - "value": 34758098.5, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/10", - "value": 69328321.66666666, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/15", - "value": 103927071, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/20", - "value": 138376641.75, - "unit": "ns" - } + "lastUpdate": 1788338865130, + "repoUrl": "https://github.com/EnergySystemsModellingLab/MUSE2", + "entries": { + "Benchmark": [ + { + "commit": { + "author": { + "email": "t.bland@imperial.ac.uk", + "name": "Tom Bland", + "username": "tsmbland" + }, + "committer": { + "email": "noreply@github.com", + "name": "GitHub", + "username": "web-flow" + }, + "distinct": true, + "id": "849164f50fd97a3388189aee2b020d8e4c594619", + "message": "Merge pull request #1516 from EnergySystemsModellingLab/allow_push_main\n\nUse PR instead of direct push to main", + "timestamp": "2026-09-01T10:45:49+01:00", + "tree_id": "f4e331cadaf5c3b9c48399c16a7484e673f3283e", + "url": "https://github.com/EnergySystemsModellingLab/MUSE2/commit/849164f50fd97a3388189aee2b020d8e4c594619" + }, + "date": 1788256182014, + "tool": "customSmallerIsBetter", + "benches": [ + { + "name": "example_run/circularity example", + "value": 414093669, + "unit": "ns" + }, + { + "name": "example_run/missing_commodity example", + "value": 224283879.25, + "unit": "ns" + }, + { + "name": "example_run/muse1_default example", + "value": 257200258.5, + "unit": "ns" + }, + { + "name": "example_run/simple example", + "value": 82232509.625, + "unit": "ns" + }, + { + "name": "example_run/two_outputs example", + "value": 397768111.5, + "unit": "ns" + }, + { + "name": "example_run/two_regions example", + "value": 444982302.5, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/01", + "value": 7184719.770833334, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/05", + "value": 21415495.111111112, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/10", + "value": 35291724, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/15", + "value": 51844114.66666667, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/20", + "value": 66430136.16666667, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/01", + "value": 7215430.817307692, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/05", + "value": 34758098.5, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/10", + "value": 69328321.66666666, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/15", + "value": 103927071, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/20", + "value": 138376641.75, + "unit": "ns" + } + ] + }, + { + "commit": { + "author": { + "email": "t.bland@imperial.ac.uk", + "name": "Tom Bland", + "username": "tsmbland" + }, + "committer": { + "email": "noreply@github.com", + "name": "GitHub", + "username": "web-flow" + }, + "distinct": true, + "id": "7cd741def65f50e860ac253032b4ca3251c7b017", + "message": "Merge pull request #1518 from EnergySystemsModellingLab/tranche_terminology\n\nRename \"asset units\" to \"asset tranches\"", + "timestamp": "2026-09-02T09:43:48+01:00", + "tree_id": "da1bdb1e874694d494a495efec980fe3a5ea84c9", + "url": "https://github.com/EnergySystemsModellingLab/MUSE2/commit/7cd741def65f50e860ac253032b4ca3251c7b017" + }, + "date": 1788338865130, + "tool": "customSmallerIsBetter", + "benches": [ + { + "name": "example_run/circularity example", + "value": 409557107.5, + "unit": "ns" + }, + { + "name": "example_run/missing_commodity example", + "value": 230289347.5, + "unit": "ns" + }, + { + "name": "example_run/muse1_default example", + "value": 296044869, + "unit": "ns" + }, + { + "name": "example_run/simple example", + "value": 84885164.5, + "unit": "ns" + }, + { + "name": "example_run/two_outputs example", + "value": 411436145, + "unit": "ns" + }, + { + "name": "example_run/two_regions example", + "value": 562801454, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/01", + "value": 7261651.715277778, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/05", + "value": 25327450.23125, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/10", + "value": 41248697.5, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/15", + "value": 59006656.5, + "unit": "ns" + }, + { + "name": "select_best_assets_parallel/20", + "value": 77051985, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/01", + "value": 7245930.892045455, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/05", + "value": 34925940.8, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/10", + "value": 69812982.5, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/15", + "value": 104842185.25, + "unit": "ns" + }, + { + "name": "select_best_assets_sequential/20", + "value": 139540480.75, + "unit": "ns" + } + ] + } ] - }, - { - "commit": { - "author": { - "email": "t.bland@imperial.ac.uk", - "name": "Tom Bland", - "username": "tsmbland" - }, - "committer": { - "email": "noreply@github.com", - "name": "GitHub", - "username": "web-flow" - }, - "distinct": true, - "id": "7cd741def65f50e860ac253032b4ca3251c7b017", - "message": "Merge pull request #1518 from EnergySystemsModellingLab/tranche_terminology\n\nRename \"asset units\" to \"asset tranches\"", - "timestamp": "2026-09-02T09:43:48+01:00", - "tree_id": "da1bdb1e874694d494a495efec980fe3a5ea84c9", - "url": "https://github.com/EnergySystemsModellingLab/MUSE2/commit/7cd741def65f50e860ac253032b4ca3251c7b017" - }, - "date": 1788338865130, - "tool": "customSmallerIsBetter", - "benches": [ - { - "name": "example_run/circularity example", - "value": 409557107.5, - "unit": "ns" - }, - { - "name": "example_run/missing_commodity example", - "value": 230289347.5, - "unit": "ns" - }, - { - "name": "example_run/muse1_default example", - "value": 296044869, - "unit": "ns" - }, - { - "name": "example_run/simple example", - "value": 84885164.5, - "unit": "ns" - }, - { - "name": "example_run/two_outputs example", - "value": 411436145, - "unit": "ns" - }, - { - "name": "example_run/two_regions example", - "value": 562801454, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/01", - "value": 7261651.715277778, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/05", - "value": 25327450.23125, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/10", - "value": 41248697.5, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/15", - "value": 59006656.5, - "unit": "ns" - }, - { - "name": "select_best_assets_parallel/20", - "value": 77051985, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/01", - "value": 7245930.892045455, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/05", - "value": 34925940.8, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/10", - "value": 69812982.5, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/15", - "value": 104842185.25, - "unit": "ns" - }, - { - "name": "select_best_assets_sequential/20", - "value": 139540480.75, - "unit": "ns" - } - ] - } - ] - } -} \ No newline at end of file + } +} From 1b7b23a01705d2320a5c76597eab8ea603e5b06e Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Wed, 2 Sep 2026 17:57:31 +0100 Subject: [PATCH 08/10] Copilot suggestions --- .lycheeignore | 3 +++ docs/release_notes/v2.2.0.md | 22 +++++++++++----------- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/.lycheeignore b/.lycheeignore index e3dedb138..5ac5d3664 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -20,3 +20,6 @@ # UKRI gateway tracker is unreliable ^https://gtr\.ukri\.org/ + +# TO REMOVE AFTER v2.2.0 RELEASE +^https://energysystemsmodellinglab\.github\.io/MUSE2/v2\.2\.0/ diff --git a/docs/release_notes/v2.2.0.md b/docs/release_notes/v2.2.0.md index 26bd93e1a..bb8bc1019 100644 --- a/docs/release_notes/v2.2.0.md +++ b/docs/release_notes/v2.2.0.md @@ -32,13 +32,13 @@ As always, you can keep track of upcoming changes for the next release in the This release fundamentally changes the investment appraisal approaches for both the LCOX and NPV objectives. Appraisal now uses a more consistent approach across objectives: all objectives now -appraise a capacity pre-determined capacity (see "tranching" section below), optimise -dispatch of that capacity over remaining demand, and calculate an objective-specific metric based on -this dispatch ([#1319]). For LCOX, this replaces the previous approach that used dynamic capacity -variables and the Value of Lost Load parameter, which had a tendency to inflate capacities. The NPV -formulation has also changed to use SNAS (Specific Net Annualised Surplus) rather than Profitability -Index, which is more robust to assets with low/zero fixed costs ([#1379]). More details can be found -in the updated [investment documentation]. +appraise a pre-determined capacity (see "tranching" section below), optimise dispatch of that +capacity over remaining demand, and calculate an objective-specific metric based on this dispatch +([#1319]). For LCOX, this replaces the previous approach that used dynamic capacity variables and +the Value of Lost Load parameter, which had a tendency to inflate capacities. The NPV formulation +has also changed to use SNAS (Specific Net Annualised Surplus) rather than Profitability Index, +which is more robust to assets with low/zero fixed costs ([#1379]). More details can be found in +the updated [investment documentation]. A further change is to introduce a fallback cost to the activity coefficient calculation, set by the `fallback_pricing_strategy` parameter in [`model.toml`] ([#1420]). This reframes the optimisation @@ -57,11 +57,11 @@ performance, particularly for large models run on multi-core machines ([#1466]). [v2.1.0] introduced the concept of asset groups as a proxy for modelling asset divisibility, i.e. the idea that overall asset capacity may be made up of multiple discrete components, or _tranches_, (e.g. a group of wind turbines in a wind farm) which can be mothballed and decommissioned -independently. This approach resulted in a (potentially large) number of `Asset`'s (with distinct -`asset_id`'s) linked together by a common `group_id`. +independently. This approach resulted in a (potentially large) number of `Asset`s (with distinct +`asset_id`s) linked together by a common `group_id`. v2.2.0 does away with asset groups, and instead expresses the capacity of each individual `Asset` as -a collection of tranches, each of which work in unison in dispatch, but can be independently +a collection of tranches, which work in unison in dispatch, but can be independently mothballed and decommissioned ([#1464], [#1483]). Tranches are __not__ reported individually in the output results. Rather, results files report @@ -128,7 +128,7 @@ previously sensitive to differences between platforms and operating systems, as differences could push the solver to a different convergence point, these additions constrain the optimisation problem in a way that should substantially reduce the sensitivity of results to these platform-dependent differences. That said, identical results cannot yet be guaranteed across all -platforms in all cases - this is an area of onging investigation. +platforms in all cases - this is an area of ongoing investigation. ## Other new features From c321b586d2be65feef789c3df2fe424cf699d827 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Wed, 2 Sep 2026 18:08:08 +0100 Subject: [PATCH 09/10] Remove note about doc versions - not a new feature --- docs/release_notes/v2.2.0.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/release_notes/v2.2.0.md b/docs/release_notes/v2.2.0.md index bb8bc1019..01ebede8c 100644 --- a/docs/release_notes/v2.2.0.md +++ b/docs/release_notes/v2.2.0.md @@ -11,9 +11,7 @@ is very much a live and evolving project. Along with changes to the core code, this release also brings significant improvements to the user-facing documentation, bringing this up to date with the current state of the code. -In particular, see the [Model Description] and [Glossary]. In addition, the documentation site now -hosts permanent documentation versions for each release of MUSE2, which should serve as a useful -record as new MUSE2 versions are continually released. +In particular, see the [Model Description] and [Glossary]. Please be aware that there are some breaking changes in this release, which may require you to update the input files of any existing models. We have tried to outline these in the "Breaking From d938184bfe1bd9d3ce93cb6ccbcc3c8b9b584925 Mon Sep 17 00:00:00 2001 From: Tom Bland Date: Thu, 3 Sep 2026 13:49:08 +0100 Subject: [PATCH 10/10] Update docs/release_notes/v2.2.0.md Co-authored-by: Dan Cummins <45606273+dc2917@users.noreply.github.com> --- docs/release_notes/v2.2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release_notes/v2.2.0.md b/docs/release_notes/v2.2.0.md index 01ebede8c..6aad3eb73 100644 --- a/docs/release_notes/v2.2.0.md +++ b/docs/release_notes/v2.2.0.md @@ -41,7 +41,7 @@ the updated [investment documentation]. A further change is to introduce a fallback cost to the activity coefficient calculation, set by the `fallback_pricing_strategy` parameter in [`model.toml`] ([#1420]). This reframes the optimisation problem to consider the alternative cost of choosing _not_ to invest in a process, which encourages -investment in cases where there would otherwise lack an incentive to do so. This is also described +investment in cases where there would otherwise be no incentive to do so. This is also described in more detail in the [investment documentation]. Users may notice changes in asset selection, better matching of capacities to demands, and fewer