Skip to content
8 changes: 5 additions & 3 deletions benches/assets.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,9 @@ use muse2::simulation::investment::competitive::{get_candidate_assets, select_be
use muse2::simulation::market::{
collect_agent_limits, get_demand_portion_for_market, get_responsible_agents,
};
use muse2::simulation::optimisation::DispatchRun;
use muse2::simulation::prices::{Prices, calculate_prices_from_solutions};
use muse2::simulation::prices::Prices;
use muse2::simulation::system_dispatch::calculate_prices_from_solutions;
use muse2::simulation::system_dispatch::optimisation::DispatchRun;
use rayon::ThreadPoolBuilder;
use std::hint::black_box;
use std::sync::Arc;
Expand Down Expand Up @@ -88,7 +89,7 @@ fn build_assets_for_investment_year(
}

/// Dispatch the base year (with and without the investment-year candidates) to obtain realistic
/// seed prices for investment appraisal, as per `simulation::run_dispatch_for_year` (this is the
/// seed prices for investment appraisal, as per `simulation::system_dispatch::run_dispatch_for_year` (this is the
/// dispatch performed before any agent investment has taken place).
fn calculate_seed_prices(
model: &Model,
Expand All @@ -115,6 +116,7 @@ fn calculate_seed_prices(
BASE_YEAR,
)
.expect("Failed to calculate prices")
.0
}

/// Build `n` synthetic candidate processes, based on cycling through `templates`, so that we can
Expand Down
5 changes: 4 additions & 1 deletion docs/developer_guide/custom_highs_options.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@ set `please_give_me_broken_results = true` in your [`model.toml` file][model.tom
You can change any of the options exposed by the HiGHS solver; for more information, see [the HiGHS
documentation][highs-opts].

You can set options to be applied to all optimisations, just dispatch or just appraisal.
You can set options to be applied to all optimisations, just dispatch or just appraisal. Note that
dispatch options are only used by the `system_dispatch` [simulation protocol][protocols], which is
currently the only one available.

Here is an example:

Expand All @@ -33,4 +35,5 @@ optimality_tolerance = 10e-6
```

[model.toml]: ../file_formats/input_files.md#model-parameters-modeltoml
[protocols]: ../model/index.html#simulation-protocols
[highs-opts]: https://ergo-code.github.io/HiGHS/stable/options/definitions/
94 changes: 55 additions & 39 deletions docs/model/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,45 +53,61 @@ At a high level, the user defines:
## Framework Overview

The model operates sequentially across a series of milestone years (MSYs). For the base year,
existing assets are commissioned and a [dispatch optimisation][dispatch-optimisation] is run to
establish [commodity prices][prices] for the first investment year. For each subsequent MSY, the
model performs the following steps:

### 1. Decommission end-of-life assets

Assets whose scheduled decommissioning year has been reached are removed from the active pool.

### 2. Agent investment

Agents select assets to meet commodity demand for the current MSY. Investment decisions follow a
pre-computed **investment order** derived from the topology of the [commodity graph][commodity-graphs]:
markets are processed deepest-first (most downstream to most upstream), grouped into **layers** of
independent markets at the same depth. For each market, each responsible agent selects assets using
the algorithm for its [agent type][agents]. See [Investment][investment] for full details.

After all markets in each layer are settled, a **partial system dispatch** is run over all assets
selected so far. This propagates demand upstream: input commodity flows consumed by newly committed
assets become demand targets for the markets not yet invested in.

### 3. Mothballing and decommissioning

Capacity of previously commissioned assets that was not selected for retention is mothballed. This
may be the whole of an asset or only some of its capacity. Any capacity that has remained mothballed
for `mothball_years` (defined in [`model.toml`][model-toml]) is permanently decommissioned.

### 4. Ironing-out loop

Investment and dispatch are repeated iteratively to resolve any price instability introduced by new
capacity commitments. Each iteration runs the full agent investment pass followed by a full system
dispatch. The loop terminates when time-slice-weighted market prices have converged within
`price_tolerance`, or when `max_ironing_out_iterations` is reached (both defined in
[`model.toml`][model-toml]).

### 5. Final dispatch

A full [dispatch optimisation][dispatch-optimisation] is run over the settled asset pool. The
resulting flows and commodity prices are written to the output files and carried forward as the
price basis for the next MSY's investment.
existing assets are commissioned and the model establishes the [commodity prices][prices] used as
the starting point for the first investment year. For each subsequent MSY, the model performs the
following steps:

1. **Decommission end-of-life assets.** Assets whose scheduled decommissioning year has been
reached are removed from the active pool.

2. **Agent investment.** Agents select assets to meet commodity demand for the current MSY.
Investment decisions follow a pre-computed **investment order** derived from the topology of the
[commodity graph][commodity-graphs]: markets are processed deepest-first (most downstream to most
upstream), grouped into **layers** of independent markets at the same depth. For each market,
each responsible agent selects assets using the algorithm for its [agent type][agents]. As markets
are settled, the commodity flows of the newly selected assets are used to propagate demand
upstream: input commodity flows consumed by newly committed assets become demand targets for the
markets not yet invested in. See [Investment][investment] for full details.

3. **Ironing out.** Investment is repeated iteratively with updated prices to resolve any price
instability introduced by new capacity commitments. The loop terminates when time-slice-weighted
market prices have converged within `price_tolerance`, or when `max_ironing_out_iterations` is
reached (both defined in [`model.toml`][model-toml]).

4. **Mothballing and decommissioning.** Capacity of previously commissioned assets that was not
selected for retention is mothballed. This may be the whole of an asset or only some of its
capacity. Any capacity that has remained mothballed for `mothball_years` (defined in
[`model.toml`][model-toml]) is permanently decommissioned.

5. **Final flows and prices.** The commodity flows and prices for the MSY are calculated for the
settled asset pool, written to the output files, and carried forward as the price basis for the
next MSY's investment.

How commodity flows and prices are obtained in each of these steps is determined by the
[simulation protocol](#simulation-protocols).

## Simulation protocols

The simulation protocol is selected with the `simulation_protocol` setting in
[`model.toml`][model-toml]. If it is not specified, `system_dispatch` is used.

### `system_dispatch`

In this protocol, agents choose capacity and the flows and prices for each year are obtained from a
system-wide [dispatch optimisation][dispatch-optimisation]. It works as follows:

- **Base year:** Dispatch optimisations are run over the existing assets, with and without candidate
assets, to establish commodity flows and prices.
- **Agent investment:** After all markets in each layer are settled, a **partial system dispatch** is
run over all assets selected so far. For markets in a cycle, a partial dispatch is run after each
market is settled. This provides the flows used to propagate demand upstream.
- **Ironing out:** Each iteration runs the full agent investment pass followed by a full system
dispatch of the selected assets, from which updated prices are calculated.
- **Final dispatch:** A full dispatch optimisation is run over the settled asset pool. The
resulting flows and commodity prices are written to the output files.

The `value_of_lost_load`, `commodity_balance_epsilon` and `highs.dispatch_options` settings in
[`model.toml`][model-toml] are only used by this protocol.

[investment]: ./investment.md
[agents]: ./agents.md
Expand Down
2 changes: 2 additions & 0 deletions docs/model/dispatch_optimisation.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ milestone year (MSY), the dispatch model calculates the least-cost operation of
energy system assets to satisfy commodity demands. It is solved as a Linear Programme (LP) using the
HiGHS solver.

This formulation is used by the `system_dispatch` [simulation protocol](index.html#simulation-protocols).

## Sets and Indices

The energy system is defined using the following sets:
Expand Down
3 changes: 3 additions & 0 deletions docs/release_notes/upcoming.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@
- Agents now have an agent type, set with the new optional `agent_type` column in `agents.csv`. The
new `portfolio` agent type selects assets for each market by solving a single optimisation,
rather than appraising options one at a time ([#1574])
- A new optional `simulation_protocol` setting in `model.toml` selects how each milestone year is
simulated. The only value currently available is `system_dispatch`, which is the default and
corresponds to the existing behaviour

## Breaking changes

Expand Down
18 changes: 17 additions & 1 deletion schemas/input/model.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,18 @@ properties:
US dollars in 2020 terms), or take any other form chosen by the modeller. The label is metadata
only: MUSE2 does not interpret it, perform currency conversion, or adjust monetary values for
inflation. Monetary inputs should use a consistent currency and reference year.
simulation_protocol:
type: string
description: The protocol used to simulate each milestone year
default: system_dispatch
enum:
- system_dispatch
notes: |
A simulation protocol defines how agents' investment decisions are combined with dispatch of
the energy system to produce commodity flows and prices for each milestone year. Currently the
only option is `system_dispatch`, in which agents choose capacity and flows and prices come
from a system-wide, cost-minimising dispatch optimisation. See
[the model documentation](../model/index.html#simulation-protocols) for details.
candidate_asset_capacity:
type: number
description: Capacity to give to candidate assets in dispatch optimisation
Expand All @@ -30,6 +42,8 @@ properties:
default: 1e-6
notes: |
The default value should work. Do not change this value unless you know what you're doing!

Only used by the `system_dispatch` simulation protocol.
capacity_tranche_fraction:
type: number
description: Scales the size of inferred investment tranches for candidate assets
Expand Down Expand Up @@ -64,6 +78,8 @@ properties:
default: 1e9
notes: |
Currently this only applies to the LCOX appraisal.

Only used by the `system_dispatch` simulation protocol.
seasonal_utilisation_penalty:
type: number
description: Penalty per unit of capacity used within a season
Expand Down Expand Up @@ -124,7 +140,7 @@ properties:
properties: {}
dispatch_options:
type: object
description: HiGHS options applied only to dispatch optimisations
description: HiGHS options applied only to dispatch optimisations (only used by the `system_dispatch` simulation protocol)
properties: {}
appraisal_options:
type: object
Expand Down
2 changes: 1 addition & 1 deletion src/graph/investment.rs
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
//! Module for solving the investment order of commodities
use super::{CommoditiesGraph, GraphEdge, GraphNode};
use crate::commodity::{CommodityMap, CommodityType};
use crate::optimisation::{ModelError, solve_optimal};
use crate::process::ProcessID;
use crate::region::RegionID;
use crate::simulation::market::MarketSet;
use crate::simulation::optimisation::{ModelError, solve_optimal};
use anyhow::{Context, Result};
use highs::{Col, RowProblem, Sense};
use indexmap::{IndexMap, IndexSet};
Expand Down
1 change: 1 addition & 0 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ pub mod id;
pub mod input;
pub mod log;
pub mod model;
mod optimisation;
pub mod output;
pub mod patch;
pub mod process;
Expand Down
32 changes: 30 additions & 2 deletions src/model/parameters.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ use crate::input::{
deserialise_finite_non_negative, deserialise_proportion_nonzero, input_err_msg,
is_sorted_and_unique, read_toml,
};
use crate::simulation::SimulationProtocol;
use crate::units::{Capacity, Dimensionless, Flow, MoneyPerCapacityPerYear, MoneyPerFlow};
use anyhow::{Context, Result, ensure};
use itertools::Itertools;
Expand Down Expand Up @@ -78,12 +79,16 @@ pub struct ModelParameters {
/// Allow potentially dangerous options to be enabled.
#[serde(rename = "please_give_me_broken_results")] // Can't use constant here :-(
pub allow_dangerous_options: bool,
/// The protocol used to simulate each milestone year.
pub simulation_protocol: SimulationProtocol,
/// The (small) value of capacity given to candidate assets.
///
/// Don't change unless you know what you're doing.
pub candidate_asset_capacity: Capacity,
/// The epsilon added to commodity balance lower bounds to force candidate dispatch.
///
/// Only used by the `system_dispatch` simulation protocol.
///
/// Don't change unless you know what you're doing.
#[serde(deserialize_with = "deserialise_finite_non_negative")]
pub commodity_balance_epsilon: Flow,
Expand All @@ -101,7 +106,8 @@ pub struct ModelParameters {
pub fallback_pricing_strategy: PricingStrategy,
/// The cost applied to unmet demand.
///
/// Currently this only applies to the LCOX appraisal.
/// Currently this only applies to the LCOX appraisal. Only used by the `system_dispatch`
/// simulation protocol.
pub value_of_lost_load: MoneyPerFlow,
/// Additive penalty per unit of capacity used within a season.
#[serde(deserialize_with = "deserialise_finite_non_negative")]
Expand All @@ -123,7 +129,8 @@ pub struct ModelParameters {
pub remaining_demand_absolute_tolerance: Flow,
/// Options for the HiGHS solver.
///
/// For a full list of options, see [the HiGHS documentation].
/// For a full list of options, see [the HiGHS documentation]. The `dispatch_options` are only
/// used by the `system_dispatch` simulation protocol.
///
/// [the HiGHS documentation]: https://ergo-code.github.io/HiGHS/stable/options/definitions/
pub highs: HighsOptions,
Expand All @@ -139,6 +146,7 @@ impl Default for ModelParameters {
// Default values for optional parameters
currency: None,
allow_dangerous_options: false,
simulation_protocol: SimulationProtocol::default(),
candidate_asset_capacity: Capacity(1e-4),
commodity_balance_epsilon: Flow(1e-6),
capacity_tranche_fraction: Dimensionless(0.05),
Expand Down Expand Up @@ -461,6 +469,26 @@ mod tests {
assert_eq!(model_params.price_cycle_iterations, 3);
}

#[rstest]
#[case("", Some(SimulationProtocol::SystemDispatch))]
#[case(
"simulation_protocol = \"system_dispatch\"",
Some(SimulationProtocol::SystemDispatch)
)]
#[case("simulation_protocol = \"unknown_protocol\"", None)]
fn model_params_simulation_protocol(
#[case] setting: &str,
#[case] expected: Option<SimulationProtocol>,
) {
let result: Result<ModelParameters, _> =
toml::from_str(&format!("milestone_years = [2020, 2100]\n{setting}"));

assert_eq!(
result.ok().map(|params| params.simulation_protocol),
expected
);
}

#[test]
fn model_params_currency_is_optional_metadata() {
let with_currency: ModelParameters = toml::from_str(
Expand Down
Loading
Loading