Input files

This file contains information about the file formats for MUSE 2.0 input files.

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`.

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 or `all`
`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 or `all`
`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 or `all`
`objective_type`	The type of objective	Must be `npv` (net present value) or `lcox` (levelised cost of X). Note that support for NPV is experimental and may give bad results.
`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_weight value must be provided, otherwise it must be omitted.
If the lexico decision rule is in use, the decision_lexico_order value 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 or `all`
`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.

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 or `all`
`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 consumption and production)
`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. At least one levy/incentive entry must be provided for at least one commodity.

`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 or `all`
`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 or `all`
`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_availabilities.csv`

Defines how much of a process's capacity is available 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 or `all`
`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
`limit_type`	The type of limit	Can be `lo` (a lower bound), `up` (an upper bound) or `fx` (indicating that the availability is constant)
`value`	The proportion of capacity which is available	Must be >0 and <=1

Notes

Must be provided for every process.
Only one type of limit can be supplied for each combination of process/region/year/time slice.

`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 or `all`
`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.

Keyboard shortcuts

MUSE 2.0