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 model
  • model: model settings
  • run: run settings
  • techs: 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

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/m2 | kW/m2 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 m2  
resource_area_max False Maximum installed collector area m2 Set to false by default in order to disable this constraint
resource_area_equals False Specific installed collector area m2  
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.

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 from supply.
  • 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

../_images/supply.svg

Default constraints provided by the parent tech group:

essentials:
  parent:
constraints:
  resource: inf
  resource_unit: power
  energy_prod: true
costs: {}

Required constraints, allowed constraints, and allowed costs:

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
allowed_costs:
-   interest_rate
-   resource_area
-   energy_cap
-   om_annual_investment_fraction
-   om_annual
-   om_prod
-   om_con
-   export
-   purchase
-   depreciation_rate
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]

supply_plus

../_images/supply_plus.svg

Default constraints provided by the parent tech group:

essentials:
  parent:
constraints:
  resource: inf
  resource_unit: power
  resource_eff: 1.0
  energy_prod: true
costs: {}

Required constraints, allowed constraints, and allowed costs:

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
-   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
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]

demand

../_images/demand.svg

Default constraints provided by the parent tech group:

essentials:
  parent:
constraints:
  resource_unit: power
  force_resource: true
  energy_con: true
costs: {}

Required constraints, allowed constraints, and allowed costs:

allowed_constraints:
-   energy_con
-   resource
-   force_resource
-   resource_unit
-   resource_scale
-   resource_area_equals
allowed_costs: []
required_constraints:
-   resource

storage

../_images/storage.svg

Default constraints provided by the parent tech group:

essentials:
  parent:
constraints:
  energy_prod: true
  energy_con: true
  storage_cap_max: inf
costs: {}

Required constraints, allowed constraints, and allowed costs:

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
allowed_costs:
-   interest_rate
-   storage_cap
-   energy_cap
-   om_annual_investment_fraction
-   om_annual
-   om_prod
-   export
-   purchase
-   depreciation_rate
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]
- [storage_cap_max, storage_cap_equals]

transmission

../_images/transmission.svg

Default constraints provided by the parent tech group:

essentials:
  parent:
constraints:
  energy_prod: true
  energy_con: true
costs: {}

Required constraints, allowed constraints, and allowed costs:

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
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]

conversion

../_images/conversion.svg

Default constraints provided by the parent tech group:

essentials:
  parent:
constraints:
  energy_prod: true
  energy_con: true
costs: {}

Required constraints, allowed constraints, and allowed costs:

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
allowed_costs:
-   interest_rate
-   energy_cap
-   om_annual_investment_fraction
-   om_annual
-   om_prod
-   om_con
-   export
-   purchase
-   depreciation_rate
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]

conversion_plus

../_images/conversion_plus.svg

Default constraints provided by the parent tech group:

essentials:
  parent:
constraints:
  energy_prod: true
  energy_con: true
costs: {}

Required constraints, allowed constraints, and allowed costs:

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
allowed_costs:
-   interest_rate
-   energy_cap
-   om_annual_investment_fraction
-   om_annual
-   om_prod
-   om_con
-   export
-   purchase
-   depreciation_rate
required_constraints:
- [energy_cap_max, energy_cap_equals, energy_cap_per_unit]

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 AttrDicts, 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