Input file format

This file contains information about the input file format for MUSE 2.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

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

`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	Currently only `lcox` is supported
`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_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.

`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 `simple`
`decision_lexico_tolerance`	Tolerance for `lexico` decision rule	Currently unused

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), `inc` (input commodity) or `ouc` (output commodity)
`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.

`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

`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), `hi` (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_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_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.
`capacity_to_activity`	Factor for calculating the maximum consumption/production over a year.	Must be >=0

Notes

For each process, entries must be provided which cover every combination of milestone year and region in which the process operates.

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

Keyboard shortcuts

MUSE 2.0