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
78 changes: 76 additions & 2 deletions docs/model/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ selected by the agent: the existing assets to retain and the new candidate asset
of the investment process (the investment order, handling of circularities, partial system
dispatch, mothballing, etc.) is the same for all agent types.

There are two agent types, set with the `agent_type` column of [`agents.csv`][agents-csv]:
competitive agents (`competitive`) and portfolio agents (`portfolio`)
The `agent_type` column of [`agents.csv`][agents-csv] selects competitive agents (`competitive`),
portfolio agents (`portfolio`), or population agents (`population`).

## Competitive agents

Expand Down Expand Up @@ -487,6 +487,80 @@ Once the LP has been solved, the selected assets are constructed from the capaci
3. Selected existing assets have any mothballed capacity that is needed reactivated, and selected
candidate assets are assigned to the agent, to be commissioned.

## Population agents

A population agent represents a large number of discrete entities with identical needs, such as
households. Each asset represents equipment that a group of these entities uses to meet one of its
needs, such as the gas boilers of homes heated with gas.

At each milestone year, the agent selects equipment for a market: one commodity in one region. Its
target is its share of that market's demand. Demand is a profile across time slices (or groups of
time slices, according to the commodity's time-slice level), rather than just a single annual total.
The population agent appraises options against the full profile, then selects them in merit order.

### Population agent options

The options considered are the agent's [investment options][investment-options]:

- each of the agent's existing assets in the region which have the commodity as their primary
output, including any mothballed capacity; and
- one candidate asset for each process in the agent's search space for the commodity, region and
milestone year.

### Appraisal

A candidate asset has continuous capacity unless its process defines a `tranche_size`, in which
case its capacity is in whole multiples of that size. The appraisal finds the capacity needed for
the full demand profile; the capacity and investment limits described under
[Population agent asset selection](#population-agent-asset-selection) are applied when assets are
selected.

Each option is appraised independently, once, against the full demand profile. An optimisation finds
the capacity and activity in each time slice that would supply the full profile using that option
alone. Activity must respect the process's availability limits, and output must match demand in
every time-slice group at the commodity's time-slice level. An option that cannot reproduce the
profile is excluded.

The optimisation minimises the option's total annual cost:

\\[
\mathrm{Metric} =
\mathrm{AnnualFixedCost} \times \mathrm{Capacity}
+ \sum_t \left(
\mathrm{OperatingCost}_t + \mathrm{InputCost}_t
\right) \times \mathrm{Activity}_t
+ \mathrm{UtilisationPenalties}
\\]

- **Annual fixed cost** includes fixed operating and maintenance costs. For a candidate asset it
also includes annualised capital cost; for an existing asset, capital cost is already sunk and is
not included.
- **Operating cost** includes the process's variable operating costs, levies and flow costs.
- **Input cost** is the cost of the asset's input commodities, valued at their market prices.
- **Utilisation penalties** are included when seasonal or annual peak-utilisation penalties are
configured.

The resulting minimum cost is the option's appraisal metric; lower-cost options rank higher. If
metrics are approximately equal, commissioned assets rank ahead of candidates, and newer
commissioned assets rank ahead of older ones. Any remaining ties keep the options' input order.

### Population agent asset selection

1. Rank existing assets and candidates together by their appraisal metric, with lower-cost options
first.
2. Consider options in merit order. For each option, scale its full-demand capacity to the fraction
of demand that remains. Limit the selected capacity by the available capacity and the agent's
share of any investment constraints (process limits scaled by the agent's share of demand).
Candidate capacity is limited by both the process's `addition_limit` and `total_capacity_limit`;
existing capacity is limited by its total capacity and any `total_capacity_limit`. Round
discrete capacity down to whole tranches so it does not exceed demand or a limit. Scale the
fitted activity profile by the ratio of selected capacity to its full-demand capacity, and
subtract the resulting supply from the remaining demand. Any existing capacity not retained
remains mothballed.
3. Continue until demand is met within the `remaining_demand_absolute_tolerance` configured in
`model.toml`. If the available options cannot meet demand after applying their capacity and
investment limits, the simulation ends with an error.

[investment]: ./investment.md
[investment-options]: ./investment.md#investment-options
[investment-constraints]: ./investment.md#investment-constraints
Expand Down
6 changes: 3 additions & 3 deletions docs/model/investment.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,12 +119,12 @@ Every asset consists of either a continuous capacity or one or more equal-capaci
has continuous capacity.
- Assets invested in _by MUSE_ are made up of tranches of the process `tranche_size`, if defined.
Otherwise, their capacity depends on the agent type: competitive agents build new capacity in
tranches whose size is inferred from demand at the time of investment, while portfolio agents
build a continuous capacity (see [Agents][agents]).
tranches whose size is inferred from demand at the time of investment, while portfolio and
population agents build a continuous capacity (see [Agents][agents]).

The tranches of a multi-tranche asset can be retained or mothballed independently. A
continuous-capacity asset is retained or mothballed as a whole by competitive agents, whereas
portfolio agents may retain only part of its capacity (see
portfolio and population agents may retain only part of its capacity (see
[Mothballing and Decommissioning](#mothballing-and-decommissioning)).

## Investment Constraints
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,8 @@
- 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 `population` agent type represents a population of discrete entities with identical needs,
such as households, and selects assets in merit order ([#1603])
- A new optional `simulation_protocol` setting in `model.toml` selects how each milestone year is
simulated. The new default, `agent_dispatch`, calculates flows and prices directly from the
activities determined by agents' own optimisations, without a system-wide dispatch.
Expand All @@ -29,3 +31,4 @@
[#1548]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1548
[#1557]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1557
[#1574]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1574
[#1603]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1603
16 changes: 8 additions & 8 deletions examples/circularity/agents.csv
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
id,description,regions,decision_rule,decision_lexico_tolerance
A0_OAG,Oil and gas IOC,all,single,
A0_ELC,Electricity generators,all,single,
A0_RES,Residential consumer,all,single,
A0_TRA,Consumer who drives,all,single,
A0_BPD,Biomass producer,all,single,
A0_BPL,Biomass pelletiser,all,single,
A0_REF,Refiners,all,single,
id,description,regions,decision_rule,decision_lexico_tolerance,agent_type
A0_OAG,Oil and gas IOC,all,single,,portfolio
A0_ELC,Electricity generators,all,single,,portfolio
A0_RES,Residential consumer,all,single,,population
A0_TRA,Consumer who drives,all,single,,population
A0_BPD,Biomass producer,all,single,,portfolio
A0_BPL,Biomass pelletiser,all,single,,portfolio
A0_REF,Refiners,all,single,,portfolio
4 changes: 2 additions & 2 deletions examples/circularity/assets.csv
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
process_id,region_id,agent_id,capacity,commission_year
GASDRV,GBR,A0_OAG,4010.2,2020
OAGRSV,GBR,A0_OAG,2073.38,2020
OAGRSV,GBR,A0_OAG,2097.18,2020
GASPRC,GBR,A0_OAG,3789.64,2020
OILREF,GBR,A0_REF,716.5,2020
OILRF2,GBR,A0_REF,929.5,2020
OILRF2,GBR,A0_REF,962.71,2020
WNDFRM,GBR,A0_ELC,3.964844,2020
GASCGT,GBR,A0_ELC,5.519,2020
H2YGEN,GBR,A0_ELC,1.0,2020
Expand Down
14 changes: 7 additions & 7 deletions examples/missing_commodity/agents.csv
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
id,description,regions,decision_rule,decision_lexico_tolerance
A0_GEX,Gas extractors,all,single,
A0_GPR,Gas processors,all,single,
A0_BPD,Biomass producer,all,single,
A0_BPL,Biomass pelletiser,all,single,
A0_ELC,Electricity generators,all,single,
A0_RES,Residential consumer,all,single,
id,description,regions,decision_rule,decision_lexico_tolerance,agent_type
A0_GEX,Gas extractors,all,single,,portfolio
A0_GPR,Gas processors,all,single,,portfolio
A0_BPD,Biomass producer,all,single,,portfolio
A0_BPL,Biomass pelletiser,all,single,,portfolio
A0_ELC,Electricity generators,all,single,,portfolio
A0_RES,Residential consumer,all,single,,population
8 changes: 4 additions & 4 deletions examples/muse1_default/agents.csv
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
id,description,regions,decision_rule,decision_lexico_tolerance
A1_RES,Residential sector agent,R1,single,
A1_PWR,Power sector agent,R1,single,
A1_GAS,Gas sector agent,R1,single,
id,description,regions,decision_rule,decision_lexico_tolerance,agent_type
A1_RES,Residential sector agent,R1,single,,population
A1_PWR,Power sector agent,R1,single,,portfolio
A1_GAS,Gas sector agent,R1,single,,portfolio
10 changes: 5 additions & 5 deletions examples/simple/agents.csv
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
id,description,regions,decision_rule,decision_lexico_tolerance
A0_GEX,Gas extractors,all,single,
A0_GPR,Gas processors,all,single,
A0_ELC,Electricity generators,all,single,
A0_RES,Residential consumer,all,single,
id,description,regions,decision_rule,decision_lexico_tolerance,agent_type
A0_GEX,Gas extractors,all,single,,portfolio
A0_GPR,Gas processors,all,single,,portfolio
A0_ELC,Electricity generators,all,single,,portfolio
A0_RES,Residential consumer,all,single,,population
16 changes: 8 additions & 8 deletions examples/two_outputs/agents.csv
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
id,description,regions,decision_rule,decision_lexico_tolerance
A0_OAG,Oil and gas IOC,all,single,
A0_ELC,Electricity generators,all,single,
A0_RES,Residential consumer,all,single,
A0_TRA,Consumer who drives,all,single,
A0_BPD,Biomass producer,all,single,
A0_BPL,Biomass pelletiser,all,single,
A0_REF,Refiners,all,single,
id,description,regions,decision_rule,decision_lexico_tolerance,agent_type
A0_OAG,Oil and gas IOC,all,single,,portfolio
A0_ELC,Electricity generators,all,single,,portfolio
A0_RES,Residential consumer,all,single,,population
A0_TRA,Consumer who drives,all,single,,population
A0_BPD,Biomass producer,all,single,,portfolio
A0_BPL,Biomass pelletiser,all,single,,portfolio
A0_REF,Refiners,all,single,,portfolio
8 changes: 4 additions & 4 deletions examples/two_regions/agents.csv
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
id,description,regions,decision_rule
A1_RES,Residential sector agent,R1;R2,single
A1_PWR,Power sector agent,R1;R2,single
A1_GAS,Gas sector agent,R1;R2,single
id,description,regions,decision_rule,agent_type
A1_RES,Residential sector agent,R1;R2,single,population
A1_PWR,Power sector agent,R1;R2,single,portfolio
A1_GAS,Gas sector agent,R1;R2,single,portfolio
8 changes: 5 additions & 3 deletions schemas/input/agents.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,16 @@ fields:
notes: One or more region IDs, separated by semicolons or the string `all`
- name: agent_type
type: string
enum: [competitive, portfolio]
enum: [competitive, portfolio, population]
description: The asset selection algorithm used by the agent
notes: |
Optional (defaults to `portfolio` if omitted). With `portfolio`, the capacities of all
existing and candidate assets are chosen together in a single optimisation. With
`competitive`, existing and candidate assets compete in rounds, with the best option according
to the agent's objective selected in each round. Competitive agents are experimental and
require `please_give_me_broken_results = true` in `model.toml`. See the
to the agent's objective selected in each round. With `population`, the agent represents many
discrete entities with identical needs, such as households; existing assets and candidates are
appraised against the full demand profile and selected in merit order. Competitive agents are
experimental and require `please_give_me_broken_results = true` in `model.toml`. See the
[Agents](../model/agents.md) page for details.
- name: decision_rule
type: string
Expand Down
2 changes: 2 additions & 0 deletions src/agent.rs
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,8 @@ pub enum AgentType {
/// Existing and candidate assets compete in rounds, with the best option according to the
/// agent's objective selected in each round
Competitive,
/// Placeholder for a population agent; not yet implemented
Population,
}

/// The decision rule for a particular objective
Expand Down
4 changes: 4 additions & 0 deletions src/input/agent.rs
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,10 @@ mod tests {
"id,description,regions,decision_rule,agent_type\nagent,,GBR,single,portfolio\n",
Some(AgentType::Portfolio)
)]
#[case(
"id,description,regions,decision_rule,agent_type\nagent,,GBR,single,population\n",
Some(AgentType::Population)
)]
fn read_agents_file_agent_type(#[case] csv: &str, #[case] expected: Option<AgentType>) {
let dir = tempdir().unwrap();
fs::write(dir.path().join(AGENT_FILE_NAME), csv).unwrap();
Expand Down
1 change: 1 addition & 0 deletions src/simulation/investment.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ use std::sync::Arc;
use strum::IntoEnumIterator;

pub mod competitive;
pub mod population;
pub mod portfolio;

/// A map of demand across time-slice selections for a specific market
Expand Down
Loading
Loading