Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/developer_guide/custom_highs_options.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@ You can change any of the options exposed by the HiGHS solver; for more informat
documentation][highs-opts].

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.
dispatch options are only used by the `system_dispatch` [simulation protocol][protocols].

Here is an example:

Expand Down
16 changes: 7 additions & 9 deletions docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,10 +107,7 @@ across the year remains equal to the annual demand.
present-value terms. For example, a discount rate of 0.05 means that £100 received in one year's
time is valued at approximately £95.24 today (100 / (1 + 0.05)).

**Dispatch:** The way in which *Assets* are operated to serve demand. Within the limits imposed by
*Availability*, *Commodity* balances, and other user-defined constraints, MUSE2 effectively dispatches
*Assets* in *Merit Order*: cheaper *Assets* are used first, up to their available capacity or until
demand is met. The resulting operation is calculated by a least-cost linear program.
**Dispatch:** The way in which *Assets* are operated to serve demand.

**End Year:** The final year in the model *Time Horizon*.

Expand Down Expand Up @@ -143,9 +140,10 @@ MUSE2 generally processes downstream markets before upstream markets, so that de
example, investment in electricity generation is considered before investment in gas production
when gas is used to generate electricity.

**Ironing-out Loop:** The repeated sequence of *Agent* investment and *Dispatch* used to resolve
price instability introduced by new capacity commitments. The loop stops when time-slice-weighted
market prices converge within the configured tolerance or the maximum number of iterations is reached.
**Ironing-out Loop:** The repeated sequence of *Agent* investment and price calculation used to
resolve price instability introduced by new capacity commitments. The loop stops when
time-slice-weighted market prices converge within the configured tolerance or the maximum number
of iterations is reached.

**Levelised Cost of X (LCOX):** The cost per unit of output *Commodity* X from an *Asset*,
calculated by dividing its discounted lifetime costs by its discounted lifetime output under a
Expand Down Expand Up @@ -178,8 +176,8 @@ output commodities.
**Partial Equilibrium:** An equilibrium in which only the user-defined *Commodities* and markets are
balanced. MUSE2 does not attempt to equilibrate the whole economy.

**Pricing Strategy:** The method used to calculate a *Commodity*'s price. This includes *Marginal
Cost* pricing, *Full Cost* pricing, and *Shadow Price* pricing.
**Pricing Strategy:** The method used to calculate a *Commodity*'s price. Options include *Marginal
Cost* and *Full Cost* pricing.

**Process:** A blueprint of an available *Process* that converts *Input Commodities* to *Output
Commodities*. *Processes* have economic attributes of *Capital Cost*, *Fixed Operating Cost* per
Expand Down
19 changes: 18 additions & 1 deletion docs/model/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,9 @@ How commodity flows and prices are obtained in each of these steps is determined
## 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.
[`model.toml`][model-toml]. If it is not specified, `agent_dispatch` is used.
The experimental `system_dispatch` protocol requires setting
`please_give_me_broken_results = true` in `model.toml`.

### `system_dispatch`

Expand All @@ -109,6 +111,21 @@ system-wide [dispatch optimisation][dispatch-optimisation]. It works as follows:
The `value_of_lost_load`, `commodity_balance_epsilon` and `highs.dispatch_options` settings in
[`model.toml`][model-toml] are only used by this protocol.

### `agent_dispatch`

In this protocol, no system-wide dispatch is run. Instead, the activities determined by agents' own
optimisations are used directly. It works as follows:

- **Base year:** Agents dispatch the existing assets. Flows come from the resulting activities and
prices are calculated from them.
- **Agent investment:** The flows of newly selected assets, taken from their activities, are used
to propagate demand upstream as each market (or, for markets in a cycle, each market in turn) is
settled.
- **Ironing out:** Each iteration runs the full agent investment pass, and updated prices are
calculated from the activities of the selected assets.
- **Final flows and prices:** The flows and prices for the year are calculated from the activities
of the final selection.

[investment]: ./investment.md
[agents]: ./agents.md
[commodity-graphs]: ./commodity_graphs.md
Expand Down
10 changes: 3 additions & 7 deletions docs/model/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@ feasible options remain.

### Commodity prices used in appraisal

Investment appraisal uses two price sets calculated from the previous MSY's dispatch (or from the
previous [ironing-out loop][framework-overview] iteration if enabled):
Investment appraisal uses two price sets from the previous MSY (or from the previous
[ironing-out loop][framework-overview] iteration if enabled):

- **Market prices** \\( \pi\_{c,r,t} \\): used for activity coefficients in the mini dispatch and
for the investment metric (Cost Index or SNAS).
Expand Down Expand Up @@ -275,11 +275,7 @@ with the updated set of selected assets. This continues until:

- The remaining demand falls below `remaining_demand_absolute_tolerance`
(in [`model.toml`][model-toml]), or
- No feasible options remain. In this case, a warning is logged and the loop ends early. The
unmet demand may still be satisfied during the full system dispatch, but is not guaranteed.

If demand cannot be met at all due to overly restrictive investment constraints, the simulation
terminates with an error.
- No feasible options remain. In this case, the simulation terminates with an error.

### Example: Gas Power Plant

Expand Down
5 changes: 2 additions & 3 deletions docs/model/commodity_graphs.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,8 +147,8 @@ The investment order is worked out from the commodity graph for each year as fol
markets that supply it (a [topological sort]).
4. **Group independent markets into layers.** Each market is given a depth, which is the length of
the longest supply chain leading to it. Markets with the same depth do not depend on one another,
so they are grouped into a **layer**. MUSE2 invests in all markets in a layer before running a
single [partial system dispatch][partial-dispatch], rather than one per market, which saves time.
so they are grouped into a **layer**. MUSE2 invests in all markets in a layer before updating
upstream demand.

### Circularities

Expand Down Expand Up @@ -267,7 +267,6 @@ When reading these graphs, note that:
[investment]: ./investment.md
[prices]: ./prices.md
[topological sort]: https://en.wikipedia.org/wiki/Topological_sorting
[partial-dispatch]: ./investment.md#partial-system-dispatch
[order-scc]: ../api/muse2/graph/investment/fn.order_scc.html
[investment-circularities]: ./investment.md#circularities
[pricing-circularities]: ./prices.md#circularities
Expand Down
34 changes: 16 additions & 18 deletions docs/model/investment.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,11 @@ demand created by already-committed downstream assets is already known.
Markets are processed in **layers**: a layer is a set of commodity markets that are independent of
one another (i.e. at the same depth in the commodity graph and with no dependencies between them).
All markets within a layer are settled before moving to the next layer. After each layer is
settled, a single [partial system dispatch](#partial-system-dispatch) is run over all assets
selected so far. This quantifies the input commodity flows consumed by newly committed assets —
for example, a gas generator committed during electricity market investment will consume gas,
creating demand that the gas market investment must subsequently meet.
settled, the flows of newly selected assets are used to update upstream demand. Depending on the
[simulation protocol][simulation-protocols], these flows come from a
[partial system dispatch](#partial-system-dispatch) or directly from the activities determined by
agents. For example, a gas generator committed during electricity market investment will consume
gas, creating demand that the gas market investment must subsequently meet.

Only commodities of type `ServiceDemand` and `SupplyEqualsDemand` are subject to
investment decisions. Other commodity types (e.g. `OTH`) are excluded.
Expand All @@ -46,8 +47,8 @@ market which is invested in *before* the market they supply (see
[Commodity Graphs][graph-circularities]). If assets are selected for a feedback process, they create
extra demand for a market that has already been invested in.

To deal with this, MUSE2 invests in the circularity in two passes over its markets, running a
[partial system dispatch](#partial-system-dispatch) after each market in each pass:
To deal with this, MUSE2 invests in the circularity in two passes over its markets, updating demand
from the selected assets' flows after each market in each pass:

1. **First pass (provisional).** The markets are visited in order, with all processes available,
including feedback processes. Any feedback assets selected will leave some demand for earlier
Expand Down Expand Up @@ -167,8 +168,8 @@ process, agent, region, commodity and milestone year is:

## Commodity Prices

Agents use commodity prices when selecting assets. These prices come from the previous MSY's
dispatch (or from the previous [ironing-out loop][framework-overview] iteration, if enabled). See
Agents use commodity prices when selecting assets. These prices come from the previous MSY
(or from the previous [ironing-out loop][framework-overview] iteration, if enabled). See
[Commodity Prices][prices] for how market, shadow and fallback prices are calculated, and
[Agents][agents] for how each agent type uses them.

Expand All @@ -179,11 +180,7 @@ has selected to meet its share of demand. Selected existing assets are retained
selected mothballed capacity), and selected candidate assets are commissioned as new assets owned by
the agent.

If an agent is unable to meet its share of demand, the outcome depends on its agent type. A
competitive agent logs a warning and stops early, keeping the assets selected so far; the unmet
demand may still be satisfied during the full system dispatch, but this is not guaranteed. If
investment constraints are so restrictive that it has no options left, the simulation terminates
with an error. For a portfolio agent, the simulation terminates with an error.
If an agent is unable to meet its share of demand, the simulation terminates with an error.

> **Note:** only production of the *primary output* commodity is counted against demand. If a
> selected asset also produces other commodities as secondary outputs, that side-production does
Expand All @@ -209,11 +206,11 @@ and dispatch.

## Partial System Dispatch

After each layer of commodity markets is settled during the investment loop, a **partial system
dispatch** is run over all assets selected so far. Within a [circularity](#circularities), a partial
dispatch is instead run after each market in each pass, over the assets just selected for that
market. This is a standard [dispatch optimisation][dispatch-optimisation] solve, with two key
modifications described below.
With the `system_dispatch` protocol, after each layer of commodity markets is settled during the
investment loop, a **partial system dispatch** is run over all assets selected so far. Within a
[circularity](#circularities), a partial dispatch is instead run after each market in each pass,
over the assets just selected for that market. This is a standard
[dispatch optimisation][dispatch-optimisation] solve, with two key modifications described below.

### Market subset

Expand Down Expand Up @@ -246,6 +243,7 @@ assets shaping the demand seen by those upstream.

[agents]: ./agents.md
[framework-overview]: index.html#framework-overview
[simulation-protocols]: index.html#simulation-protocols
[prices]: ./prices.md
[model-toml]: ../file_formats/input_files.md#model-parameters-modeltoml
[process-investment-constraints-csv]: ../file_formats/input_files.md#process_investment_constraintscsv
Expand Down
18 changes: 9 additions & 9 deletions docs/model/prices.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Commodity Prices

This section describes how commodity prices are calculated in MUSE2 at the end of each
milestone year iteration. The pricing algorithm operates on the results of the dispatch
optimisation, translating flows and capacities into commodity market prices.
milestone year iteration. Prices are calculated from asset activities and the resulting commodity
flows.

## Pricing Strategies

Expand All @@ -15,15 +15,17 @@ commodity.
active assets.
- **`full`**: Prices are set to the full cost (marginal cost + annual fixed/capital costs) of the
highest-cost active asset producing the commodity.
- **`full_average`**: Prices are set to the output-weighted average full cost across all active
assets producing the commodity.
- **`unpriced`**: No prices are calculated for the commodity. This is mandatory for all OTH
(Other)-type commodities.

### Cost Calculations

Cost-based prices (`marginal`, `marginal_average`, `full`, `full_average`) are calculated based on
process cost parameters, asset capacities and dispatch flows. For assets producing multiple output
commodities (e.g. an asset producing both oil and gas), generic activity costs and fixed costs are
shared between outputs according to output flow coefficients.
process cost parameters, asset capacities, activities and the resulting commodity flows. For assets
producing multiple output commodities (e.g. an asset producing both oil and gas), generic activity
costs and fixed costs are shared between outputs according to output flow coefficients.

#### Generic Activity Cost

Expand Down Expand Up @@ -141,8 +143,7 @@ The following example demonstrates the calculation of full-cost prices for two c

In this scenario, GASPRD (raw gas) is produced by a single GASDRV (dry gas extraction) asset. This
asset produces 1 unit of GASPRD per unit of activity, along with 5.113 units of CO₂ emissions.
Suppose an annual utilisation of 0.20786471743 units of activity per unit of capacity (based on
dispatch results).
Suppose an annual utilisation of 0.20786471743 units of activity per unit of capacity.

#### Marginal Cost

Expand Down Expand Up @@ -184,8 +185,7 @@ The full cost is:
Following on from the above scenario, GASNAT (processed natural gas) is produced by a single GASPRC
(gas processing) asset, which consumes GASPRD as an input fuel. This asset consumes 1.05 units of
GASPRD and produces 1 unit of GASNAT per unit of activity, along with 2.5565 units of CO₂ emissions.
Suppose an annual utilisation of 0.2094885671 units of activity per unit of capacity (based on
dispatch results).
Suppose an annual utilisation of 0.2094885671 units of activity per unit of capacity.

#### Marginal Cost

Expand Down
5 changes: 3 additions & 2 deletions docs/release_notes/upcoming.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,9 @@
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
simulated. The new default, `agent_dispatch`, calculates flows and prices directly from the
activities determined by agents' own optimisations, without a system-wide dispatch.
`system_dispatch` selects the previous behaviour

## Breaking changes

Expand Down
10 changes: 5 additions & 5 deletions examples/circularity/assets.csv
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
process_id,region_id,agent_id,capacity,commission_year
GASDRV,GBR,A0_OAG,4010.2,2020
OAGRSV,GBR,A0_OAG,1738.05,2020
OAGRSV,GBR,A0_OAG,2073.38,2020
GASPRC,GBR,A0_OAG,3789.64,2020
OILREF,GBR,A0_OAG,716.5,2020
OILRF2,GBR,A0_OAG,573.9,2020
OILREF,GBR,A0_REF,716.5,2020
OILRF2,GBR,A0_REF,929.5,2020
WNDFRM,GBR,A0_ELC,3.964844,2020
GASCGT,GBR,A0_ELC,2.999,2020
GASCGT,GBR,A0_ELC,5.519,2020
H2YGEN,GBR,A0_ELC,1.0,2020
H2YPRO,GBR,A0_ELC,31.54,2020
H2YPRO,GBR,A0_ELC,47.311,2020
TPETCR,GBR,A0_TRA,451.91,2020
TDIECR,GBR,A0_TRA,176.58,2020
TELCCR,GBR,A0_TRA,20.99,2020
Expand Down
2 changes: 1 addition & 1 deletion examples/missing_commodity/assets.csv
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@ process_id,region_id,agent_id,capacity,commission_year
GASDRV,GBR,A0_GEX,4002.26,2020
GASPRC,GBR,A0_GPR,3782.13,2020
WNDFRM,GBR,A0_ELC,3.964844,2020
GASCGT,GBR,A0_ELC,2.43,2020
GASCGT,GBR,A0_ELC,3.0,2020
RGASBR,GBR,A0_RES,2900.0,2020
RELCHP,GBR,A0_RES,399.98,2020
2 changes: 1 addition & 1 deletion examples/simple/assets.csv
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@ process_id,region_id,agent_id,capacity,commission_year
GASDRV,GBR,A0_GEX,4002.26,2020
GASPRC,GBR,A0_GPR,3782.13,2020
WNDFRM,GBR,A0_ELC,3.964844,2020
GASCGT,GBR,A0_ELC,2.43,2020
GASCGT,GBR,A0_ELC,3.0,2020
RGASBR,GBR,A0_RES,2900.0,2020
RELCHP,GBR,A0_RES,399.98,2020
8 changes: 4 additions & 4 deletions examples/two_outputs/assets.csv
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
process_id,region_id,agent_id,capacity,commission_year
GASDRV,GBR,A0_OAG,4010.2,2020
OAGRSV,GBR,A0_OAG,1738.05,2020
OAGRSV,GBR,A0_OAG,2500,2020
GASPRC,GBR,A0_OAG,3789.64,2020
OILREF,GBR,A0_OAG,716.5,2020
OILRF2,GBR,A0_OAG,573.9,2020
OILREF,GBR,A0_REF,716.5,2020
OILRF2,GBR,A0_REF,1000,2020
WNDFRM,GBR,A0_ELC,3.964844,2020
GASCGT,GBR,A0_ELC,2.999,2020
GASCGT,GBR,A0_ELC,4.5191,2020
TPETCR,GBR,A0_TRA,451.91,2020
TDIECR,GBR,A0_TRA,176.58,2020
TELCCR,GBR,A0_TRA,20.99,2020
Expand Down
12 changes: 8 additions & 4 deletions schemas/input/model.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,18 @@ properties:
simulation_protocol:
type: string
description: The protocol used to simulate each milestone year
default: system_dispatch
default: agent_dispatch
enum:
- system_dispatch
- agent_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 energy system to produce commodity flows and prices for each milestone year. With
`system_dispatch`, agents choose capacity and flows and prices come from a system-wide,
cost-minimising dispatch optimisation. With `agent_dispatch`, flows and prices are calculated
directly from the activities determined by agents' own optimisations, and no system-wide
dispatch is run. The experimental `system_dispatch` protocol requires setting
`please_give_me_broken_results` to true. See
[the model documentation](../model/index.html#simulation-protocols) for details.
candidate_asset_capacity:
type: number
Expand Down
3 changes: 2 additions & 1 deletion src/asset/pool.rs
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,8 @@ impl AssetPool {

/// Extend the active pool with Commissioned or Ready assets.
///
/// Returns the newly commissioned assets (those that were in `Ready` state on entry).
/// Returns the newly commissioned assets (those that were in `Ready` state on entry), in the
/// order they appeared in `assets`.
pub fn extend<I>(&mut self, assets: I) -> &[AssetRef]
where
I: IntoIterator<Item = AssetRef>,
Expand Down
Loading
Loading