Built-in example models

This section gives a listing of all the YAML configuration files included in the built-in example models. Refer to the tutorials section for a brief overview of how these parts together can provide a simple working model.

The example models are accessible in the calliope.examples module. To create an instance of an example model, e.g.:

urban_model = calliope.examples.UrbanScale()

National-scale example

Available as calliope.examples.NationalScale.

Model settings

The layout of the model directory is as follows (+ denotes directories, - files):

+ model_config
   + data
      - csp_r.csv
      - demand-1.csv
      - demand-2.csv
      - set_t.csv
   - locations.yaml
   - model.yaml
   - techs.yaml

model.yaml:

##
# IMPORT OTHER FILES
##

# Can either be paths relative to this file, or absolute paths

import:
    - 'techs.yaml'
    - 'locations.yaml'

##
# MODEL NAME
##

name: "Test model"


##
# DATASET PATH
##

# Can either be a path relative to this file, or an absolute path

data_path: 'data'

##
# OBJECTIVE FUNCTION
##

# 'constraints.objective.objective_cost_minimization' is used by default
# objective:

##
# ADDITIONAL CONSTRAINTS
##

constraints:
    - constraints.optional.ramping_rate

##
# OTHER MODEL-WIDE OPTIONS
##

system_margin:
    power: 0
    heat: 0

techs.yaml:

##
# TECHNOLOGY DEFINITIONS
##

techs:

    ##
    # Supply
    ##
    ccgt:
        name: 'Combined cycle gas turbine'
        color: '#FDC97D'
        stack_weight: 200
        parent: supply
        carrier_out: power
        constraints:
            r: inf
            e_eff: 0.5
            e_cap.max: 40000  # kW
        costs:
            monetary:
                e_cap: 750  # USD per kW
                om_fuel: 0.02  # USD per kWh
    csp:
        name: 'Concentrating solar power'
        color: '#99CB48'
        stack_weight: 100
        parent: supply_plus
        carrier_out: power
        constraints:
            use_s_time: true
            s_time.max: 24
            s_loss: 0.002
            r: file  # Will look for `csp_r.csv` in data directory
            e_eff: 0.4
            p_eff: 0.9
            r_area.max: inf
            e_cap.max: 10000
        costs:
            monetary:
                s_cap: 50
                r_area: 200
                r_cap: 200
                e_cap: 1000
                om_var: 0.002
        depreciation:
            monetary:
                interest: 0.12

    ##
    # Storage
    ##
    battery:
        name: 'Battery storage'
        color: '#DC5CE5'
        parent: storage
        carrier: power
        constraints:
            e_cap.max: 1000  # kW
            s_cap.max: inf
            c_rate: 4
            e_eff: 0.95  # 0.95 * 0.95 = 0.9025 round trip efficiency
            s_loss: 0  # No loss over time assumed
        costs:
            monetary:
                s_cap: 200  # USD per kWh storage capacity
    ##
    # Demand
    ##
    demand_power:
        name: 'Power demand'
        parent: demand
        carrier: power
    unmet_demand_power:
        name: 'Unmet power demand'
        parent: unmet_demand
        carrier: power

    ##
    # Transmission
    ##
    ac_transmission:
        name: 'AC power transmission'
        parent: transmission
        carrier: power
        constraints:
            e_eff: 0.85
        costs:
            monetary:
                e_cap: 200
                om_var: 0.002

locations.yaml:

##
# LOCATIONS
##

locations:
    region1:
        techs: ['demand_power', 'unmet_demand_power', 'ccgt']
        override:
            demand_power:
                x_map: 'region1: demand'
                constraints:
                    r: file=demand-1.csv
                    r_scale_to_peak: -40000
            ccgt:
                constraints:
                    e_cap.max: 30000 # increased to ensure no unmet_demand in first timestep

    region2:
        techs: ['demand_power', 'unmet_demand_power', 'battery']
        override:
            demand_power:
                x_map: 'region2: demand'
                constraints:
                    r: file=demand-2.csv
                    r_scale_to_peak: -5000

    region1-1,region1-2,region1-3:
        within: region1
        techs: ['csp']

##
# TRANSMISSION CAPACITIES
##

links:
    region1,region2:
        ac_transmission:
            constraints:
                e_cap.max: 10000



##
# METADATA
##

metadata:
    # map boundary defined by the lower left and upper right of the square
    map_boundary:
        lower_left:
            lat: 35
            lon: -10
        upper_right:
            lat: 45
            lon: 5

    location_coordinates:  # lat, lon coordinates in a dictionary
        region1: {lat: 40, lon: -2}
        region2: {lat: 40, lon: -8}
        region1-1: {lat: 41, lon: -2}
        region1-2: {lat: 39, lon: -1}
        region1-3: {lat: 39, lon: -2}

Run settings

run.yaml:

##
# RUN SETTINGS
##

name: "Test run"  # Run name -- distinct from model name!

model: 'model_config/model.yaml'

output:  # Only used if run via the 'calliope run' command-line tool
    format: csv  # Choices: netcdf, csv
    path: 'Output'  # Will be created if it doesn't exist

mode: plan  # Choices: plan, operate

solver: glpk

##
# PARALLEL RUN SETTINGS
##

# Ignored unless run via the 'calliope generate' tool

parallel:
    name: example-model-national
    environment: bsub  # Choices: bsub, qsub
    pre_run:  # Commands to run before executing model
    post_run:  # Commands to run after executing model
    iterations:
        - subset_t: ['2005-01-01', '2005-01-31']
          override.locations.r1.techs: ['demand', 'unmet_demand', 'ccgt']
        - subset_t: ['2005-02-01', '2005-02-31']
          override.locations.r1.techs: ['demand', 'unmet_demand']
    resources:  # Request resources on a computing cluster
        threads:  # Non-default number of threads
        wall_time:  # Run time (minutes)
        memory:  # Working memory (MB)

##
# TIME RESOLUTION ADJUSTMENT
##

# time:
#     resolution: 6  # Reduce rest of data to 6-hourly timesteps
#     masks:  # Look for week where CSP output is minimal
#         - function: mask_extreme_week
#           options: {what: min, tech: csp}
#

##
# SUBSETS
##

# Leave any of these empty to disable subsetting

subset_y: []  # Subset of technologies
subset_x: []  # Subset of locations
subset_t: ['2005-01-01', '2005-01-05']  # Subset of timesteps

##
# MODEL SETTINGS OVERRIDE
##

# Override anything in the model configuration

override:

##
# DEBUG OPTIONS
##

debug:
    keep_temp_files: false  # Keep temporary files
    symbolic_solver_labels: false # Use human-readable component labels? (slower)

Urban-scale example

Available as calliope.examples.UrbanScale.

Model settings

model.yaml:

##
# IMPORT OTHER FILES
##

# Can either be paths relative to this file, or absolute paths

import:
    - 'techs.yaml'
    - 'locations.yaml'

##
# MODEL NAME
##

name: "Urban scale example model"


##
# DATASET PATH
##

# Can either be a path relative to this file, or an absolute path

data_path: 'data'

##
# OBJECTIVE FUNCTION
##

# 'constraints.objective.objective_cost_minimization' is used by default
# objective:

##
# ADDITIONAL CONSTRAINTS
##

constraints:
    - constraints.optional.max_r_area_per_loc

# OTHER MODEL-WIDE OPTIONS
##

system_margin:
    power: 0
    heat: 0
    cooling: 0

techs.yaml:

##
# TECHNOLOGY DEFINITIONS
##

techs:

##-GRID SUPPLY-##

    supply_grid_power:
        color: '#92c6ff'
        name: 'National grid import'
        parent: supply
        carrier: power
        constraints:
            r: inf
            e_cap.max: 2000
        costs:
            monetary:
                e_cap: 15
                om_fuel: 0.1 # 10p/kWh electricity price #ppt

    supply_gas:
        color: '#97f0aa'
        name: 'Natural gas import'
        parent: supply
        carrier: gas
        constraints:
            r: inf
            e_cap.max: 2000
        costs:
            monetary:
                e_cap: 1
                om_fuel: 0.025 # 2.5p/kWh gas price #ppt

##-Renewables-##

    pv:
        name: 'Solar photovoltaic power'
        color: '#fffea3'
        stack_weight: 100
        parent: supply_plus
        export: true
        carrier_out: power
        constraints:
            r: file  # Will look for `pv_r.csv` in data directory - already accounted for panel efficiency - kWh/m2. Source: Renewables.ninja Solar PV Power - Version: 1.1 - License: https://creativecommons.org/licenses/by-nc/4.0/ - Reference: https://doi.org/10.1016/j.energy.2016.08.060
            p_eff: 0.85 # inverter losses
            e_cap.max: 250
            r_area.max: 1500
            force_r: true
            r_area_per_e_cap: 7 # 7m2 of panels needed to fit 1kWp of panels
        costs:
            monetary:
                e_cap: 1350
# Conversion

    boiler:
        color: '#ff9f9a'
        name: 'Natural gas boiler'
        stack_weight: 100
        parent: conversion
        carrier_out: heat
        carrier_in: gas
        constraints:
            e_cap.max: 600
            e_eff: 0.85

# Conversion_plus

    chp:
        color: '#d0bbff'
        name: 'Combined heat and power'
        stack_weight: 100
        parent: conversion_plus
        export: true
        primary_carrier: power
        carrier_in: gas
        carrier_out: power
        carrier_out_2:
            heat: 0.8
        constraints:
            e_cap.max: 1500
            e_eff: 0.405
        costs:
            monetary:
                e_cap: 750
                om_var: 0.004 # .4p/kWh for 4500 operating hours/year
                export: file=export_power.csv

##-DEMAND-##

    demand_power:
        color: '#b0e0e6'
        name: 'Electrical demand'
        parent: demand
        carrier: power

    unmet_demand_power:
        name: 'Unmet electrical demand'
        parent: unmet_demand
        carrier: power

    demand_heat:
        color: '#ff9f9a'
        name: 'Heat demand'
        parent: demand
        carrier: heat

    unmet_demand_heat:
        name: 'Unmet heat demand'
        parent: unmet_demand
        carrier: heat

##-DISTRIBUTION-##

    power_lines:
        color: '#d0bbff'
        name: 'Electrical power distribution'
        parent: transmission
        carrier: power
        constraints:
            e_cap.max: 2000
            e_eff: 0.98
        costs_per_distance:
            monetary:
                e_cap: 80

    heat_pipes:
        color: '#ff9f9a'
        name: 'District heat distribution'
        parent: transmission
        carrier: heat
        constraints:
            e_cap.max: 2000
        constraints_per_distance:
            e_loss: 0.025
        costs_per_distance:
            monetary:
                e_cap: 500

locations.yaml:

##
# LOCATIONS
##

locations:
    X1:
        techs: ['chp', 'pv',
         'supply_grid_power', 'supply_gas',
         'demand_power', 'demand_heat',
         'unmet_demand_power', 'unmet_demand_heat']
        available_area: 500
        override:
            demand_power.constraints.r: file=demand_power.csv
            demand_heat.constraints.r: file=demand_heat.csv
            supply_grid_power.costs.monetary.e_cap: 100 # cost of transformers

    X2:
        techs: ['boiler', 'pv',
         'supply_gas',
         'demand_power', 'demand_heat',
         'unmet_demand_power', 'unmet_demand_heat'
         ]
        available_area: 1300
        override:
            demand_power.constraints.r: file=demand_power.csv
            demand_heat.constraints.r: file=demand_heat.csv
            boiler.costs.monetary.e_cap: 43.1 # different boiler costs
            pv.costs.monetary:
                        om_var: -0.0203 # revenue for just producing electricity
                        export: -0.0491 # FIT return for PV export

    X3:
        techs: ['boiler', 'pv',
         'supply_gas',
         'demand_power', 'demand_heat',
         'unmet_demand_power', 'unmet_demand_heat'
         ]
        available_area: 900
        override:
            demand_power.constraints.r: file=demand_power.csv
            demand_heat.constraints.r: file=demand_heat.csv
            boiler.costs.monetary.e_cap: 78 # different boiler costs
            pv:
                constraints:
                    e_cap.max: 50 # changing tariff structure below 50kW
                costs.monetary:
                        om_fixed: -80.5 # reimbursement per kWp from FIT


    N1: # location for branching heat transmission network
        techs: ['heat_pipes']

links:
    X1,X2:
        power_lines:
            distance: 10
    X1,X3:
        power_lines:
            constraints: # nothing to define, but model requires a key at this level of nesting
    X1,N1:
        heat_pipes:
            constraints: # nothing to define, but model requires a key at this level of nesting
    N1,X2:
        heat_pipes:
            constraints: # nothing to define, but model requires a key at this level of nesting
    N1,X3:
        heat_pipes:
            constraints: # nothing to define, but model requires a key at this level of nesting

metadata:
    # metadata given in cartesian coordinates, not lat, lon.
    map_boundary:
        lower_left:
            x: 0
            y: 0
        upper_right:
            x: 1
            y: 1
    location_coordinates:
        X1: {x: 2, y: 7}
        X2: {x: 8, y: 7}
        X3: {x: 5, y: 3}
        N1: {x: 5, y: 7}

Run settings

run.yaml:

##
# RUN SETTINGS
##

name: "Test run"  # Run name -- distinct from model name!

model: 'model_config/model.yaml'

output:  # Only used if run via the 'calliope run' command-line tool
    format: csv  # Choices: netcdf, csv
    path: 'Output'  # Will be created if it doesn't exist

mode: plan  # Choices: plan, operate

solver: glpk

##
# TIME RESOLUTION ADJUSTMENT
##

# time:
#     resolution: 6  # Reduce rest of data to 6-hourly timesteps
#     masks:  # Look for week where CSP output is minimal
#         - function: mask_extreme_week
#           options: {what: min, tech: csp}
#

##
# SUBSETS
##

# Leave any of these empty to disable subsetting

subset_y: []  # Subset of technologies
subset_x: []  # Subset of locations
subset_t: ['2005-07-01', '2005-07-02']  # Subset of timesteps

##
# MODEL SETTINGS OVERRIDE
##

# Override anything in the model configuration

override:

##
# DEBUG OPTIONS
##

debug:
    keep_temp_files: false  # Keep temporary files
    symbolic_solver_labels: false # Use human-readable component labels? (slower)

Mixed Integer Linear Programming (MILP) example

Available as calliope.examples.MILP.

This example is based on the Urban scale example, calling a different run configuration which includes the necessary overrides for MILP functionality.

Model settings

model.yaml:

##
# IMPORT OTHER FILES
##

# Can either be paths relative to this file, or absolute paths

import:
    - 'techs.yaml'
    - 'locations.yaml'

##
# MODEL NAME
##

name: "Urban scale example model"


##
# DATASET PATH
##

# Can either be a path relative to this file, or an absolute path

data_path: 'data'

##
# OBJECTIVE FUNCTION
##

# 'constraints.objective.objective_cost_minimization' is used by default
# objective:

##
# ADDITIONAL CONSTRAINTS
##

constraints:
    - constraints.optional.max_r_area_per_loc

# OTHER MODEL-WIDE OPTIONS
##

system_margin:
    power: 0
    heat: 0
    cooling: 0

techs.yaml:

##
# TECHNOLOGY DEFINITIONS
##

techs:

##-GRID SUPPLY-##

    supply_grid_power:
        color: '#92c6ff'
        name: 'National grid import'
        parent: supply
        carrier: power
        constraints:
            r: inf
            e_cap.max: 2000
        costs:
            monetary:
                e_cap: 15
                om_fuel: 0.1 # 10p/kWh electricity price #ppt

    supply_gas:
        color: '#97f0aa'
        name: 'Natural gas import'
        parent: supply
        carrier: gas
        constraints:
            r: inf
            e_cap.max: 2000
        costs:
            monetary:
                e_cap: 1
                om_fuel: 0.025 # 2.5p/kWh gas price #ppt

##-Renewables-##

    pv:
        name: 'Solar photovoltaic power'
        color: '#fffea3'
        stack_weight: 100
        parent: supply_plus
        export: true
        carrier_out: power
        constraints:
            r: file  # Will look for `pv_r.csv` in data directory - already accounted for panel efficiency - kWh/m2. Source: Renewables.ninja Solar PV Power - Version: 1.1 - License: https://creativecommons.org/licenses/by-nc/4.0/ - Reference: https://doi.org/10.1016/j.energy.2016.08.060
            p_eff: 0.85 # inverter losses
            e_cap.max: 250
            r_area.max: 1500
            force_r: true
            r_area_per_e_cap: 7 # 7m2 of panels needed to fit 1kWp of panels
        costs:
            monetary:
                e_cap: 1350
# Conversion

    boiler:
        color: '#ff9f9a'
        name: 'Natural gas boiler'
        stack_weight: 100
        parent: conversion
        carrier_out: heat
        carrier_in: gas
        constraints:
            e_cap.max: 600
            e_eff: 0.85

# Conversion_plus

    chp:
        color: '#d0bbff'
        name: 'Combined heat and power'
        stack_weight: 100
        parent: conversion_plus
        export: true
        primary_carrier: power
        carrier_in: gas
        carrier_out: power
        carrier_out_2:
            heat: 0.8
        constraints:
            e_cap.max: 1500
            e_eff: 0.405
        costs:
            monetary:
                e_cap: 750
                om_var: 0.004 # .4p/kWh for 4500 operating hours/year
                export: file=export_power.csv

##-DEMAND-##

    demand_power:
        color: '#b0e0e6'
        name: 'Electrical demand'
        parent: demand
        carrier: power

    unmet_demand_power:
        name: 'Unmet electrical demand'
        parent: unmet_demand
        carrier: power

    demand_heat:
        color: '#ff9f9a'
        name: 'Heat demand'
        parent: demand
        carrier: heat

    unmet_demand_heat:
        name: 'Unmet heat demand'
        parent: unmet_demand
        carrier: heat

##-DISTRIBUTION-##

    power_lines:
        color: '#d0bbff'
        name: 'Electrical power distribution'
        parent: transmission
        carrier: power
        constraints:
            e_cap.max: 2000
            e_eff: 0.98
        costs_per_distance:
            monetary:
                e_cap: 80

    heat_pipes:
        color: '#ff9f9a'
        name: 'District heat distribution'
        parent: transmission
        carrier: heat
        constraints:
            e_cap.max: 2000
        constraints_per_distance:
            e_loss: 0.025
        costs_per_distance:
            monetary:
                e_cap: 500

locations.yaml:

##
# LOCATIONS
##

locations:
    X1:
        techs: ['chp', 'pv',
         'supply_grid_power', 'supply_gas',
         'demand_power', 'demand_heat',
         'unmet_demand_power', 'unmet_demand_heat']
        available_area: 500
        override:
            demand_power.constraints.r: file=demand_power.csv
            demand_heat.constraints.r: file=demand_heat.csv
            supply_grid_power.costs.monetary.e_cap: 100 # cost of transformers

    X2:
        techs: ['boiler', 'pv',
         'supply_gas',
         'demand_power', 'demand_heat',
         'unmet_demand_power', 'unmet_demand_heat'
         ]
        available_area: 1300
        override:
            demand_power.constraints.r: file=demand_power.csv
            demand_heat.constraints.r: file=demand_heat.csv
            boiler.costs.monetary.e_cap: 43.1 # different boiler costs
            pv.costs.monetary:
                        om_var: -0.0203 # revenue for just producing electricity
                        export: -0.0491 # FIT return for PV export

    X3:
        techs: ['boiler', 'pv',
         'supply_gas',
         'demand_power', 'demand_heat',
         'unmet_demand_power', 'unmet_demand_heat'
         ]
        available_area: 900
        override:
            demand_power.constraints.r: file=demand_power.csv
            demand_heat.constraints.r: file=demand_heat.csv
            boiler.costs.monetary.e_cap: 78 # different boiler costs
            pv:
                constraints:
                    e_cap.max: 50 # changing tariff structure below 50kW
                costs.monetary:
                        om_fixed: -80.5 # reimbursement per kWp from FIT


    N1: # location for branching heat transmission network
        techs: ['heat_pipes']

links:
    X1,X2:
        power_lines:
            distance: 10
    X1,X3:
        power_lines:
            constraints: # nothing to define, but model requires a key at this level of nesting
    X1,N1:
        heat_pipes:
            constraints: # nothing to define, but model requires a key at this level of nesting
    N1,X2:
        heat_pipes:
            constraints: # nothing to define, but model requires a key at this level of nesting
    N1,X3:
        heat_pipes:
            constraints: # nothing to define, but model requires a key at this level of nesting

metadata:
    # metadata given in cartesian coordinates, not lat, lon.
    map_boundary:
        lower_left:
            x: 0
            y: 0
        upper_right:
            x: 1
            y: 1
    location_coordinates:
        X1: {x: 2, y: 7}
        X2: {x: 8, y: 7}
        X3: {x: 5, y: 3}
        N1: {x: 5, y: 7}

Run settings

run.yaml:

##
# RUN SETTINGS
##

name: "Test run"  # Run name -- distinct from model name!

model: 'model_config/model.yaml'

output:  # Only used if run via the 'calliope run' command-line tool
    format: csv  # Choices: netcdf, csv
    path: 'Output'  # Will be created if it doesn't exist

mode: plan  # Choices: plan, operate

solver: glpk

##
# TIME RESOLUTION ADJUSTMENT
##

# time:
#     resolution: 6  # Reduce rest of data to 6-hourly timesteps
#     masks:  # Look for week where CSP output is minimal
#         - function: mask_extreme_week
#           options: {what: min, tech: csp}
#

##
# SUBSETS
##

# Leave any of these empty to disable subsetting

subset_y: []  # Subset of technologies
subset_x: []  # Subset of locations
subset_t: ['2005-07-01', '2005-07-02']  # Subset of timesteps

##
# MODEL SETTINGS OVERRIDE
##

# Override anything in the model configuration

override:
    techs:
        chp:
            constraints:
                units.max: 4
                e_cap_per_unit: 100
                e_cap_min_use: 0.2
            costs:
                monetary:
                    e_cap: 700
                    purchase: 10000
        boiler:
            costs:
                monetary:
                    e_cap: 35
                    purchase: 2000


##
# DEBUG OPTIONS
##

debug:
    keep_temp_files: false  # Keep temporary files
    symbolic_solver_labels: false # Use human-readable component labels? (slower)

Previous: Configuration reference | Next: Development guide