Listing of configuration options¶
Configuration layout¶
There must always be at least one model configuration YAML file, probably called model.yaml
or similar. This file can import any number of additional files.
This file or this set of files must specify the following top-level configuration keys:
name
: the name of the modelmodel
: model settingsrun
: run settingstechs
: technology definitions- (optionally)
tech_groups
: tech group definitions locations
: location definitions- (optionally)
links
: transmission link definitions
Note
Model settings (model
) affect how the model and its data are built by Calliope, while run settings (run
) only take effect once a built model is run (e.g. interactively via model.run()
). This means that run settings, unlike model settings, can be updated after a model is built and before it is run, by modifying attributes in the built model dataset.
List of model settings¶
Setting | Default | Comments |
---|---|---|
name | Model name | |
calliope_version | Calliope framework version this model is intended for | |
timeseries_data_path | Path to time series data | |
timeseries_dateformat | %Y-%m-%d %H:%M:%S | Timestamp format of all time series data when read from file |
timeseries_data | Dict of dataframes with time series data (when passing in dicts rather than YAML files to Model constructor) | |
subset_time | Subset of timesteps as a two-element list giving the range, e.g. [‘2005-01-01’, ‘2005-01-05’], or a single string, e.g. ‘2005-01’ | |
reserve_margin | {} | Per-carrier system-wide reserve margins |
random_seed | Seed for random number generator used during clustering | |
time | {} | Optional settings to adjust time resolution, see Time resolution adjustment for the available options |
group_share | {} | Optional settings for the group_share constraint |
List of run settings¶
Setting | Default | Comments |
---|---|---|
backend | pyomo | Backend to use to build and solve the model. As of v0.6.0, only pyomo is available |
solver | glpk | Which solver to use |
solver_options | A list of options, which are passed on to the chosen solver, and are therefore solver-dependent | |
solver_io | What method the Pyomo backend should use to communicate with the solver | |
save_logs | Directory into which to save logs and temporary files. Also turns on symbolic solver labels in the Pyomo backend | |
bigM | 1000000000.0 | Used for unmet demand, but should be of a similar order of magnitude as the largest cost that the model could achieve. Too high and the model will not converge |
ensure_feasibility | False | If true, unmet_demand will be a decision variable, to account for an ability to meet demand with the available supply. If False and a mismatch occurs, the optimisation will fail due to infeasibility |
operation | {} | Settings for operational mode |
objective | minmax_cost_optimization | Name of internal objective function to use, currently only min/max cost-based optimisation is available |
objective_options | {} | Arguments to pass to objective function. If cost-based objective function in use, should include ‘cost_class’ and ‘sense’ (maximize/minimize) |
mode | plan | Which mode to run the model in: ‘plan’ or ‘operation’ |
zero_threshold | 1e-10 | Any value coming out of the backend that is smaller than this threshold (due to floating point errors, probably) will be set to zero |
cyclic_storage | False | If true, storage in the last timestep of the timeseries is considered to be the ‘previous timestep’ in the first timestep of the timeseries |
List of possible constraints¶
The following table lists all available technology constraint settings and their default values. All of these can be set by tech_identifier.constraints.constraint_name
, e.g. nuclear.constraints.e_cap.max
.
Setting | Default | Name | Unit | Comments |
---|---|---|---|---|
lifetime | Technology lifetime | years | Must be defined if fixed capital costs are defined. A reasonable value for many technologies is around 20-25 years. | |
carrier_ratios | {} | Carrier ratios | fraction | Ratio of summed output of carriers in [‘out_2’, ‘out_3’] / [‘in_2’, ‘in_3’] to the summed output of carriers in ‘out’ / ‘in’. given in a nested dictionary. |
resource | 0 | Available resource | kWh/m^{2} | kW/m^{2} | Maximum available resource (static, or from file as timeseries). Unit dictated by reosurce_unit |
force_resource | False | Force resource | boolean | Forces this technology to use all available resource , rather than making it a maximum upper boundary (for production) or minimum lower boundary (for consumption). Static boolean, or from file as timeseries |
resource_unit | power | Resource unit | N/A | Sets the unit of resource to either power (i.e. kW) or energy (i.e. kWh), which affects how resource time series are processed when performing time resolution adjustments |
resource_eff | 1.0 | Resource efficiency | fraction | Efficiency (static, or from file as timeseries) in capturing resource before it reaches storage (if storage is present) or conversion to carrier. |
resource_area_min | 0 | Minimum installed collector area | m^{2} | |
resource_area_max | False | Maximum installed collector area | m^{2} | Set to false by default in order to disable this constraint |
resource_area_equals | False | Specific installed collector area | m^{2} | |
resource_area_per_energy_cap | False | Energy capacity per unit collector ares | boolean | If set, forces resource_area to follow energy_cap with the given numerical ratio (e.g. setting to 1.5 means that resource_area == 1.5 * energy_cap ) |
resource_cap_min | 0 | Minimum installed resource consumption capacity | kW | |
resource_cap_max | inf | Maximum installed resource consumption capacity | kW | |
resource_cap_equals | False | Specific installed resource consumption capacity | kW | overrides _max and _min constraints. |
resource_cap_equals_energy_cap | False | Resource capacity equals energy cpacity | boolean | If true, resource_cap is forced to equal energy_cap |
resource_min_use | False | Minimum resource consumption | fraction | Set to a value between 0 and 1 to force minimum resource consumption for production technologies |
resource_scale | 1.0 | Resource scale | fraction | Scale resource (either static value or all valuesin timeseries) by this value |
storage_initial | 0 | Initial storage level | kWh | Set stored energy in device at the first timestep |
storage_cap_min | 0 | Minimum storage capacity | kWh | |
storage_cap_max | inf | Maximum storage capacity | kWh | If not defined, energy_cap_max * charge_rate will be used as the capacity. |
storage_cap_equals | False | Specific storage capacity | kWh | If not defined, energy_cap_equals * charge_rate will be used as the capacity and overrides _max and _min constraints. |
storage_cap_per_unit | False | Storage capacity per purchased unit | kWh/unit | Set the storage capacity of each integer unit of a technology perchased. |
charge_rate | False | Charge rate | hour ^{-1} | ratio of maximum charge/discharge (kW) for a given maximum storage capacity (kWh) |
storage_loss | 0 | Storage loss rate | hour ^{-1} | rate of storage loss per hour (static, or from file as timeseries), used to calculate lost stored energy as (1 - storage_loss)^hours_per_timestep |
energy_prod | False | Energy production | boolean | Allow this technology to supply energy to the carrier (static boolean, or from file as timeseries). |
energy_con | False | Energy consumption | boolean | Allow this technology to consume energy from the carrier (static boolean, or from file as timeseries). |
parasitic_eff | 1.0 | Plant parasitic efficiency | fraction | Additional losses as energy gets transferred from the plant to the carrier (static, or from file as timeseries), e.g. due to plant parasitic consumption |
energy_eff | 1.0 | Energy efficiency | fraction | conversion efficiency (static, or from file as timeseries), from resource /storage /carrier_in (tech dependent) to carrier_out . |
energy_eff_per_distance | 1.0 | Energy efficiency per distance | distance ^{-1} | Set as value between 1 (no loss) and 0 (all energy lost) |
energy_cap_min | 0 | Minimum installed energy capacity | kW | Limits decision variables carrier_prod /carrier_con to a minimum/maximum. |
energy_cap_max | inf | Maximum installed energy capacity | kW | Limits decision variables carrier_prod /carrier_con to a maximum/minimum. |
energy_cap_equals | False | Specific installed energy capacity | kW | fixes maximum/minimum if decision variables carrier_prod /carrier_con and overrides _max and _min constraints. |
energy_cap_max_systemwide | inf | System-wide maximum installed energy capacity | kW | Limits the sum to a maximum/minimum, for a particular technology, of the decision variables carrier_prod /carrier_con over all locations. |
energy_cap_equals_systemwide | False | System-wide specific installed energy capacity | kW | fixes the sum to a maximum/minimum, for a particular technology, of the decision variables carrier_prod /carrier_con over all locations. |
energy_cap_scale | 1.0 | Energy capacity scale | float | Scale all energy_cap min/max/equals/total_max/total_equals constraints by this value |
energy_cap_min_use | False | Minimum carrier production | fraction | Set to a value between 0 and 1 to force minimum carrer production as a fraction of the technology maximum energy capacity. If non-zero and technology is not defined by units , this will force the technology to operate above its minimum value at every timestep. |
energy_cap_per_unit | False | Energy capacity per purchased unit | kW/unit | Set the capacity of each integer unit of a technology purchased |
energy_ramping | False | Ramping rate | fraction / hour | Set to false to disable ramping constraints, otherwise limit maximum carrier production to a fraction of maximum capacity, which increases by that fraction at each timestep. |
export_cap | inf | Export capacity | kW | Maximum allowed export of produced energy carrier for a technology. |
export_carrier | Export carrier | N/A | Name of carrier to be exported. Must be an output carrier of the technology | |
units_min | False | Minimum number of purchased units | integer | Turns the model from LP to MILP. |
units_max | False | Maximum number of purchased units | integer | Turns the model from LP to MILP. |
units_equals | False | Specific number of purchased units | integer | Turns the model from LP to MILP. |
units_max_systemwide | inf | System-wide maximum installed energy capacity | kW | Limits the sum to a maximum/minimum, for a particular technology, of the decision variables carrier_prod /carrier_con over all locations. |
units_equals_systemwide | False | System-wide specific installed energy capacity | kW | fixes the sum to a |
List of possible costs¶
These are all the available costs, which are set to \(0\) by default for every defined cost class. Costs are set by tech_identifier.costs.cost_class.cost_name
, e.g. nuclear.costs.monetary.e_cap
.
Setting | Default | Name | Unit | Comments |
---|---|---|---|---|
interest_rate | 0 | Interest rate | fraction | Used when computing levelized costs |
storage_cap | 0 | Cost of storage capacity | kWh ^{-1} | |
resource_area | 0 | Cost of resource collector area | m^{-2} | |
resource_cap | 0 | Cost of resource consumption capacity | kW ^{-1} | |
energy_cap | 0 | Cost of energy capacity | kW _{gross} ^{-1} | |
energy_cap_per_distance | 0 | Cost of energy capacity, per unit distance | kW _{gross} ^{-1} / distance | Applied to transmission links only |
om_annual_investment_fraction | 0 | Fractional yearly O&M costs | fraction / total investment | |
om_annual | 0 | Yearly O&M costs | kW _{energy_cap} ^{-1} | |
om_prod | 0 | Carrier production cost | kWh ^{-1} | Applied to carrier production of a technology |
om_con | 0 | Carrier consumption cost | kWh ^{-1} | Applied to carrier consumption of a technology |
export | 0 | Carrier export cost | kWh ^{-1} | Usually used in the negative sense, as a subsidy. |
purchase | 0 | Purchase cost | unit ^{-1} | Triggers a binary variable for that technology to say that it has been purchased or is applied to integer variable units |
Technology depreciation settings apply when calculating levelized costs. The interest rate and life times must be set for each technology with investment costs.
List of abstract base technology groups¶
Technologies must always define a parent, and this can either be one of the pre-defined abstract base technology groups or a user-defined group (see Using tech_groups to group configuration). The pre-defined groups are:
supply
: Supplies energy to a carrier, has a positive resource.supply_plus
: Supplies energy to a carrier, has a positive resource. Additional possible constraints, including efficiencies and storage, distinguish this fromsupply
.demand
: Demands energy from a carrier, has a negative resource.storage
: Stores energy.transmission
: Transmits energy from one location to another.conversion
: Converts energy from one carrier to another.conversion_plus
: Converts energy from one or more carrier(s) to one or more different carrier(s).
A technology inherits the configuration that its parent group specifies (which, in turn, may inherit from its own parent).
Note
The identifiers of the abstract base tech groups are reserved and cannot be used for a user-defined technology or tech group.
The following lists the pre-defined base tech groups and the defaults they provide.
supply¶
Default constraints provided by the parent tech group:
costs: {}
constraints:
resource: inf
resource_unit: power
energy_prod: true
essentials:
parent:
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]
allowed_constraints:
- energy_prod
- lifetime
- resource
- force_resource
- resource_min_use
- resource_unit
- resource_area_min
- resource_area_max
- resource_area_equals
- resource_area_per_energy_cap
- resource_scale
- energy_eff
- energy_cap_min
- energy_cap_max
- energy_cap_equals
- energy_cap_max_systemwide
- energy_cap_equals_systemwide
- energy_cap_scale
- energy_cap_min_use
- energy_cap_per_unit
- energy_ramping
- energy_eff_per_distance
- export_cap
- export_carrier
- units_min
- units_max
- units_equals
- units_max_systemwide
- units_equals_systemwide
allowed_costs:
- interest_rate
- resource_area
- energy_cap
- om_annual_investment_fraction
- om_annual
- om_prod
- om_con
- export
- purchase
- depreciation_rate
supply_plus¶
Default constraints provided by the parent tech group:
costs: {}
constraints:
resource: inf
resource_unit: power
resource_eff: 1.0
energy_prod: true
essentials:
parent:
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]
allowed_constraints:
- energy_prod
- lifetime
- resource
- force_resource
- resource_min_use
- resource_unit
- resource_eff
- resource_area_min
- resource_area_max
- resource_area_equals
- resource_area_per_energy_cap
- resource_cap_min
- resource_cap_max
- resource_cap_equals
- resource_cap_equals_energy_cap
- resource_scale
- parasitic_eff
- energy_eff
- energy_cap_min
- energy_cap_max
- energy_cap_equals
- energy_cap_max_systemwide
- energy_cap_equals_systemwide
- energy_cap_scale
- energy_cap_min_use
- energy_cap_per_unit
- energy_ramping
- energy_eff_per_distance
- export_cap
- export_carrier
- units_min
- units_max
- units_equals
- units_max_systemwide
- units_equals_systemwide
- storage_initial
- storage_cap_min
- storage_cap_max
- storage_cap_equals
- storage_cap_per_unit
- charge_rate
- storage_time_max
- storage_loss
allowed_costs:
- interest_rate
- storage_cap
- resource_area
- resource_cap
- energy_cap
- om_annual_investment_fraction
- om_annual
- om_prod
- om_con
- export
- purchase
- depreciation_rate
demand¶
Default constraints provided by the parent tech group:
costs: {}
constraints:
resource_unit: power
force_resource: true
energy_con: true
essentials:
parent:
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- resource
allowed_constraints:
- energy_con
- resource
- force_resource
- resource_unit
- resource_scale
- resource_area_equals
allowed_costs: []
storage¶
Default constraints provided by the parent tech group:
costs: {}
constraints:
energy_prod: true
energy_con: true
storage_cap_max: inf
essentials:
parent:
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]
- [storage_cap_max, storage_cap_equals]
allowed_constraints:
- energy_prod
- energy_con
- lifetime
- energy_eff
- energy_cap_min
- energy_cap_max
- energy_cap_equals
- energy_cap_max_systemwide
- energy_cap_equals_systemwide
- energy_cap_scale
- energy_cap_min_use
- energy_cap_per_unit
- energy_ramping
- storage_initial
- storage_cap_min
- storage_cap_max
- storage_cap_equals
- storage_cap_per_unit
- charge_rate
- storage_time_max
- storage_loss
- export_cap
- export_carrier
- units_min
- units_max
- units_equals
- units_max_systemwide
- units_equals_systemwide
allowed_costs:
- interest_rate
- storage_cap
- energy_cap
- om_annual_investment_fraction
- om_annual
- om_prod
- export
- purchase
- depreciation_rate
transmission¶
Default constraints provided by the parent tech group:
costs: {}
constraints:
energy_prod: true
energy_con: true
essentials:
parent:
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]
allowed_constraints:
- energy_prod
- energy_con
- lifetime
- energy_con
- energy_prod
- energy_eff_per_distance
- energy_eff
- one_way
- energy_cap_scale
allowed_costs:
- interest_rate
- energy_cap
- energy_cap_per_distance
- om_annual_investment_fraction
- om_annual
- om_prod
- purchase
- purchase_per_distance
- depreciation_rate
conversion¶
Default constraints provided by the parent tech group:
costs: {}
constraints:
energy_prod: true
energy_con: true
essentials:
parent:
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]
allowed_constraints:
- energy_prod
- energy_con
- lifetime
- energy_eff
- energy_cap_min
- energy_cap_max
- energy_cap_equals
- energy_cap_max_systemwide
- energy_cap_equals_systemwide
- energy_cap_scale
- energy_cap_min_use
- energy_cap_per_unit
- energy_ramping
- energy_eff_per_distance
- export_cap
- export_carrier
- units_min
- units_max
- units_equals
- units_max_systemwide
- units_equals_systemwide
allowed_costs:
- interest_rate
- energy_cap
- om_annual_investment_fraction
- om_annual
- om_prod
- om_con
- export
- purchase
- depreciation_rate
conversion_plus¶
Default constraints provided by the parent tech group:
costs: {}
constraints:
energy_prod: true
energy_con: true
essentials:
parent:
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]
allowed_constraints:
- energy_prod
- energy_con
- lifetime
- carrier_ratios
- energy_eff
- energy_cap_min
- energy_cap_max
- energy_cap_equals
- energy_cap_max_systemwide
- energy_cap_equals_systemwide
- energy_cap_scale
- energy_cap_min_use
- energy_cap_per_unit
- energy_ramping
- energy_eff_per_distance
- export_cap
- export_carrier
- units_min
- units_max
- units_equals
- units_max_systemwide
- units_equals_systemwide
allowed_costs:
- interest_rate
- energy_cap
- om_annual_investment_fraction
- om_annual
- om_prod
- om_con
- export
- purchase
- depreciation_rate
YAML configuration file format¶
All configuration files (with the exception of time series data files) are in the YAML format, “a human friendly data serialisation standard for all programming languages”.
Configuration for Calliope is usually specified as option: value
entries, where value
might be a number, a text string, or a list (e.g. a list of further settings).
Calliope allows an abbreviated form for long, nested settings:
one:
two:
three: x
can be written as:
one.two.three: x
Calliope also allows a special import:
directive in any YAML file. This can specify one or several YAML files to import. If both the imported file and the current file define the same option, the definition in the current file takes precedence.
Using quotation marks ('
or "
) to enclose strings is optional, but can help with readability. The three ways of setting option
to text
below are equivalent:
option: "text"
option: 'text'
option: text
Sometimes, a setting can be either enabled or disabled, in this case, the boolean values true
or false
are used.
Comments can be inserted anywhere in YAML files with the #
symbol. The remainder of a line after #
is interpreted as a comment.
See the YAML website for more general information about YAML.
Calliope internally represents the configuration as AttrDict
s, which are a subclass of the built-in Python dictionary data type (dict
) with added functionality such as YAML reading/writing and attribute access to keys.
Previous: Built-in example models | Next: Mathematical formulation