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 Assets (with distinct asset_ids) 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 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)