Configuration reference

YAML configuration file format

All configuration files (with the exception of time series data files) are in the YAML format, “a human friendly data serialization 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.

Warning

When generating parallel runs with the calliope generate command-line tool, any import directive, unlike other settings that point to file system paths such as model_override or data_path, is evaluated immediately and all imported files are combined into one model configuration file for the parallel runs. This means that while paths used in import directives don’t need adjustment for parallel runs, other settings that work with file system paths probably do need adjustment to account for the way files are laid out on the system running the parallel runs. For this purpose, the data_path_adjustment inside a parallel configuration block can change the data path for parallel runs only.

Model-wide settings

These settings can either be in a central model.yaml file, or imported from other files if desired.

Mandatory model-wide settings with no default values (see Model configuration for more information on defining techs, locations and links):

data_path: 'data'  # Path to CSV (time series) data files

techs:
    # ... technology definitions ...

locations:
    # ... location definitions ...

links:
    # ... transmission link definitions ...

Optional model-wide settings with no default values (example settings are shown here):

constraints:  # List of additional constraints
    - constraints.optional.ramping_rate
    # ... other constraints to load ...

group_fraction:
    # ... setup for group_fraction constraints (see model formulation section) ...

metadata:  # Metadata for analysis and plotting
    map_boundary: []
    location_coordinates:
    location_ordering:

Optional model-wide settings that have defaults set by Calliope (default values are shown here):

# Chooses the objective function
# If not set, defaults to the included cost minimization objective
objective:  'constraints.objective.objective_cost_minimization'

startup_time: 12  # Length of startup period (hours)

opmode:  # Operation mode settings
    horizon: 48  # Optimization period length (hours)
    window: 24  # Operation period length (hours)

system_margin:  # Per-carrier system margins
    power: 0

Technology

A technology with the identifier tech_identifier is configured by a YAML block within a techs block. The following block shows all available options and their defaults (see further below for the constraints, costs, and depreciation definitions):

tech_identifier:
    name:  # A descriptive name, e.g. "Offshore wind"
    parent:  # An abstract base technology, or a previously defined one
    stack_weight: 100  # Weight of this technology in the stack when plotting
    color: false  # HTML color code, or `false` to choose a random color
    source_carrier: false # Carrier to consume, for conversion technologies
    group: false  # Make this a group for purposes of supply diversity analysis
    weight: 1.0 # Cost weighting in objective function
    constraints:
        # ... constraint definitions ...
    costs:
        monetary:
            # ... monetary cost definitions ...
        # ... other cost classes ...
    depreciation:
        # ... depreciation definitions ...

Each technology must define a parent, which can either be an abstract base technology such as supply, or any other technology previously defined in the model. The technology inherits all settings from its parent, but overwrites anything it specifies again itself. See Parents and groups for more details on this and on the function of the group: option.

stack_weight and color determine how the technology is shown in model outputs. The higher the stack_weight, the lower a technology will be shown in stackplots.

The depreciation definition is optional and only necessary if defaults need to be overridden. However, at least one constraint (such as e_cap.max) and one cost should usually be defined.

Transmission technologies can additionally specify per-distance constraints and per-distance costs (see Transmission links). Currently, only e_loss constraints and e_cap costs are supported:

transmission_tech:
   # per_distance constraints specified per 100 units of distance
   per_distance: 100
   constraints_per_distance:
      e_loss: 0.01  # loss per 100 units of distance
   costs_per_distance:
      monetary:
         e_cap: 10  # cost per 100 units of distance

Note

Transmission technologies can define both an e_loss (per-distance) and an e_eff (distance-independent). For example, setting e_eff to 0.9 implies a 10% loss during transmission, independent of distance. If both e_loss and e_eff are defined, their effects are cumulative.

Technology 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 Details
force_r false Forces this technology to use all available r, rather than making it a maximum upper boundary (for production) or minimum lower boundary (for consumption)
r_unit power Sets the unit of r to either power (i.e. kW) or energy (i.e. kWh), which affects how resource time series are processed when performing time resolution adjustments
r_eff 1.0 Resource to/from storage conversion efficiency
r_area.min 0 Minimum installed collector area (m2)
r_area.max false Maximum installed collector area (m2), set to false by default in order to disable this constraint and force r_area to 1
r_area.equals false Specific installed collector area (m2)
r_area_per_e_cap false If set, forces r_area to follow e_cap with the given numerical ration (e.g. setting to 1.5 means that r_area == 1.5 * e_cap)
r_cap.min 0 Minimum installed resource to/from storage conversion capacity (kW)
r_cap.max inf Maximum installed resource to/from storage conversion capacity (kW)
r_cap.equals false Specific installed resource to/from storage conversion capacity (kW)
r_cap_equals_e_cap false If true, r_cap is forced to equal e_cap
r_scale 1.0 Scale resource by this value
r_scale_to_peak false Scale resource such that its peak is as defined here, false to disable. This setting only has an effect if a time series is used via r: file
allow_rb false Allow secondary resource
rb_startup_only false Allow secondary resource during startup_time only (only has an effect if allow_rb is true)
rb_eff 1.0 Secondary resource to/from storage conversion efficiency
rb_cap.min 0 Minimum installed secondary resource to storage conversion capacity (kW)
rb_cap.max inf Maximum installed secondary resource to storage conversion capacity (kW)
rb_cap.equals 0 Specific installed secondary resource to storage conversion capacity (kW)
rb_cap_follow false Can be set to e_cap or r_cap to set rb_cap.max to the respective value (in which case, any given rb_cap.max is ignored). false to disable
rb_cap_follow_mode ‘max’ Can be set to max or equals to specifiy which rb_cap constraint is specific by the variable given in rb_cap_follow
s_init 0 Initial storage level (kWh)
s_cap.min 0 Minimum storage capacity (kWh)
s_cap.max 0 Maximum storage capacity (kWh)
s_cap.equals false Specific storage capacity (kWh)
use_s_time false Use full load hours for storage sizing? (set to true or false)
s_time.max 0 Max storage time (full load hours). Only has an effect if use_s_time is set to true
s_loss 0 Storage loss rate (per hour)
e_prod true Allow this technology to supply energy to the carrier
e_con false Allow this technology to consume energy from the carrier
c_eff 1.0 Carrier efficiency (additional losses as energy gets transferred from the plant to the carrier, e.g. due to plant parasitic consumption)
e_eff 1.0 Storage to/from carrier conversion efficiency. Can be set to file or file: or to a single numerical value
e_eff_ref false Reference storage to/from carrier efficiency. If set to false, e_eff is used instead. Currently only used when for storage size calculation when suse_s_time is true.
e_cap.min 0 Minimum installed storage to/from carrier conversion capacity (kW), per location
e_cap.max 0 Maximum installed storage to/from carrier conversion capacity (kW), per location
e_cap.equals false Specific installed storage to/from carrier conversion capacity (kW), per location
e_cap.total_max inf Maximum installed storage to/from carrier conversion capacity (kW), model-wide
e_cap.total_equals false Specific installed storage to/from carrier conversion capacity (kW), model-wide
e_cap_scale 1.0 Scale all e_cap min/max/equals/total_max/total_equals constraints by this value
e_cap_min_use false Set to a value between 0 and 1 to force minimum storage to carrier capacity use for production technologies
e_ramping false Ramping rate (fraction of installed capacity per hour), set to false to disable ramping constraints (only has an effect if the optional ramping constraints are loaded)

Technology 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 Details
s_cap 0 Cost of storage capacity (per kWh)
r_area 0 Cost of resource collector area (per m2)
r_cap 0 Cost of resource conversion capacity (per kW)
rb_cap 0 Cost of secondary resource conversion capacity (per kW)
e_cap 0 Cost of carrier conversion capacity (per kW gross)
om_frac 0 Yearly O&M costs (fraction of total investment)
om_fixed 0 Yearly O&M costs (per kW of e_cap)
om_var 0 Variable O&M costs (per kWh of es_prod)
om_fuel 0 Fuel costs (per kWh of r used)
om_rb 0 Fuel costs for secondary resource (per kWh of rb used)

Technology depreciation

These technology depreciation settings apply when calculating levelized costs. The interest rate can be set on a per-cost class basis, and defaults to \(0.10\) for monetary and \(0\) for every other cost class.

plant_life: 25  # Lifetime of a plant (years)
interest:
    default: 0  # Default interest rate if not specified for a cost class ``k``
    monetary: 0.10  # Interest rate for the ``monetary`` cost class

Abstract base technologies

This lists all pre-defined abstract base technologies and the defaults they provide. Note that it is not possible to define a technology with the same identifier as one of the abstract base technologies. In addition to providing default values for some options, which abstract base technology a user-defined technology inherits from determines how Calliope treats the technology internally.

Supply and demand

supply:

parent: defaults

demand:

parent: defaults
constraints:
    r: 0
    force_r: true
    e_cap.max: inf
    e_prod: false
    e_con: true

Unmet demand

unmet_demand:

stack_weight: 0
color: '#666666'
parent: defaults
constraints:
    r: inf
    e_cap.max: inf
costs:
    monetary:
        om_var: 1.0e+9

unmet_demand_as_supply_tech:

stack_weight: 0
color: '#666666'
parent: supply
constraints:
    r: inf
    e_cap.max: inf
costs:
    monetary:
        om_var: 1.0e+9

Storage, transmission and conversion

Warning

The default values provided for r and e_con by storage, transmission, and conversion should not be overridden.

storage:

parent: defaults
constraints:
    r: inf
    e_con: true

transmission:

parent: defaults
constraints:
    r: inf
    e_cap.max: inf
    e_con: true

conversion:

parent: defaults
constraints:
    r: inf
    e_con: true

Run settings

These settings will usually be in a central run.yaml file, which may import from other files if desired.

Mandatory settings:

  • model: Path to the model configuration which is to be used for this run
  • mode: plan or operate, whether to run the model in planning or operational mode
  • solver: Name of the solver to use

Optional settings:

  • Output options – these are only used when the model is run via the calliope run command-line tool:
    • output.path: Path to an output directory to save results (will be created if it doesn’t exist already)
    • output.format: Format to save results in, either hdf or csv
  • parallel: Settings used to generate parallel runs, see Settings for parallel runs for the available options

  • time: Settings to adjust time resolution, see Time resolution adjustment for the available options

  • override: Override arbitrary settings from the model configuration. E.g., this could specify techs.nuclear.costs.monetary.e_cap: 1000 to set the e_cap costs of nuclear, overriding whatever was set in the model configuration

  • model_override: Path to a YAML configuration file which contains additional overrides for the model configuration. If both this and override are specified, anything defined in override takes precedence over model configuration added in the model_override file.

  • solver_options: A list of options, which are passed on to the chosen solver, and are therefore solver-dependent (see below)

Debugging failing runs

A number of run settings exist to make debugging failing runs easier:

  • subset_y, subset_x, subset_t: specify if only a subset of technologies (y), locations (x), or timesteps (t) should be used for this run. This can be useful for debugging purposes. The timestep subset can be specified as [startdate, enddate], e.g. ['2005-01-01', '2005-01-31']. The subsets are processed before building the model and applying time resolution adjustments, so time resolution functions will only see the reduced set of data.

In addition, settings relevant to debugging can be specified inside a debug block as follows:

  • debug.keep_temp_files: Whether to keep temporary files inside a Logs directory rather than deleting them after completing the model run (which is the default). Useful to debug model problems.
  • debug.overwrite_temp_files: When debug.keep_temp_files is true, and the Logs directory already exists, Calliope will stop with an error, but if this setting is true, it will overwrite the existing temporary files.
  • debug.symbolic_solver_labels: By default, Pyomo uses short random names for all generated model components, rather than the variable and parameter names used in the model setup. This is faster but for debugging purposes models must be human-readable. Thus, particularly when using debug.keep_temp_files: true, this setting should also be set to true.
  • debug.echo_solver_log: Displays output from the solver on screen while solving the model (by default, output is only logged to the log file, which is removed unless debug.keep_temp_files is true).

The following example debug block would keep temporary files, removing possibly existing files from a previous run beforehand:

debug:
    keep_temp_files: true
    overwrite_temp_files: true

Solver options

Gurobi: Refer to the Gurobi manual, which contains a list of parameters. Simply use the names given in the documentation (e.g. “NumericFocus” to set the numerical focus value).

CPLEX: Refer to the CPLEX documentation, which contains a list of parameters. Use the “Interactive” parameter names, replacing any spaces with underscores (for example, the memory reduction switch is called “emphasis memory”, and thus becomes “emphasis_memory”).

Previous: Analyzing results | Next: The built-in example model