Configuration

PyPSA-Earth imports the configuration options originally developed in PyPSA-Eur and here reported and adapted. The options here described are collected in a config.yaml file located in the root directory. Users should copy the provided default configuration (config.default.yaml) and amend their own modifications and assumptions in the user-specific configuration file (config.yaml); confer installation instructions at installation.

Credits to PyPSA-Eur developers for the initial drafting of the configuration documentation here reported

Keeping your config up to date

PyPSA-Earth loads config.default.yaml first and then merges your config.yaml on top (see the configfile entries in the Snakefile). You therefore only need to list settings in config.yaml that differ from the defaults—a small override file is enough for most studies.

When you upgrade to a new version, open the updated config.default.yaml and check what changed: new keys, renamed paths, or reorganised sections. Compare it with your config.yaml and copy across any new defaults you want to use, or move keys you still override to their new locations. The release notes summarise breaking config changes per release.

Some deprecated key names are migrated automatically when the workflow starts; if Snakemake prints a FutureWarning about an old path, update your config.yaml to the new key and remove the obsolete one. See Renamed keys for the full mapping. For study-specific settings you can also pass extra files with snakemake --configfile my_study.yaml instead of growing a single config.yaml.

Renamed keys

The table below lists all keys that have been renamed or moved. The old keys still work (their values are copied to the new location), but you should update your config.yaml to avoid future breakage.

Old key (deprecated)	New key
electricity.co2limit	co2.limit
electricity.co2base	co2.base
electricity.automatic_emission	co2.automatic_emission.enable
electricity.automatic_emission_base_year	co2.automatic_emission.base_year
costs.emission_prices.co2	co2.emission_price
co2_budget.enable	co2.budget.enable
co2_budget.override_co2opt	co2.budget.override_co2opt
co2_budget.year	co2.budget.year
co2_budget.co2base_value	co2.budget.base_value
sector.solar_thermal (bool flag)	sector.solar_thermal_collector.enable
sector.solar_cf_correction	sector.solar_thermal_collector.cf_correction
solar_thermal.clearsky_model	sector.solar_thermal_collector.clearsky_model
solar_thermal.orientation	sector.solar_thermal_collector.orientation
clean_osm_data_options	osm.clean_osm_data
build_osm_network	osm.build_osm_network
cluster_options	clustering
fossil_reserves.{carrier}	sector.{carrier}.reserves

{carrier} is the fuel name (e.g. oil, coal, gas, lignite, biomass). Migrations run automatically via migrate_config in scripts/_helpers.py; see also the release notes when upgrading.

Top-level configuration

Version, tutorial mode, logging, and optional custom Snakemake rules (# META banner in config.default.yaml).

version: 0.8.0
tutorial: false

logging:
  level: INFO
  format: "%(levelname)s:%(name)s:%(message)s"

custom_rules: [] # paths to additional .smk files included in the Snakefile

Parameter	Unit	Values	Description
version	--	0.x.x	Version of PyPSA-Earth.
tutorial	bool	{true, false}	Use the tutorial dataset instead of the full dataset.
logging	nan	nan	nan
-- level	--	{INFO, WARNING, ERROR}	Console log level.
-- format	--	nan	Log message format; see Python LogRecord attributes.
custom_rules	list	[] or ["path/to/rules.smk"]	Additional Snakemake rule files to include in the workflow.

Study setup

Options under the STUDY SETUP banner in config.default.yaml: region, run namespacing, scenario wildcards, model time range, and output directories.

Region and foresight mode.

countries: ["NG", "BJ"] # ISO codes, continent, or custom region

foresight: overnight # "myopic" or "overnight"

Parameter	Unit	Values	Description
countries	--	ISO 3166-1 alpha-2 codes, continent name, or custom region	Countries or regions included in the model.
foresight	--	{overnight, myopic}	Optimization foresight mode.

run

It is common conduct to analyse energy system optimisation models for multiple scenarios for a variety of reasons, e.g. assessing their sensitivity towards changing the temporal and/or geographical resolution or investigating how investment changes as more ambitious greenhouse-gas emission reduction targets are applied.

The run section is used for running and storing scenarios with different configurations which are not covered by wildcards. It determines the path at which resources, networks and results are stored. Therefore the user can run different configurations within the same directory. If a run with a non-empty name should use cutouts shared across runs, set shared_cutouts to true.

run:
  name: "" # optional; stores intermediate files in a subfolder (e.g. "KZ" → resources/KZ/, results/KZ/); empty = no subfolder
  sector_name: "" # optional; sector-coupling only — subfolder under results_dir/
  shared_cutouts: true # true: cutouts/ shared across runs; false: cutouts/{name}/ per run
  allow_scenario_failure: false # If True, the workflow will continue even if a scenario in run_scenario fails

Parameter	Unit	Values	Description
name	string	nan	Run label; prefixes resources/ and results/ paths when non-empty.
sector_name	string	nan	Sector scenario label; subfolder under results_dir and summary_dir.
shared_cutouts	bool	{true, false}	If true, cutout files are stored at cutouts/{cutout}.nc and shared across named runs. If false and run.name is set, cutouts are stored under cutouts/{run.name}/ instead (applies to retrieve_cutout and build_cutout).
allow_scenario_failure	bool	{true, false}	Continue the workflow if a scenario in run_scenario fails.

scenario

The scenario section is an extraordinary section of the config file that is strongly connected to the wildcards and is designed to facilitate running multiple scenarios through a single command

snakemake -j 1 solve_all_networks

For each wildcard, a list of values is provided. The rule solve_all_networks will trigger the rules for creating results/networks/elec_s{simpl}_{clusters}_ec_l{ll}_{opts}.nc for all combinations of the provided wildcard values as defined by Python's itertools.product(...) function that snakemake's expand(...) function uses.

An exemplary dependency graph (starting from the simplification rules) then looks like this:

scenario:
  simpl: [""]
  ll: ["copt"]
  clusters: [10]
  opts: [Co2L-3h] # hyphen-joined options: 3h/6h/24h/Nseg temporal | Co2L/Ep/CH4L caps & prices | ATK/ATKc autarky | {carrier}+p/c/m scale | CCL/BAU/SAFE/RES/EQ solve constraints — see doc/user-guide/wildcards.md
  planning_horizons: # investment years for myopic; costs year for overnight
  - 2030
  sopts:
  - "144h"
  demand:
  - "AB"

Parameter	Unit	Values	Description
simpl	--	cf. wildcards	{simpl} pre-clustering wildcard in simplify_network: empty skips optional bus reduction; integer clusters to that many buses before cluster_network.
ll	--	cf. wildcards	{ll} transmission expansion wildcard in prepare_network ({c\|v\|l}{opt\|float}): c = cap on total transmission expansion cost, v = cap on total line volume (length-weighted capacity), l = cap each line/link at factor × existing capacity; suffix opt enables cost-optimal expansion without a global cap (e.g. copt).
clusters	--	cf. wildcards	{clusters} spatial wildcard in cluster_network: integer bus target; suffix m move-only or flex cap at available buses; all or min for special modes.
opts	--	cf. wildcards	{opts} option wildcard (combine with -): Co2L applies annual CO2 cap from co2.limit (default run is emission-constrained); temporal/gas limits in prepare_network; CCL/EQ/BAU/SAFE in solve_network; see opts.csv.
planning_horizons	--	list of years	{planning_horizons} year wildcard: investment year in prepare_sector_network; brownfield grouping and myopic sequencing in solve_network; costs year for overnight sector runs.
sopts	--	cf. wildcards	{sopts} sector-only wildcard in prepare_sector_network: same role as nH in {opts} (e.g. 144h resamples snapshots via average_every_nhours).
demand	--	cf. wildcards	{demand} sector-only wildcard: labels sector demand inputs (energy totals transport industry shares) in resource file paths.

snapshots

Specifies the temporal range for the historical weather data, which is used to build the energy system model. It uses arguments to pandas.date_range. The date range must be in the past (before 2022). A well-tested year is 2013.

snapshots:
  start: "2013-01-01"
  end: "2014-01-01"
  inclusive: "left" # end is not inclusive

Parameter	Unit	Values	Description
start	--	YYYY-MM-DD	Start of the model time range; must be in the past.
end	--	YYYY-MM-DD	End of the model time range; must be in the past.
inclusive	--	{left, right, both, neither}	Bounds inclusion for pandas.date_range; default left means end is not inclusive.

Output directories

Default paths for solved networks, summaries, and plots. Top-level keys at the end of the study setup block in config.default.yaml (not nested under run). Rarely changed in day-to-day runs.

results_dir: results/ # solved networks and sector postprocessing (RESDIR in Snakefile)
summary_dir: results/ # summaries, plots, and copied configs (SDIR in Snakefile)

Parameter	Unit	Values	Description
results_dir	--	path	Base directory for solved networks and sector postprocessing (RESDIR in Snakefile).
summary_dir	--	path	Base directory for summary CSVs plots and copied configs (SDIR in Snakefile).

Data retrieval

Switches in enable for downloading databundles, OSM data, cutouts, and building inputs locally. Set most retrieve flags to true for the first run.

enable:
  # ----------------- Retrieving data -----------------
  retrieve_databundle: true # recommended for first run
  download_osm_data: true # download OpenStreetMap data for the countries specified above
  retrieve_cutout: true # retrieves the bundled 2013 cutout (cutout-2013-era5); changing load_options.weather_year (default: 2013) requires retrieve_cutout:false and build_cutout: true.
  retrieve_cost_data: true # false: use existing data/costs.csv
  retrieve_databundle_sector: true
  download_global_buildings: false # download GlobalMLBuildingFootprints data for the countries specified above
  # ----------------- Building locally -----------------
  build_cutout: false # requires CDS API key (see https://cds.climate.copernicus.eu/how-to-api); uses snapshots and countries
  build_natura_raster: false
  # ----------------- Advanced -----------------
  progress_bar: true
  custom_busmap: false # optional override for cluster_network busmap

Parameter	Unit	Values	Description
enable	nan	nan	nan
-- retrieve_databundle	bool	{true, false}	Retrieve databundle from Zenodo via retrieve_databundle_light; recommended for the first run.
-- download_osm_data	bool	{true, false}	Download OpenStreetMap data for countries.
-- retrieve_cutout	bool	{true, false}	Retrieve cutout databundle via retrieve_databundle_light.
-- retrieve_cost_data	bool	{true, false}	Retrieve cost data from technology-data into resources/costs.csv; false uses data/costs.csv.
-- retrieve_databundle_sector	bool	{true, false}	Retrieve sector databundle.
-- download_global_buildings	bool	{true, false}	Download GlobalMLBuildingFootprints for countries.
-- build_cutout	bool	{true, false}	Build cutouts via build_cutout; requires CDS API key and uses snapshots and countries.
-- build_natura_raster	bool	{true, false}	Build exclusion raster natura.tiff via build_natura_raster.
-- progress_bar	bool	{true, false}	Show progress bars during long downloads and builds.
-- custom_busmap	bool	{true, false}	Use data/custom_busmap_elec_s{simpl}_{clusters}.csv instead of the clustering busmap algorithm.

Geography & shapes

Coordinate systems, regional shapes, subregions, land-cover exclusions, OpenStreetMap, clustering, and optional augmented connectivity (# GEOGRAPHY & SHAPES in config.default.yaml).

crs

Defines the coordinate reference systems (crs).

crs:
  geo_crs: EPSG:4326 # general geographic projection, not used for metric measures. "EPSG:4326" is the standard used by OSM and google maps
  distance_crs: EPSG:3857 # projection for distance measurements only. Possible recommended values are "EPSG:3857" (used by OSM and Google Maps)
  area_crs: ESRI:54009 # projection for area measurements only. Possible recommended values are Global Mollweide "ESRI:54009"

Parameter	Unit	Values	Description
geo_crs	nan	"General geographic projection. Not used for metric measures."	"Recommended value is ‘EPSG:4326’ (used by OSM and Google Maps)."
distance_crs	nan	"Projection for distance measurements only."	"Recommended value is ‘EPSG:3857’ (used by OSM and Google Maps)."
area_crs	nan	"Projection for area measurements only."	"Recommended value is the Global Mollweide projection ‘ESRI:54009’."

build_shape_options

Specifies the options to build the shapes in which the region of interest (countries) is divided.

build_shape_options:
  gadm_layer_id: 1 # GADM level area used for the gadm_shapes. Codes are country-dependent but roughly: 0: country, 1: region/county-like, 2: municipality-like
  year: 2020 # reference year used to derive shapes, info on population and info on GDP
  simplify_gadm: true # When true, shape polygons are simplified else no
  simplify_tolerance: 0.01 # Default value is 0.01, higher the value more is the simplification of the GADM shapes
  minarea: 0.01 # Minimum area of polygons to be retained in GADM shapes after simplification, in square degrees. Polygons with area smaller than this value will be removed
  contended_flag: "set_by_country" # "set_by_country" assigns the contended areas to the countries according to the GADM database, "drop" drops these contended areas from the model
  worldpop_method: "standard" # "standard" pulls from web 1kmx1km raster, "api" pulls from API 100mx100m raster,
  # false (not "false") no pop addition to shape which is useful when generating only cutout
  gdp_method: "standard" # "standard" pulls from web 1x1km raster, false (not "false") no gdp addition to shape which useful when generating only cutout
  update_file: false # When true, all the input files are downloaded again and replace the existing files
  nprocesses: 3 # number of processes to be used in build_shapes
  out_logging: true # When true, logging is printed to console

Parameter	Unit	Values	Description
gadm_layer_id	nan	{0,1,2}	GADM level area used for the gadm_shapes. Codes are country-dependent but roughly: 0: country,1: region/county-like, 2: municipality-like.
simplify_gadm	bool	{True, False}	True: shape polygons are simplified else no
simplify_tolerance	float	>= 0	Specifies tolerance limit when simplifying GADM shapes. A higher value indicates more simplification
minarea	float	>= 0	Minimum area of polygons to be retained after GADM simplification. If area is lower than minarea, then the shape is removed
update_file	bool	{True,False}	True: all input files are downloaded again and replace the existing files.
out_logging	bool	{True,False}	True: Logging is printed in the console.
year	nan	past year; e.g. YYYY	Reference year used to derive shapes, info on population and info on GDP.
nprocesses	int	nan	Number of processes to be used in build_shapes.
worldpop_method	nan	{standard,api,false}	Specifies how population is added to every shape: standard pulls from web 1kmx1km raster; api pulls from API 100mx100m raster; false (not false) no population addition to shape. This is useful when generating only cutout.
gdp_method	nan	{standard,false}	Specifies how GDP is added to every shape: standard pulls from web 1x1km raster; false (not false) no gdp addition to shape. This is useful when generating only cutout.
contended_flag	nan	{set_by_country,drop}	Specifies what to do with contended countries: set_by_country assigns the contended areas to the countries according to the GADM database; drop drops the contended areas from the model.

subregion

If enabled, this option allows a region of interest (countries) to be redefined into subregions, which can be activated at various stages of the workflow. Currently, it is used in simplify_network and cluster_network rule.

subregion:
  method: false # method to define subregions, either "gadm" or "custom", false to not use subregions.
  apply_on: ["simplify_network", "cluster_network"] # apply subregion on the simplify_network and/or cluster_network rule.
  define_by_gadm: false # name of the subregion. Multiple countries can be part in the same subregion.
  path_custom_shapes: false # provide the specific absolute path of the custom file e.g. (...\data\custom_shapes.geojson)
  path_custom_offshore: false # (optional) provide the specific absolute path of the custom offshore file e.g. (...\data\custom_offshore.geojson)
  tolerance: 100 # Buffer distance (in km) for assigning a country/subregion shape to a bus (the default tolerance is 100 km)

Parameter	Unit	Values	Description
method	nan	{gadm, custom , false}	"method to define subregions, either "gadm" or "custom", false to not use subregions".
apply_on	list	Any subset of	Enables subregion definitions in specific rules. simplify_network allows network simplification functions to drop or merge nodes based on subregions rather than just countries. cluster_network allows focus_weights to set clustering focus based on subregion names.
define_by_gadm	Str: list	{subregion_name}: [GADM IDs]	Used only when subregion: method: gadm. Specifies the names of subregions and its GADM IDs as a list
path_custom_shapes	-	path	Used only when subregion: method: custom. Specifies the subregion based on a custom shapes
path_custom_offshore	-	path	"(optional) Used only when subregion: method: custom. Specifies the offshore subregion based on a custom shapes. If not specified, offshore subregions are generated from the available subregion shapes."
tolerance	km	int	Buffer distance for assigning a country/subregion shape to a bus (the default tolerance is 100 km)

The names of subregions are arbitrary. Its sizes are determined by how many GADM IDs that are included in the list. A single country can be divided into multiple subregions, and a single subregion can include GADM IDs from multiple countries. If the same GADM ID appears in different subregions, the first subregion listed will take precedence over that region. The remaining GADM IDs that are not listed will be merged back to form the remaining parts of their respective countries. For example, consider the Central District of Botswana, which has a GADM ID of BW.3. To separate this district from the rest of the country, you can select:

See config.default.yaml for the full configuration.

There are several formats for GADM IDs depending on the version, so before using this feature, please review the resources/shapes/gadm_shape.geojson file which can be created using the command:

snakemake -j 1 build_shapes

Note

The rule build_shapes currently use Version 4.1 for their GADM data. This may change in the future.

natura

Land-cover exclusion raster settings. Only relevant when enable.build_natura_raster is true.

natura: # only relevant when using build_natura_raster: true
  natura_size: countries # countries, cutout, or global. Select which regions to include in the natura raster.
  natura_resolution: 100 # [m] Grid resolution of the natura data.
  window_size: 10000 # [bytes] Size of the shifting rasterization window. The required RAM scales with window_size^2.
  buffer_size: 10000 # [unit of area_crs, default: m] Buffer around the regions of interest to include every required value. A buffer of around 100 km will be sufficient for most cases.

Parameter	Unit	Values	Description
natura_size	string	{countries, cutout, global}	Select which regions to include in the natura raster. Either include all selected countries (counties), the entire cutout (cutout) or the entire globe (global).
natura_resolution	m	nan	Grid resolution of the natura output data in meters.
window_size	int	nan	Size of the shifting rasterization window in bytes. The required RAM scales with window_size^2
buffer_size	int	nan	Buffer around the regions of interest to include every required value in the unit of area_crs, default: m. A buffer of around 100 km will be sufficient for most cases.

osm

OpenStreetMap (OSM) pipeline settings live under the osm block: osm.clean_osm_data filters raw downloads; osm.build_osm_network merges buses and lines into the base-network CSV inputs. If your config still uses the old top-level names, see Renamed keys.

osm:
  clean_osm_data:
    threshold_voltage: 51000 # [V] minimum voltage threshold to keep the asset (cable, line, generator, etc.) [V]
    tag_substation: "transmission" # Filters only substations with 'transmission' tag, ('distribution' also available)
    names_by_shapes: true # Set the country name based on the extended country shapes
    add_line_endings: true # When "True", then line endings are added to the dataset of the substations
    generator_name_method: OSM # Methodology to specify the name to the generator. Options: OSM (name as by OSM dataset), closest_city (name by the closest city)
    use_custom_lines: "OSM_only" # Use OSM (OSM_only), customized (custom_only), both data sets (add_custom) or none (none)
    path_custom_lines: false # If exists, provide the specific absolute path of the custom file e.g. (...\data\custom_lines.geojson)
    use_custom_substations: "OSM_only" # Use OSM (OSM_only), customized (custom_only), both data sets (add_custom) or none (none)
    path_custom_substations: false # If exists, provide the specific absolute path of the custom file e.g. (...\data\custom_substations.geojson)
    use_custom_cables: "OSM_only" # Use OSM (OSM_only), customized (custom_only), both data sets (add_custom) or none (none)
    path_custom_cables: false # If exists, provide the specific absolute path of the custom file e.g. (...\data\custom_cables.geojson)

  build_osm_network: # Options of the build_osm_network script
    group_close_buses: true # When "True", close buses are merged and guarantee the voltage matching among line endings
    group_tolerance_buses: 5000 # [m] (default 5000) Tolerance in meters of the close buses to merge
    split_overpassing_lines: true # When True, lines overpassing buses are splitted and connected to the bueses
    overpassing_lines_tolerance: 1 # [m] (default 1) Tolerance to identify lines overpassing buses
    force_ac: false # When true, it forces all components (lines and substation) to be AC-only. To be used if DC assets create problem.

Parameter	Unit	Values	Description
clean_osm_data	nan	nan	Options passed to the clean_osm_data rule.
-- threshold_voltage	V	nan	Assets below the voltage threshold will not be considered (cable, line, generator, etc.).
-- tag_substation	nan	{transmission, distribution}	Filters only substations with the corresponding tag (transmission or distribution).
-- names_by_shapes	bool	{True, False}	True: the country name is set based on the extended country shapes.
-- add_line_endings	bool	{True, False}	True: line endings are added to the dataset of the substations.
-- generator_name_method	nan	{OSM, closest_city}	Methodology to specify the name of generators. From OpenStreetMap (OSM) or named after the closest city (closest_city).
-- use_custom_lines	nan	{OSM_only, custom_only, add_custom, none}	Method for selecting which type of data is used for lines in the clean_osm_data script.
-- path_custom_lines	nan	str	Path to custom line data when use_custom_lines is custom_only or add_custom.
-- use_custom_substations	nan	{OSM_only, custom_only, add_custom, none}	Method for selecting which type of data is used for substations in the clean_osm_data script.
-- path_custom_substations	nan	str	Path to custom substation data when use_custom_substations is custom_only or add_custom.
-- use_custom_cables	nan	{OSM_only, custom_only, add_custom, none}	Method for selecting which type of data is used for cables in the clean_osm_data script.
-- path_custom_cables	nan	str	Path to custom cable data when use_custom_cables is custom_only or add_custom.
build_osm_network	nan	nan	Options passed to the build_osm_network rule.
-- group_close_buses	bool	{True, False}	True: close buses are merged and guarantee the voltage matching among line endings.
-- group_tolerance_buses	m	nan	Tolerance in meters of the close buses to merge.
-- split_overpassing_lines	bool	{True, False}	True: lines overpassing buses are splitted and connected to the buses.
-- overpassing_lines_tolerance	m	nan	Tolerance to identify lines overpassing buses.
-- force_ac	bool	{True, False}	True: forces all components (lines and substation) to be AC-only. To be used if DC assets create problems.

clustering

Specifies the options to simplify and cluster the network. This is done in two stages, first using the rule simplify_network and then using the rule cluster_network. For more details on this process, see the PyPSA-Earth paper, section 3.7.

clustering:
  alternative_clustering: false # "False" use Voronoi shapes, "True" use GADM shapes
  distribute_cluster: ["load"] # Distributes cluster nodes per country according to ['load'],['pop'] or ['gdp']
  simplify_network:
    exclude_carriers: []
    remove_stubs: true
    remove_stubs_across_borders: false
    p_threshold_drop_isolated: 20 # [MW] isolated (sub)networks or nodes are being discarded if total mean power is below the specified threshold
    p_threshold_merge_isolated: 300 # [MW] isolated (sub)networks or nodes are being merged into a single isolated bus if total mean power is below the specified threshold
    s_threshold_fetch_isolated: false # [-] a share of the national load for merging an isolated network into a backbone network
    to_substations: false # network is simplified to nodes with positive or negative power injection (i.e. substations or offwind connections)
    algorithm: kmeans # choose from: [hac, kmeans]
    feature: solar+onwind-time # only for hac. choose from: [solar+onwind-time, solar+onwind-cap, solar-time, solar-cap, solar+offwind-cap] etc.
  cluster_network:
    exclude_carriers: []
    algorithm: kmeans
    feature: solar+onwind-time
  aggregation_strategies:
    generators: # use "min" for more conservative assumptions
      p_nom: sum
      p_nom_max: sum
      p_nom_min: sum
      p_min_pu: mean
      p_max_pu: weighted_average
      marginal_cost: mean
      committable: any
      ramp_limit_up: max
      ramp_limit_down: max
      efficiency: mean
      build_year: mean
      lifetime: mean
    one_ports: # storage units and loads
      StorageUnit:
        build_year: mean
        lifetime: mean
  focus_weights: false # false: use distribute_cluster; or {country_or_subregion: share} e.g. NG: 0.4 (shares must sum to <= 1)
  out_logging: true # When "True", logging is printed to console

Parameter	Unit	Values	Description
alternative_clustering	bool	{True, False}	False: use Voronoi shapes in the clustering. True: use GADM shapes in the clustering.
distribute_cluster	nan	{['load'], ['pop'], ['gdp']}	Distributes cluster nodes per country according to load (['load']), population (['pop']) or GDP (['gdp']).
simplify_network	nan	nan	nan
-- exclude_carriers	nan	List of Str like [ 'solar', 'onwind'] or empty list []	Carriers not considered in the simplify_network rule. Can be any set of carriers (conventional or renewable).
-- remove_stubs	bool	{True, False}	True: Stub lines and links, i.e. dead-ends of the network, are sequentially removed from the network.
-- remove_stubs_across_borders	bool	{True, False}	True: Stub lines and links can be removed across borders.
-- p_threshold_drop_isolated	MW	positive number	Isolated buses are discarded if bus mean power is below the p_threshold_drop_isolated.
-- p_threshold_merge_isolated	MW	positive number	Isolated buses are merged into a single isolated bus if bus mean power is below p_threshold_merge_isolated.
-- s_threshold_fetch_isolated	[-]	positive number	Isolated networks are merged into a backbone network of a respective country if the network load comprises a share of the national load less than p_threshold_fetch_isolated.
-- to_substations	bool	{True, False}	False: network is simplified to nodes with positive or negative power injection (i.e. substations or offwind connections).
-- algorithm	nan	{hac, kmeans, modularity}	Clustering algorithm used in the simplify_network rule. Options available are Hierarchical Agglomerative Clustering (HAC), k-means, or greedy modularity.
-- feature	nan	Str in the format ‘carrier1+carrier2+...+carrierN-X’, where CarrierI can be from {‘solar’, ‘onwind’, ‘offwind’, ‘ror’} and X is one of {‘cap’, ‘time’}. Examples: solar+offwind-cap, solar-time	Only for Hierarchical Agglomerative Clustering (HAC). Feature(s) used to do the clustering.
cluster_network	nan	nan	nan
-- exclude_carriers	nan	List of Str like [ 'solar', 'onwind'] or empty list []	Carriers not considered in the cluster_network rule. Can be any set of carriers (conventional or renewable).
-- algorithm	nan	{hac, kmeans}	Clustering algorithm used in the cluster_network rule. Options available are Hierarchical Agglomerative Clustering (HAC) or k-means.
-- feature	nan	Str in the format ‘carrier1+carrier2+...+carrierN-X’, where CarrierI can be from {‘solar’, ‘onwind’, ‘offwind’, ‘ror’} and X is one of {‘cap’, ‘time’}. Examples: solar+offwind-cap, solar-time	Only for Hierarchical Agglomerative Clustering (HAC). Feature(s) used to do the clustering.
aggregation_strategies	nan	nan	nan
-- generators	nan	nan	nan
-- -- p_nom	nan	{min, mean, max, sum}	Indicates how the p_nom of the aggregated generator is computed from the original p_nom values. For example, if sum, then all values within each cluster are summed to represent the new generator.
-- -- p_nom_max	nan	{min, mean, max, sum}	Indicates how the p_nom_max of the aggregated generator is computed from the original p_nom_max values.
-- -- p_nom_min	nan	{min, mean, max, sum}	Indicates how the p_nom_min of the aggregated generator is computed from the original p_nom_min values.
-- -- p_min_pu	nan	{min, mean, max, sum}	Indicates how the p_min_pu of the aggregated generator is computed from the original p_min_pu values.
-- -- p_max_pu	nan	{weighted_average, min, mean, max, sum}	Indicates how the p_max_pu of the aggregated generator is computed from the original p_max_pu values.
-- -- marginal_cost	nan	{min, mean, max, sum}	Indicates how the marginal_cost of the aggregated generator is computed from the original marginal_cost values.
-- -- committable	nan	{any}	Indicates how the commit status of the aggregated generator is set depending on the original values of the generators. Unit Commitment is currently under development, so should be left to any.
-- -- ramp_limit_up	nan	{min, mean, max, sum}	Indicates how the ramp_limit_up of the aggregated generator is computed from the original ramp_limit_up values.
-- -- ramp_limit_down	nan	{min, mean, max, sum}	Indicates how the ramp_limit_down of the aggregated generator is computed from the original ramp_limit_down values.
-- -- efficiency	nan	{min, mean, max, sum}	Indicates how the efficiency of the aggregated generator is computed from the original efficiency values.
-- -- build_year	nan	{min, mean, max, sum}	Indicates how the build_year of the aggregated generator is computed from the original build_year values.
-- -- lifetime	nan	{min, mean, max, sum}	Indicates how the lifetime of the aggregated generator is computed from the original lifetime values.
-- one_ports	nan	nan	nan
-- -- StorageUnit	nan	nan	nan
-- -- -- build_year	nan	{min, mean, max, sum}	Indicates how the build_year of the aggregated StorageUnit is computed from the original build_year values.
-- -- -- lifetime	nan	{min, mean, max, sum}	Indicates how the lifetime of the aggregated StorageUnit is computed from the original lifetime values.
focus_weights	nan	Dict consisting of {country: share} such as {NG: 0.4}	When specified, set the share of nodes allocated to each country. The sum of focus weights must be less than or equal to 1.
out_logging	bool	{True, False}	True: Logging is printed to the console.

augmented_line_connection

If enabled, it increases the connectivity of the network. It makes the network graph k-edge-connected, i.e., if fewer than k edges are removed, the network graph stays connected. It uses the k-edge-augmentation algorithm from the NetworkX Python package.

augmented_line_connection:
  add_to_snakefile: false # If True, includes this rule to the workflow
  connectivity_upgrade: 2 # Min. lines connection per node,
  # https://networkx.org/documentation/stable/reference/algorithms/generated/networkx.algorithms.connectivity.edge_augmentation.k_edge_augmentation.html#networkx.algorithms.connectivity.edge_augmentation.k_edge_augmentation
  new_line_type: ["HVAC"] # Expanded lines can be either ["HVAC"] or ["HVDC"] or both ["HVAC", "HVDC"]
  min_expansion: 1 # [MW] New created line expands by float/int input
  min_DC_length: 600 # [km] Minimum line length of DC line

Parameter	Unit	Values	Description
add_to_snakefile	bool	{True, False}	True: includes this rule to the workflow.
connectivity_upgrade	int	{1, 2, 3, ...}	Number k such that the network graph is k-edge-connected.
new_line_type	nan	{[HVAC], [HVDC], [HVAC, HVDC]}	Type of expanded lines.
min_expansion	int or float	nan	[MW] New created line capacity.
min_DC_length	int or float	nan	[km] Minimum line length of HVDC line.

Network & resources

Base network assembly, demand, electricity grid, weather and renewables, costs and emissions, and Monte Carlo settings (# NETWORK & RESOURCES in config.default.yaml).

base_network

Specifies the minimum voltage magnitude in the base network and the offshore substations.

base_network:
  min_voltage_substation_offshore: 51000 # [V] minimum voltage of the offshore substations
  min_voltage_rebase_voltage: 51000 # [V] minimum voltage in base network

Parameter	Unit	Values	Description
min_voltage_substation_offshore	V	nan	"Minimum voltage magnitude in offshore substations."
min_voltage_rebase_voltage	V	nan	"Minimum voltage magnitude in base network."

load_options

Specifies the options to estimate future electricity demand (load). Different years might be considered for weather and the socioeconomic pathway (GDP and population growth), to enhance modelling capabilities.

load_options:
  source: "gegis" # "gegis" (scenario-based: 2011, 2013, 2018 available) or "demcast" (hourly 2000–2024 available): view [issue #1724](https://github.com/pypsa-meets-earth/pypsa-earth/issues/1724) for more details
  weather_year: 2013 # Weather year of the load profile
  prediction_year: 2030 # Valid only if "gegis" used as a source
  scale: 1 # scales all load time-series, i.e. 2 = doubles load

Parameter	Unit	Values	Description
source	--	{gegis, demcast}	Load dataset provider. gegis: bundled GEGIS SSP2-2.6 scenario loads (2011, 2013, and 2018 are available); requires prediction_year; weather_year must match an available folder (2011, 2013, 2018, or a *_custom suffix for user data). demcast: DemandCast hourly parquet; weather_year may be 2000–2024; prediction_year is ignored. Comparison and download notes: issue #1724. Legacy value ssp is accepted with a deprecation warning (same as gegis).
weather_year	--	YYYY (past year)	Calendar year of the load time series. Must lie within the snapshots date range. Available years depend on source (see source row).
prediction_year	--	YYYY (past or future)	Future demand scenario year (GDP and population); used only when source is gegis. Selects the path segment under data/ssp2-2.6/<prediction_year>/.
scale	--	float or dict	Multiplier for all load time series (e.g. 2 doubles demand), or per-country factors via a dict with optional DEFAULT key.

The snapshots date range (snapshots\start - snapshots\end) must be in the weather_year.

electricity

Specifies the options for the rule add_electricity. This includes options across several features, including but not limited to: voltage levels, electricity carriers available, renewable capacity estimation, operational reserve, storage parameters. See the table below for more details.

electricity:
  # ----------------- Electricity generation -------------------
  extendable_carriers:
    Generator: [solar, onwind, offwind-ac, offwind-dc, OCGT] # Remove 'offwind-ac' and 'offwind-dc' for landlocked countries (e.g., Jordan, Austria, Switzerland)
    StorageUnit: [] # battery, H2
    Store: [battery, H2]
    Link: [] # H2 pipeline

  conventional_carriers: [nuclear, oil, OCGT, CCGT, coal, lignite, geothermal, biomass]
  renewable_carriers: [solar, onwind, offwind-ac, offwind-dc, hydro]

  max_hours: # Storage duration [h]: fill time at max power for extendable battery/H2 storage
    battery: 6
    H2: 168

  # ----------------- Existing powerplants -------------------
  powerplants_filter: (DateOut >= 2022 or DateOut != DateOut) and (DateIn <= 2023 or DateIn != DateIn)
  custom_powerplants: false #  "false" use only powerplantmatching (ppm) data, "merge" combines ppm and custom powerplants, "replace" use only custom powerplants

  estimate_renewable_capacities:
    stats: "irena" # False, = greenfield expansion, 'irena' uses IRENA stats to add expansion limits
    year: 2023 # Reference year, available years for IRENA stats are 2000 to 2023
    p_nom_min: 1 # any float, scales the minimum expansion acquired from stats, i.e. 110% of <years>'s capacities => p_nom_min: 1.1
    p_nom_max: false # sets the expansion constraint, False to deactivate this option and use estimated renewable potentials determine by the workflow, float scales the p_nom_min factor accordingly
    technology_mapping:
      # Wind is the Fueltype in ppm.data.Capacity_stats, onwind, offwind-{ac,dc} the carrier in PyPSA-Earth
      Offshore: [offwind-ac, offwind-dc]
      Onshore: [onwind]
      PV: [solar]

  # ----------------- Grid topology -------------------
  base_voltage: 380.
  voltages: [132., 220., 300., 380., 500., 750.]
  hvdc_as_lines: false # false: HVDC as Link; true: HVDC as Line

  # ----------------- Constraints & reserve -------------------
  agg_p_nom_limits: # enables to set country-wise maximum and minimum generation capacities for generators (e.g. renewables, nuclear, and geothermal)
    file: data/agg_p_nom_minmax.csv # path to csv file containing country-wise generation capacity limits
    include_existing: false # false: only new built capacities are constrained; true: existing capacities are accounted in the constraints

  operational_reserve: # like https://genxproject.github.io/GenX.jl/stable/Model_Reference/core/#Operational-Reserves
    activate: false
    epsilon_load: 0.02 # share of total load
    epsilon_vres: 0.02 # share of total renewable supply
    contingency: 0 # fixed capacity in MW

Parameter	Unit	Values	Description
extendable_carriers	nan	nan	nan
-- Generator	--	Any subset of renewable_carriers (except hydro) and/or conventional_carriers	Lists which generator carriers are capacity-expansion candidates in add_electricity. Renewables in this list (e.g. solar, onwind, offwind-ac, offwind-dc, csp) are added at all suitable buses with p_nom_extendable=True; conventional entries (e.g. OCGT, CCGT, coal, nuclear) are extendable only at buses with existing plants of that carrier. For landlocked countries, remove offwind-ac and offwind-dc.
-- StorageUnit	--	Any subset of	Adds extendable storage units (battery and/or hydrogen) at every node/bus after clustering without capacity limits and with zero initial capacity. It is used in the add_extra_components rule.
-- Store	--	Any subset of	Adds extendable storage units (battery and/or hydrogen) at every node/bus after clustering without capacity limits and with zero initial capacity.
-- Link	--	Any subset of	Adds extendable links (H2 pipelines only) at every connection where there are lines or HVDC links without capacity limits and with zero initial capacity. Hydrogen pipelines require hydrogen storage to be modelled as Store.
conventional_carriers	--	Any subset of	List of conventional power plants to include in the model from resources/powerplants.csv.
renewable_carriers	--	Any subset of	List of renewable power plants to include in the model from resources/powerplants.csv.
max_hours	nan	nan	Storage duration [h]: hours to fill empty storage at max power; sets e_nom = p_nom × max_hours for StorageUnit and scales combined storage costs in process_cost_data.
-- battery	hours	nan	Amount of time it takes to fully charge batteries from empty if done at maximum power rate. See PyPSA documentation. It is used in the rule add_extra_components.
-- H2	hours	nan	Amount of time it takes to fully charge hydrogen storage from empty if done at maximum power rate. See PyPSA documentation. It is used in the rule add_extra_components.
powerplants_filter	--	use pandas.query strings here, e.g. Country not in ['Germany']	Filter query for the default powerplant database.
custom_powerplants	--	{false, merge, replace}	Adds custom powerplants from custom_powerplants.csv: false - use only powerplantmatching (ppm) data, merge - combines ppm and custom powerplants, replace - use only custom powerplants.
estimate_renewable_capacities	nan	nan	Initial renewable capacity floors from existing plants in powerplants.csv and optional IRENA national targets (see add_electricity).
-- stats	nan	{irena or False}	Defines which database to use, currently only irena is available. irena uses IRENA stats to add expansion limits. False enables greenfield expansion.
-- year	nan	Any year between 2000 and 2023	Reference year for renewable capacities. Available years for IRENA stats are from 2000 to 2023.
-- p_nom_min	nan	float	Scales the minimum expansion acquired from stats. For example, 110% of 's capacities is obtained with p_nom_min: 1.1.
-- p_nom_max	nan	float or False	sets the expansion constraint, False to deactivate this option and use estimated renewable potentials determine by the workflow, float scales the p_nom_min factor accordingly.
-- technology_mapping	nan	nan	Maps the technologies defined in ppm.data.Capacity_stats with the carriers in PyPSA-Earth.
-- -- Offshore	nan	{'offwind-ac', 'offwind-dc'}	nan
-- -- Onshore	nan	{'onwind'}	nan
-- -- PV	nan	{'solar'}	nan
base_voltage	kV	float	Base voltage to which all lines are simplified/aggregated. Simplification preserves transmission capacities.
voltages	kV	A subset of 'standard' voltages considered to map OSM-extracted voltages into 'standard' linetypes.	nan
hvdc_as_lines	bool	{True, False}	True: HVDC cables are modelled as PyPSA Line components. False: HVDC cables are modeled as PyPSA Link components.
agg_p_nom_limits	nan	nan	Configure per carrier generator capacity constraints limiting minimum and maximum values of the expanded capacity p_nom_opt for individual countries. Is enabled if 'CCL' is present in {opts} wildcard.
-- file	file	path	Reference to .csv file that specifies per carrier generator nominal capacity constraints for individual countries. Default is data/agg_p_nom_minmax.csv.
-- include_existing	bool	{True, False}	True: Existing capacities are considered in the CCL constraints. False: Existing capacities are not considered in the CCL constraints. Default is false.
operational_reserve	nan	nan	The total operational reserve requirements consist of three components: epsilon_load, epsilon_vres, contingency. See GenX for more details.
-- activate	bool	{True, False}	True: Operational reserve requirements are considered in the model.
-- epsilon_load	float	[0, 1]	Share of total load that is required for operational reserve.
-- epsilon_vres	float	[0, 1]	Share of total renewable supply that is required for operational reserve.
-- contingency	MW	nan	Operational reserve added as a contigency. For example, 5000 adds 5000 MW to the operational reserve requirements.

Carriers in conventional_carriers must not also be in extendable_carriers.

lines

Specifies electricity line parameters.

lines:
  ac_types:
    132.: "243-AL1/39-ST1A 20.0"
    220.: "Al/St 240/40 2-bundle 220.0"
    300.: "Al/St 240/40 3-bundle 300.0"
    380.: "Al/St 240/40 4-bundle 380.0"
    500.: "Al/St 240/40 4-bundle 380.0"
    750.: "Al/St 560/50 4-bundle 750.0"
  dc_types:
    500.: "HVDC XLPE 1000"
  s_max_pu: 0.7
  s_nom_max: .inf
  s_nom_max_min: -.inf
  length_factor: 1.25
  under_construction: "zero" # 'zero': set capacity to zero, 'remove': remove, 'keep': with full capacity

Parameter	Unit	Values	Description
ac_types	--	Values should specify a line type in PyPSA for AC lines. Keys should specify the corresponding voltage level (e.g. 220., 300. and 380. kV)	Specifies line types to assume for the different voltage levels of the target region. Should normally handle voltage levels 220, 300, and 380 kV.
dc_types	--	Values should specify a line type in PyPSA for DC-lines. Keys should specify the corresponding voltage level (e.g. 220., 300. and 380. kV)	Specifies DC-line types.
s_max_pu	--	Value in [0.,1.]	Correction factor for line capacities (s_nom) to approximate :math:N-1 security and reserve capacity for reactive power flows
s_nom_max	MW	float	Global upper limit for the maximum capacity of each extendable line.
s_nom_max_min	MW	float	Global lower limit for the maximum capacity of each extendable line.
length_factor	--	float	Correction factor to account for the fact that buses are not connected by lines through air-line distance.
under_construction	--	One of	Specifies how to handle lines which are currently under construction.

links

Specifies Link parameters. Links are a fundamental component of PyPSA .

links:
  p_max_pu: 1.0
  p_nom_max: .inf
  p_nom_max_min: -.inf
  under_construction: "zero" # 'zero': set capacity to zero, 'remove': remove, 'keep': with full capacity

Parameter	Unit	Values	Description
p_max_pu	--	Value in [0.,1.]	Correction factor for link capacities p_nom.
p_nom_max	MW	float	Global upper limit for the maximum capacity of each extendable DC link.
p_nom_max_min	MW	float	Global lower limit for the maximum capacity of each extendable DC link.
under_construction	--	One of	Specifies how to handle lines which are currently under construction. 'zero': set capacity to zero; 'remove': remove completely, 'keep': keep with full capacity.

transformers

Specifies transformers parameters and types.

transformers:
  x: 0.1
  s_nom: 2000.
  type: ""

Parameter	Unit	Values	Description
x	p.u.	float	Series reactance (per unit, using s_nom as base power of the transformer. Overwritten if type is specified.
s_nom	MVA	float	Limit of apparent power which can pass through branch. Overwritten if type is specified.
type	--	A transformer type in PyPSA.	Specifies transformer types to assume for the transformers of the ENTSO-E grid extraction.

atlite

Define and specify the atlite.Cutout used for calculating renewable potentials and time-series. All options except for features are directly used as cutout parameters.

Parameter	Unit	Values	Description
nprocesses	--	int	Number of parallel processes in cutout preparation
cutouts	nan	nan	nan
--	--	Convention is to name cutouts like <region>-<year>-<source> (e.g. europe-2013-era5).	Name of the cutout netcdf file. The user may specify multiple cutouts under configuration atlite: cutouts:. Reference is used in configuration renewable: {technology}: cutout:. The cutout base may be used to automatically calculate temporal and spatial bounds of the network.
-- -- module	--	Subset of	Source of the reanalysis weather dataset (e.g. ERA5 or SARAH-2)
-- -- x	°	Float interval within [-180, 180]	Range of longitudes to download weather data for. If not defined, it defaults to the spatial bounds of all bus shapes.
-- -- y	°	Float interval within [-90, 90]	Range of latitudes to download weather data for. If not defined, it defaults to the spatial bounds of all bus shapes.
-- -- time	nan	Time interval within ['1979', '2018'] (with valid pandas date time strings)	Time span to download weather data for. If not defined, it defaults to the time interval spanned by the snapshots.
-- -- features	nan	String or list of strings with valid cutout features ('inlfux', 'wind').	When freshly building a cutout, retrieve data only for those features. If not defined, it defaults to all available features.

renewable

Specifies the options to obtain renewable potentials in every cutout. These are divided in five different renewable technologies: onshore wind (onwind), offshore wind with AC connection (offwind-ac), offshore wind with DC connection (offwind-dc), solar (solar), and hydropower (hydro).

onwind

  onwind:
    cutout: auto
    resource:
      method: wind
      turbine: Vestas_V112_3MW
    capacity_per_sqkm: 3 # conservative, ScholzPhd Tab 4.3.1: 10MW/km^2
    # correction_factor: 0.93
    copernicus:
      # Scholz, Y. (2012). Renewable energy based electricity supply at low costs:
      #  development of the REMix model and application for Europe. ( p.42 / p.28)
      # CLC grid codes:
      # 11X/12X - Various forest types
      # 20  - Shrubs
      # 30  - Herbaceus vegetation
      # 40  - Cropland
      # 50  - Urban
      # 60  - Bare / Sparse vegetation
      # 80  - Permanent water bodies
      # 100 - Moss and lichen
      # 200 - Open sea
      grid_codes: [20, 30, 40, 60, 100, 111, 112, 113, 114, 115, 116, 121, 122, 123, 124, 125, 126]
      distance: 1000
      distance_grid_codes: [50]
    natura: true
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
    extendable: true

Parameter	Unit	Values	Description
cutout	--	Should be a file name listed in the configuration atlite: cutouts: (e.g. 'cutout-2013-era5'), reference an existing folder in the directory cutouts, or set as auto which redirects to the cutout configuration atlite: default:. Source module must be ERA5.	Specifies the directory where the relevant weather data is stored.
resource	nan	nan	nan
-- method	--	Must be 'wind'	A superordinate technology type.
-- turbine	--	One of turbine types included in atlite	Specifies the turbine type and its characteristic power curve.
capacity_per_sqkm	:math:MW/km^2	float	Allowable density of wind turbine placement.
copernicus	nan	nan	nan
-- grid_codes	--	Any subset of the Copernicus Land Cover code list	Specifies areas based on CLC which generally eligible for AC-connected offshore wind turbine placement.
-- distance	m	int	(Optional) Distance to reserve as uneligible area around 'distance_grid_codes' for the renewable technology.
-- distance_grid_codes	--	(Optional with 'distance') Any subset of the Copernicus Land Cover code list	Specifies from which a distance of 'distance' metres is unavailable as a buffer area.
natura	bool	{true, false}	Switch to exclude Natura 2000 natural protection areas. Area is excluded if true.
potential	--	One of	Method to compute the maximal installable potential for a node; confer :ref:renewableprofiles
clip_p_max_pu	p.u.	float	To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero.
extendable	bool	{True, False}	True: In nodes where there is no onwind generation, adds a zero-capacity onwind generator so that onwind is considered in the capacity expansion. It is done in the add_electricity rule.

offwind-ac

  offwind-ac:
    cutout: auto
    resource:
      method: wind
      turbine: NREL_ReferenceTurbine_5MW_offshore
    capacity_per_sqkm: 2
    # correction_factor: 0.8855
    # proxy for wake losses
    # from 10.1016/j.energy.2018.08.153
    # until done more rigorously in #153
    copernicus:
      grid_codes: [80, 200]
    natura: true
    max_depth: 50
    max_shore_distance: 30000
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
    extendable: true

Parameter	Unit	Values	Description
cutout	--	Should be a file name listed in the configuration atlite: cutouts: (e.g. 'cutout-2013-era5'), reference an existing folder in the directory cutouts, or set as auto which redirects to the cutout configuration atlite: default:. Source module must be ERA5.	Specifies the directory where the relevant weather data is stored.
resource	nan	nan	nan
-- method	--	Must be 'wind'	A superordinate technology type.
-- turbine	--	One of turbine types included in atlite	Specifies the turbine type and its characteristic power curve.
capacity_per_sqkm	:math:MW/km^2	float	Allowable density of wind turbine placement.
correction_factor	nan	[0., 1.]	Wind correction factor to account for wake losses. It gets multiplied by the theoretical maximum in the cutout to account for wake losses.
copernicus	nan	nan	nan
-- grid_codes	--	Any subset of the Copernicus Land Cover code list	Specifies areas based on CLC which generally eligible for AC-connected offshore wind turbine placement.
natura	bool	{true, false}	Switch to exclude Natura 2000 natural protection areas. Area is excluded if true.
max_depth	m	float	Maximum sea water depth at which wind turbines can be build. Maritime areas with deeper waters are excluded in the process of calculating the AC-connected offshore wind potential.
max_shore_distance	m	float	Maximum distance to the shore beyond which wind turbines with AC connections cannot be build. Such areas far away from shore are excluded in the process of calculating the AC-connected offshore wind potential.
potential	--	One of	Method to compute the maximal installable potential for a node; confer :ref:renewableprofiles
clip_p_max_pu	p.u.	float	To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero.
extendable	bool	{True, False}	True: In nodes where there is no offwind-ac generation, adds a zero-capacity offwind-ac generator so that offwind-ac is considered for capacity expansion. It is done in the add_electricity rule.

offwind-dc

  offwind-dc:
    cutout: auto
    resource:
      method: wind
      turbine: NREL_ReferenceTurbine_5MW_offshore
    # ScholzPhd Tab 4.3.1: 10MW/km^2
    capacity_per_sqkm: 3
    # correction_factor: 0.8855
    # proxy for wake losses
    # from 10.1016/j.energy.2018.08.153
    # until done more rigorously in #153
    copernicus:
      grid_codes: [80, 200]
    natura: true
    max_depth: 50
    min_shore_distance: 30000
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
    extendable: true

Parameter	Unit	Values	Description
cutout	--	Should be a file name listed in the configuration atlite: cutouts: (e.g. 'cutout-2013-era5'), reference an existing folder in the directory cutouts, or set as auto which redirects to the cutout configuration atlite: default:. Source module must be ERA5.	Specifies the directory where the relevant weather data is stored.
resource	nan	nan	nan
-- method	--	Must be 'wind'	A superordinate technology type.
-- turbine	--	One of turbine types included in atlite	Specifies the turbine type and its characteristic power curve.
capacity_per_sqkm	:math:MW/km^2	float	Allowable density of wind turbine placement.
correction_factor	nan	[0., 1.]	Wind correction factor to account for wake losses. It gets multiplied by the theoretical maximum in the cutout to account for wake losses.
copernicus	nan	nan	nan
-- grid_codes	--	Any subset of the Copernicus Land Cover code list	Specifies areas based on CLC which generally eligible for AC-connected offshore wind turbine placement.
natura	bool	{true, false}	Switch to exclude Natura 2000 natural protection areas. Area is excluded if true.
max_depth	m	float	Maximum sea water depth at which wind turbines can be build. Maritime areas with deeper waters are excluded in the process of calculating the AC-connected offshore wind potential.
min_shore_distance	m	float	Minimum distance to the shore below which wind turbines cannot be build. Such areas close to the shore are excluded in the process of calculating the AC-connected offshore wind potential.
potential	--	One of	Method to compute the maximal installable potential for a node; confer :ref:renewableprofiles
clip_p_max_pu	p.u.	float	To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero.
extendable	bool	{True, False}	True: In nodes where there is no offwind-dc generation, adds a zero-capacity offwind-dc generator so that offwind-dc is considered for capacity expansion. It is done in the add_electricity rule.

solar

  solar:
    cutout: auto
    resource:
      method: pv
      panel: CSi
      orientation: latitude_optimal # will lead into optimal design
      # slope: 0.  # slope: 0 represent a flat panel
      # azimuth: 180.  # azimuth: 180 south orientation
    capacity_per_sqkm: 4.6 # From 1.7 to 4.6 addresses issue #361
    # Determined by comparing uncorrected area-weighted full-load hours to those
    # published in Supplementary Data to
    # Pietzcker, Robert Carl, et al. "Using the sun to decarbonize the power
    # sector: The economic potential of photovoltaics and concentrating solar
    # power." Applied Energy 135 (2014): 704-720.
    correction_factor: 0.854337
    copernicus:
      grid_codes: [20, 30, 40, 50, 60, 90, 100]
    natura: true
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
    extendable: true

Parameter	Unit	Values	Description
cutout	--	Should be a file name listed in the configuration atlite: cutouts: (e.g. 'cutout-2013-era5'), reference an existing folder in the directory cutouts, or set as auto which redirects to the cutout configuration atlite: default:. Source module must be ERA5.	Specifies the directory where the relevant weather data is stored.
resource	nan	nan	nan
-- method	--	Must be 'pv'	A superordinate technology type.
-- panel	--	One of {'Csi', 'CdTe', 'KANENA'} as defined in atlite	Specifies the solar panel technology and its characteristic attributes.
-- orientation	nan	use either {latitude_optimal} or options such {slope: 0, azimuth: 180}	nan
-- -- latitude_optimal	--	Atlite function which returns for every raster the optimal slope and azimuth	nan
-- -- slope	°	Realistically any angle in [0., 90.]	Specifies the tilt angle (or slope) of the solar panel. A slope of zero corresponds to the face of the panel aiming directly overhead. A positive tilt angle steers the panel towards the equator.
-- -- azimuth	°	Any angle in [0., 360.]	Specifies the azimuth orientation of the solar panel. South corresponds to 180.°.
capacity_per_sqkm	:math:MW/km^2	float	Allowable density of solar panel placement. Value relates to socio-technical acceptable density.
correction_factor	--	float	A correction factor for the capacity factor (availability) time series.
copernicus	nan	nan	nan
-- grid_codes	--	Any subset of the Copernicus Land Cover code list	Specifies areas based on CLC which generally eligible for AC-connected offshore wind turbine placement.
natura	bool	{true, false}	Switch to exclude Natura 2000 natural protection areas. Area is excluded if true.
potential	--	One of	Method to compute the maximal installable potential for a node; confer :ref:renewableprofiles
clip_p_max_pu	p.u.	float	To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero.
extendable	bool	{True, False}	True: In nodes where there is no solar generation, adds a zero-capacity solar generator so that solar is considered for capacity expansion. It is done in the add_electricity rule.

hydro

  hydro:
    cutout: auto
    hydrobasins_level: 6
    resource:
      method: hydro
      hydrobasins: data/hydrobasins/hybas_world.shp
      flowspeed: 1.0 # m/s
      # weight_with_height: false
      # show_progress: true
    carriers: [ror, PHS, hydro]
    PHS_max_hours: 6
    hydro_max_hours: "energy_capacity_totals_by_country" # not active
    hydro_max_hours_default: 6.0 # (optional, default 6) Default value of max_hours for hydro when NaN values are found
    clip_min_inflow: 1.0
    extendable: true
    normalization:
      method: irena # 'hydro_capacities' to rescale country hydro production by using hydro_capacities, 'eia' or 'irena' to rescale by eia or irena data, false for no rescaling
      # use the weather year for weather-dominated variations (installed capacity is changing slowly)
      # the technology-year for policy-determined changes (installed capacity is changing quickly)
      year: 2023 # (optional) year of statistics used to rescale the runoff time series. When not provided, the cutout weather year is used
    multiplier: 1.1 # multiplier applied after the normalization of the hydro production; default 1.0
    hydro_min_inflow_pu: 1.0 # [hour] A threshold of energy to power ratio to classify hydro powerplants as reservoirs in case type is missed

See config.default.yaml for the full configuration.

Unnamed: 0	Unit	Values	Description
cutout	--	Should be a file name listed in the configuration atlite: cutouts: (e.g. 'europe-2013-era5'), reference an existing folder in the directory cutouts, or set as auto which redirects to the cutout configuration atlite: default:. Source module must be ERA5.	Specifies the directory where the relevant weather data is stored.
resource	nan	nan	nan
-- method	nan	nan	Specifies the Atlite method to calculate renewable potential.
-- hydrobasin	nan	nan	Specifies the file location for hydrobasins. They are used to make the runoff calibration, defining a polygon to compute the available water surface using a surface integral.
-- flowspeed	nan	nan	nan
carriers	--	Any subset of	Specifies the types of hydro power plants to build per-unit availability time series for. 'ror' stands for run-of-river plants, 'PHS' represents pumped-hydro storage, and 'hydro' stands for hydroelectric dams.
PHS_max_hours	h	float	Maximum state of charge capacity of the pumped-hydro storage (PHS) in terms of hours at full output capacity p_nom. Cf. PyPSA documentation <https://pypsa.readthedocs.io/en/latest/components.html#storage-unit>_.
hydro_max_hours	h	Any of	Maximum state of charge capacity of the pumped-hydro storage (PHS) in terms of hours at full output capacity p_nom or heuristically determined. Cf. PyPSA documentation <https://pypsa.readthedocs.io/en/latest/components.html#storage-unit>_.
hydro_max_hours_default	h	float	(optional, default 6) Default value of max_hours for hydro plants with missing values
clip_min_inflow	MW	float	To avoid too small values in the inflow time series, values below this threshold are set to zero.
extendable	bool	{True, False}	True: In nodes where there is no hydro generation, adds a zero-capacity hydro generator so that hydro is considered for capacity expansion. It is done in the add_electricity rule.
normalization	--	dict	When specified, it describes how to normalize hydro time series to adhere to national statistics
--method	--	str	Data source used to rescale the hydro runoff; option 'hydro_capacities' to use the provided 'data/hydro_capacities.csv', 'eia' or 'irena' for using the eia or irena file
--year	--	year	(optional) Specify the desired year to be used for normalization, the default value corresponds to the cutout weather year
multiplier	--	float	Multiplier factor of the rescaling process (default 1.0)
hydro_min_inflow_pu	hours	float	Minimum energy-to-capacity ratio used to classify hydropower plants with missing technology information: values above this threshold are treated as reservoir plants, while smaller values are classified as run-of-river.

csp

  csp:
    cutout: auto
    resource:
      method: csp
      installation: SAM_solar_tower
    capacity_per_sqkm: 2.392 # From 1.7 to 4.6 addresses issue #361
    # Determined by comparing uncorrected area-weighted full-load hours to those
    # published in Supplementary Data to
    # Pietzcker, Robert Carl, et al. "Using the sun to decarbonize the power
    # sector: The economic potential of photovoltaics and concentrating solar
    # power." Applied Energy 135 (2014): 704-720.
    copernicus:
      grid_codes: [20, 30, 40, 60, 90]
      distancing_codes: [50]
      distance_to_codes: 3000
    natura: true
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
    extendable: true
    csp_model: advanced # simple or advanced

See config.default.yaml for the full configuration.

Parameter	Unit	Values	Description
cutout	--	Should be a file name listed in the configuration atlite: cutouts: (e.g. 'cutout-2013-era5'), reference an existing folder in the directory cutouts, or set as auto which redirects to the cutout configuration atlite: default:. Source module must be ERA5.	Specifies the directory where the relevant weather data is stored.
resource	nan	nan	nan
-- method	--	Must be 'csp'	nan
-- installation	--	Should be 'SAM_solar_tower' as defined in atlite	Specifies the csp technology and its characteristic attributes.
capacity_per_sqkm	:math:MW/km^2	float	Allowable density of csp tower placement. Value relates to socio-technical acceptable density.
copernicus	nan	nan	nan
-- grid_codes	--	Any subset of the Copernicus Land Cover code list	Specifies areas based on CLC which generally eligible for csp tower placement.
-- distance	m	int	(Optional) Distance to reserve as uneligible area around 'distance_grid_codes' for the renewable technology.
-- distance_grid_codes	--	(Optional with 'distance') Any subset of the Copernicus Land Cover code list	Specifies from which a distance of 'distance' metres is unavailable as a buffer area.
natura	bool	{true, false}	Switch to exclude Natura 2000 natural protection areas. Area is excluded if true.
potential	--	One of	Method to compute the maximal installable potential for a node; confer :ref:renewableprofiles
clip_p_max_pu	p.u.	float	To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero.
extendable	bool	{True, False}	True: In nodes where there is no csp generation, adds a zero-capacity csp generator so that csp is considered for capacity expansion. It is done in the add_electricity rule.
csp_model	--	One of	Specifies the CSP model to be used. The advanced model attach stores and links to the csp buses while the simple has no stores and links.

costs

Specifies the cost assumptions of the technologies considered. Cost information is obtained from the config file and the file data/costs.csv, which can also be modified manually.

costs:
  year: 2030 # cost file selection, i.e. costs_2030.csv in this case; reference year for costs is always 2020
  technology_data_version: v0.13.2
  discountrate: [0.071] #, 0.086, 0.111]
  country_specific_data: "" # (optional) Reference to the desired technology-data directory for techno-economic input data; Only "" and "US" supported, for other values check the technology-data output directory
  # Only needed if "US" is selected as `country_specific_data`, otherwise ignore
  cost_scenario: "moderate" # only used if `country_specific_data: "US"`; can be "moderate", "advanced" or "conservative"
  financial_case: "market" # only used if `country_specific_data: "US"`; can be "market" or "r&d"
  # Management of output currencies and exchange rates
  output_currency: "EUR" # full list of supported currencies at https://github.com/alexprengere/currencyconverter/blob/master/currency_converter/eurofxref.csv
  default_exchange_rate: 0.7532 # previously USD2013_to_EUR2013; should be sufficient as current data from 'technology-data` are either in EUR or USD; [EUR/USD] ECB: https://www.ecb.europa.eu/stats/exchange/eurofxref/html/eurofxref-graph-usd.en.html
  future_exchange_rate_strategy: "reference" # reference: the exchange rate from `reference_year`, ensuring all costs are expressed in the same currency and year; "latest" uses the yearly average of the latest available exchange rates for the selected `output_currency`; "custom" allows to specify a `custom_future_exchange_rate`
  custom_future_exchange_rate: None # if `future_exchange_rate_strategy: "custom"`, please insert here the desired output_currency-to-EUR exchange rate
  rooftop_share: 0.14 # based on the potentials, assuming (0.1 kW/m2 and 10 m2/person)
  fill_values:
    FOM: 0
    VOM: 0
    efficiency: 1
    fuel: 0
    investment: 0
    lifetime: 25
    CO2 intensity: 0
    discount rate: 0.07
  marginal_cost: # EUR/MWh
    solar: 0.01
    onwind: 0.015
    offwind: 0.015
    hydro: 0.
    H2: 0.
    electrolysis: 0.
    fuel cell: 0.
    battery: 0.
    battery inverter: 0.
  # investment: # EUR/MW
  #   CCGT: 830000
  # FOM: # %/year
  #   CCGT: 3.35
  # VOM: # EUR/MWh
  #   CCGT: 4.2
  # fuel: # EUR/MWh
  #   gas: 10.1
  # lifetime: # years
  #   CCGT: 25.0
  # efficiency: # per unit
  #   CCGT: 0.58

Parameter	Unit	Values	Description
year	--	YYYY (e.g. 2030)	Year for which to retrieve cost assumptions for resources/costs.csv
technology_data_version	--	vX.X.X (e.g. v0.1.0)	Version of technology-data repository to use
discountrate	--	float	Rate of return used to discount future cash flows back to their present value
country_specific_data	bool	{True, False}	Reference to the desired technology-data directory for techno-economic input data
cost_scenario	--	{moderate, advanced, conservative}	Only used if country_specific_data is set to select the desired NREL financial case
financial_case	--	{market, r&d}	Only used if country_specific_data is set to select the desired NREL financial case
output_currency	--	{EUR, USD, JPY, CAD, CNY}	Reference currency for all costs (EUR is the base unit for conversion)
default_exchange_rate	--	float	Default US Dollar-Euro exchange rate
future_exchange_rate_strategy	--	{reference, latest, custom}	Strategy for currency conversion
custom_future_exchange_rate	--	{None, float}	Customized exchange rate if future_exchange_rate_strategy is custom
rooftop_share	--	float	Share of rooftop PV when calculating capital cost of solar
fill_values	--	dict	Default values if not specified for a technology in resources/costs.csv
marginal_cost	EUR/MWh	dict	Marginal operating costs for specified technologies
-- FOM	%/year	dict	Fixed Operations and Maintenance assumptions
-- VOM	EUR/MWh	dict	Variable Operations and Maintenance assumptions
-- efficiency	--	dict	Efficiency assumptions per technology
-- fuel	EUR/MWh	dict	Fuel price assumptions
-- investment	EUR/MW	dict	Investment cost assumptions
-- lifetime	years	dict	Technology lifetime assumptions
-- CO2 intensity	t_CO2/MWh	dict	CO2 intensity per technology
-- discount rate	--	dict	Discount rate per technology

Note

To change cost assumptions in more detail (i.e. other than marginal_cost), consider modifying cost assumptions directly in data/costs.csv as this is not yet supported through the config file. You can also build multiple different cost databases. Make a renamed copy of data/costs.csv (e.g. data/costs-optimistic.csv) and set the variable COSTS=data/costs-optimistic.csv in the Snakefile.

The marginal costs or in this context variable costs of operating the assets is important for realistic operational model outputs. It can define the curtailment order of renewable generators, the dispatch order of generators, and the dispatch of storage units. If not appropriately set, the model might output unrealistic results. Learn more about this in Parzen et al. 2023 and in Kittel et al. 2022.

co2

Carbon dioxide policy settings: emission caps and carbon prices (via Co2L/Ep wildcards), automatic emission extraction, and optional planning-horizon budgets in sector-coupled runs.

co2:
  limit: 7.75e+7     # annual cap [tCO2/year]; European default — adjust for your region; active via Co2L wildcard
  base: 1.487e+9     # baseline emissions used for relative reduction targets; European default
  emission_price: 0. # [currency/tCO2]; active via Ep wildcard
  automatic_emission: # derive co2.limit from historical emission data instead of the value above
    enable: false
    base_year: 1990  # any year from 1970 to 2018
  budget:            # year-by-year reduction trajectory; used in all sector-coupled runs
    enable: false
    override_co2opt: true
    base_value: limit # which co2 scalar to scale by year factors: "limit", "base", "absolute", or a float [tCO2/a]
    year:
      2020: 1.0
      2025: 0.85
      2030: 0.70
      2035: 0.55
      2040: 0.40
      2045: 0.25
      2050: 0.1

Parameter	Unit	Values	Description
limit	tCO2-eq/a	float	Cap on system total annual carbon dioxide equivalent emissions. Active via Co2L in the {opts} wildcard.
base	tCO2-eq/a	float	Reference value of system total annual carbon dioxide equivalent emissions. Used when a relative reduction target is specified in {opts} (e.g. Co2L0.7).
emission_price	currency/tCO2-eq	float	Exogenous CO₂ price applied to marginal costs when Ep is present in {opts}.
automatic_emission	nan	nan	Derive co2.limit from historical emission data instead of the configured limit value.
-- enable	bool	{true, false}	True: emissions are obtained from the automatic emission extraction procedure.
-- base_year	nan	integer	Reference year for automatic emission extraction (1970–2018).
budget	nan	nan	Year-by-year CO₂ reduction trajectory applied in all sector-coupled runs.
-- enable	bool	{true, false}	Switch to activate planning-horizon-specific CO₂ budgets.
-- override_co2opt	bool	{true, false}	If true and a CO₂ limit already exists (e.g. from Co2L in {opts}), overwrite it with the budget value.
-- base_value	str	{"limit", "base", "absolute", float}	Which co2 scalar to scale by year factors: limit or base (sibling keys above), absolute (factor is the cap directly), or a custom float [tCO₂-eq/a].
-- year	nan	Dictionary with planning horizons as keys	CO₂ budget as a fraction of the selected base_value scalar. If absolute is selected then the factor is the annual cap [tCO₂-eq/a].

monte_carlo

Specifies the options for Monte Carlo sampling.

monte_carlo:
  # Description: Specify Monte Carlo sampling options for uncertainty analysis.
  # Define the option list for Monte Carlo sampling.
  # Make sure add_to_snakefile is set to true to enable Monte-Carlo
  options:
    add_to_snakefile: false # When set to true, enables Monte Carlo sampling
    samples: 9 # number of optimizations. Note that number of samples when using scipy has to be the square of a prime number
    sampling_strategy: "chaospy" # "pydoe2", "chaospy", "scipy", packages that are supported
    seed: 42 # set seedling for reproducibilty
  # Uncertanties on any PyPSA object are specified by declaring the specific PyPSA object under the key 'uncertainties'.
  # For each PyPSA object, the 'type' and 'args' keys represent the type of distribution and its argument, respectively.
  # Supported distributions types are uniform, normal, lognormal, triangle, beta and gamma.
  # The arguments of the distribution are passed using the key 'args'  as follows, tailored by distribution type
  # normal: [mean, std], lognormal: [mean, std], uniform: [lower_bound, upper_bound],
  # triangle: [mid_point (between 0 - 1)], beta: [alpha, beta], gamma: [shape, scale]
  # More info on the distributions are documented in the Chaospy reference guide...
  # https://chaospy.readthedocs.io/en/master/reference/distribution/index.html
  # An abstract example is as follows:
  # {pypsa network object, e.g. "loads_t.p_set"}:
  # type: {any supported distribution among the previous: "uniform", "normal", ...}
  # args: {arguments passed as a list depending on the distribution, see the above and more at https://pypsa.readthedocs.io/}
  uncertainties:
    loads_t.p_set:
      type: uniform
      args: [0.5, 1]
    generators_t.p_max_pu.loc[:, n.generators.carrier == "onwind"]:
      type: lognormal
      args: [1.5]
    generators_t.p_max_pu.loc[:, n.generators.carrier == "solar"]:
      type: beta
      args: [0.5, 2]

Parameter	Unit	Values	Description
options	nan	nan	nan
add_to_snakemake	nan	true or false	Set to true to enable Monte-Carlo
samples	nan	int	Defines the number of total sample networks that will be optimized. If the chosen sampling strategy is scipy, then a square of a prime number needs to be chosen. E.g. 49 which is (7^2)
sampling_strategy	nan	Any subset of	Current supported packages to create an experimental design
seed	nan	int	Allows experimentation to be reproduced easily
uncertainties	nan	nan	nan
	MW/MWh	nan	Key is a dynamic PyPSA object that allows to access any pypsa object such as loads_t.p_set or the max. wind generation per hour generators_t.p_max_pu.loc[:, n.generators.carrier == "wind"]. Values or bounds are multiplication for each object.
type	nan	str	Defines the distribution for the chosen pypsa.object parameter. Distribution can be either uniform, normal, lognormal, triangle, beta or gamma
args	nan	list	Defines parameters for the chosen distribution. [mean, std] for normal and lognormal, [lower_bound, upper_bound] for uniform, [mid_point (between 0 - 1)] for triangle, [alpha, beta] for beta, [shape, scale] for gamma

Sector options

Options under the SECTOR OPTIONS banner in config.default.yaml: hydrogen policy and export, sector demand inputs, custom data overrides, brownfield capacity grouping, and sector coupling settings.

policy_config

Specifies energy-policy options for hydrogen, for example temporal matching and additionality constraints.

policy_config:
  hydrogen:
    temporal_matching: "no_temporal_matching" #either "hour", "month", "year", "no_temporal_matching"
    spatial_matching: false
    temporal_matching_carriers: [csp, solar, onwind, offwind-ac, offwind-dc, ror, hydro]
    matching_technologies: ["H2 Electrolysis", "Alkaline electrolyzer large", "Alkaline electrolyzer medium", "Alkaline electrolyzer small", "PEM electrolyzer", "SOEC"]
    additionality: false # RE electricity is equal to the amount required for additional hydrogen export compared to the 0 export case ("reference_case")
    allowed_excess: 1.0
    is_reference: false # Whether or not this network is a reference case network, relevant only if additionality is _true_
    remove_h2_load: false #Whether or not to remove the h2 load from the network, relevant only if is_reference is _true_
    path_to_ref: "" # Path to the reference case network for additionality calculation, relevant only if additionality is _true_ and is_reference is _false_
    re_country_load: false # Set to "True" to force the RE electricity to be equal to the electricity required for hydrogen export and the country electricity load. "False" excludes the country electricity load from the constraint.

Parameter	Unit	Values	Description
hydrogen
-- temporal_matching	--	One of	Specifies the temporal matching method for hydrogen production.
-- spatial_matching	bool	{true, false}	Indicates whether spatial matching is applied for hydrogen production. Currently, only 'false' is supported.
-- temporal_matching_carriers	--	Any subset of	Defines a list of renewable energy carriers considered for temporal matching of hydrogen production.
-- matching_technologies	--	Any subset of	Defines a list of hydrogen production technologies considered for matching.
-- additionality	bool	{true, false}	If true, ensures renewable electricity is equal to the amount required for additional hydrogen export compared to the reference case without hydrogen export. Currently, only 'false' is supported.
-- allowed_excess	p.u.	float	Defines the allowable excess renewable energy for hydrogen production.
-- is_reference	bool	{true, false}	Indicates whether the network is a reference case for additionality calculations. It is relevant only if additionality is true.
-- remove_h2_load	bool	{true, false}	Specifies whether to remove hydrogen load from the network in the reference case. It is relevant only if is_reference is true.
-- path_to_ref	--	string	Path to the reference case network for additionality calculation. It is relevant only if additionality is true and is_reference is false.
-- re_country_load	bool	{true, false}	If true, forces renewable electricity to match hydrogen export and country electricity load. If false, renewable electricity is only matched to hydrogen export. Currently, only 'false' is supported.

export

Specifies hydrogen export demand, storage, and shipping profile settings.

export:
  endogenous: false # If true, the export demand is endogenously determined by the model
  endogenous_price: 400 # EUR/MWh # Market price, for which the hydrogen for endogenous exports is sold. Only considered, if ["export"]["endogenous"] is set to true.
  store: true # [True, False] # specifies whether an export store to balance demand is implemented
  store_capital_costs: "no_costs" # ["standard_costs", "no_costs"] # specifies the costs of the export store. "standard_costs" takes CAPEX of "hydrogen storage tank type 1 including compressor"
  h2export: [10] # Yearly export demand in TWh. Only considered, if ["export"]["endogenous"] is set to false
  export_profile: "ship" # use "ship" or "constant". Only considered, if ["export"]["endogenous"] is set to false
  ship:
    ship_capacity: 0.4 # TWh # 0.05 TWh for new ones, 0.003 TWh for Susio Frontier, 0.4 TWh according to Hampp2021: "Corresponds to 11360 t H2 (l) with LHV of 33.3333 Mwh/t_H2. Cihlar et al 2020 based on IEA 2019, Table 3-B"
    travel_time: 288 # hours # From Agadir to Rotterdam and back (12*24)
    fill_time: 24 # hours, for 48h see Hampp2021
    unload_time: 24 # hours for 48h see Hampp2021

Parameter	Unit	Values	Description
endogenous	bool	{true, false}	If true, the export demand is endogenously determined by the model. Default is 'false'.
endogenous_price	EUR/MWh	float	Market price at which hydrogen for endogenous exports is sold. Only considered if endogenous is true.
store	bool	{true, false}	Indicates whether an export store is implemented to balance hydrogen export demand. Default is 'true'.
store_capital_costs	--	One of	Specifies the costs of the export store. 'standard_costs' uses CAPEX of 'hydrogen storage tank type 1 including compressor'. 'no_costs' assumes zero costs for the export store. Only considered if store is true.
h2export	TWh	float	Specifies the yearly hydrogen export demand in TWh. This parameter is only applicable if endogenous is set to false.
export_profile	--	One of	Specifies the export profile. Only considered if endogenous is false.
ship	nan	nan	Specifies parameters for hydrogen export via shipping.
ship_capacity	TWh	float	Specifies the ship capacity for hydrogen export. Example values: 0.05 TWh for new ships, 0.003 TWh for Susio Frontier, and 0.4 TWh based on Hampp 2021 (this corresponds to 11,360 t of liquid hydrogen (LHV of 33.3333 MWh/t_H2)).
travel_time	hours	int	Travel time for hydrogen export shipping (e.g. from Agadir to Rotterdam and back takes 288 hours).
fill_time	hours	int	Time required to fill the ship for hydrogen export. 48 hours is needed to fill the ship (see Hampp 2021).
unload_time	hours	int	Time required to unload the ship for hydrogen export. 48 hours is needed to unload the ship (see Hampp 2021).

demand_data

Specifies sector-coupled demand inputs (UNSD energy balances and related years).

demand_data:
  update_data: true # if true, the workflow downloads the energy balances data saved in data/demand/unsd/data again. Turn on for the first run.
  base_year: 2019
  other_industries: false # Whether or not to include industries that are not specified. some countries have has exaggerated numbers, check carefully.
  aluminium_year: 2019 # Year of the aluminium demand data specified in `data/AL_production.csv`

Parameter	Unit	Values	Description
demand_data
update_data	bool	{true, false}	If true, the workflow downloads the energy balances data saved in data/demand/unsd/data again.
base_year	int	Any year (e.g. 2019)	Specifies the base year for energy balances data. Default year is 2019. If interested in a different year, please check presence of data for selected base year and country in data/demand/unsd/data.
other_industries	bool	{true, false}	Determines whether to include unspecified industries. Note that some countries may have inflated numbers; review cautiously.
aluminium_year	int	Any year between 2015 and 2022	Year of the aluminium production data specified in data/AL_production.csv. Default year is 2019.

custom_data

Specifies which custom datasets are used to replace or supplement the default model data. For full details see Custom Data Integration.

custom_data:
  heat_demand: false
  industry_demand: false
  industry_database: false
  transport_demand: false
  water_costs: false
  h2_underground: false
  add_existing: false
  custom_sectors: false
  gas_network: false # If "True" then a custom .csv file must be placed in "resources/custom_data/pipelines.csv" , If "False" the user can choose btw "greenfield" or Model built-in datasets. Please refer to ["sector"] below.
  export_ports: false # If "True" then a custom .csv file must be placed in "data/custom/export_ports.csv"
  airports: false # If "True" then a custom .csv file must be placed in "data/custom/airports.csv". Data format for aiports must be in the format of the airports.csv file in the data folder.

Parameter	Unit	Values	Description
renewables	--	list of	List of renewable technologies for which custom time series data is used. Leave empty [] to use default data.
elec_demand	bool	{true, false}	If true, custom electricity demand data is used instead of the built-in dataset.
heat_demand	bool	{true, false}	If true, custom heat demand data is used instead of the built-in dataset.
industry_demand	bool	{true, false}	If true, custom industry demand data is used instead of the built-in dataset.
industry_database	bool	{true, false}	If true, a custom industry database is used instead of the built-in dataset.
transport_demand	bool	{true, false}	If true, custom transport demand data is used instead of the built-in dataset.
water_costs	bool	{true, false}	If true, custom water cost data is used instead of the built-in dataset.
h2_underground	bool	{true, false}	If true, custom hydrogen underground storage data is used instead of the built-in dataset.
add_existing	bool	{true, false}	If true, existing capacities are added from custom data.
custom_sectors	bool	{true, false}	If true, custom sector data is used.
gas_network	bool	{true, false}	If true, a custom gas network CSV must be placed at resources/custom_data/pipelines.csv. If false, the user can choose between greenfield or model built-in datasets.
export_ports	bool	{true, false}	If true, a custom export ports CSV must be placed at data/custom/export_ports.csv.
airports	bool	{true, false}	If true, a custom airports CSV must be placed at data/custom/airports.csv. Data format must match the airports.csv file in the data folder.

existing_capacities

Vintage grouping and thresholds for brownfield power and heating capacities in add_existing_baseyear and related rules.

existing_capacities:
  grouping_years_power: [1960, 1965, 1970, 1975, 1980, 1985, 1990, 1995, 2000, 2005, 2010, 2015, 2020, 2025, 2030]
  grouping_years_heat: [1980, 1985, 1990, 1995, 2000, 2005, 2010, 2015, 2019] # these should not extend 2020
  threshold_capacity: 10
  default_heating_lifetime: 20
  conventional_carriers:
  - lignite
  - coal
  - oil
  - uranium

Parameter	Unit	Values	Description
grouping_years_power	list of years	nan	Vintage grouping years for existing power plant capacities in add_existing_baseyear and add_electricity.
grouping_years_heat	list of years	nan	Vintage grouping years for existing heating capacities; should not extend beyond 2020.
threshold_capacity	MW	nan	Minimum installed capacity [MW] for an asset to be included when building existing capacities.
default_heating_lifetime	years	nan	Default lifetime [years] for existing heating assets when missing from input data.
conventional_carriers	list	nan	Carriers listed for existing-capacity handling alongside brownfield data.

sector

Specifies the options for sector coupling, i.e. the integration of the electricity system with other sectors such as heating and transport.

top-level

Carrier toggles, fossil-fuel supply settings (gas, coal, lignite, oil), hydrogen, and ammonia. Fossil fuel reserves are set per carrier as sector.{carrier}.reserves [TWh/bus] (e.g. sector.oil.reserves, sector.coal.reserves). The value sets initial Store energy in add_carrier_buses for fuel carriers used in sector.conventional_generation (gas, oil, coal, lignite, biomass); it defaults to 0 if omitted. The former top-level fossil_reserves block is deprecated — see Renamed keys.

sector:
  enable:
    heat: true
    biomass: true
    industry: true
    shipping: true
    aviation: true
    land_transport: true
    rail_transport: true
    agriculture: true
    residential: true
    services: true

  gas:
    spatial_gas: true # ALWAYS TRUE
    network: false # ALWAYS FALSE for now (NOT USED)
    network_data: GGIT # Global dataset -> 'GGIT' , European dataset -> 'IGGIELGN'
    network_data_GGIT_status: ["Construction", "Operating", "Idle", "Shelved", "Mothballed", "Proposed"]

  hydrogen:
    network: true
    H2_retrofit_capacity_per_CH4: 0.6
    network_limit: 2000 #GWkm
    network_routes: gas # "gas or "greenfield". If "gas"  ->  the network data are fetched from ["sector"]["gas"]["network_data"]. If "greenfield"  -> the network follows the topology of electrical transmission lines
    gas_network_repurposing: true # If true -> ["sector"]["gas"]["network"] is automatically false
    h2_turbine: true
    underground_storage:
      enabled: false
      # calculations based on https://doi.org/10.1016/j.energy.2026.141729
      min_area_km2: 13 # minimum area for kaverns in km2
      method: "surface" # surface or physics
      technical_realization_factor: 3.5e-5
      energy_density_MWh_per_m3: 0.336 # energy density varies in europe between 0.214 and 0.0458 MWh/m3
      cavern_height_bedded_m: 120
      cavern_diameter_bedded_m: 84
      cavern_height_dome_m: 300
      cavern_diameter_dome_m: 58
      salt_buffer_m_bedded: 2000
      salt_buffer_m_dome: 500
      copernicus:
        # CLC grid codes:
        # 11X/12X - Various forest types
        # 20  - Shrubs
        # 30  - Herbaceus vegetation
        # 40  - Cropland
        # 50  - Urban
        # 60  - Bare / Sparse vegetation
        # 80  - Permanent water bodies
        # 100 - Moss and lichen
        # 200 - Open sea
        grid_codes: [50, 80, 100]
        distance_buffer_by_code:
          50: 2500 # urban
          80: 200 # protected areas / water bodies
          100: 200 # natural protected areas
      rho_min: 5.0         # Minimum hydrogen density in kg/m³ (at low pressure, e.g. ~30 bar)
      rho_max: 42.0        # Maximum hydrogen density in kg/m³ (at high pressure, e.g. ~200–250 bar)
      theta_safety: 0.8    # Usable working gas fraction (portion of H₂ that can actually be withdrawn)
      lhv_h2: 120          # Lower Heating Value (LHV) of hydrogen in MJ/kg (energy content per kg H₂)
      locations:
      - onshore
      - offshore
    hydrogen_colors: false
    set_color_shares: false
    blue_share: 0.40
    pink_share: 0.05
    production_technologies: # H2 production carriers from costs data; uncomment lines to enable
    - H2 Electrolysis
    - SMR
    - SMR CC
    # - Alkaline electrolyzer large
    # - Alkaline electrolyzer medium
    # - Alkaline electrolyzer small
    # - PEM electrolyzer
    # - SOEC
    # - Solid biomass steam reforming
    # - Biomass gasification
    # - Biomass gasification CC
    # - Natural gas steam reforming
    # - Natural gas steam reforming CC
    # - Coal gasification
    # - Coal gasification CC
    # - Heavy oil partial oxidation

  coal:
    spatial_coal: true
    shift_to_elec: true # If true, residential and services demand of coal is shifted to electricity. If false, the final energy demand of coal is disregarded

  lignite:
    spatial_lignite: false

  oil:
    spatial_oil: true
    reserves: 100 # TWh per bus: Maybe redundant

  ammonia:
    enable: true
    spatial_ammonia: true
    production_year: 2019 # 2019 - 2023 are available
    gas_MWh_per_tNH3: 7.81   # MWh natural gas per tNH3 (SMR eff.=0.76, HB H2-input=1.1484 MWh_H2/MWh_NH3, NH3 LHV=5.167 MWh/t)
    elec_MWh_per_tNH3: 1.278  # MWh electricity per tNH3 (HB elec-input=0.2473 MWh_el/MWh_NH3, NH3 LHV=5.167 MWh/t)
    co2_t_per_tNH3: 1.547    # tCO2 per tNH3 (gas CO2 intensity=0.198 tCO2/MWh_gas x 7.81 MWh_gas/tNH3)

Parameter	Unit	Values	Description
enable			Configuration for sector settings.
-- heat	bool	{true, false}	Flag to include heating sector.
-- biomass	bool	{true, false}	Flag to include biomass sector.
-- industry	bool	{true, false}	Flag to include industry sector.
-- shipping	bool	{true, false}	Flag to include shipping sector.
-- aviation	bool	{true, false}	Flag to include aviation sector.
-- land_transport	bool	{true, false}	Flag to include land transport sector.
-- rail_transport	bool	{true, false}	Flag to include rail transport sector.
-- agriculture	bool	{true, false}	Flag to include agriculture sector.
-- residential	bool	{true, false}	Flag to include residential sector.
-- services	bool	{true, false}	Flag to include service sector.
gas			Configuration for sector.gas settings.
-- spatial_gas	bool	{true, false}	Add option to spatially resolve carrier representing gas (methane) supply.
-- network	bool	{true, false}	Currently not available for gas carriers.
-- network_data	--	One of	Specify which existing gas pipeline to use. Either from Global Gas Infrastructure Tracker (GGIT) or European Gas Infrastructure (IGGIELGN)
-- network_data_GGIT_status	--	Any subset of	List of status to be included when retrieving gas infrastructure data.
hydrogen			Configuration for sector.hydrogen settings.
-- network	bool	{true, false}	Add option for new hydrogen pipelines.
-- H2_retrofit_capacity_per_CH4	MW/CH4	nan	Hydrogen transport capacity compared to natural gas capacity in retrofitted pipelines.
-- network_limit	GWkm	nan	Add maximum hydrogen network capacity.
-- network_routes	--	One of	Specify if either hydrogen network follows the topology of gas networks (gas) or closely resembles electrical transmission lines (greenfield).
-- gas_network_repurposing	bool	{true, false}	Specify if gas networks can be repurposed for hydrogen networks.
-- underground_storage	bool	{true, false}	Add options for storing hydrogen underground. Storage potential depends regionally.
-- hydrogen_colors	bool	{true, false}	Specify if hydrogen carriers are disaggregated based on their source.
-- set_color_shares	bool	{true, false}	Add option if hydrogen sources must be derived from specific sources.
-- blue_share	float	[0, 1]	Share of hydrogen derived from gas with carbon capture.
-- pink_share	float	[0, 1]	Share of hydrogen derived from nuclear.
-- production_technologies	--	Any subset of	List of hydrogen production technologies that can be added.
coal			Configuration for sector.coal settings.
-- spatial_coal	bool	{true, false}	Add option to spatially resolve carrier representing coal supply.
-- shift_to_elec	bool	{true, false}	Specify if sectoral coal consumption can be electrified.
lignite			Configuration for sector.lignite settings.
-- spatial_lignite	bool	{true, false}	Add option to spatially resolve carrier representing lignite supply.
oil			Configuration for sector.oil settings.
-- spatial_oil	bool	{true, false}	Add option to spatially resolve carrier representing oil supply.
-- reserves	TWh	float	Initial fossil-fuel reserve energy per bus [TWh] for the carrier Store. Optional; defaults to 0. Same key may be set under other sector.{carrier} blocks (e.g. sector.coal.reserves).
ammonia			Configuration for sector.ammonia settings.
-- enable	bool	{true, false}	Flag to include conventional Haber-Bosch ammonia production in the industry sector.
-- production_year	int	[2019, 2023]	Year of ammonia production statistics used to scale nodal demand (data available 2019–2023).
-- gas_MWh_per_tNH3	MWh/t	nan	Natural gas consumption per tonne of NH3 (feedstock + fuel for SMR-based Haber-Bosch route).
-- elec_MWh_per_tNH3	MWh/t	nan	Electricity consumption per tonne of NH3 (SMR-based Haber-Bosch route).
-- co2_t_per_tNH3	tCO2/t	nan	CO2 emissions per tonne of NH3 (SMR-based process emissions).

heat sector

Solar thermal collector settings live under sector.solar_thermal_collector (not sector.solar_thermal). Deprecated solar-thermal keys are listed in Renamed keys.

  # ------------------- Heat sector -------------------
  district_heating:
    potential: 0.3 #maximum fraction of urban demand which can be supplied by district heating
    #increase of today's district heating demand to potential maximum district heating share
    #progress = 0 means today's district heating share, progress=-1 means maximum fraction of urban demand is supplied by district heating
    progress: 1
    # 2020: 0.0
    # 2030: 0.3
    # 2040: 0.6
    # 2050: 1.0
    district_heating_loss: 0.15
  reduce_space_heat_exogenously: false # reduces space heat demand by a given factor (applied before losses in DH)
  # this can represent e.g. building renovation, building demolition, or if
  # the factor is negative: increasing floor area, increased thermal comfort, population growth
  # NB The value of space heat reduction are Europe-specific
  # if they usage is enabled (reduce_space_heat_exogenously) a regional adjustment is needed
  reduce_space_heat_exogenously_factor: 0.29 # per unit reduction in space heat demand
  # the default factors are determined by the LTS scenario from http://tool.european-calculator.eu/app/buildings/building-types-area/?levers=1ddd4444421213bdbbbddd44444ffffff11f411111221111211l212221
  # 2020: 0.10  # this results in a space heat demand reduction of 10%
  # 2025: 0.09  # first heat demand increases compared to 2020 because of larger floor area per capita
  # 2030: 0.09
  # 2035: 0.11
  # 2040: 0.16
  # 2045: 0.21
  # 2050: 0.29
  space_heat_share: 0.6 # the share of space heating from all heating. Remainder goes to water heating.

  tes: true
  tes_tau: # 180 day time constant for centralised, 3 day for decentralised
    decentral: 3
    central: 180
  boilers: true
  oil_boilers: false
  chp: true
  micro_chp: false

  solar_thermal_collector:
    enable: true
    cf_correction: 0.788457 # correction factor applied to atlite's raw output; = 1/1.2683
    clearsky_model: simple
    orientation:
      slope: 45.
      azimuth: 180.

  heat_pump_sink_T: 55 #Celsius, based on DTU / large area radiators; used un build_cop_profiles.py
  time_dep_hp_cop: true #time dependent heat pump coefficient of performance

Parameter	Unit	Values	Description
district_heating
-- potential	float	[0, 1]	Maximum fraction of urban demand which can be supplied by district heating
-- progress	float/dict	[0, 1] or {planning_horizons}: [0, 1]	Increase of today's district heating demand to potential maximum district heating share. Progress = 0 means today's district heating share. Progress = 1 means maximum fraction of urban demand is supplied by district heating.
-- district_heating_loss	float	[0, 1]	Share increase in district heat demand in urban central due to heat losses.
reduce_space_heat_exogenously	bool	{true, false}	Influence on space heating demand by a certain factor (applied before losses in district heating).
reduce_space_heat_exogenously_factor	float/dict	[0, 1] or {planning_horizons}: [0, 1]	A positive factor can mean renovation or demolition of a building. If the factor is negative, it can mean an increase in floor area, increased thermal comfort, population growth. The default factors are determined by the Eurocalc Homes and buildings decarbonization scenario <http://tool.european-calculator.eu/app/buildings/building-types-area/?levers=1ddd4444421213bdbbbddd44444ffffff11f411111221111211l212221>_.
space_heat_share	float	[0, 1]	Share of space heating from all heating. Remainder goes to water heating
tes	bool	{true, false}	Add option for storing thermal energy in large water pits associated with district heating systems and individual thermal energy storage (TES).
tes_tau
-- decentral	days	nan	The duration of a decentralized TES thermal energy is depleted due to standing losses.
-- central	days	nan	The duration of a centralized TES thermal energy is depleted due to standing losses.
boilers	bool	{true, false}	Add option for transforming gas into heat using gas boilers.
oil_boilers	bool	{true, false}	Add option for transforming oil into heat using boilers.
chp	bool	{true, false}	Add option for using Combined Heat and Power (CHP).
micro_chp	bool	{true, false}	Add option for using gas-fired Combined Heat and Power (CHP) for decentral areas.
solar_thermal_collector			Solar thermal collector settings for heat sector profiles and network build-out.
-- enable	bool	{true, false}	Add option for using solar thermal to generate heat.
-- cf_correction	float	nan	Correction factor applied to atlite's raw solar thermal output to match observed collector yields.
-- clearsky_model	str	{simple, enhanced}	Clearsky irradiance model for diffuse irradiation. 'enhanced' also uses ambient temperature and relative humidity.
-- orientation
-- -- slope	float	[0, 90]	Tilt angle of solar thermal collector.
-- -- azimuth	float	[0, 360]	Azimuth angle of solar thermal collector (180 = south-facing).
heat_pump_sink_T	celsius	nan	The temperature heat sink used in heat pumps based on DTU / large area radiators. The value is conservatively high to cover hot water and space heating in poorly-insulated buildings.
time_dep_hp_cop	bool	{true, false}	Consider the time dependent coefficient of performance (COP) of the heat pump.

land transport sector

  # ------------------- Land transport sector -------------------
  bev_plug_to_wheel_efficiency: 0.2 #kWh/km from EPA https://www.fueleconomy.gov/feg/ for Tesla Model S
  bev_charge_efficiency: 0.9 #BEV (dis-)charging efficiency
  transport_heating_deadband_upper: 20.
  transport_heating_deadband_lower: 15.
  ICE_lower_degree_factor: 0.375 #in per cent increase in fuel consumption per degree above deadband
  ICE_upper_degree_factor: 1.6
  EV_lower_degree_factor: 0.98
  EV_upper_degree_factor: 0.63
  bev_avail_max: 0.95
  bev_avail_mean: 0.8
  bev_dsm_restriction_value: 0.75 #Set to 0 for no restriction on BEV DSM
  bev_dsm_restriction_time: 7 #Time at which SOC of BEV has to be dsm_restriction_value
  v2g: true #allows feed-in to grid from EV battery
  bev_dsm: true #turns on EV battery
  bev_energy: 0.05 #average battery size in MWh
  bev_availability: 0.5 #How many cars do smart charging
  transport_fuel_cell_efficiency: 0.5
  transport_internal_combustion_efficiency: 0.3

  land_transport_fuel_cell_share: # 1 means all FCEVs HERE
    BU_2030: 0.00
    AP_2030: 0.004
    NZ_2030: 0.02
    DF_2030: 0.01
    AB_2030: 0.01
    BU_2050: 0.00
    AP_2050: 0.06
    NZ_2050: 0.28
    DF_2050: 0.08
  land_transport_electric_share: # 1 means all EVs  # This leads to problems when non-zero HERE
    BU_2030: 0.00
    AP_2030: 0.075
    NZ_2030: 0.13
    DF_2030: 0.01
    AB_2030: 0.01
    BU_2050: 0.00
    AP_2050: 0.42
    NZ_2050: 0.68
    DF_2050: 0.011

  dynamic_transport:
    enable: false # If "True", then the BEV and FCEV shares are obtained depending on the "Co2L"-wildcard (e.g. "Co2L0.70: 0.10"). If "False", then the shares are obtained depending on the "demand" wildcard and "planning_horizons" wildcard as listed below (e.g. "DF_2050: 0.08")
    land_transport_fuel_cell_share:
      Co2L2.0: 0.01
      Co2L1.0: 0.01
      Co2L0.90: 0.01
      Co2L0.80: 0.01
      Co2L0.70: 0.01
      Co2L0.60: 0.01
      Co2L0.50: 0.01
      Co2L0.40: 0.01
      Co2L0.30: 0.01
      Co2L0.20: 0.01
      Co2L0.10: 0.01
      Co2L0.00: 0.01
    land_transport_electric_share:
      Co2L2.0: 0.00
      Co2L1.0: 0.01
      Co2L0.90: 0.03
      Co2L0.80: 0.06
      Co2L0.70: 0.10
      Co2L0.60: 0.17
      Co2L0.50: 0.27
      Co2L0.40: 0.40
      Co2L0.30: 0.55
      Co2L0.20: 0.69
      Co2L0.10: 0.80
      Co2L0.00: 0.88

Parameter	Unit	Values	Description
bev_plug_to_wheel_efficiency	kWh/km	nan	The distance traveled per energy used of battery electric vehicles (BEV). Default inputs are based on EPA estimation for Tesla Model S https://www.fueleconomy.gov/feg/.
bev_charge_efficiency	float	[0, 1]	Battery electric vehicles (BEV) charge and discharge efficiency.
transport_heating_deadband_upper	float	nan	The maximum temperature in the vehicle. At higher temperatures, the energy required for cooling in the vehicle increases.
transport_heating_deadband_lower	float	nan	The minimum temperature in the vehicle. At lower temperatures, the energy required for heating in the vehicle increases.
ICE_lower_degree_factor	float	nan	Share increase in energy demand in internal combustion engine (ICE) for each degree difference between the cold environment and the minimum temperature.
ICE_upper_degree_factor	float	nan	Share increase in energy demand in internal combustion engine (ICE) for each degree difference between the hot environment and the maximum temperature.
EV_lower_degree_factor	float	nan	Share increase in energy demand in electric vehicles (EV) for each degree difference between the cold environment and the minimum temperature.
EV_upper_degree_factor	float	nan	Share increase in energy demand in electric vehicles (EV) for each degree difference between the hot environment and the maximum temperature.
bev_avail_max	float	[0, 1]	The maximum share plugged-in availability for passenger electric vehicles.
bev_avail_mean	float	[0, 1]	The average share plugged-in availability for passenger electric vehicles.
bev_dsm_restriction_value	float	nan	Adds a lower state of charge (SOC) limit for battery electric vehicles (BEV) to manage its own energy demand (DSM). Located in prepare_transport_data.py <https://github.com/PyPSA/pypsa-earth/blob/master/scripts/prepare_transport_data.py>_. Set to 0 for no restriction on BEV DSM.
bev_dsm_restriction_time	float	nan	Time at which SOC of BEV has to be dsm_restriction_value.
v2g	bool	{true, false}	Allows feed-in to grid from EV battery. This is only enabled if BEV demand-side management is enabled, and the share of vehicles participating is V2G is given by bev_availability.
bev_dsm	bool	{true, false}	Add the option for battery electric vehicles (BEV) to participate in demand-side management (DSM).
bev_energy	MWh/car	nan	The average size of battery electric vehicles (BEV) in MWh.
bev_availability	float	nan	The share for battery electric vehicles (BEV) that are able to do demand side management (DSM).
transport_fuel_cell_efficiency	float	[0, 1]	The H2 conversion efficiencies of fuel cells in transport.
transport_internal_combustion_efficiency	float	[0, 1]	The oil conversion efficiencies of internal combustion engine (ICE) in transport.
land_transport_fuel_cell_share	float/dict	[0, 1] or {demand}_{planning_horizons}: [0, 1]	The share of vehicles that uses fuel cells in a given demand wildcard and given year.
land_transport_electric_share	float/dict	[0, 1] or {demand}_{planning_horizons}: [0, 1]	The share of vehicles that uses electric vehicles (EV) in a given demand wildcard and given year.
dynamic_transport
-- enable	bool	{true, false}	If 'True', then the BEV and FCEV shares are obtained depending on the 'Co2L'-wildcard (e.g. 'Co2L0.70: 0.10'). If 'False', then the shares are obtained depending on the 'demand' wildcard and 'planning_horizons' wildcard as listed below (e.g. 'DF_2050: 0.08')
-- land_transport_fuel_cell_share	float/dict	[0, 1] or {opts}_{planning_horizons}: [0, 1]	The share of vehicles that uses fuel cells in a given Co2L wildcard and given year.
-- land_transport_electric_share	float/dict	[0, 1] or {opts}_{planning_horizons}: [0, 1]	The share of vehicles that uses electric vehicles (EV) in a given Co2L wildcard and given year.

biomass sector

  # ------------------- Biomass sector -------------------
  biomass_transport: true # biomass transport between nodes
  biomass_transport_default_cost: 0.1 #EUR/km/MWh
  solid_biomass_potential: 40 # TWh/a, Potential of whole modelled area
  biogas_potential: 0.5 # TWh/a, Potential of whole modelled area

Parameter	Unit	Values	Description
biomass_transport	bool	{true, false}	Add option for transporting solid biomass between nodes.
biomass_transport_default_cost	currency/km/MWh	nan	The cost of transporting one MWh of biomass per kilometer.
solid_biomass_potential	TWh/a	nan	The solid biomass potential in the model per year and investment period.
biogas_potential	TWh/a	nan	The biogas potential in the model per year and investment period.

electricity distribution grid

  # ------------------- Electricity distribution grid -------------------
  electricity_distribution_grid: true # adds low voltage buses and shifts AC loads, BEVs, heat pumps, and resistive heaters, micro CHPs to low voltage buses if technologies are present
  enable_electricity_connection_cost: false # adds electricity grid connection costs to fixed capital costs for solar and onwind generators in prepare_sector_network.
  solar_rooftop: # adds distribution side customer rooftop PV (only work if electricity_distribution_grid: true)
    enable: true
    kW_per_m2: 0.1
    m2_per_person: 20
    use_building_size: false
    # proportion of rooftop suitable for PV installation
    install_ratio:
      0: 0
      10: 0.3
      100: 0.36
      200: 0.41
      450: 0.49
      2300: 0.66
    # maximum distance [km] to allocate a building within the nearest bus shapes
    tolerance: 100

  home_battery: true # adds home batteries to low voltage buses ((only work if electricity_distribution_grid: true)
  transmission_efficiency:
    electricity distribution grid:
      efficiency_static: 0.97 # efficiency of distribution grid (i.e. 3% loses)
    H2 pipeline:
      efficiency_per_1000km: 1
      compression_per_1000km: 0.017 # DEA technology data. Mean of  Energy losses, lines 5000-20000 MW and lines >20000 MW for 2020, 2030 and 2050, [%/1000 km]

Parameter	Unit	Values	Description
electricity_distribution_grid	bool	{true, false}	Add a simplified representation of the exchange capacity between transmission and distribution grid level through a link.
enable_electricity_connection_cost	bool	{true, false}	Adds electricity grid connection costs to fixed capital costs for solar and onwind generators in prepare_sector_network.
solar_rooftop
-- enable	bool	{true, false}	Add option for using solar rooftops to generate electricity in the distribution grid level.
-- kW_per_m2	kW/m2	nan	Estimate the kW of PV that can be installed per square meter of rooftop.
-- m2_per_person	m2/person	nan	If use_building_size is False, estimate the size of rooftop per capita.
-- use_building_size	bool	{true, false}	If True, estimate the area where solar rooftops can be placed using global building datasets.
-- install_ratio	dict	rooftop size: percentage of rooftop area	The usable solar rooftop area for buildings when considering that only a portion of each rooftop can be allocated for PV installation based on its size.
-- tolerance	nan	nan	Maximum distance in kilometers for spatial join to find nearest country shapes.
home_battery	bool	{true, false}	Add option for using home batteries to store electricity in the distribution grid level.
transmission_efficiency
-- electricity distribution grid
-- -- efficiency_static	float	[0, 1]	Electricity distribution grid transmission efficiency.
-- H2 pipeline
-- -- efficiency_per_1000km	1/1000km	nan	H2 pipeline transmission efficiency per 1000km
-- -- compression_per_1000km	1/1000km	nan	H2 pipeline transmission compression demand per 1000km

shipping & aviation sector

  # ------------------- Shipping & aviation sector -------------------
  shipping_hydrogen_liquefaction: false
  shipping_average_efficiency: 0.4 #For conversion of fuel oil to propulsion in 2011
  shipping_hydrogen_share: #1.0
    BU_2030: 0.00
    AP_2030: 0.00
    NZ_2030: 0.10
    DF_2030: 0.05
    AB_2030: 0.05
    BU_2050: 0.00
    AP_2050: 0.25
    NZ_2050: 0.36
    DF_2050: 0.12
  airport_sizing_factor: 3
  international_bunkers: false #Whether or not to count the emissions of international aviation and navigation

Parameter	Unit	Values	Description
shipping_hydrogen_liquefaction	bool	{true, false}	Whether to include liquefaction costs for hydrogen demand in shipping.
shipping_average_efficiency	float	[0, 1]	The efficiency of hydrogen-powered ships in the conversion of hydrogen to meet shipping needs (fuel cell).
shipping_hydrogen_share	float/dict	[0, 1] or {demand}_{planning_horizons}: [0, 1]	The share of ships powered by hydrogen in a given year.
airport_sizing_factor	float	nan	Size of large airports relative to medium-sized airports.
international_bunkers	bool	{true, false}	Whether or not to count the emissions of international aviation and navigation

ccus & conversion options

  # ------------------- CCUS & conversion options -------------------
  co2_network: true
  co2_sequestration_potential: 200 #MtCO2/a sequestration potential for Europe
  co2_sequestration_cost: 10 #EUR/tCO2 for sequestration of CO2

  methanation: true
  helmeth: true
  dac: true
  cc_fraction: 0.9
  cc: true
  fischer_tropsch: true
  min_part_load_fischer_tropsch: 0.9

Parameter	Unit	Values	Description
co2_network	bool	{true, false}	Add option for planning a new carbon dioxide transmission network.
co2_sequestration_potential	MtCO2/a	nan	The potential of sequestering CO2 in the model per year and investment period.
co2_sequestration_cost	currency/tCO2	nan	The cost of sequestering a ton of CO2 (currency/tCO2).
methanation	bool	{true, false}	Add option for transforming hydrogen and CO2 into methane using methanation.
helmeth	bool	{true, false}	Add option for transforming electricity and CO2 into methane using HELMETH (Integrated High-Temperature ELectrolysis and METHanation).
dac	bool	{true, false}	Add option for Direct Air Capture (DAC).
cc_fraction	float	[0, 1]	The default fraction of CO2 captured with post-combustion capture.
cc	bool	{true, false}	Add option for carbon capture (CC).
fischer_tropsch	bool	{true, false}	Add option for converting H2 and CO2 into oil (Fischer Tropsch).
min_part_load_fischer_tropsch	float	[0, 1]	The minimum unit dispatch (p_min_pu) for the Fischer-Tropsch process.

industry options

  # ------------------- Industry options -------------------
  industry_util_factor: 0.7

  efficiency_heat_oil_to_elec: 0.9
  efficiency_heat_biomass_to_elec: 0.9
  efficiency_heat_gas_to_elec: 0.9

Parameter	Unit	Values	Description
industry_util_factor	float	[0, 1]	Industry utility fraction in generating process emission
efficiency_heat_oil_to_elec	float	[0, 1]	The heat efficiency of oil if that energy is supplied using electricity instead. Used to determine residential electricity.
efficiency_heat_biomass_to_elec	float	[0, 1]	The heat efficiency of biomass if that energy is supplied using electricity instead. Used to determine residential electricity.
efficiency_heat_gas_to_elec	float	[0, 1]	The heat efficiency of gas if that energy is supplied using electricity instead. Used to determine residential electricity.

powerplants options

  # ------------------- Powerplants options -------------------
  conventional_generation: # generator : carrier
    OCGT: gas
    CCGT: gas
    oil: oil
    coal: coal
    lignite: lignite
    biomass: biomass
  keep_existing_capacities: false

  marginal_cost_storage: 0

Parameter	Unit	Values	Description
conventional_generation	dict	generator : carrier	Add a more detailed description of conventional carriers. Any power generation requires the consumption of fuel from nodes representing that fuel.
keep_existing_capacities	bool	{true, false}	Add options to keep powerplant capacities previously assigned in add_electricity.
marginal_cost_storage	currency/MW	nan	The default marginal cost of storage technologies.

Solving

Options under the SOLVING banner in config.default.yaml: solver choice, linear formulation, load shedding, iteration settings, solver presets, and memory limit.

solver

  solver:
    name: gurobi
    options: gurobi-default

Parameter	Unit	Values	Description
name	--	One of {'gurobi', 'cplex', 'cbc', 'glpk', 'ipopt'}; potentially more possible	Solver to use for optimisation problems in the workflow; e.g. clustering and linear optimal power flow.
opts	--	Parameter list for Gurobi and CPLEX	Solver specific parameter settings.

options

  # ------------------- Optimization options -------------------
  options:
    load_shedding: 100 # Set to "false" or willingness to pay in €/kWh, e.g. 100 €/kWh (intersect between macroeconomic and surveybased willingness to pay https://doi.org/10.3389/fenrg.2015.00055)
    noisy_costs: true
    formulation: kirchhoff
    min_iterations: 4
    max_iterations: 6
    clip_p_max_pu: 0.01
    skip_iterations: true
    track_iterations: false
    # nhours: 10

Parameter	Unit	Values	Description
load_shedding	--	Either 'false' or float	Add generators with a prohibitively high marginal cost to simulate load shedding. Choose 'false' to turn off or alternatively add willingness to pay for load shedding in EUR/kWh
noisy_costs	bool	{true, false}	Add random noise to marginal cost of generators and capital cost of lines and links.
formulation	--	{angles, kirchhoff, cycles, ptdf}	Specifies which variant of linearized power flow formulations to use in the optimisation problem. Recommended is 'kirchhoff'.
min_iterations	--	int	Minimum number of solving iterations in between which resistance and reactance (x/r) are updated for branches according to s_nom_opt of the previous run.
max_iterations	--	int	Maximum number of solving iterations in between which resistance and reactance (x/r) are updated for branches according to s_nom_opt of the previous run.
clip_p_max_pu	p.u.	float	To avoid too small values in the renewables per-unit availability time series values below this threshold are set to zero.
skip_iterations	bool	{true, false}	Skip iterating, do not update impedances of branches.
track_iterations	bool	{true, false}	Flag whether to store the intermediate branch capacities and objective function values are recorded for each iteration.
nhours	--	int	Specifies the n first snapshots to take into account. Must be less than the total number of snapshots. Recommended only for debugging.

Plotting

Options under the PLOTTING banner in config.default.yaml: map layout, plot thresholds, technology groupings, carrier colours, and display names.

plotting:
  map:
    figsize: [7, 7]
    boundaries: [-10.2, 29, 35, 72]
    p_nom:
      bus_size_factor: 5.e+4
      linewidth_factor: 3.e+3
    color_geomap:
      ocean: white
      land: whitesmoke

  costs_max: 10
  costs_threshold: 0.2

  energy_max: 20000
  energy_min: -20000
  energy_threshold: 15

  vre_techs:
  - onwind
  - offwind-ac
  - offwind-dc
  - solar
  - ror
  conv_techs:
  - OCGT
  - CCGT
  - nuclear
  - Nuclear
  - coal
  - oil
  storage_techs:
  - hydro+PHS
  - battery
  - H2
  renewable_storage_techs:
  - PHS
  - hydro
  load_carriers:
  - AC load
  AC_carriers:
  - AC line
  - AC transformer
  link_carriers:
  - DC line
  - Converter AC-DC
  heat_links:
  - heat pump
  - resistive heater
  - CHP heat
  - CHP electric
  - gas boiler
  - central heat pump
  - central resistive heater
  - central CHP heat
  - central CHP electric
  - central gas boiler
  heat_generators:
  - gas boiler
  - central gas boiler
  - solar thermal collector
  - central solar thermal collector

  tech_colors:
    onwind: "#235ebc"
    onshore wind: "#235ebc"
    offwind: "#6895dd"
    offwind-ac: "#6895dd"
    offshore wind: "#6895dd"
    offshore wind ac: "#6895dd"
    offshore wind (AC): "#6895dd"
    offwind-dc: "#74c6f2"
    offshore wind dc: "#74c6f2"
    offshore wind (DC): "#74c6f2"
    wave: "#004444"
    hydro: "#08ad97"
    hydro+PHS: "#08ad97"
    PHS: "#08ad97"
    hydro reservoir: "#08ad97"
    hydroelectricity: "#08ad97"
    ror: "#4adbc8"
    run of river: "#4adbc8"
    solar: "#f9d002"
    solar PV: "#f9d002"
    solar thermal: "#ffef60"
    solar rooftop: "#ffef60"
    biomass: "#0c6013"
    solid biomass: "#06540d"
    solid biomass for industry co2 from atmosphere: "#654321"
    solid biomass for industry co2 to stored: "#654321"
    solid biomass for industry CC: "#654321"
    biogas: "#23932d"
    waste: "#68896b"
    geothermal: "#ba91b1"
    OCGT: "#d35050"
    OCGT marginal: "sandybrown"
    OCGT-heat: "#ee8340"
    CCGT: "#b80404"
    gas: "#d35050"
    natural gas: "#d35050"
    gas boiler: "#ee8340"
    gas boilers: "#ee8340"
    gas boiler marginal: "#ee8340"
    gas-to-power/heat: "brown"
    SMR: "#4F4F2F"
    SMR CC: "darkblue"
    oil: "#262626"
    oil boiler: "#B5A642"
    oil emissions: "#666666"
    gas for industry: "#333333"
    gas for industry CC: "brown"
    gas for industry co2 to atmosphere: "#654321"
    gas for industry co2 to stored: "#654321"
    nuclear: "#ff9000"
    Nuclear: "r"
    Nuclear marginal: "r"
    uranium: "r"
    coal: "#707070"
    Coal: "k"
    Coal marginal: "k"
    lignite: "#9e5a01"
    Lignite: "grey"
    Lignite marginal: "grey"
    H2: "#ea048a"
    H2 export: "#ea048a"
    H2 for industry: "#222222"
    H2 for shipping: "#6495ED"
    H2 liquefaction: "m"
    hydrogen storage: "#ea048a"
    battery: "slategray"
    battery discharger: "slategray"
    battery charger: "slategray"
    EV battery storage: "slategray"
    home battery: "#614700"
    home battery storage: "#614700"
    lines: "#70af1d"
    transmission lines: "#70af1d"
    AC: "#70af1d"
    AC-AC: "#70af1d"
    AC line: "#70af1d"
    links: "#8a1caf"
    HVDC links: "#8a1caf"
    DC: "#8a1caf"
    DC-DC: "#8a1caf"
    DC link: "#8a1caf"
    load: "#ff0000"
    load shedding: "#ff0000"
    Electric load: "b"
    electricity: "k"
    electric demand: "k"
    electricity distribution grid: "y"
    heat: "darkred"
    Heat load: "r"
    heat pumps: "#76EE00"
    heat pump: "#76EE00"
    air heat pump: "#76EE00"
    ground heat pump: "#40AA00"
    CHP: "r"
    CHP heat: "r"
    CHP electric: "r"
    heat demand: "darkred"
    rural heat: "#880000"
    central heat: "#b22222"
    decentral heat: "#800000"
    low-temperature heat for industry: "#991111"
    process heat: "#FF3333"
    power-to-heat: "red"
    resistive heater: "pink"
    Sabatier: "#FF1493"
    methanation: "#FF1493"
    power-to-gas: "purple"
    power-to-liquid: "darkgreen"
    helmeth: "#7D0552"
    DAC: "deeppink"
    co2 stored: "#123456"
    CO2 pipeline: "gray"
    CO2 sequestration: "#123456"
    co2: "#123456"
    co2 vent: "#654321"
    process emissions: "#222222"
    process emissions CC: "gray"
    process emissions to stored: "#444444"
    process emissions to atmosphere: "#888888"
    agriculture heat: "#D07A7A"
    agriculture machinery oil: "#1e1e1e"
    agriculture machinery oil emissions: "#111111"
    agriculture electricity: "#222222"
    Fischer-Tropsch: "#44DD33"
    kerosene for aviation: "#44BB11"
    naphtha for industry: "#44FF55"
    land transport oil: "#44DD33"
    land transport oil emissions: "#666666"
    land transport fuel cell: "#AAAAAA"
    land transport EV: "grey"
    V2G: "grey"
    BEV charger: "grey"
    shipping: "#6495ED"
    shipping oil: "#6495ED"
    shipping oil emissions: "#6495ED"
    water tanks: "#BBBBBB"
    hot water storage: "#BBBBBB"
    hot water charging: "#BBBBBB"
    hot water discharging: "#999999"
    Li ion: "grey"
    district heating: "#CC4E5C"
    retrofitting: "purple"
    building retrofitting: "purple"
    solid biomass transport: "green"
    biomass EOP: "green"
    high-temp electrolysis: "magenta"
    today: "#D2691E"
    Ambient: "k"
    industry coal emissions: "#654321"
    agriculture oil: "#1e1e1e"
    gas emissions: "#666666"
    industry oil emissions: "#654321"
    industry electricity: "#222222"
    rail transport electricity: "grey"
    solid biomass for industry: "#654321"
    rail transport oil: "#44DD33"
    low voltage: "y"


  nice_names:
    OCGT: Open-Cycle Gas
    CCGT: Combined-Cycle Gas
    offwind-ac: Offshore Wind (AC)
    offwind-dc: Offshore Wind (DC)
    onwind: Onshore Wind
    solar: Solar
    PHS: Pumped Hydro Storage
    hydro: Reservoir & Dam
    battery: Battery Storage
    H2: H2
    lines: Transmission Lines
    ror: Run of River

Parameter	Unit	Values	Description
map	nan	nan	nan
-- figsize	--	[width, height]; e.g. [7,7]	Figure size in inches.
-- boundaries	°	[x1,x2,y1,y2]	Boundaries of the map plots in degrees latitude (y) and longitude (x)
-- p_nom	nan	nan	nan
-- -- bus_size_factor	--	float	Factor by which values determining bus sizes are scaled to fit well in the plot.
-- -- linewidth_factor	--	float	Factor by which values determining bus sizes are scaled to fit well in the plot.
costs_max	bn Euro	float	Upper y-axis limit in cost bar plots.
costs_threshold	bn Euro	float	Threshold below which technologies will not be shown in cost bar plots.
energy_max	TWh	float	Upper y-axis limit in energy bar plots.
energy_min	TWh	float	Lower y-axis limit in energy bar plots.
energy_threshold	TWh	float	Threshold below which technologies will not be shown in energy bar plots.
tech_colors	--	carrier -> HEX colour code	Mapping from network carrier to a colour (HEX colour code).
nice_names	--	str -> str	Mapping from network carrier to a more readable name.