Configuration#
How configuration is layered#
workflow/Snakefile loads its whole base out of the tracked
workflow/repo_data/config/ templates, in this order:
file |
holds |
|---|---|
|
HPC scheduler settings and the per-rule |
|
renewable/atlite plumbing that rarely changes per scenario |
|
figure styling |
|
API-key placeholders |
|
sector-coupling defaults |
|
the scenario base — every user-facing knob, with defaults |
Two optional per-user overlays follow (config/config.api.yaml,
config/config.slurm.yaml, seeded by init_pypsa_usa.sh), and whatever you
pass with --configfile is merged last.
Because config.default.yaml is itself a loaded layer, your scenario config is
an overlay, not a fork: it only needs the keys it actually changes. Nested
mappings merge key by key; lists and scalars are replaced wholesale, so a list
you change must be restated in full.
Every top-level key is owned by exactly one file — nothing is defined twice across layers.
The one value that does not come from a file at all is the EIA API key: workflow/Snakefile
reads $EIA_API_KEY from the environment and it takes precedence over api: eia: in
config/config.api.yaml, which keeps the secret out of the checkout entirely. The key is
optional: a default power-only run never calls the EIA API. It is only required for dynamic
fuel prices (conventional: dynamic_fuel_price: enable: true), sector-coupled/AEO-scaled
demand, trade cost lookups and the validation plots.
Validation#
The merged configuration is checked against workflow/schemas/config.schema.yaml
at parse time. The check covers the top-level structure, the enum-typed knobs
(foresight, electricity: retirement, renewable: dataset, clustering
algorithms, ATB scenario/model case, solver names, …) and closes the
well-bounded sections such as electricity: and model_topology: against
unknown keys — so a misspelling like retirment: fails immediately instead of
silently falling back to a default several rules later. The top level itself
stays open, since Snakemake and the scenarios feature inject keys there.
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.
run:
name: "Default" # label that becomes the resources/<name>/ subdir; pick something unique per scenario
disable_progressbar: false # silence atlite/snakemake progress bars in non-interactive shells
shared_resources: false # true = reuse resources/ across all runs (DAG-keyed); false = isolate per run.name
shared_cutouts: true # true = share atlite cutouts across runs (recommended; cutouts are large and slow)
validation: false # true = wire in back-casting validation plots (historical-only)
benchmark_cpuc: false # true = compare installed capacity against the CPUC Baseline Generator List (California runs)
benchmark_cpuc_horizons: [2026] # benchmark year(s); 2026 = today's fleet vs today's baseline (network-free). Empty list = use scenario planning_horizons
# NB: the whole `renewable:` block — including `renewable.dataset`
# (atlite | godeeep), which used to be duplicated here — lives in
# config.common.yaml, which owns that key outright. See
# docs/source/config-configuration.md#renewable-godeeep.
#
# `godeeep` retrieves its CF files through the `godeeep_cf_registry`
# block in config.common.yaml: every (dataset, year) the run may fetch is
# declared there, sources are tried in order, and an undeclared
# dataset/year fails at parse time naming the dataset key, the requested
# year and the years each source offers. Nothing is substituted silently.
# ====================================================================
# SCENARIO — workflow wildcards and planning horizons
# ====================================================================
# Each list entry becomes a separate run in the Snakemake DAG. Most
# users set a single value per wildcard. See docs/source/config-wildcards.md.
Unit |
Values |
Description |
|
|---|---|---|---|
name |
– |
any string |
Specify a name for your run. Results will be stored under this name. |
disable_progressbar |
bool |
{true, false} |
Switch to select whether progressbar should be disabled. |
shared_resources |
bool |
{true, false} |
Switch to select whether resources should be shared across runs. |
shared_cutouts |
bool |
{true, false} |
Switch to select whether cutouts should be shared across runs. |
validation |
bool |
{true, false} |
Switch to enable back-casting validation plotting |
benchmark_cpuc |
bool |
{true, false} |
Switch to enable the CPUC Baseline Generator List capacity benchmark (California runs) |
benchmark_cpuc_horizons |
list |
years from the CPUC list horizon range |
Benchmark year(s) for the CPUC capacity comparison; default [2026] compares today’s fleet against today’s baseline without any network build. Empty list falls back to scenario planning_horizons. |
scenario#
The scenario section is used for setting the wildcards and defining planning horizon settings. All configurations within this section are described in wildcards with the exception of planning_horizons and foresight.
Planning horizons determines which year(s) of future demand forecast to use for your planning model. To build a multi-investment period model set multiple planning_horizons: years. The foresight: option specifies whether perfect foresight or myopic foresight optimization model is developed. In perfect foresight, a monolithic model is developed where all planning_horizons specified are optimized at once, e.g. future horizon values of costs and demand are incorporated into decisions made in earlier planning horizons. Myopic optimization solves each planning horizon sequentially, and passes the results forward.
scenario:
interconnect: [western] # geographic scope; one of: usa | texas | western | eastern
planning_horizons: [2030, 2040, 2050] # investment-period years (2018-2023 | 2030 | 2040 | 2050)
clusters: [33] # final cluster count; plain integer keeps renewable resource zones (== m); suffix s / a / c or "all"
simpl: [75] # pre-clustering kmeans granularity; alphanumeric or "all"
ll: [v1.0] # line-limit scenario; v|c + number/opt/all (e.g. v1.0, copt)
opts: [REM-3h] # dash/plus-separated options string (REM = renewable-energy mix, 3h = 3-hour temporal resolution)
sector: "" # sector-coupling; "" (electricity-only) | E | G | E-G
foresight: 'perfect' # multi-horizon solve mode; perfect (monolithic) | myopic (sequential)
# ====================================================================
# MODEL TOPOLOGY — transmission backbone and zonal aggregation
# ====================================================================
Unit |
Values |
Description |
|
|---|---|---|---|
planning_horizons |
int |
(2018-2023, 2030, 2040, 2050) |
Specifies the year of demand data to use. Historical values will use EIA930 data, Future years will use NREL EFS data. Specify multiple planning horizons to build a multi-horizon model. |
foresight |
str |
One of {‘perfect’,’myopic’} |
Specifies foresight option for multi-horizon optimization. |
model_topology#
The model_topology section selects the transmission backbone and the spatial zones the final
network is aggregated to. transmission_network chooses between the ReEDS zonal backbone and the
TAMU synthetic nodal network; topological_boundaries sets the zone type used after clustering
(county, REeDS zone, state, or balancing area). Use include to subset the modeled footprint to
specific zones, states, or balancing authorities (mixed zone types are not supported), and
aggregate to pre-aggregate buses into larger regions. interface_transmission_limits switches
on the aggregate inter-regional transfer limits read from
electricity: transmission_interface_limits and requires the ReEDS backbone; the limits are
applied in solve_network as a per-snapshot cap on the total flow across each interface, and
constrain only the import/export links, so they are inert unless electricity: imports or
electricity: exports is enabled. See Spatial Configuration for a worked California example
(workflow/repo_data/config/config.california.yaml) at both REeDS-zone and county resolution.
model_topology:
transmission_network: 'reeds' # transmission dataset; reeds | tamu
topological_boundaries: 'reeds_zone' # post-cluster zone type; county | reeds_zone | state
interface_transmission_limits: false # apply NARIS2024 inter-region transfer caps (requires reeds backbone)
# KEEP THIS NULL, not {}. build_base_network treats "not None" as "the user
# asked for a footprint filter" and then asserts that topological_boundaries
# is not 'state'; an empty mapping would trip that assertion on every
# state-resolution run even though no filtering was requested.
include: # subset the network to specific zones (mixed zone types NOT supported)
# reeds_zone: [] # restrict by REeDS zone ids
# reeds_state: ['CA'] # restrict by state code(s)
# reeds_ba: [] # restrict by balancing authority
aggregate: {} # pre-aggregate buses; eligible keys: reeds_zone | trans_reg
# trans_grp: [] # (empty mapping = no aggregation; the only
# reeds_zone: [] # consumer is a truthiness check in cluster_network)
# ====================================================================
# ENABLE — top-level feature flags
# ====================================================================
enable#
Top-level feature flags. build_cutout switches between consuming the prebuilt atlite cutouts
downloaded from Zenodo (the default) and building a fresh cutout from raw ERA5 data, which is slow
and requires a CDS API key. The optional custom_busmap flag makes cluster_network read a
user-provided busmap from data/{interconnect}/custom_busmap_{clusters}.csv instead of computing
one; custom busmaps must key on the bus IDs produced by the cluster_resources stage.
enable:
build_cutout: false # true = build a fresh atlite cutout from raw ERA5 (slow); false = consume prebuilt
# custom_busmap: false # OPTIONAL: read a user-provided busmap from data/ instead of computing one
# ====================================================================
# SNAPSHOTS & WEATHER YEARS — temporal scope
# ====================================================================
# For Atlite (any year) and GODEEEP-historical, configure renewable_weather_years.
# For GODEEEP future scenarios, the year is taken from planning_horizons above.
# Under `godeeep` the first entry must be a year declared for the requested
# dataset in `godeeep_cf_registry` (config.common.yaml) — the Oak mirror covers
# 1980-2022 historical, Zenodo publishes only 2012. An undeclared year is a
# parse-time error, never a silent swap to a neighbouring year.
pudl_path#
Points the build scripts at a versioned release of the PUDL
(Public Utility Data Liberation) parquet outputs, which supply the EIA-860, EIA-923, and CEMS
tables used to build powerplants and fuel prices. Bump the version tag to pull fresher data, or
point it at a local file:// mirror for offline runs. This key lives in config.common.yaml
since it rarely changes per scenario.
pudl_path: s3://pudl.catalyst.coop/v2026.8.0 # versioned S3 prefix to PUDL parquet outputs (or a local file:// path)
# ====================================================================
# RENEWABLE — per-technology resource and land-availability settings
# ====================================================================
# These knobs feed `build_renewable_profiles`. The atlite resource:
# method, capacity_per_sqkm, and the corine/natura/cec/boem land
# screens together define each cell's potential and per-hour CF.
snapshots#
Specifies the temporal range to build an energy system model for as arguments to pandas.date_range
snapshots:
start: "2019-01-01" # ISO date string; first snapshot timestamp
end: "2020-01-01" # ISO date string; one past the last snapshot if inclusive=left
inclusive: "left" # pandas.date_range inclusive arg; left | right | both | neither
# GODEEEP future-scenario controls. Used only when renewable.dataset = godeeep
# (set in config.common.yaml) and renewable_scenarios != "historical".
# `add_electricity.py` and `build_electricity.smk` index renewable_scenarios[0]
# directly whenever the dataset is godeeep, so the key must stay defined.
# Future-scenario CF years come from scenario.planning_horizons above; the
# (scenario, hub height, year) triple must be declared in `godeeep_cf_registry`
# (config.common.yaml). Note rcp45hotter is published for solar only — its
# wind_125m Zenodo record is unregistered.
Unit |
Values |
Description |
|
|---|---|---|---|
start |
– |
str or datetime-like; e.g. YYYY-MM-DD |
Left bound of date range |
end |
– |
str or datetime-like; e.g. YYYY-MM-DD |
Right bound of date range |
inclusive |
– |
One of {‘neither’, ‘both’, ‘left’, ‘right’} |
Make the time interval closed to the |
renewable_weather_years#
Sets the weather year(s) the renewable capacity-factor time series are built for. With
renewable.dataset: atlite any year with a matching cutout works; with godeeep this key is only
used when renewable_scenarios is historical — for future climate scenarios the year is taken
from planning_horizons instead. The optional commented renewable_weather_years_by_horizon
mapping assigns a different weather year to each planning horizon in multi-horizon atlite runs.
renewable_weather_years: [2019] # weather years to use (single year unless multi-horizon godeeep)
renewable_scenarios#
Selects the GODEEEP climate scenario used for renewable capacity factors — one historical record
or four future climate projections. Only consumed when renewable.dataset: godeeep; see
renewable: godeeep for how scenarios, years, and snapshots interact.
renewable_scenarios: ["rcp85cooler"] # climate scenario; historical | rcp45cooler | rcp45hotter | rcp85cooler | rcp85hotter
# For multi-horizon godeeep, the YEAR is taken from each planning_horizon
# automatically — these knobs only set the month/day slice within that year.
renewable_snapshots#
Sets the month/day window sampled within each weather year for GODEEEP-based runs. In
multi-horizon godeeep models the year itself comes from each planning horizon automatically, so
these knobs only control how much of the 8760-hour capacity-factor series is used;
end_inclusive: true keeps the full end day rather than stopping at midnight.
renewable_snapshots:
start_month: 1 # int 1-12; first month of the snapshot window
start_day: 1 # int 1-31
end_month: 12 # int 1-12; last month of the snapshot window
end_day: 31 # int 1-31
end_inclusive: true # true = include full end day; false = stop before end day
# ====================================================================
# ELECTRICITY — generators, storage, demand, reserves, trade
# ====================================================================
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
atlite:
default_cutout: era5_2019 # cutout name picked when a config does not specify one
nprocesses: 8 # atlite worker processes
show_progress: false # progress bar; false saves wall time
cutouts:
era5_2019:
module: era5 # weather data source; era5 (default) — see atlite docs
time: ['2019', '2019'] # [start, end] year strings (atlite consumes year-level)
interconnects: # bbox + grid resolution per interconnect
western:
x: [-126, -99] # longitude min/max
y: [27, 50] # latitude min/max
dx: 0.3 # x-grid resolution (degrees)
dy: 0.3 # y-grid resolution (degrees)
eastern:
x: [-109, -65]
y: [23, 50]
dx: 0.3
dy: 0.3
texas:
x: [-110, -90]
y: [24, 37]
dx: 0.3
dy: 0.3
usa:
x: [-126, -65]
y: [23, 50]
dx: 0.3
dy: 0.3
# ====================================================================
# OFFSHORE — offshore-shape source and OSW bus spacing
# ====================================================================
Unit |
Values |
Description |
|
|---|---|---|---|
default_cutout |
– |
str |
Defines a default cutout. |
nprocesses |
– |
int |
Number of parallel processes in cutout preparation |
show_progress |
bool |
true/false |
Whether progressbar for atlite conversion processes should be shown. False saves time. |
cutouts |
|||
– {name} |
– |
Convention is to name cutouts |
Defines an available cutout. On disk, cutouts are stored as |
– – module |
– |
Must be ‘era5’ |
Source of the reanalysis weather dataset (ERA5). |
– – time |
Year interval as strings, e.g. |
[start, end] years of weather data to include in the cutout (atlite consumes year-level bounds). |
|
interconnects |
Bounding box and grid resolution per interconnect, consumed by |
||
– {interconnect} |
One of |
||
– – x |
° |
Float interval within [-180, 180] |
Range of longitudes to download weather data for. |
– – y |
° |
Float interval within [-90, 90] |
Range of latitudes to download weather data for. |
– – dx |
° |
Larger than 0.25 |
Grid resolution for longitude |
– – dy |
° |
Larger than 0.25 |
Grid resolution for latitude |
electricity#
Specifies the types of generators that are included in the network, which are extendable, and the CO2 base for which the optimized reduction is relative to.
electricity:
conventional_carriers: [nuclear, oil, OCGT, CCGT, coal, geothermal, biomass, waste] # plant types attached as existing capacity from EIA-860
renewable_carriers: [onwind, offwind_floating, solar, hydro] # variable renewables attached as existing capacity
retirement: economic # economic = allow early retirement at fixed cost; technical = lock p_nom_min to p_nom
honor_planned_retirements: true # drop existing/proposed units at their EIA planned_generator_retirement_date (false = keep every existing unit indefinitely)
# Capacity-expansion candidates. Carriers listed here get extendable
# p_nom and pay annualized capex; carriers listed only above are
# fixed (brownfield-only).
extendable_carriers:
Generator: [solar, onwind, offwind_floating, OCGT, CCGT, CCGT-95CCS, coal, nuclear, hydrogen_ct]
StorageUnit: [4hr_battery_storage, 8hr_battery_storage] # Xhr_battery_storage (X = 2..10)
Store: [] # candidate Store carriers (e.g. H2_tank); requires sector coupling
Link: [] # candidate Link carriers (e.g. HVDC)
# ---------------- Out-of-state contracted resources (California) ----------------
# Adds the physically out-of-state resources the CPUC ledger attributes to
# California load regions (Palo Verde's SCE share, LADWP's Intermountain and
# Apex, the Hoover entitlements, ~2 GW of AZ/NV solar and battery contracts)
# back into a California-scoped model as generators at California buses, at
# their CONTRACTED capacity. Requires `demand: profile: servm` (the SERVM load
# weights decide which bus each region's contracts attach to).
remote_contracted_resources:
enable: false # attach CA-contracted out-of-state units at CA buses
file: repo_data/CPUC/servm_out_of_state_units.csv
# ---------------- Reserves & resource adequacy ----------------
SAFE_reservemargin: 0.14 # SAFE planning reserve margin (fraction of peak load); used with SAFE opt
SAFE_regional_reservemargins: 'repo_data/config/policy_constraints/SAFE_regional_prm.csv'
erm: # Energy Reserve Margin — only consumed when the ERM opt is enabled
all: 0.15 # default ERM applied to every region (fraction of annual energy)
# ---------------- Policy & emissions ----------------
# co2base: 2.4e9 # OPTIONAL: reference CO2 budget (tCO2/yr) scaled by the Co2L<x> opt; required by Co2L<x>
# co2limit_enable: false # OPTIONAL: system-wide CO2 cap on/off (a bare Co2L opt sets it true)
# co2limit: 1.0e9 # OPTIONAL: the cap itself (tCO2/yr); Co2L<x> computes it as x * co2base
# gaslimit_enable: false # OPTIONAL: gas-fired primary-energy cap on/off (a bare CH4L opt sets it true)
# gaslimit: 2.0e8 # OPTIONAL: the cap itself (MWh thermal/yr); CH4L<x> sets x * 1e6
regional_Co2_limits: 'repo_data/config/policy_constraints/regional_Co2_limits.csv' # per-region CO2 caps (tCO2/yr)
technology_capacity_targets: 'repo_data/config/policy_constraints/technology_capacity_targets.csv' # forced min/max build by tech & region
portfolio_standards: 'repo_data/config/policy_constraints/portfolio_standards.csv' # RPS/CES fractions by region
transmission_interface_limits: 'repo_data/config/policy_constraints/transmission_interface_limits.csv' # MW caps on inter-region flows
# ---------------- Demand ----------------
demand:
profile: efs # demand time series source; efs (EIA-EFS) | eia (historical actuals) | eer (EER scenarios) | servm (CPUC SERVM, California only)
bus_allocation: population # per-bus demand weight; population (2020 census counties) | breakthrough (legacy BE Pd)
scenario: # EFS/EER/SERVM scenario knobs (ignored if profile=eia)
efs_case: reference # reference | medium | high
efs_speed: moderate # slow | moderate | rapid
eer_file: demand_EER2025_100by2050.h5 # EER h5 (profile=eer): demand_EER2025_100by2050 | demand_EER2025_Baseline_AEO2023 | demand_EER2025_IRAlow
aeo: reference # AEO (EIA Annual Energy Outlook) scaling case; reference | high | low
# ---- profile: servm (CPUC SERVM 2026, California regions) ----
# Weather year drawn from the stacked 2000-2024 SERVM record. Single-entry
# list = deterministic; multiple entries are reserved for stochastic
# scenarios (phase 3) and currently raise NotImplementedError.
# RECOMMENDED: keep equal to top-level `renewable_weather_years` so load
# and renewable profiles share a weather year (mismatch logs a warning).
servm_weather_years: [2019]
demand_response: # price-responsive shiftable load; 0 = disabled
shift: 0 # fraction of hourly load that can shift in time
marginal_cost: 999999 # $/MWh for shifted energy (set high to deter use unless needed)
# by_carrier: false # OPTIONAL: enable per-end-use DR controls (sector-coupling only)
# ---------------- Inter-regional trade ----------------
# When enable=true and transmission_network=reeds, the model adds
# virtual imports/exports between the modeled footprint and external
# neighbors using historical EIA interchange data.
imports:
enable: false
representation: store # store = priced links off a bottomless Store; generator = priced generator (+ CPUC contracted units) behind an unpriced interface link
costs: wholesale # wholesale | carrier | float — how imported energy is priced
co2_emissions: 0.428 # tCO2/MWh assigned to imported energy
capacity_limit: true # cap import power to historical maxima
volume_limit: inf # cap import energy in TWh per balancing period; 0 < x < 100 or 'inf'
balancing_period: month # day | week | month | year
exports:
enable: false
costs: wholesale # wholesale | carrier | float
capacity_limit: true
volume_limit: inf # 0 < x < 100 or 'inf'
balancing_period: month # day | week | month | year
# ====================================================================
# CONVENTIONAL — unit-commitment and fuel-price overrides
# ====================================================================
Unit |
Values |
Description |
|
|---|---|---|---|
conventional_carriers |
– |
Any subset of {nuclear, oil, OCGT, CCGT, coal, geothermal, biomass, waste} |
List of conventional power plants to include in the model from |
renewable_carriers |
– |
Any subset of {onwind, offwind, offwind_floating, solar, hydro} |
List of renewable generators to include in the model as existing capacity. |
retirement |
– |
One of |
Sets the retirement method for conventional generators. If |
honor_planned_retirements |
bool |
{true, false} |
Drop existing/proposed units at their EIA |
extendable_carriers: |
Capacity-expansion candidates. Carriers listed here get extendable |
||
– Generator |
– |
Defaults: {solar, onwind, offwind_floating, OCGT, CCGT, CCGT-95CCS, coal, nuclear, hydrogen_ct}; also supported: {EGS, SMR, coal-95CCS} |
Extendable generation carriers. Conventional generators can only be built/expanded where already existent today. If a listed conventional carrier is not included in the |
– StorageUnit |
– |
Any subset of {2hr_battery_storage, 4hr_battery_storage, 6hr_battery_storage, 8hr_battery_storage, 10hr_battery_storage, 8hr_PHS, 10hr_PHS, 12hr_PHS} |
Adds extendable storage units of the given duration at every node/bus after clustering with zero initial capacity. |
– Store |
– |
e.g. {H2_tank} |
Adds extendable stores at every node/bus after clustering with zero initial capacity. Requires sector coupling. |
– Link |
– |
e.g. {HVDC} |
Adds extendable links at every connection where there are lines or HVDC links with zero initial capacity. |
remote_contracted_resources: |
California only. Re-adds the physically out-of-state resources the CPUC ledger attributes to California load regions (Palo Verde’s SCE share, LADWP’s Intermountain and Apex, the Hoover entitlements, ~2 GW of AZ/NV solar and battery contracts) as generators at California buses, at their CONTRACTED capacity, with techno-economics from the same PUDL fleet build. A California-scoped footprint otherwise drops them because they sit outside the model regions. Requires |
||
– enable |
bool |
{true, false} |
Attach the CA-contracted out-of-state units at CA buses. |
– file |
– |
path |
CPUC out-of-state contracted-unit ledger (default |
SAFE_reservemargin |
p.u. |
float |
System-wide planning reserve margin as a fraction of peak load. Reserved setting — not currently enforced by an active constraint; the |
SAFE_regional_reservemargins |
– |
path |
CSV of per-region planning reserve margins ( |
erm: |
Energy Reserve Margin settings (used when ERM opt is enabled). Ensures sufficient firm capacity to meet demand plus reserve margin at every timestep. |
||
– <region> |
– |
float |
Reserve margin as a fraction (e.g., 0.15 for 15%). Use |
regional_Co2_limits |
– |
path |
CSV of per-region CO2 caps in tCO2/yr ( |
technology_capacity_targets |
– |
path |
CSV of forced minimum/maximum capacity builds by technology and region ( |
portfolio_standards |
– |
path |
CSV of RPS/CES clean-energy fractions by region ( |
transmission_interface_limits |
– |
path |
CSV of MW limits on flows across inter-regional transmission interfaces ( |
co2base |
\(t_{CO_2}/a\) |
float |
Reference CO2 budget scaled by a |
co2limit_enable |
bool |
true or false |
Switch to activate the system-wide CO2 cap below. Optional; defaults to false when unset. Can also be set via the |
co2limit |
\(t_{CO_2}/a\) |
float |
System-wide cap on annual CO2 emissions, added as a global constraint in |
gaslimit_enable |
bool |
true or false |
Switch to activate the gas-use cap below. Optional; defaults to false when unset. Can also be set via the |
gaslimit |
MWh thermal |
float |
Cap on annual gas-fired primary energy from gas carriers (OCGT, CCGT, CHP), added as a global constraint in |
demand: |
|||
– bus_allocation |
– |
One of { |
How zone-level demand is distributed to individual buses. |
– profile |
– |
One of { |
Datasource for electrical load data. |
– scenario: |
|||
– – efs_case |
– |
One of { |
(UNDER DEVELOPMENT) Extracts EFS data according to level of adoption |
– – efs_speed |
– |
One of { |
(UNDER DEVELOPMENT) Extracts EFS data according to speed of electrification |
– – eer_file |
– |
One of { |
Selects the EER demand dataset file to download and use when |
– – aeo |
– |
One of the AEO scenarios here |
(UNDER DEVELOPMENT) Scales future demand according to the AEO scenario |
– – servm_weather_years |
– |
List with exactly one year from 2000-2024 |
Weather year drawn from the stacked SERVM record when |
demand_response: |
Settings to activate and configure demand response |
||
– shift |
per_unit |
float {0 <=, >= 1} or ‘inf’ |
Allowable load to be shifted per snapshot. Set to 0 to turn off demand response. Set to ‘inf’ to not enforce capacity limits. |
– marginal_cost |
$/MWh |
float {0 <=} |
Cost to store one unit of energy for one hour |
imports: |
Configure electric imports from regions outside of model scope |
||
– enable |
|
Enable electric imports |
|
– representation |
|
How out-of-footprint supply is represented. |
|
– costs |
$/MWh |
|
Cost of electric imports from regions outside of model scope. |
– co2_emissions |
CO2/MWh |
|
CO2 emissions of electric imports from regions outside of model scope. |
– capacity_limit |
|
Enable capacity limit for electric imports from regions outside of model scope |
|
– volume_limit |
percent |
float {0 <=, >= 100} or ‘inf’ |
Volume limit for electric imports from regions outside of model scope (in % of total demand). Set to |
– balancing_period |
|
Balancing period for electric imports from regions outside of model scope. |
|
exports: |
Configure electric exports to regions outside of model scope |
||
– enable |
|
Enable electric exports |
|
– costs |
$/MWh |
|
Cost of electric exports to regions outside of model scope. |
– capacity_limit |
|
Enable capacity limit for electric exports to regions outside of model scope |
|
– volume_limit |
percent |
float {0 <=, >= 100} or ‘inf’ |
Volume limit for electric exports to regions outside of model scope (in % of total demand). Set to |
– balancing_period |
|
Balancing period for electric exports to regions outside of model scope. |
renewable#
Per-technology resource and land-availability settings live in config.common.yaml and feed
build_renewable_profiles. Note that when renewable.dataset: godeeep is selected, the
corine, natura, and cec land screens below are bypassed in favor of the NREL reV
renewable_land_access exclusions (see renewable: godeeep).
solar#
solar:
cutout: era5
resource:
method: pv
panel: CSi
orientation: latitude_optimal # latitude_optimal | flat | <custom dict>
capacity_per_sqkm: 4.6 # MW/km^2 (raised from 1.7 per issue #361; revisit assumption)
correction_factor: 1 # 0.854337 in some references
corine:
grid_codes: [20, 30, 60, 90, 100]
natura: true
cec: true # apply CEC BaseScreen in CA
potential: conservative
clip_p_max_pu: 1.e-2
extendable: true
Unit |
Values |
Description |
|
|---|---|---|---|
cutout |
– |
Name of a source defined under |
Selects the weather-data source for this technology. Combined with the weather year to pick the cutout file |
resource |
|||
– 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 |
– |
|
Panel orientation. |
capacity_per_sqkm |
\(MW/km^2\) |
float |
Allowable density of solar panel placement. |
correction_factor |
– |
float |
A correction factor for the capacity factor (availability) time series. |
corine |
– |
Any subset of the Copernicus Land Cover code list (see assumptions). |
Specifies areas according to Land Cover codes which are generally eligible for solar panel placement. |
natura |
bool |
{true, false} |
Switch to exclude Protected Planet natural protection areas. Area is excluded if |
cec |
bool |
{true, false} |
Switch to apply the California Energy Commission Solar BaseScreen inside California (no effect elsewhere). |
potential |
– |
One of {‘simple’, ‘conservative’} |
Method to compute the maximal installable potential for a node. |
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} |
Whether the technology is eligible for capacity expansion. |
note |
The |
onwind#
onwind:
cutout: era5 # atlite cutout name (must match an entry under atlite.cutouts below)
resource:
method: wind
turbine: Vestas_V112_3MW # atlite turbine config (see atlite.resource.windturbines)
add_cutout_windspeed: true # store raw windspeeds in profile output (used by GODEEEP scaling)
capacity_per_sqkm: 3 # MW/km^2 of available land (conservative; ScholzPhD Tab 4.3.1 cites 10)
correction_factor: 1 # scalar applied to CF (e.g. 0.93 for wake losses)
# CORINE land-cover screen. NB: keys are labeled `corine` for
# pypsa-eur parity, but the codes are actually Copernicus CGLS
# (https://land.copernicus.eu/global/sites/cgls.vito.be/files/products/CGLOPS1_PUM_LC100m-V3_I3.4.pdf).
corine:
grid_codes: [20, 30, 40, 60, 100, 111, 112, 113, 114, 115] # eligible Copernicus land-cover classes
distance: 10 # buffer (km) from `distance_grid_codes` that is excluded
distance_grid_codes: [50] # classes that trigger the buffer (e.g. urban)
natura: true # exclude protected areas (Natura 2000 / US protected lands)
cec: true # apply CEC Wind/Solar BaseScreen in CA (additional CA-only screen)
potential: conservative # simple | conservative
clip_p_max_pu: 1.e-2 # treat CFs below this as zero
extendable: true # eligible for capacity expansion
Unit |
Values |
Description |
|
|---|---|---|---|
cutout |
– |
Name of a source defined under |
Selects the weather-data source for this technology. Combined with the weather year to pick the cutout file |
resource |
|||
– method |
– |
Must be ‘wind’ |
A superordinate technology type. |
– turbine |
– |
One of the turbine types included in atlite |
Specifies the turbine type and its characteristic power curve. |
– add_cutout_windspeed |
bool |
{true, false} |
Store the raw hub-height windspeeds in the profile output (used by the GODEEEP scaling workflow). |
capacity_per_sqkm |
\(MW/km^2\) |
float |
Allowable density of wind turbine placement. |
correction_factor |
– |
float |
Correction factor for capacity factor time series (e.g. wake losses). |
corine |
|||
– grid_codes |
– |
Any subset of the Copernicus Land Cover code list (see assumptions). |
Specifies areas according to Land Cover codes which are generally eligible for wind turbine placement. |
– distance |
km |
float |
Distance to keep from areas specified in |
– distance_grid_codes |
– |
Any subset of the Copernicus Land Cover code list (see assumptions). |
Specifies areas according to Land Cover codes to which the exclusion buffer |
natura |
bool |
{true, false} |
Switch to exclude Protected Planet natural protection areas. Area is excluded if |
cec |
bool |
{true, false} |
Switch to apply the California Energy Commission Wind BaseScreen inside California (no effect elsewhere). |
potential |
– |
One of {‘simple’, ‘conservative’} |
Method to compute the maximal installable potential for a node. |
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} |
Whether the technology is eligible for capacity expansion. |
note |
The |
offwind#
Fixed-bottom offshore wind, screened to water depths up to max_depth (60 m by default) within
the configured shore-distance band.
offwind:
cutout: era5
resource:
method: wind
turbine: NREL_ReferenceTurbine_2020ATB_5.5MW
# add_cutout_windspeed: true
capacity_per_sqkm: 3 # MW/km^2 (2021–2022 CAISO Transmission Plan)
correction_factor: 1 # 0.8855 in 10.1016/j.energy.2018.08.153 for wake losses
corine:
grid_codes: [80, 200] # offshore CGLS codes (open water)
natura: true
boem_screen: false # overlay BOEM offshore-wind planning areas
max_depth: 60 # meters; fixed-bottom upper bound (NREL fy16osti/66599)
min_shore_distance: 22000 # meters
max_shore_distance: 65000 # meters
potential: conservative
clip_p_max_pu: 1.e-2
extendable: true
# ---------- Offshore wind (floating) ----------
Unit |
Values |
Description |
|
|---|---|---|---|
cutout |
– |
Name of a source defined under |
Selects the weather-data source for this technology. Combined with the weather year to pick the cutout file |
resource |
|||
– method |
– |
Must be ‘wind’ |
A superordinate technology type. |
– turbine |
– |
One of the turbine types included in atlite |
Specifies the turbine type and its characteristic power curve. |
– add_cutout_windspeed |
bool |
{true, false} |
Store the raw hub-height windspeeds in the profile output (used by the GODEEEP scaling workflow). Enabled by default for |
capacity_per_sqkm |
\(MW/km^2\) |
float |
Allowable density of offshore wind turbine placement. |
correction_factor |
– |
float |
Correction factor for capacity factor time series (e.g. 0.8855 for wake losses). |
corine |
|||
– grid_codes |
– |
Offshore Copernicus Land Cover codes, e.g. |
Specifies areas which are generally eligible for offshore wind placement. |
natura |
bool |
{true, false} |
Switch to exclude Protected Planet natural protection areas. Area is excluded if |
boem_screen |
bool |
{true, false} |
Restrict eligible area to BOEM offshore-wind planning areas. Off by default for fixed-bottom |
min_depth |
m |
float |
Minimum water depth ( |
max_depth |
m |
float |
Maximum water depth; deeper sites are excluded (60 m for fixed-bottom |
min_shore_distance |
m |
float |
Minimum distance to shore; nearer sites are excluded. |
max_shore_distance |
m |
float |
Maximum distance to shore; farther sites are excluded. |
potential |
– |
One of {‘simple’, ‘conservative’} |
Method to compute the maximal installable potential for a node. |
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} |
Whether the technology is eligible for capacity expansion. |
note |
The |
offwind_floating#
Floating offshore wind, screened to the depth band between min_depth and max_depth
(60–1300 m by default, following NREL fy22osti/83650) within the configured shore-distance band.
The BOEM offshore-wind planning-area screen (boem_screen) is on by default for floating sites.
The same option keys as fixed-bottom offwind apply.
offwind_floating:
cutout: era5
resource:
method: wind
turbine: NREL_ReferenceTurbine_2020ATB_15MW_offshore
add_cutout_windspeed: true
capacity_per_sqkm: 3 # MW/km^2
correction_factor: 1 # 0.8855 wake-loss proxy
corine:
grid_codes: [80, 200]
natura: true
boem_screen: true # default ON for floating
min_depth: 60 # meters; floating lower bound
max_depth: 1300 # meters; floating upper bound (NREL fy22osti/83650)
min_shore_distance: 22000 # meters
max_shore_distance: 65000 # meters
potential: conservative
clip_p_max_pu: 1.e-2
extendable: true
hydro#
Configures the hydro fleet attached from EIA-860 capacity and atlite inflow time series.
carriers selects which hydro types are modeled: ror (run-of-river), PHS (pumped hydro
storage), and hydro (reservoir hydro). The optional commented PHS_max_hours overrides the
pumped-storage duration that otherwise comes from the cost tables.
hydro:
cutout: era5
carriers: [ror, PHS, hydro] # ror = run-of-river; PHS = pumped hydro storage; hydro = reservoir hydro
resource:
method: hydro
extendable: true
# PHS_max_hours: 6 # OPTIONAL: PHS storage duration in hours; defaults from cost table
# ====================================================================
# NREL LAND-ACCESS — GODEEEP exclusion overlay settings (REQUIRED for godeeep)
# ====================================================================
# When renewable.dataset == "godeeep" (set in your main config), the
# workflow downloads `data/nrel_exclusion/derived/{avail,caps}_*.nc`
# from Zenodo and weights GODEEEP CFs by per-cell availability and
# per-bus supply-curve capacities. The variables here pick which
# overlay variant gets loaded.
EGS#
Options for Enhanced Geothermal Systems supply curves (used when EGS is listed under
electricity: extendable_carriers: Generator). dispatch selects baseload (constant output) or
flexible (dispatchable) operation, drilling_cost picks the base or advanced drilling-cost
column of the EGS supply curves, and seismic_exclusion applies the seismic-risk mask to
candidate sites. The underlying supply-curve and profile methodology is to be detailed in a
forthcoming publication.
EGS:
dispatch: baseload # baseload (constant) | flexible (dispatchable like CCGT)
drilling_cost: advanced # base | advanced — selects EGS supply-curve capex column
seismic_exclusion: true # apply the EGS seismic-risk mask (upstream PR #750)
# ---------- Onshore wind ----------
renewable: godeeep#
PyPSA-USA supports two sources for renewable capacity-factor time series, selected via renewable.dataset in config.common.yaml:
atlite— runtime computation of capacity factors from ERA5 cutouts, weighted by Copernicus / CORINE land-use exclusions (the legacy default; see Renewable Capacity Factors under Model Data).godeeep— pre-computed regional climate-model capacity factors from the GODEEEP (Grid Operations, Decarbonization, Environmental and Energy Equity Platform) dataset, weighted at runtime by NREL reV land-access exclusions.
The godeeep path consumes two file families:
Compressed GODEEEP capacity factors — per-cell hourly capacity factors on the GODEEEP Lambert Conformal grid, uint8-quantized and zlib-compressed (~12× smaller than the raw aggregated files; ~350 MB per solar year, ~800 MB per wind year). One file per
(tech, hub height, scenario, year), retrieved byrule retrieve_godeeep_cffrom the sources declared ingodeeep_cf_registry(see below).NREL land-access artifacts (10.5281/zenodo.20127899) —
avail_{tech}_{access}[_cec|_boem].ncper-cell availability rasters andcaps_{tech}_{access}[_cec|_boem].ncper-bus rollups (weight,p_nom_max,potential,average_distance, andunderwater_fractionfor offshore).
How capacity-factor files are retrieved#
Capacity-factor files are no longer downloaded from inside build_renewable_profiles. A dedicated
rule, retrieve_godeeep_cf, places each file, driven by the godeeep_cf_registry block of
config.common.yaml. The registry is an ordered list of sources — a local mirror and Zenodo —
and each source declares exactly which (dataset key, year) pairs it holds. The first source
declaring the requested pair wins.
There are no fallback paths: no default hub height, no nearest-year substitution, no swap to an
unscreened variant. A request for a dataset or year that no source declares fails at snakemake
parse time with an error naming the dataset key, the requested year and the years available from
each source. Local hits are symlinked into the run’s data/ directory (set copy_local: true to
copy instead) and verified against the mirror’s SHA256SUMS manifest before use.
Which data is available#
Dataset keys are {tech}{wind_height}_{scenario}_compressed. On Sherlock all of the following is
reachable out of the box, because the shipped config declares the group’s Oak mirror
(/oak/stanford/groups/iazevedo/GoDEEEP_Capacity_Factors_compressed, group oak_iazevedo) as the
first source. Off Sherlock, edit godeeep_cf_registry to remove or repoint the local source —
only the Zenodo subset is then reachable.
Dataset key |
|
Oak mirror |
Zenodo |
|---|---|---|---|
|
— |
1980–2022 |
2012 only (20127513) |
|
|
1980–2022 |
not published |
|
|
1980–2022 |
2012 only (20127520) |
|
— |
— |
2030 / 2040 / 2050 (20127523) |
|
— |
— |
2030 / 2040 / 2050 (20127562) |
|
— |
— |
2030 / 2040 / 2050 (20127589) |
|
— |
— |
2030 / 2040 / 2050 (20127633) |
|
|
— |
not published (record 20127545 returns HTTP 404) |
|
|
— |
2030 / 2040 / 2050 (20127572) |
|
|
— |
2030 / 2040 / 2050 (20127604) |
|
|
— |
2030 / 2040 / 2050 (20127645) |
Notable gaps:
Full historical coverage (1980–2022) requires the Oak mirror. From Zenodo the historical scenario is a single year, 2012.
100 m hub-height wind exists only on the Oak mirror. Zenodo publishes 125 m only.
rcp45hotteris solar-only. The corresponding 125 m wind record was never registered, so the registry declares it with an empty year list; requesting it fails withavailable years: (none)rather than silently downloading nothing.
The Oak mirror also holds an 80 m wind archive (1980–2022, sha256-verified alongside the rest), but
it is not yet wired into godeeep_cf_registry and the workflow accepts only "_100m" and
"_125m" for godeeep_wind_height. ("_80m" was the silent default behind
#803 and is now rejected.)
godeeep_cf_registry:
copy_local: false # false = the retrieve rule symlinks local hits (no duplication); true = copy into the run's data/
sources:
# ---- 1. Local Oak mirror: full 1980-2022 historical archive, both hub heights.
- kind: local
root: /oak/stanford/groups/iazevedo/GoDEEEP_Capacity_Factors_compressed
layout: "{scenario}/{tech_dir}/{filename}" # placeholders: scenario, tech_dir (solar|wind_100m|wind_125m), technology, wind_height, year, filename, dataset_key
datasets:
solar_historical_compressed:
years: "1980-2022"
wind_100m_historical_compressed:
years: "1980-2022"
wind_125m_historical_compressed:
years: "1980-2022"
# ---- 2. Zenodo: the published subset. Historical is a single year (2012);
# future scenarios hold 2030/2040/2050 per (tech, scenario) record.
# Every year list below was read off the live Zenodo API file listing
# (GET https://zenodo.org/api/records/<id>), not assumed.
- kind: zenodo
datasets:
solar_historical_compressed:
record: 20127513
years: [2012]
wind_125m_historical_compressed:
record: 20127520
years: [2012]
solar_rcp45hotter_compressed:
record: 20127523
years: [2030, 2040, 2050]
solar_rcp45cooler_compressed:
record: 20127562
years: [2030, 2040, 2050]
solar_rcp85hotter_compressed:
record: 20127589
years: [2030, 2040, 2050]
solar_rcp85cooler_compressed:
record: 20127633
years: [2030, 2040, 2050]
wind_125m_rcp45cooler_compressed:
record: 20127572
years: [2030, 2040, 2050]
wind_125m_rcp85hotter_compressed:
record: 20127604
years: [2030, 2040, 2050]
wind_125m_rcp85cooler_compressed:
record: 20127645
years: [2030, 2040, 2050]
# wind_125m_rcp45hotter is NOT published. Record 20127545 (hardcoded in the
# old zenodo_downloader.py) returns HTTP 404 "The persistent identifier is
# not registered", and no such record appears in a Zenodo search of the
# series — the other 9 records of the series do. Declaring it with an empty
# year list keeps the failure honest: requesting it raises "available years:
# (none)" instead of the legacy silent `None` download path. Use the local
# source or re-publish the record to make this scenario runnable.
wind_125m_rcp45hotter_compressed:
record: 20127545
years: []
# ====================================================================
# ATLITE — ERA5 cutout definitions
# ====================================================================
# An atlite cutout is a spatial+temporal slice of ERA5 used to
# compute renewable CFs. `cutouts:` defines named cutouts;
# `interconnects:` sets the bounding box and grid resolution per
# interconnect (consumed by build_cutout when build_cutout=true).
Configuring a godeeep run#
A complete godeeep configuration requires four config blocks beyond the standard electricity: / clustering: settings:
Dataset selection (
config.common.yaml):renewable: dataset: godeeep # set to atlite for the ERA5 + CORINE workflow
Scenario and year selection. The GODEEEP dataset has a historical scenario and four future climate scenarios (
rcp45hotter,rcp45cooler,rcp85hotter,rcp85cooler) at planning horizons 2030 / 2040 / 2050. Historical years run 1980–2022 via the Oak mirror; from Zenodo only 2012 is available. Any(scenario, year)outside the table above fails at parse time.renewable_scenarios: ["rcp45cooler"] # one of: historical | rcp45hotter | rcp45cooler | rcp85hotter | rcp85cooler renewable_weather_years: [2012] # used only when scenario == historical
Future-scenario years come from the
planning_horizonswildcard (underscenario:); the historical year comes fromrenewable_weather_years.Wind runs must also set the hub height, which has no default — leaving it unset fails the run:
godeeep_wind_height: "_125m" # "_100m" (Oak mirror only) | "_125m" (Oak mirror + Zenodo)
Snapshots — the temporal slice within the chosen year. For godeeep this controls how much of the 8760-hour GODEEEP CF is sampled:
renewable_snapshots: start_month: 1 start_day: 1 end_month: 12 end_day: 31 end_inclusive: true # include the full end day, not just up to 00:00
NREL land-access exclusions (required when
renewable.dataset: godeeep; the workflow raises ifrenewable_land_accessis unset):
# REQUIRED (non-null) whenever `renewable.dataset` is godeeep - the schema and
# build_renewable_profiles both enforce it. `reference` is NREL's central
# land-access assumption and the value the equivalence harness validates
# against. Note this key drives the DAG: any godeeep run pulls the NREL
# exclusion artifacts (retrieve_nrel_exclusion_artifact jobs).
renewable_land_access: reference # reference | limited | open (null allowed only with dataset: atlite)
apply_cec_basescreen: false # overlay CEC Wind/Solar BaseScreen on onwind+solar (CA-only)
apply_boem_osw: false # overlay BOEM offshore-wind planning areas on offwind + offwind_floating
godeeep_wind_height: "_125m" # raw GODEEEP wind-CF hub height; "_100m" | "_125m" — NO DEFAULT is applied if unset, the run fails loudly.
# "_125m" is the only height published on Zenodo; "_100m" REQUIRES the local (Oak) source below.
# "_80m" is not a GODEEEP product — there is no data at that height.
nrel_caps_reassign: # out-of-footprint caps recovery for footprint-scoped runs (caps are rolled up nationally)
enable: false # when true, fold unmapped caps entries onto the nearest in-footprint bus (needs x/y in the caps file)
max_km: 100 # only reassign entries within this distance (km); farther entries stay dropped (prevents cross-seam teleporting)
# ====================================================================
# GODEEEP CF REGISTRY — where compressed capacity-factor files come from
# ====================================================================
# Declares every (dataset key, year) the workflow is allowed to retrieve.
# `godeeep_cf_registry.py` walks `sources` IN ORDER and the FIRST source
# declaring the requested (dataset key, year) wins. There are NO fallback
# paths: a missing dataset/year raises an error naming the dataset key, the
# requested year and the available years per source — it never substitutes a
# different year, hub height or screening variant (issue #803).
#
# Dataset keys are "{tech}{wind_height}_{scenario}_compressed", e.g.
# `solar_historical_compressed`, `wind_125m_rcp85cooler_compressed`.
# `years:` takes an inclusive range string ("1980-2022") or an explicit list.
Unit |
Values |
Description |
|
|---|---|---|---|
renewable_land_access |
|
One of { |
NREL reV access scenario applied as availability weighting to GODEEEP capacity factors. Required non-null when |
apply_cec_basescreen |
– |
bool |
If true, overlay the California Energy Commission Wind/Solar BaseScreen on the NREL exclusion raster for onwind and solar (CA-only — outside California the variant equals the base). Selects the |
apply_boem_osw |
– |
bool |
If true, overlay the BOEM OSW planning-area screen on the NREL exclusion raster for offwind and offwind_floating. Selects the |
godeeep_wind_height |
– |
str (e.g. |
Hub-height suffix used to construct the raw GODEEEP wind capacity-factor filename (e.g. |
renewable: godeeep_cf_weighting |
|
One of { |
How GODEEEP cell capacity factors are weighted up to the |
The _cec and _boem variants overlay additional regulatory screens on top of the base NREL availability raster: California Energy Commission Wind/Solar BaseScreen for onshore solar/wind in CA, and BOEM offshore wind planning areas for offshore. Outside their applicable region the variant equals the base.
offshore_shape#
Selects the offshore region polygons used to delineate offshore wind resource areas: eez uses
the federal Exclusive Economic Zone shapes (the default, covering all coasts), while ca_osw
restricts offshore development to the California offshore wind areas.
offshore_shape:
use: eez # offshore region polygons; ca_osw (CA-only) | eez (federal EEZ)
offshore_network#
Controls the density of the synthetic offshore network: bus_spacing sets the distance in meters
between adjacent offshore buses, which determines how many offshore wind connection points are
created along the offshore shapes.
offshore_network:
bus_spacing: 25000 # meters between adjacent offshore buses (OSW network density)
# NB: `co2:` used to be duplicated here with the same values it has in
# config.default.yaml, which now owns the key outright. Its defaults are
# still always defined, because config.default.yaml is itself a loaded
# layer — so every rule reading config["co2"][...] still resolves.
# ====================================================================
# UCAP — Unforced Capacity for resource-adequacy accounting
# ====================================================================
# Applies a derate to conventional plants based on Forced Outage Rates:
# UCAP = ICAP * (1 - FOR), implemented as p_max_pu = 1 - FOR.
lines#
lines:
s_max_pu: 0.7 # apparent-power utilization cap (fraction of s_nom); 0.7 = N-1 derate
s_nom_max: .inf # MVA cap on expanded line capacity per corridor (.inf = unbounded)
max_extension: 20000 # MW cap on total network-wide line expansion
length_factor: 1.25 # multiplier on geographic length to account for routing/right-of-way
# pyPSA line-type catalog, mapped onto AC corridors by v_nom. Every line in
# the base network is assigned the LineType matching its voltage; values
# reference pypsa.LineType library entries. (Moved here from
# config.common.yaml so `lines:` is defined in exactly one file.)
types: # Temp values; replaced when actual conductor data is loaded
115.: "Al/St 240/40 2-bundle 220.0"
138.: "Al/St 240/40 2-bundle 220.0"
161.: "Al/St 240/40 2-bundle 220.0"
230.: "Al/St 240/40 2-bundle 220.0"
345.: "Al/St 240/40 4-bundle 380.0"
500.: "Al/St 560/50 4-bundle 750.0"
765.: "Al/St 560/50 4-bundle 750.0"
# ====================================================================
# LINKS — HVDC and controllable links (DC ties, internal HVDC)
# ====================================================================
Unit |
Values |
Description |
|
|---|---|---|---|
types |
– |
Values should specify a line type in PyPSA. 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 TAMU Network. |
s_max_pu |
– |
Value in [0.,1.] |
Correction factor for line capacities (s_nom) to approximate \(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. |
max_extension |
MW |
float |
Upper limit for the extended 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. Only used in TAMU network. |
links#
links:
p_max_pu: 1.0 # active-power utilization cap (fraction of p_nom)
p_nom_max: .inf # MW cap on expanded link capacity per corridor
max_extension: 20000 # MW cap on total network-wide HVDC expansion
# ====================================================================
# CO2 — sequestration storage and pipeline transport
# ====================================================================
Unit |
Values |
Description |
|
|---|---|---|---|
p_max_pu |
– |
Value in [0.,1.] |
Correction factor for link capacities |
p_nom_max |
MW |
float |
Global upper limit for the maximum capacity of each extendable DC link. |
max_extension |
MW |
float |
Upper limit for the extended capacity of each extendable line. |
co2#
The co2 section specifies whether the model may use underground storage to sequester captured CO2 or not. In case underground storage is specified, each node (composing the network) has a specific storage potential and a cost associated with it. The storage potential (in tonnes) is calculated by aggregating all the underlying storage potentials of the U.S. counties encompassed in the node’s geographical area. Counties that are only partially covered by the node’s geographical area have their potential fractionated accordingly. The storage cost (in $/tonne) is calculated by weighting the potential with the cost of each county encompassed. The dataset containing information about underground CO2 storage potentials and costs at a county level (and used in PyPSA-USA) was provided by Edna Calzado at The University of Texas (Austin), which was derived from the Roads to Removal project (https://roads2removal.org). To get an illustration, enabling underground co2 storage for a sector-less network will render its topography similar to this, while for a sector-based network will render its topography similar to this. As a reference, disabling underground co2 storage (i.e. no CCTS), a sector-less network has a topography similar to this, while a sector-based network has a topography similar to this.
Sector-less network with underground CO2 storage enabled.#
Sector-based network with underground CO2 storage enabled.#
Reference: sector-less network without CCTS.#
Reference: sector-based network without CCTS.#
In addition, the section specifies whether the model may transport captured CO2 between nodes or not. In case transportation is specified, a network of CO2 pipelines is built based on the electricity grid layout represented in PyPSA-USA to determine where/how to build pipelines to connect nodes. To get an illustration, enabling co2 transport for a sector-less network will render its topography similar to this, while for a sector-based network will render its topography similar to this.
Sector-less network with underground CO2 storage and CO2 transport.#
Sector-based network with underground CO2 storage and CO2 transport.#
co2:
storage: false # true = enable underground CO2 sequestration at each node (Roads2Removal potentials)
network: # CO2 pipeline transport between nodes
enable: false
capital_cost: 2736000 # USD per 12-inch-diameter mile
marginal_cost: 4 # USD per tCO2 transported
lifetime: 40 # years
discount_rate: 0.07 # annual real discount rate (fraction)
# ====================================================================
# DAC — Direct Air Capture
# ====================================================================
Unit |
Values |
Description |
|
|---|---|---|---|
storage |
bool |
true or false |
Specifies whether the model may use underground storage to sequester captured CO2 or not. The default value is |
network |
– |
Specifies whether the model may transport captured CO2 between nodes or not. In case transportation is specified, a network of CO2 pipelines is built based on the costs, discount rate, as well as the lifetime stipulated in this subsection. |
|
– enable |
bool |
true or false |
Enable ( |
– capital_cost |
int |
$/mile |
Capital cost of building one mile long CO2 pipeline. The default value is |
– marginal_cost |
int |
$/t |
Marginal cost of transporting one tonne of captured CO2. The default value is |
– lifetime |
int |
year |
Lifetime of a CO2 pipeline. The default value is |
– discount_rate |
float |
% |
Discount rate of the capital cost of building a network of CO2 pipelines. The default value is |
dac#
The dac section specifies whether the model should use Direct Air Capture (DAC) or not to capture emitted CO2. DAC may operate in a multitude of scenarios depending on different granularities (or scopes) and whether the model is based on sectors or not.
For a sector-less model:
When
granularityis set tonode, each node (composing the network) has a specific “air atmosphere” into which all the processes belonging to the node emit CO2. For each node, DAC is built to capture CO2 from its “air atmosphere”. To get an illustration, settinggranularitytonodewill render the topography of a sector-less network similar to this.When
granularityis set tostate, each U.S. state (represented in the network) has a specific “air atmosphere” into which all the processes of the nodes belonging to the state emit CO2. For each node, DAC is built to capture CO2 from the state “air atmosphere” it belongs to. To get an illustration, settinggranularitytostatewill render the topography of a sector-less network similar to this.When
granularityis set tonation, the model only has one single “air atmosphere” into which all the processes of all the nodes emit CO2. For each node, DAC is built to capture CO2 from this “air atmosphere”. To get an illustration, settinggranularitytonationwill render the topography of a sector-less network similar to this.
Sector-less network with DAC at node granularity.#
Sector-less network with DAC at state granularity.#
Sector-less network with DAC at nation granularity.#
For a sector-based model:
When
granularityis set tonode, each sector/node pair has a specific “air atmosphere” into which all the processes belonging to the sector/node pair emit CO2. For each sector/node pair, DAC is built to capture CO2 from its “air atmosphere”. To get an illustration, settinggranularitytonodewill render the topography of a sector-based network similar to this.When
granularityis set tostate, each sector/U.S. state pair has a specific “air atmosphere” into which all the processes of the nodes belonging to the state emit CO2. For each sector/node pair, DAC is built to capture CO2 from the sector/state pair’s “air atmosphere” it belongs to. To get an illustration, settinggranularitytostatewill render the topography of a sector-based network similar to this.Given that a
granularityset tonationdoes not make sense in a sector-based model, it defaults tonodein this case.
Sector-based network with DAC at node granularity.#
Sector-based network with DAC at state granularity.#
dac:
enable: false
granularity: "node" # CO2 atmosphere scope; node | state | nation
capital_cost: 6000000 # USD per (tCO2/h) of capture capacity
electricity_input: 2.5 # MWh of electricity consumed per tCO2 captured
lifetime: 20 # years
discount_rate: 0.07 # annual real discount rate (fraction)
# ====================================================================
# COSTS — capex/opex scenarios and policy incentives
# ====================================================================
Unit |
Values |
Description |
|
|---|---|---|---|
enable |
bool |
true or false |
Specifies whether the model may use Direct Air Capture (DAC) to capture emitted CO2 or not. In case DAC is specified, it is built based on the costs, discount rate, as well as the lifetime stipulated in this section. |
granularity |
str |
‘node’, ‘state’ or ‘nation’ |
Specifies the granularity (scope) of DAC. The default value is |
capital_cost |
int |
$/tCO2/h |
Capital cost of DAC to capture one tonne of CO2 per hour. The default value is |
electricity_input |
float |
MWh/tCO2 |
Amount of electricity needed for DAC to capture one tonne of emitted CO2. The default value is |
lifetime |
int |
year |
Lifetime of DAC. The default value is |
discount_rate |
float |
% |
Discount rate of the capital cost of DAC. The default value is |
costs#
Selects the capital- and operating-cost assumptions: the NREL Annual Technology Baseline (ATB)
scenario used for capex/FOM, the EIA Annual Energy Outlook (AEO) case used for fuel-price
escalation, and policy incentives (PTC/ITC modifiers, emission prices, per-carrier availability
years and build-rate caps). Processed cost tables are written to resources/costs/costs_{year}.csv.
costs:
# NREL Annual Technology Baseline (ATB) — primary capex/fom source
atb:
model_case: "Market" # Market (commercial) | R&D (advanced research)
scenario: "Moderate" # Advanced | Conservative | Moderate
overrides: # OPTIONAL: per-carrier overrides; falls back to defaults above
# solar:
# scenario: "Advanced"
# nuclear:
# scenario: "Conservative"
# model_case: "R&D"
# EIA Annual Energy Outlook — used for fuel-price escalation
aeo:
scenario: "reference" # reference | high | low
social_discount_rate: 0.02 # fraction; applied to annualization of capex
ng_fuel_year: 2019 # CAISO NG price vintage year; 2019..2023
emission_prices: # CO2/SOx/NOx adder (only with Ep opt)
enable: false
co2: 0. # USD/tCO2 flat price
co2_monthly_prices: false # true = use a monthly time series instead of flat co2 above
ptc_modifier: # Production Tax Credit; subtracted from marginal cost ($/MWh)
onwind: 27.50
biomass: 27.50
itc_modifier: # Investment Tax Credit; fraction of capex reduced
solar: 0.3
offwind: 0.3
offwind_floating: 0.3
EGS: 0.3
geothermal: 0.3
SMR: 0.3
nuclear: 0.3
hydro: 0.3
2hr_battery_storage: 0.3
4hr_battery_storage: 0.3
6hr_battery_storage: 0.3
8hr_battery_storage: 0.3
10hr_battery_storage: 0.3
8hr_PHS: 0.3 # PHS = pumped hydro storage
10hr_PHS: 0.3
12hr_PHS: 0.3
min_year: # earliest commercial-availability year per carrier; carrier excluded before this year
hydrogen_ct: 2040
# null and {} are equivalent here (add_extra_components short-circuits on
# None and would otherwise iterate an empty mapping); null is kept as the
# "nothing configured" spelling used by the other optional maps.
max_growth: # per-carrier annual build-rate caps; {carrier: {base: MW, rate: fraction}}
# ====================================================================
# CLUSTERING — pre-cluster (simpl) and final (cluster) settings
# ====================================================================
Unit |
Values |
Description |
|
|---|---|---|---|
atb |
NREL ATB scenario selection. ATB carries every (scenario, model_case) for each carrier — these settings choose which slice |
||
– scenario |
– |
|
Global default ATB cost trajectory. |
– model_case |
– |
|
Global default. |
– overrides |
Mapping |
Optional per-carrier overrides. Keys are pypsa-names ( |
|
aeo |
EIA AEO fuel-cost scenario. |
||
– scenario |
– |
|
AEO case used to fetch projected fuel costs for the requested year. |
social_discount_rate |
– |
float; e.g. |
Discount rate used for weighting multi-investment objective function values. |
ng_fuel_year |
– |
int; one of 2019-2023 |
Vintage year of the CAISO natural-gas hub prices used for wholesale gas costs. |
emission_prices |
Specify exogenous prices for emission types listed in |
||
– enable |
bool |
|
Add cost for a carbon-dioxide price configured in |
– co2 |
$/t |
float |
Exogenous flat price of carbon-dioxide added to the marginal costs of fossil-fuelled generators according to their carbon intensity. |
– co2_monthly_prices |
bool |
|
Request a monthly carbon-price time series instead of the flat |
ptc_modifier |
Production Tax Credit, subtracted from the marginal cost of the listed carriers. |
||
– {carrier} |
$/MWh |
float; e.g. |
Per-carrier PTC value (e.g. |
itc_modifier |
Investment Tax Credit, applied as a fractional reduction of the capital cost of the listed carriers. |
||
– {carrier} |
p.u. |
float in [0, 1]; e.g. |
Per-carrier ITC fraction (e.g. |
min_year |
Earliest commercial-availability year per carrier; the carrier is excluded from investment periods before this year. |
||
– {carrier} |
– |
int; e.g. |
Per-carrier first-available year. |
max_growth |
Optional per-carrier annual build-rate caps limiting how fast a technology can be deployed. |
||
– {carrier} |
Mapping |
Base build rate in MW and fractional annual growth allowed on top of it. |
ucap#
The ucap section applies an Unforced Capacity (UCAP) derate to conventional generators for
resource-adequacy accounting: each carrier’s capacity is derated by its Forced Outage Rate (FOR),
implemented as p_max_pu = 1 - FOR. Enable it when reserve-margin constraints should be met with
outage-derated rather than installed capacity. Rates are given in percent per carrier.
ucap:
enable: false # true = apply FOR derate to conventional generators
forced_outage_rates: # FOR per carrier, in PERCENT
coal: 11.061
oil: 11.061
hydro: 8.127
CCGT: 6.107
nuclear: 2.207
OCGT: 6.259
sector#
Sector-coupling options (natural gas, heating, service, transport, and industrial demand) are documented on the dedicated sector configuration page.
clustering#
Each clustering and interconnection option will have a different number of minimum nodes which can be clustered to, an error will be thrown in cluster_network notifying you of that number if you have selected a value too low.
Cleaned and labeled REeDs Shapes are pulled from this github repository: https://github.com/pandaanson/NYU-law-work
Note the naming trap: the simplify_network: config block feeds the rule named cluster_resources
(the historical rule name simplify_network no longer exists), while cluster_network: feeds the
rule of the same name. The temporal: block is the primary temporal-resolution knob for solved
networks.
clustering:
simplify_network: # kmeans pre-clustering at the {simpl} wildcard
weighting_strategy: demand-capacity # population | demand-capacity
algorithm: kmeans # kmeans | modularity (HAC removed in v1)
cluster_network: # final clustering at the {clusters} wildcard
weighting_strategy: demand-capacity # population | demand-capacity
algorithm: kmeans # kmeans | modularity
exclude_carriers: [] # carriers to drop before clustering
consider_efficiency_classes: false # true = bin generators by efficiency before aggregation
# Aggregation strategies for generator attributes during clustering.
# Keys map PyPSA generator columns to pandas-groupby reductions.
aggregation_strategies:
generators:
build_year: 'capacity_weighted_average'
lifetime: 'capacity_weighted_average'
start_up_cost: sum # aggregate acts as one unit: starting it starts the members; cap-weighted average understates cycling cost ~N-fold
min_up_time: 'capacity_weighted_average'
min_down_time: 'capacity_weighted_average'
ramp_limit_up: capacity_weighted_average # max would make the cluster as flexible as its single nimblest member
ramp_limit_down: capacity_weighted_average
committable: any
vom_cost: mean
fuel_cost: mean
heat_rate: mean
temporal: # temporal aggregation (segments/typical periods)
resolution_elec: false # int H or false = native hourly
resolution_sector: false # int H or false = native hourly
# KEEP THIS NULL, not {}. cluster_network branches on `is not None`, and an
# empty mapping would send it down the custom-weights path: it re-normalises
# every region's factor and logs "using custom focus weights", for a result
# that is only float-equal to the uniform path by luck.
focus_weights: # OPTIONAL: per-region weights for the clustering objective; null = uniform
# ====================================================================
# SOLVING — solver selection, options, and per-solver tunings
# ====================================================================
Unit |
Value |
Description |
|
|---|---|---|---|
simplify_network: |
Settings for the kmeans pre-clustering stage at the |
||
– weighting_strategy |
str |
{population, demand-capacity} |
When building multiple networks, use ‘population’ if you want to ensure the clusters are assigned constant names. |
– algorithm |
str |
{kmeans, modularity} |
Clustering algorithm for the pre-clustering stage (HAC has been removed). |
cluster_network: |
Settings for the final clustering stage at the |
||
– weighting_strategy |
str |
{population, demand-capacity} |
When building multiple networks, use ‘population’ if you want to ensure the clusters are assigned constant names. |
– algorithm |
str |
{kmeans, modularity} |
Clustering algorithm for the final clustering stage (HAC has been removed). |
– exclude_carriers |
list |
List of carrier names, e.g. |
Carriers whose generators are dropped from the network before clustering. |
– consider_efficiency_classes |
bool |
{true, false} |
If true, bin generators of a carrier into low/medium/high efficiency classes before aggregation so that efficiency spread survives clustering. |
aggregation_strategies: |
|||
– generators –> {key} |
str |
{‘mean’,’max’,’min’,’capacity_weighted_average’,’any’,etc} |
Specify the method of aggregating generator attributes (e.g. |
temporal: |
Temporal aggregation — the primary temporal-resolution knob for solved networks. Equivalent to (and written by) the |
||
– resolution_elec |
– |
int hours or |
Resample electricity-only networks to every n hours; |
– resolution_sector |
– |
int hours or |
Resample sector-coupled networks to every n hours; |
focus_weights: |
|||
– {region_name} |
p.u. |
float |
Optional per-region share of clusters in the form |
solving#
solving:
# tmpdir: "path/to/tmp" # OPTIONAL: solver scratch dir (large LP files)
options:
load_shedding: false # true = add slack generators at very high cost (debug infeasibility)
clip_p_max_pu: 1.e-2 # threshold below which renewable p_max_pu is set to 0
noisy_costs: true # add small random noise to costs to break LP degeneracies
skip_iterations: true # skip line-iteration loop (typically true for capacity expansion)
rolling_horizon: false # true = solve in time-overlapping windows
seed: 123 # RNG seed for noisy_costs
# --- options passed into n.optimize() ---
track_iterations: false
min_iterations: 4
max_iterations: 6
transmission_losses: 2 # 0 = no losses; N = N-piecewise quadratic loss approximation
linearized_unit_commitment: true # LP relaxation of UC binaries
horizon: 8760 # rolling-horizon window length (hours)
assign_all_duals: true # populate dual variables for every constraint
# snapshot_portion: null # OPTIONAL: solve only first fraction of snapshots (smoke testing)
# overlap: 0 # OPTIONAL: rolling-horizon window overlap (hours)
solver:
name: gurobi # gurobi | highs | cplex | cbc | glpk
options: gurobi-default # name of options block below
# Solver-native tuning blocks. The selected block above is passed
# verbatim to the solver. Refer to each solver's docs for the keys.
solver_options:
highs-default:
# https://ergo-code.github.io/HiGHS/options/definitions.html
threads: 4
solver: "ipm"
run_crossover: "off"
small_matrix_value: 1e-6
large_matrix_value: 1e9
primal_feasibility_tolerance: 1e-5
dual_feasibility_tolerance: 1e-5
ipm_optimality_tolerance: 1e-4
parallel: "on"
random_seed: 123
gurobi-default:
threads: 8
method: 2 # 2 = barrier
crossover: 0 # 0 = barrier-only solution (no crossover)
BarHomogeneous: 1 # use homogeneous barrier if standard does not converge
BarConvTol: 1.e-5
OptimalityTol: 1.e-4
FeasibilityTol: 1.e-3
ScaleFlag: 1
Seed: 123
AggFill: 0
PreDual: 0
GURO_PAR_BARDENSETHRESH: 200
gurobi-numeric-focus:
name: gurobi
NumericFocus: 3 # favor numeric stability over speed
method: 2
crossover: 0
BarHomogeneous: 1
BarConvTol: 1.e-5
FeasibilityTol: 1.e-4
OptimalityTol: 1.e-4
ObjScale: -0.5
threads: 8
Seed: 123
gurobi-fallback: # tighter tolerances, retried after a numerical failure
name: gurobi
crossover: 0
method: 2
BarHomogeneous: 1
BarConvTol: 1.e-5
FeasibilityTol: 1.e-5
OptimalityTol: 1.e-5
Seed: 123
threads: 8
cplex-default:
threads: 4
lpmethod: 4 # 4 = barrier
solutiontype: 2 # 2 = non-basic solution (no crossover)
barrier.convergetol: 1.e-5
feasopt.tolerance: 1.e-6
cbc-default: {} # used in CI
glpk-default: {} # used in CI
# Solver-side wall-time cap (HH:MM:SS), enforced via solver hooks. This is
# NOT the scheduler's job time limit: per-rule HPC wall times live in the
# single `walltime:` block in config.slurm.yaml.
walltime: "12:00:00"
# ====================================================================
# CUSTOM FILES — bring-your-own network or costs
# ====================================================================
Unit |
Values |
Description |
|
|---|---|---|---|
options |
|||
– load_shedding |
bool/float |
{‘true’,’false’, float} |
Add generators with very high marginal cost to simulate load shedding and avoid problem infeasibilities. If load shedding is a float, it denotes the marginal cost in $/kWh. |
– 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. |
– noisy_costs |
bool |
{‘true’,’false’} |
Add random noise to marginal cost of generators by \(\mathcal{U}(0.009,0,011)\) and capital cost of lines and links by \(\mathcal{U}(0.09,0,11)\). |
– skip_iterations |
bool |
{‘true’,’false’} |
Skip iterating, do not update impedances of branches. Defaults to true. |
– rolling_horizon |
bool |
{‘true’,’false’} |
Whether to optimize the network in a rolling horizon manner, where the snapshot range is split into slices of size horizon which are solved consecutively. |
– seed |
int |
Random seed for increased deterministic behaviour. |
|
– track_iterations |
bool |
{‘true’,’false’} |
Flag whether to store the intermediate branch capacities and objective function values are recorded for each iteration in |
– min_iterations |
– |
int |
Minimum number of solving iterations in between which resistance and reactence ( |
– max_iterations |
– |
int |
Maximum number of solving iterations in between which resistance and reactence ( |
– transmission_losses |
int |
[0-9] |
Add piecewise linear approximation of transmission losses based on n tangents. 0 means losses are ignored; the shipped default is 2. |
– linearized_unit_commitment |
bool |
{‘true’,’false’} |
Whether to optimise using the linearized unit commitment formulation. |
– horizon |
int |
Number of snapshots in each rolling-horizon window (only used when |
|
– assign_all_duals |
bool |
{‘true’,’false’} |
Whether to populate dual values (shadow prices) for every constraint after solving, not just the standard subset. Needed for downstream price and policy-cost reporting. |
solver |
|||
– name |
– |
One of {‘gurobi’, ‘highs’, ‘cplex’, ‘cbc’, ‘glpk’} |
Solver to use for optimisation problems in the workflow; e.g. clustering and linear optimal power flow. |
– options |
– |
Name of solver_options to use from dictionary below. |
|
solver_options |
dict |
Named blocks of solver-native tuning options (e.g. |
|
walltime |
– |
HH:MM:SS; e.g. ‘12:00:00’ |
Wall-time cap for the solver itself. Per-rule scheduler walltimes are set separately in the top-level |
walltime#
Per-rule wall-time overrides consumed as Snakemake walltime resources and forwarded to
sbatch --time by workflow/run_slurm.sh. This is the single source for per-rule wall times;
it lives in config.slurm.yaml (renamed from config.cluster.yaml, whose name collided with
the {clusters} wildcard and the clustering: section). Rules not listed here fall back to
per-rule defaults defined in the workflow. Local runs ignore these values.
Not to be confused with solving: walltime:, which caps the solver, not the scheduler job.
walltime:
build_renewable_profiles: '04:00:00'
build_fuel_prices: '00:20:00'
add_demand: '02:00:00'
add_electricity: '04:00:00'
aggregate_to_substations: '02:00:00'
aggregate_egs: '01:00:00'
cluster_resources: '05:00:00'
cluster_network: '04:00:00'
solve_network: '20:00:00'
solve_network_validation: '09:00:00'
custom_files#
Bring-your-own network or cost inputs. When activate: true, prepare_network loads
network_name from files_path in place of the cluster_network output (and expects a
costs_2030.csv alongside it), letting you solve an externally-modified network with the standard
solve pipeline.
custom_files:
activate: false # true = use the network/costs paths below instead of pipeline outputs
files_path: '' # directory containing the custom files
network_name: '' # .nc filename inside files_path; loaded in place of cluster_network output
plotting#
plotting:
tech_colors:
"onwind": "#235ebc"
"wind": "#235ebc"
"onshore wind": "#235ebc"
'offwind': "#dd6895"
'offshore wind': "#6895dd"
'offwind-ac': "#6895dd"
'offshore wind ac': "#6895dd"
'offwind-dc': "#74c6f2"
'offshore wind dc': "#74c6f2"
'offwind_floating': "#11a1c1"
"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'
'biomass': '#0c6013'
'solid biomass': '#06540d'
'biogas': '#23932d'
'waste': '#68896b'
'geothermal': '#ba91b1'
"OCGT": "#d35050"
"gas": "#d35050"
"ng": "#d35050"
"natural gas": "#d35050"
"CCGT": "#b20101"
"nuclear": "#ff9000"
"coal": "#707070"
"lignite": "#9e5a01"
"oil": "#262626"
"H2": "#ea048a"
"hydrogen storage": "#ea048a"
"battery": "#b8ea04"
"2hr_battery_storage": "#aee000"
"4hr_battery_storage": "#a4d600"
"6hr_battery_storage": "#9acc00"
"8hr_battery_storage": "#90c200"
"10hr_battery_storage": "#86b800"
"Electric load": "#f9d002"
"electricity": "#f9d002"
"lines": "#70af1d"
"transmission lines": "#70af1d"
"AC-AC": "#70af1d"
"AC line": "#70af1d"
"AC": "#70af1d"
"links": "#8a1caf"
"HVDC links": "#8a1caf"
"DC-DC": "#8a1caf"
"DC link": "#8a1caf"
"DC": "#8a1caf"
"Load": "#2ad55f"
"imports": "#9f2ad5"
"exports": "#B79B48"
"res-elec": "#f9d002"
"res-heat": "#E79CA2"
"res-cool": "#9CE7E2"
"com-elec": "#f9d002"
"com-heat": "#E79CA2"
"com-cool": "#9CE7E2"
"ind-elec": "#f9d002"
"ind-heat": "#E79CA2"
"trn-elec": "#f9d002"
"coal-95CCS": "#4b4b4b"
"coal-99CCS": "#2e2e2e"
"coal-95CC": "#4b4b4b"
"coal-99CC": "#2e2e2e"
"SMR": "#ff5733"
"CCGT-95CCS": "#800000"
"CCGT-95CC": "#800000"
"8hr_PHS": "#069686"
"10hr_PHS": "#058a79"
"12hr_PHS": "#047d6c"
"8hr_PHS_discharger": "#069686"
"10hr_PHS_discharger": "#058a79"
"12hr_PHS_discharger": "#047d6c"
"8hr_PHS_charger": "#069686"
"10hr_PHS_charger": "#058a79"
"12hr_PHS_charger": "#047d6c"
"hydrogen_ct": "#ea048a"
"demand_response": "#8c03fc"
"dac": "#4c004c"
# sector studies only
lpg: "#70217b"
ch4: "#539307"
co2: "#cd7e0d"
res-elec: "#f9d002"
res-total-elec: "#f9d002"
res-urban-elec: "#f9d002"
res-rural-elec: "#f9d002"
res-heat: "#E79CA2"
res-total-heat: "#E79CA2"
res-urban-heat: "#E79CA2"
res-rural-heat: "#E79CA2"
res-cool: "#9CE7E2"
res-total-cool: "#9CE7E2"
res-urban-cool: "#9CE7E2"
res-rural-cool: "#9CE7E2"
com-elec: "#f9d002"
com-total-elec: "#f9d002"
com-urban-elec: "#f9d002"
com-rural-elec: "#f9d002"
com-heat: "#E79CA2"
com-total-heat: "#E79CA2"
com-urban-heat: "#E79CA2"
com-rural-heat: "#E79CA2"
com-cool: "#9CE7E2"
com-total-cool: "#9CE7E2"
com-urban-cool: "#9CE7E2"
com-rural-cool: "#9CE7E2"
ind-elec: "#f9d002"
ind-heat: "#E79CA2"
trn-elec: "#f9d002"
"gas storage": "#f69d09"
"gas pipeline": "#f69d09"
"gas trade": "ae3dc2"
"gas production": "#d35050"
trn-veh: "#0a0100"
trn-veh-lgt: "#0a0100"
trn-veh-med: "#0a0100"
trn-veh-hvy: "#0a0100"
trn-veh-bus: "#0a0100"
trn-elec-veh: "#0a0100"
trn-elec-veh-lgt: "#2BAAD4"
trn-elec-veh-med: "#2FD085"
trn-elec-veh-hvy: "#6DCD32"
trn-elec-veh-bus: "#d3d32c"
trn-lpg: "#0a0100"
trn-lpg-veh: "#0a0100"
trn-lpg-veh-lgt: "#D4552B"
trn-lpg-veh-med: "#D02F7A"
trn-lpg-veh-hvy: "#9232CD"
trn-lpg-veh-bus: "#2C2CD3"
trn-rail: "#0a0100"
trn-rail-psg: "#0a0100"
trn-rail-ship: "#0a0100"
trn-lpg-rail: "#0a0100"
trn-lpg-rail-psg: "#9F9160"
trn-lpg-rail-ship: "#606E9F"
trn-air: "#0a0100"
trn-air-psg: "#0a0100"
trn-lpg-air: "#0a0100"
trn-lpg-air-psg: "#A45B75"
trn-boat: "#0a0100"
trn-boat-ship: "#0a0100"
trn-lpg-boat: "#0a0100"
trn-lpg-boat-ship: "#5BA48A"
res-space-heat: "#F10E1B"
com-space-heat: "#F10E1B"
res-water-heat: "#F10E1B"
com-water-heat: "#F10E1B"
res-rural-cool: "#196CE6"
com-rural-cool: "#196CE6"
res-urban-cool: "#196CE6"
com-urban-cool: "#196CE6"
res-total-cool: "#196CE6"
com-total-cool: "#196CE6"
res-rural-space-heat: "#F10E1B"
com-rural-space-heat: "#F10E1B"
res-urban-space-heat: "#F10E1B"
com-urban-space-heat: "#F10E1B"
res-total-space-heat: "#F10E1B"
com-total-space-heat: "#F10E1B"
res-rural-water-heat: "#E817C3"
com-rural-water-heat: "#E817C3"
res-urban-water-heat: "#E817C3"
com-urban-water-heat: "#E817C3"
res-total-water-heat: "#E817C3"
com-total-water-heat: "#E817C3"
res-rural-air-con: "#3B98C4"
com-rural-air-con: "#3B98C4"
res-urban-air-con: "#3B98C4"
com-urban-air-con: "#3B98C4"
res-total-air-con: "#3B98C4"
com-total-air-con: "#3B98C4"
res-rural-gas-furnace: "#F68D09"
com-rural-gas-furnace: "#F68D09"
res-urban-gas-furnace: "#F68D09"
com-urban-gas-furnace: "#F68D09"
res-total-gas-furnace: "#F68D09"
com-total-gas-furnace: "#F68D09"
res-rural-space-gas-furnace: "#F68D09"
com-rural-space-gas-furnace: "#F68D09"
res-urban-space-gas-furnace: "#F68D09"
com-urban-space-gas-furnace: "#F68D09"
res-total-space-gas-furnace: "#F68D09"
com-total-space-gas-furnace: "#F68D09"
res-rural-oil-furnace: "#006B88"
com-rural-oil-furnace: "#006B88"
res-urban-oil-furnace: "#006B88"
com-urban-oil-furnace: "#006B88"
res-total-oil-furnace: "#006B88"
com-total-oil-furnace: "#006B88"
res-rural-space-oil-furnace: "#006B88"
com-rural-space-oil-furnace: "#006B88"
com-urban-space-oil-furnace: "#006B88"
res-urban-space-oil-furnace: "#006B88"
com-total-space-oil-furnace: "#006B88"
res-total-space-oil-furnace: "#006B88"
res-rural-elec-furnace: "#DCEC13"
com-rural-elec-furnace: "#DCEC13"
res-urban-elec-furnace: "#DCEC13"
com-urban-elec-furnace: "#DCEC13"
res-total-elec-furnace: "#DCEC13"
com-total-elec-furnace: "#DCEC13"
res-rural-space-elec-furnace: "#DCEC13"
com-rural-space-elec-furnace: "#DCEC13"
com-urban-space-elec-furnace: "#DCEC13"
res-urban-space-elec-furnace: "#DCEC13"
com-total-space-elec-furnace: "#DCEC13"
res-total-space-elec-furnace: "#DCEC13"
res-rural-water-gas: "#D87627"
com-rural-water-gas: "#D87627"
res-urban-water-gas: "#D87627"
com-urban-water-gas: "#D87627"
res-total-water-gas: "#D87627"
com-total-water-gas: "#D87627"
res-rural-water-oil: "#774115"
com-rural-water-oil: "#774115"
res-urban-water-oil: "#774115"
com-urban-water-oil: "#774115"
res-total-water-oil: "#774115"
com-total-water-oil: "#774115"
res-rural-water-elec: "#5CDC23"
com-rural-water-elec: "#5CDC23"
res-urban-water-elec: "#5CDC23"
com-urban-water-elec: "#5CDC23"
res-total-water-elec: "#5CDC23"
com-total-water-elec: "#5CDC23"
res-rural-ashp: "#E14C1E"
com-rural-ashp: "#E14C1E"
res-urban-ashp: "#E14C1E"
com-urban-ashp: "#E14C1E"
res-total-ashp: "#E14C1E"
com-total-ashp: "#E14C1E"
res-rural-gshp: "#D926A6"
com-rural-gshp: "#D926A6"
res-urban-gshp: "#D926A6"
com-urban-gshp: "#D926A6"
res-total-gshp: "#D926A6"
com-total-gshp: "#D926A6"
res-rural-space-heat-store: "#3096CF"
com-rural-space-heat-store: "#3096CF"
res-urban-space-heat-store: "#3096CF"
com-urban-space-heat-store: "#3096CF"
res-total-space-heat-store: "#3096CF"
com-total-space-heat-store: "#3096CF"
res-elec-infra: "#9CD926"
com-elec-infra: "#9CD926"
ind-coal-furnace: "#EC13B4"
ind-heat-pump: "#E83E17"
ind-gas-furnace: "#E0AE1F"
ind-elec-infra: "#9CD926"
res-total-elec-dr: "#45ba75"
res-urban-elec-dr: "#45ba75"
res-rural-elec-dr: "#45ba75"
res-total-heat-dr: "#BA458A"
res-urban-heat-dr: "#BA458A"
res-rural-heat-dr: "#BA458A"
res-total-space-heat-dr: "#A55A80"
res-urban-space-heat-dr: "#A55A80"
res-rural-space-heat-dr: "#A55A80"
res-total-water-heat-dr: "#A844BB"
res-urban-water-heat-dr: "#A844BB"
res-rural-water-heat-dr: "#A844BB"
res-total-cool-dr: "#4692B9"
res-urban-cool-dr: "#4692B9"
res-rural-cool-dr: "#4692B9"
com-total-elec-dr: "#45ba75"
com-urban-elec-dr: "#45ba75"
com-rural-elec-dr: "#45ba75"
com-total-heat-dr: "#BA458A"
com-urban-heat-dr: "#BA458A"
com-rural-heat-dr: "#BA458A"
com-total-space-heat-dr: "#A55A80"
com-urban-space-heat-dr: "#A55A80"
com-rural-space-heat-dr: "#A55A80"
com-total-water-heat-dr: "#A844BB"
com-urban-water-heat-dr: "#A844BB"
com-rural-water-heat-dr: "#A844BB"
com-total-cool-dr: "#4692B9"
com-urban-cool-dr: "#4692B9"
com-rural-cool-dr: "#4692B9"
ind-elec-dr: "#45ba75"
ind-heat-dr: "#BA458A"
trn-elec-dr: "#45ba75"
trn-elec-veh-dr: "#45ba75"
nice_names:
OCGT: "Open-Cycle Gas"
CCGT: "Combined-Cycle Gas"
offwind: "Fixed Bottom Offshore Wind"
offwind_floating: "Floating Offshore Wind"
onwind: "Onshore Wind"
solar: "Solar"
PHS: "Pumped Hydro Storage"
hydro: "Reservoir & Dam"
battery: "Battery Storage"
H2: "Hydrogen Storage"
lines: "Transmission Lines"
ror: "Run of River"
Load: "Load Shed"
hydrogen_ct: "Hydrogen Combustion Turbine"
demand_response: "Demand Response"
dac: "Direct Air Capture"
imports: "Electricity Imports"
exports: "Electricity Exports"
# sector studies only
lpg: "Motor Oil"
ch4: "Methane"
co2: "Carbon Dioxide"
res-elec: "Residential Electrical"
res-total-elec: "Residential Electrical"
res-urban-elec: "Residential Urban Electrical"
res-rural-elec: "Residential Rural Electrical"
res-heat: "Residential Heating"
res-total-heat: "Residential Heating"
res-urban-heat: "Residential Urban Heating"
res-rural-heat: "Residential Rural Heating"
res-cool: "Residential Cooling"
res-total-cool: "Residential Cooling"
res-urban-cool: "Residential Urban Cooling"
res-rural-cool: "Residential Rural Cooling"
com-elec: "Commercial Electrical"
com-total-elec: "Commercial Electrical"
com-urban-elec: "Commercial Electrical"
com-rural-elec: "Commercial Electrical"
com-heat: "Commercial Heating"
com-total-heat: "Commercial Heating"
com-urban-heat: "Commercial Urban Heating"
com-rural-heat: "Commercial Rural Heating"
com-cool: "Commercial Cooling"
com-total-cool: "Commercial Cooling"
com-urban-cool: "Commercial Urban Cooling"
com-rural-cool: "Commercial Rural Cooling"
ind-elec: "Industrial Electrical"
ind-heat: "Industrial Heating"
trn-elec: "Transportation Electrical"
"gas storage": "Natural Gas Storage"
"gas pipeline": "Natural Gas Pipeline"
"gas trade": "Natural Gas Trading"
"gas production": "Natural Gas Production"
trn-veh: "Vehicles"
trn-veh-lgt: "Light-Duty Vehicles"
trn-veh-med: "Medium-Duty Vehicles"
trn-veh-hvy: "Heavy-Duty Vehicles"
trn-veh-bus: "Buses"
trn-elec-veh: "Electric Vehicles"
trn-elec-veh-lgt: "Light Duty EV"
trn-elec-veh-med: "Medium Duty EV"
trn-elec-veh-hvy: "Heavy Duty EV"
trn-elec-veh-bus: "Electric Bus"
trn-lpg: "Transportaion Gas"
trn-lpg-veh: "Gas Vehicles"
trn-lpg-veh-lgt: "Light Duty ICE"
trn-lpg-veh-med: "Medium Duty ICE"
trn-lpg-veh-hvy: "Heavy Duty ICE"
trn-lpg-veh-bus: "Gas Bus"
trn-rail: "Rail"
trn-rail-psg: "Passenger Rail"
trn-rail-ship: "Shipping Rail"
trn-lpg-rail: "Rail Oil"
trn-lpg-rail-psg: "Passenger Rail Oil"
trn-lpg-rail-ship: "Shipping Rail Oil"
trn-air: "Airplane"
trn-air-psg: "Passenger Airplane"
trn-lpg-air: "Airplane Gas"
trn-lpg-air-psg: "Passenger Air Gas"
trn-boat: "Marine Shipping"
trn-boat-ship: "Marine Shipping"
trn-lpg-boat: "Domestic Marine Shipping Gas"
trn-lpg-boat-ship: "Domestic Marine Shipping Gas"
res-space-heat: "Space Heat"
com-space-heat: "Space Heat"
res-water-heat: "Water Heat"
com-water-heat: "Water Heat"
res-rural-cool: "Cool"
com-rural-cool: "Cool"
res-urban-cool: "Cool"
com-urban-cool: "Cool"
res-total-cool: "Cool"
com-total-cool: "Cool"
res-rural-space-heat: "Space Heat"
com-rural-space-heat: "Space Heat"
res-urban-space-heat: "Space Heat"
com-urban-space-heat: "Space Heat"
res-total-space-heat: "Space Heat"
com-total-space-heat: "Space Heat"
res-rural-water-heat: "Water Heat"
com-rural-water-heat: "Water Heat"
res-urban-water-heat: "Water Heat"
com-urban-water-heat: "Water Heat"
res-total-water-heat: "Water Heat"
com-total-water-heat: "Water Heat"
res-rural-air-con: "Air Conditioner"
com-rural-air-con: "Air Conditioner"
res-urban-air-con: "Air Conditioner"
com-urban-air-con: "Air Conditioner"
res-total-air-con: "Air Conditioner"
com-total-air-con: "Air Conditioner"
res-rural-gas-furnace: "Gas Furnace"
com-rural-gas-furnace: "Gas Furnace"
res-urban-gas-furnace: "Gas Furnace"
com-urban-gas-furnace: "Gas Furnace"
res-total-gas-furnace: "Gas Furnace"
com-total-gas-furnace: "Gas Furnace"
res-rural-space-gas-furnace: "Gas Furnace"
com-rural-space-gas-furnace: "Gas Furnace"
res-urban-space-gas-furnace: "Gas Furnace"
com-urban-space-gas-furnace: "Gas Furnace"
res-total-space-gas-furnace: "Gas Furnace"
com-total-space-gas-furnace: "Gas Furnace"
res-rural-oil-furnace: "Oil Furnace"
com-rural-oil-furnace: "Oil Furnace"
res-urban-oil-furnace: "Oil Furnace"
com-urban-oil-furnace: "Oil Furnace"
res-total-oil-furnace: "Oil Furnace"
com-total-oil-furnace: "Oil Furnace"
res-rural-space-oil-furnace: "Oil Furnace"
com-rural-space-oil-furnace: "Oil Furnace"
com-urban-space-oil-furnace: "Oil Furnace"
res-urban-space-oil-furnace: "Oil Furnace"
com-total-space-oil-furnace: "Oil Furnace"
res-total-space-oil-furnace: "Oil Furnace"
res-rural-elec-furnace: "Electric Furnace"
com-rural-elec-furnace: "Electric Furnace"
res-urban-elec-furnace: "Electric Furnace"
com-urban-elec-furnace: "Electric Furnace"
res-total-elec-furnace: "Electric Furnace"
com-total-elec-furnace: "Electric Furnace"
res-rural-space-elec-furnace: "Electric Furnace"
com-rural-space-elec-furnace: "Electric Furnace"
com-urban-space-elec-furnace: "Electric Furnace"
res-urban-space-elec-furnace: "Electric Furnace"
com-total-space-elec-furnace: "Electric Furnace"
res-total-space-elec-furnace: "Electric Furnace"
res-rural-water-gas: "Gas Water Heater"
com-rural-water-gas: "Gas Water Heater"
res-urban-water-gas: "Gas Water Heater"
com-urban-water-gas: "Gas Water Heater"
res-total-water-gas: "Gas Water Heater"
com-total-water-gas: "Gas Water Heater"
res-rural-water-oil: "Oil Water Heater"
com-rural-water-oil: "Oil Water Heater"
res-urban-water-oil: "Oil Water Heater"
com-urban-water-oil: "Oil Water Heater"
res-total-water-oil: "Oil Water Heater"
com-total-water-oil: "Oil Water Heater"
res-rural-water-elec: "Electric Water Heater"
com-rural-water-elec: "Electric Water Heater"
res-urban-water-elec: "Electric Water Heater"
com-urban-water-elec: "Electric Water Heater"
res-total-water-elec: "Electric Water Heater"
com-total-water-elec: "Electric Water Heater"
res-rural-ashp: "Air Source Heat Pump"
com-rural-ashp: "Air Source Heat Pump"
res-urban-ashp: "Air Source Heat Pump"
com-urban-ashp: "Air Source Heat Pump"
res-total-ashp: "Air Source Heat Pump"
com-total-ashp: "Air Source Heat Pump"
res-rural-gshp: "Ground Source Heat Pump"
com-rural-gshp: "Ground Source Heat Pump"
res-urban-gshp: "Ground Source Heat Pump"
com-urban-gshp: "Ground Source Heat Pump"
res-total-gshp: "Ground Source Heat Pump"
com-total-gshp: "Ground Source Heat Pump"
res-rural-space-heat-store: "Building Insulation"
com-rural-space-heat-store: "Building Insulation"
res-urban-space-heat-store: "Building Insulation"
com-urban-space-heat-store: "Building Insulation"
res-total-space-heat-store: "Building Insulation"
com-total-space-heat-store: "Building Insulation"
res-elec-infra: "Electric Distribution"
com-elec-infra: "Electric Distribution"
ind-coal-furnace: "Coal furnace"
ind-heat-pump: "Heat Pump"
ind-gas-furnace: "Gas Furnace"
ind-elec-infra: "Electric Distribution"
res-total-elec-dr: Electric Demand Response
res-urban-elec-dr: Urban Electric Demand Response
res-rural-elec-dr: Rural Electric Demand Response
res-total-heat-dr: Heating Demand Response
res-urban-heat-dr: Urban Heating Demand Response
res-rural-heat-dr: Rural Heating Demand Response
res-total-space-heat-dr: Space Heating Demand Response
res-urban-space-heat-dr: Urban Space Heating Demand Response
res-rural-space-heat-dr: Rural Space Heating Demand Response
res-total-water-heat-dr: Water Heating Demand Response
res-urban-water-heat-dr: Urban Water Heating Demand Response
res-rural-water-heat-dr: Rural Water Heating Demand Response
res-total-cool-dr: Cooling Demand Response
res-urban-cool-dr: Urban Cooling Demand Response
res-rural-cool-dr: Rural Cooling Demand Response
com-total-elec-dr: Electric Demand Response
com-urban-elec-dr: Urban Electric Demand Response
com-rural-elec-dr: Rural Electric Demand Response
com-total-heat-dr: Heating Demand Response
com-urban-heat-dr: Urban Heating Demand Response
com-rural-heat-dr: Rural Heating Demand Response
com-total-space-heat-dr: Space Heating Demand Response
com-urban-space-heat-dr: Urban Space Heating Demand Response
com-rural-space-heat-dr: Rural Space Heating Demand Response
com-total-water-heat-dr: Water Heating Demand Response
com-urban-water-heat-dr: Urban Water Heating Demand Response
com-rural-water-heat-dr: Rural Water Heating Demand Response
com-total-cool-dr: Cooling Demand Response
com-urban-cool-dr: Urban Cooling Demand Response
com-rural-cool-dr: Rural Cooling Demand Response
ind-elec-dr: Electric Demand Response
ind-heat-dr: Heating Demand Response
trn-elec-dr: Electric Demand Response
trn-elec-veh-dr: Electric Demand Response
Unit |
Values |
Description |
|
|---|---|---|---|
tech_colors |
– |
carrier -> HEX colour code |
Mapping from network carrier to a colour ([HEX colour code](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet)). |
nice_names |
– |
str -> str |
Mapping from network carrier to a more readable name. |