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/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/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..6aad3eb73 --- /dev/null +++ b/docs/release_notes/v2.2.0.md @@ -0,0 +1,245 @@ +# 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]. + +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 + +### 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: all objectives now +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 +problem to consider the alternative cost of choosing _not_ to invest in a process, which encourages +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 +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]). + +### 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`. + +v2.2.0 does away with asset groups, and instead expresses the capacity of each individual `Asset` as +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 +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 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. 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 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. + +### 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) + +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 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]. + +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 +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 ongoing investigation. + +## 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` 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]) + +## 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 `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]) + +[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 +[#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 +[#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 +[#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 + + + + +[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 + + +[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 +[`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