Input files
This file contains information about the file formats for MUSE2 input files. It is not required to supply every input file - empty files can be omitted.
Model parameters: model.toml
Parameters which affect the behaviour of the model. Most are optional.
Top-level table
| Field | Description | Notes |
|---|---|---|
milestone_years | The milestone years for the simulation | Must be positive integers that are sorted and unique |
candidate_asset_capacity | Capacity to give to candidate assets in dispatch optimisation | Optional. Defaults to 0.0001.The default value should work. Do not change this value unless you know what you’re doing! |
capacity_limit_factor | A factor which constrains the maximum capacity given to candidate assets | Optional. Defaults to 0.1.This is the proportion of the maximum required capacity across time slices (for a given asset/commodity etc. combination). |
pricing_strategy | Change the algorithm used for calculating commodity prices | Optional. Defaults to shadow_prices.The shadow_prices option just uses the shadow prices for commodity prices.The scarcity_adjusted option adjusts prices for scarcity. This may cause price instability for assets with more than one output commodity. Do not use this unless you know what you’re doing! |
value_of_lost_load | The cost applied to unmet demand | Optional. Defaults to 1e9.Currently this only applies to the LCOX appraisal. |
max_ironing_out_iterations | The maximum number of iterations to run the “ironing out” step of agent investment for | Optional. Defaults to 10. |
price_tolerance | The relative tolerance for price convergence in the ironing out loop | Optional. Defaults to 1e-6. |
capacity_margin | Slack proportion for assets selected during cycle balancing to absorb small demand shifts | Optional. Defaults to 0.2. |
please_give_me_broken_results | Allows other options that are known to be broken to be used. Please don’t ever enable this. | |
mothball_years | Number of years an asset can remain unused before being decommissioned. Defaults to 0, decommissioning | |
| assets as soon as they are left unused. | ||
Optional. Defaults to 0. |
Time slices
time_slices.csv
Time slices define how the year is divided up. Each time slice is composed of a season and a time
of day. Often, this is written separated by a dot (e.g. winter.day).
| Field | Description | Notes |
|---|---|---|
season | Name of season | |
time_of_day | Name of time of day | |
fraction | Fraction of year | Must be >0 and <=1 |
Notes
- The fractions for the different time slices must sum to one.
Regions
regions.csv
Describes regions in the system.
| Field | Description | Notes |
|---|---|---|
id | A unique identifier for a region | |
description | A human-readable label for the region |
Agents
agents.csv
Describes agents in the system.
| Field | Description | Notes |
|---|---|---|
id | A unique identifier for an agent | |
description | A human-readable label for the agent | |
regions | The region(s) in which the agent operates | One or more region IDs, separated by semicolons or the string all |
decision_rule | The decision rule applied to objectives | Currently the only supported rule is single |
decision_lexico_tolerance | Tolerance for lexico decision rule | Currently unused |
agent_search_space.csv
Defines the processes in which an agent will invest for given parameters.
| Field | Description | Notes |
|---|---|---|
agent_id | An agent ID | |
commodity_id | The commodity to which this entry applies | |
years | The year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. |
search_space | The processes in which this agent will invest | One or more process IDs separated by semicolons. If this field is empty or all, all processes will be considered. |
Notes
- If entries are missing for any combination of agent, commodity or milestone year, then it is assumed that all processes can be considered in this case.
agent_commodity_portions.csv
Portions of commodity demand for which agents are responsible.
| Field | Description | Notes |
|---|---|---|
agent_id | The agent to apply these values to | |
commodity_id | The commodity for which the agent is responsible | |
years | The year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. |
commodity_portion | Portion of commodity demand | Value must be >0 and <=1. The portion applies only to the specified years. |
Notes
- If an entry is specified for one agent and commodity, there must be entries covering all milestone years.
- For each agent listed in this file, the total portions for each region/commodity/year combination must sum to one.
- In addition, there must be entries for every SVD and SED commodity for all regions and milestone years.
agent_objectives.csv
Describes the agents’ objectives.
| Field | Description | Notes |
|---|---|---|
agent_id | An agent ID | |
years | The year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. |
objective_type | The type of objective | Must be npv (net present value) or lcox (levelised cost of X). Note that support for NPV is currently broken, so don’t enable this option unless you know what you’re doing. |
decision_weight | Weight for weighted sum decision rule | Currently unused |
decision_lexico_order | Order in which to consider objectives for lexico decision rule | Currently unused |
Notes
- Every agent must have one objective for each milestone year.
- If the weighted sum decision rule is in use, the
decision_weightvalue must be provided, otherwise it must be omitted. - If the lexico decision rule is in use, the
decision_lexico_ordervalue must be provided, otherwise it must be omitted.
agent_cost_limits.csv
Limits on expenditure for agents.
| Field | Description | Notes |
|---|---|---|
agent_id | The agent to apply these values to | |
years | The year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. |
capex_limit | Maximum capital cost the agent will pay | Must be >0. Optional (defaults to infinity). |
annual_cost_limit | Maximum annual operating cost | The maximum annual operating cost (fuel plus variable operating cost etc.) that the agent will pay. Must be >0. Optional (defaults to infinity). |
Notes
- If cost limits are provided for an agent, they must be present for all years.
Assets
assets.csv
Defines assets in the system.
| Field | Description | Notes |
|---|---|---|
process_id | The process of which this asset is an instance | |
region_id | The region in which this agent operates | |
agent_id | The agent to which this asset belongs | |
capacity | The capacity of the asset | Must be >0 |
commission_year | The year in which to commission this asset | This value can be any integer >=0. If it is before the start of the simulation, it will already be commissioned in the first year and if it after the end of the simulation then it will never be commissioned. |
max_decommission_year | The latest year in which this asset can be decommissioned | This value can be any integer that satisfies max_decommission_year >= commission_year >=0. If it is set before the simulation starting year, the asset will not be commissioned during the simulation. |
Commodities
commodities.csv
Describes commodities in the system.
| Field | Description | Notes |
|---|---|---|
id | A unique identifier for the commodity | |
description | A human-readable label for the commodity | |
type | The type of commodity | Must be one of svd (service demand), sed (supply equals demand) or oth (other) |
time_slice_level | The time slice level at which constraints for this commodity are applied | Must be one of annual (whole year), season (whole season) or daynight (a particular time of day) |
Notes
- Every SED (supply equals demand) commodity must have both producer and consumer processes for every region and milestone year.
- Every SVD (service demand) commodity must have a producer for every region and milestone year.
commodity_levies.csv
Defines levies for commodities (or, if value is negative, incentives).
| Field | Description | Notes |
|---|---|---|
commodity_id | The commodity to which this entry applies | |
regions | The region(s) to which this entry applies | One or more region IDs, separated by semicolons or the string all |
years | The year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. |
time_slice | The time slices(s) to which this entry applies | Can be a single time slice (e.g. winter.day), a whole season (e.g. winter) or annual, representing the whole year |
balance_type | The type of balance to which this is applied | Can be cons (applies to consumption only), prod (applies to production only) or net (applies to production, with an equal and opposite levy/incentive on consumption) |
value | The value of the levy/incentive |
Notes
- If an entry is included for a given combination of commodity and region, entries must be provided covering all milestone years and time slices. For those regions not explicitly included for a given commodity, a zero levy/incentive is assumed. For one particular combination of region, year and time slice, there can be one production and one consumption levy, or a single net levy.
demand.csv
Specifies the demand for service demand commodities.
| Field | Description | Notes |
|---|---|---|
commodity_id | The service demand commodity to which this entry applies | |
region_id | The region to which this entry applies | A region ID |
year | The year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. |
demand | Total demand for this year |
Notes
- Every service demand commodity must have entries in this file covering every combination of milestone year and region.
demand_slicing.csv
Specifies how demand is distributed throughout the year (i.e. for different milestones).
| Field | Description | Notes |
|---|---|---|
commodity_id | The service demand commodity to which this entry applies | |
region_id | The region to which this entry applies | A region ID |
time_slice | The time slices(s) to which this entry applies | Can be a single time slice (e.g. winter.day), a whole season (e.g. winter) or annual, representing the whole year |
fraction | The fraction of annual demand for this entry | Must be >0 and <=1 |
Notes
- The user must provide entries covering every combination of service demand commodity, region and time slice.
- For each combination, the sum of the fractions must equal one.
Processes
processes.csv
Describes processes in the system.
| Field | Description | Notes |
|---|---|---|
id | A unique identifier for a process | |
description | A human-readable label for the process | |
regions | The region(s) in which this process can operate | One or more region IDs, separated by semicolons or the string all |
primary_output | The primary output commodity, if any, for this process | This field must be omitted for processes with only input flows. It can be omitted if there is only one output flow, in which case it will be inferred. |
start_year | The first year when this process is available to agents | |
end_year | The last year when this process is available to agents | Must be >= to start_year |
capacity_to_activity | Factor relating capacity units (e.g. GW) to activity units (e.g. PJ). It is the maximum activity per year for one unit of capacity. | Must be >=0. Optional (defaults to 1.0). |
process_flows.csv
The commodity flows for each process.
| Field | Description | Notes |
|---|---|---|
process_id | The process to which this entry applies | |
commodity_id | The commodity for this flow | |
regions | The region(s) to which this entry applies | One or more region IDs, separated by semicolons or the string all. Must be regions in which the process operates. |
years | The year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. |
coeff | The flow for this commodity | Can be <0, indicating an input flow, or >0, indicating an output flow. Cannot be zero. |
type | The type of commodity flow | Currently this value must be fixed |
cost | The cost per unit flow | Optional. If present, must be >0. |
Notes
- Commodity flows can vary by region and year.
- For each process, there must be entries covering all the years and regions in which the process operates.
process_investment_constraints.csv
Constraints on the amount agents can invest in processes.
| Field | Description | Notes |
|---|---|---|
process_id | The process to which this entry applies | |
regions | The region(s) to which this entry applies | One or more region IDs, separated by semicolons or the string all. Must be regions in which the process operates. |
commission years | The milestone year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. Must be within the process’s year range. |
addition limit | Yearly constraint on the amount agents can invest in the process | The addition limit is allocated evenly between all agents using their proportion of the processes primary commodity demand. |
Notes
- Not implemented yet! This file is reserved for future use.
process_availabilities.csv
Defines constraints on process availabilities throughout the year.
| Field | Description | Notes |
|---|---|---|
process_id | The process to which this entry applies | |
regions | The region(s) to which this entry applies | One or more region IDs, separated by semicolons or the string all |
years | The milestone year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. |
time_slice | The time slices(s) to which this entry applies | Can be a single time slice (e.g. winter.day), a season (e.g. winter) or annual. If a season or annual, this means that limit will apply to the season/year as a whole. |
limits | Lower and upper limits on the availability of the process within the specified time slice(s) | A string in the format min..max, where min and max are decimal numbers between 0 and 1 inclusive (e.g. “0.2..0.9”). 0 represents no availability, and 1 represents full availability. Either min or max can be omitted (e.g “0.2..” or “..0.9”), which will set the corresponding limit to 0 or 1, respectively. |
Notes
- Limits can be combined across multiple time periods. For example, users could provide a limit of “..0.9” for “winter.day” and “..0.5” for “winter”, indicating that the activity can reach up to 90% during winter days, so long as activity does not exceed 50% across winter as a whole.
- Incompatible limits will be flagged at the input validation stage. For example, a limit of “..0.01” for “winter” would likely be incompatible with a limit of “0.9..” for “winter.day”.
- If a limit is provided for any time slice (or season) for a particular process/region/year, it must be provided for all time slices (or seasons).
process_parameters.csv
Parameters for processes which vary by region and year.
| Field | Description | Notes |
|---|---|---|
process_id | The process to which this entry applies | |
regions | The region(s) to which this entry applies | One or more region IDs, separated by semicolons or the string all. Must be regions in which the process operates. |
years | The milestone year(s) to which this entry applies | One or more milestone years separated by semicolons, all to select all years or a year range in the form ‘start..end’ to select all valid years within range, inclusive. Either ‘start’ ‘end’ or both can be omitted, which will set the corresponding limit to the minimum or maximum valid year, respectively. |
capital_cost | Overnight capital cost per unit capacity | |
fixed_operating_cost | Annual operating cost per unit capacity | |
variable_operating_cost | Annual variable operating cost per unit activity | |
lifetime | Lifetime in years of an asset created from this process | Must be a positive integer |
discount_rate | Process-specific discount rate | Must be positive. A warning will be issued if this number is >1. |
Notes
- For each process, entries must be provided which cover every combination of milestone year and region in which the process operates.