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 |
---|---|---|
calliope_version | Calliope framework version this model is intended for | |
group_share | {} | Optional settings for the group_share constraint |
name | Model name | |
random_seed | Seed for random number generator used during clustering | |
reserve_margin | {} | Per-carrier system-wide reserve margins |
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’ | |
time | {} | Optional settings to adjust time resolution, see Time resolution adjustment for the available options |
timeseries_data_path | Path to time series data | |
timeseries_data | Dict of dataframes with time series data (when passing in dicts rather than YAML files to Model constructor) | |
timeseries_dateformat | %Y-%m-%d %H:%M:%S | Timestamp format of all time series data when read from file |
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 |
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 |
cyclic_storage | True | If true, storage in the last timestep of the timeseries is considered to be the ‘previous timestep’ in the first timestep of the timeseries |
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 |
mode | plan | Which mode to run the model in: ‘plan’ or ‘operation’ |
objective_options | {} | Arguments to pass to objective function. If cost-based objective function in use, should include ‘cost_class’ and ‘sense’ (maximize/minimize) |
objective | minmax_cost_optimization | Name of internal objective function to use, currently only min/max cost-based optimisation is available |
operation | {} | Settings for operational mode |
save_logs | Directory into which to save logs and temporary files. Also turns on symbolic solver labels in the Pyomo backend | |
solver_io | What method the Pyomo backend should use to communicate with the solver | |
solver_options | A list of options, which are passed on to the chosen solver, and are therefore solver-dependent | |
solver | glpk | Which solver to use |
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 |
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 |
---|---|---|---|---|
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. |
charge_rate | False | Charge rate | hour ^{-1} | ratio of maximum charge/discharge (kW) for a given maximum storage capacity (kWh). |
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_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_max | inf | Maximum installed energy capacity | kW | Limits decision variables carrier_prod /carrier_con to a maximum/minimum. |
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_min | 0 | Minimum installed energy capacity | kW | Limits decision variables carrier_prod /carrier_con to a minimum/maximum. |
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_cap_scale | 1.0 | Energy capacity scale | float | Scale all energy_cap min/max/equals/total_max/total_equals constraints by this value |
energy_con | False | Energy consumption | boolean | Allow this technology to consume energy from the carrier (static boolean, or from file as timeseries). |
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_prod | False | Energy production | boolean | Allow this technology to supply energy to the carrier (static boolean, or from file as timeseries). |
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 | |
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 |
lifetime | Technology lifetime | years | Must be defined if fixed capital costs are defined. A reasonable value for many technologies is around 20-25 years. | |
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 |
resource | 0 | Available resource | kWh/m^{2} | kW/m^{2} | Maximum available resource (static, or from file as timeseries). Unit dictated by reosurce_unit |
resource_area_equals | False | Specific 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_min | 0 | Minimum 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_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_cap_max | inf | Maximum installed resource consumption capacity | kW | |
resource_cap_min | 0 | Minimum installed resource consumption capacity | kW | |
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_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 values in timeseries) by this value |
resource_unit | energy | Resource unit | N/A | Sets the unit of resource to either energy (i.e. kWh), energy_per_area (i.e. kWh/m2), or energy_per_cap (i.e. kWh/kW). energy_per_area uses the resource_area decision variable to scale the available resource while energy_per_cap uses the energy_cap decision variable. |
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_max | inf | Maximum storage capacity | kWh | If not defined, energy_cap_max * charge_rate will be used as the capacity. |
storage_cap_min | 0 | Minimum storage capacity | kWh | |
storage_cap_per_unit | False | Storage capacity per purchased unit | kWh/unit | Set the storage capacity of each integer unit of a technology perchased. |
storage_initial | 0 | Initial storage level | kWh | Set stored energy in device at the first timestep |
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 |
units_equals | False | Specific number of purchased units | integer | Turns the model from LP to MILP. |
units_equals_systemwide | False | System-wide specific installed energy capacity | kW | fixes the sum to a specific value, for a particular technology, of the decision variables carrier_prod /carrier_con over all locations. |
units_max | False | Maximum 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_min | False | Minimum number of purchased units | integer | Turns the model from LP to MILP. |
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 |
---|---|---|---|---|
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 |
export | 0 | Carrier export cost | kWh ^{-1} | Usually used in the negative sense, as a subsidy. |
interest_rate | 0 | Interest rate | fraction | Used when computing levelized costs |
om_annual | 0 | Yearly O&M costs | kW _{energy_cap} ^{-1} | |
om_annual_investment_fraction | 0 | Fractional yearly O&M costs | fraction / total investment | |
om_con | 0 | Carrier consumption cost | kWh ^{-1} | Applied to carrier consumption of a technology |
om_prod | 0 | Carrier production cost | kWh ^{-1} | Applied to carrier production of a technology |
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 |
resource_area | 0 | Cost of resource collector area | m^{-2} | |
resource_cap | 0 | Cost of resource consumption capacity | kW ^{-1} | |
storage_cap | 0 | Cost of storage capacity | kWh ^{-1} |
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: {}
essentials:
parent:
constraints:
energy_prod: true
resource: inf
resource_unit: energy
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_equals, energy_cap_max, energy_cap_per_unit]
allowed_constraints:
- energy_cap_equals
- energy_cap_equals_systemwide
- energy_cap_max
- energy_cap_max_systemwide
- energy_cap_min
- energy_cap_min_use
- energy_cap_per_unit
- energy_cap_scale
- energy_eff
- energy_prod
- energy_ramping
- export_cap
- export_carrier
- force_resource
- lifetime
- resource
- resource_area_equals
- resource_area_max
- resource_area_min
- resource_area_per_energy_cap
- resource_min_use
- resource_scale
- resource_unit
- units_equals
- units_equals_systemwide
- units_max
- units_max_systemwide
- units_min
allowed_costs:
- depreciation_rate
- energy_cap
- export
- interest_rate
- om_annual
- om_annual_investment_fraction
- om_con
- om_prod
- purchase
- resource_area
supply_plus¶
Default constraints provided by the parent tech group:
costs: {}
essentials:
parent:
constraints:
energy_prod: true
resource: inf
resource_eff: 1.0
resource_unit: energy
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_equals, energy_cap_max, energy_cap_per_unit]
allowed_constraints:
- charge_rate
- energy_cap_equals
- energy_cap_equals_systemwide
- energy_cap_max
- energy_cap_max_systemwide
- energy_cap_min
- energy_cap_min_use
- energy_cap_per_unit
- energy_cap_scale
- energy_eff
- energy_prod
- energy_ramping
- export_cap
- export_carrier
- force_resource
- lifetime
- parasitic_eff
- resource
- resource_area_equals
- resource_area_max
- resource_area_min
- resource_area_per_energy_cap
- resource_cap_equals
- resource_cap_equals_energy_cap
- resource_cap_max
- resource_cap_min
- resource_eff
- resource_min_use
- resource_scale
- resource_unit
- storage_cap_equals
- storage_cap_max
- storage_cap_min
- storage_cap_per_unit
- storage_initial
- storage_loss
- units_equals
- units_equals_systemwide
- units_max
- units_max_systemwide
- units_min
allowed_costs:
- depreciation_rate
- energy_cap
- export
- interest_rate
- om_annual
- om_annual_investment_fraction
- om_con
- om_prod
- purchase
- resource_area
- resource_cap
- storage_cap
demand¶
Default constraints provided by the parent tech group:
costs: {}
essentials:
parent:
constraints:
energy_con: true
force_resource: true
resource_unit: energy
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- resource
allowed_constraints:
- energy_con
- force_resource
- resource
- resource_area_equals
- resource_scale
- resource_unit
allowed_costs: []
storage¶
Default constraints provided by the parent tech group:
costs: {}
essentials:
parent:
constraints:
energy_con: true
energy_prod: true
storage_cap_max: inf
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_equals, energy_cap_max, energy_cap_per_unit]
- [storage_cap_equals, storage_cap_max]
allowed_constraints:
- charge_rate
- energy_cap_equals
- energy_cap_equals_systemwide
- energy_cap_max
- energy_cap_max_systemwide
- energy_cap_min
- energy_cap_min_use
- energy_cap_per_unit
- energy_cap_scale
- energy_con
- energy_eff
- energy_prod
- energy_ramping
- export_cap
- export_carrier
- lifetime
- storage_cap_equals
- storage_cap_max
- storage_cap_min
- storage_cap_per_unit
- storage_initial
- storage_loss
- storage_time_max
- units_equals
- units_equals_systemwide
- units_max
- units_max_systemwide
- units_min
allowed_costs:
- depreciation_rate
- energy_cap
- export
- interest_rate
- om_annual
- om_annual_investment_fraction
- om_prod
- purchase
- storage_cap
transmission¶
Default constraints provided by the parent tech group:
costs: {}
essentials:
parent:
constraints:
energy_con: true
energy_prod: true
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_equals, energy_cap_max, energy_cap_per_unit]
allowed_constraints:
- energy_cap_equals
- energy_cap_max
- energy_cap_per_unit
- energy_cap_scale
- energy_con
- energy_eff
- energy_eff_per_distance
- energy_prod
- lifetime
- one_way
allowed_costs:
- depreciation_rate
- energy_cap
- energy_cap_per_distance
- interest_rate
- om_annual
- om_annual_investment_fraction
- om_prod
- purchase
- purchase_per_distance
conversion¶
Default constraints provided by the parent tech group:
costs: {}
essentials:
parent:
constraints:
energy_con: true
energy_prod: true
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_equals, energy_cap_max, energy_cap_per_unit]
allowed_constraints:
- energy_cap_equals
- energy_cap_equals_systemwide
- energy_cap_max
- energy_cap_max_systemwide
- energy_cap_min
- energy_cap_min_use
- energy_cap_per_unit
- energy_cap_scale
- energy_con
- energy_eff
- energy_prod
- energy_ramping
- export_cap
- export_carrier
- lifetime
- units_equals
- units_equals_systemwide
- units_max
- units_max_systemwide
- units_min
allowed_costs:
- depreciation_rate
- energy_cap
- export
- interest_rate
- om_annual
- om_annual_investment_fraction
- om_con
- om_prod
- purchase
conversion_plus¶
Default constraints provided by the parent tech group:
costs: {}
essentials:
parent:
constraints:
energy_con: true
energy_prod: true
Required constraints, allowed constraints, and allowed costs:
required_constraints:
- [energy_cap_equals, energy_cap_max, energy_cap_per_unit]
allowed_constraints:
- carrier_ratios
- energy_cap_equals
- energy_cap_equals_systemwide
- energy_cap_max
- energy_cap_max_systemwide
- energy_cap_min
- energy_cap_min_use
- energy_cap_per_unit
- energy_cap_scale
- energy_con
- energy_eff
- energy_prod
- energy_ramping
- export_cap
- export_carrier
- lifetime
- units_equals
- units_equals_systemwide
- units_max
- units_max_systemwide
- units_min
allowed_costs:
- depreciation_rate
- energy_cap
- export
- interest_rate
- om_annual
- om_annual_investment_fraction
- om_con
- om_prod
- purchase
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