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

config.slurm.yaml

HPC scheduler settings and the per-rule walltime: block

config.common.yaml

renewable/atlite plumbing that rarely changes per scenario

config.plotting.yaml

figure styling

config.api.yaml

API-key placeholders

config.sector.yaml

sector-coupling defaults

config.default.yaml

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 left, right, or both sides both or neither side None.

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 <source>_<year> (e.g. era5_2019).

Defines an available cutout. On disk, cutouts are stored as cutouts/{interconnect}_{cutout}.nc; the renewable-profiles rules consume the country-wide files cutouts/usa_{cutout}_{year}.nc (e.g. usa_era5_2019.nc), downloaded from Zenodo unless enable: build_cutout is set. Referenced from renewable: {technology}: cutout:.

– – module

–

Must be ‘era5’

Source of the reanalysis weather dataset (ERA5).

– – time

Year interval as strings, e.g. ['2019', '2019']

[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 build_cutout when enable: build_cutout is true.

– {interconnect}

One of western, eastern, texas, usa.

– – 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 resources/powerplants/powerplants.csv. If an included carrier is also listed in extendable_carriers, the capacity is taken as a lower bound.

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 economic or technical

Sets the retirement method for conventional generators. If technical all generators p_nom_min are set to p_nom to prevent selling off of the asset. Retirements are then tracked in post-processing. If economic existing plants have their p_nom_min set as 0, p_nom_max set to p_nom, and capital costs set to fixed costs. Generators with p_nom are then added to handle capacity expansion.”

honor_planned_retirements

bool

{true, false}

Drop existing/proposed units at their EIA planned_generator_retirement_date (applies at the first investment period). false keeps every existing unit indefinitely (pre-v1 behavior).

extendable_carriers:

Capacity-expansion candidates. Carriers listed here get extendable p_nom and pay annualized capex; carriers listed only in the *_carriers lists above are fixed (brownfield-only).

– 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 conventional_carriers list, the lower limit of the capacity expansion is set to 0.

– 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 demand: profile: servm — the SERVM load weights decide which bus each region’s contracts attach to. Modelling simplifications are documented under Generators & Storage Units.

– enable

bool

{true, false}

Attach the CA-contracted out-of-state units at CA buses. false (the default) is fully inert: no extra rule inputs are requested and the network is unchanged. NOTE: when this is on, the MW reported on the EXCLUDED row of the CPUC baseline benchmark is what has been added back into the model — the benchmark reads powerplants.csv rather than the network, so it keeps scoring these units as excluded.

– file

–

path

CPUC out-of-state contracted-unit ledger (default repo_data/CPUC/servm_out_of_state_units.csv). Rows with an empty eia_plant_id (Mexicali TDM/LR2, Powerex/BC, ESJ Baja wind and a few pure entitlement rows) are skipped with a summary warning.

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 ERM option is the active resource-adequacy mechanism.

SAFE_regional_reservemargins

–

path

CSV of per-region planning reserve margins (repo_data/config/policy_constraints/SAFE_regional_prm.csv). Reserved setting — not currently enforced by an active constraint.

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 all for all regions, or specify region codes (state, interconnect, NERC region, or ReEDS zone). Defaults to all: 0.15 if not specified.

regional_Co2_limits

–

path

CSV of per-region CO2 caps in tCO2/yr (repo_data/config/policy_constraints/regional_Co2_limits.csv). Enforced when the REM keyword is present in the {opts} wildcard.

technology_capacity_targets

–

path

CSV of forced minimum/maximum capacity builds by technology and region (repo_data/config/policy_constraints/technology_capacity_targets.csv). Enforced when the TCT keyword is present in the {opts} wildcard.

portfolio_standards

–

path

CSV of RPS/CES clean-energy fractions by region (repo_data/config/policy_constraints/portfolio_standards.csv). Enforced when the RPS keyword is present in the {opts} wildcard (covers both RPS and CES targets).

transmission_interface_limits

–

path

CSV of MW limits on flows across inter-regional transmission interfaces (repo_data/config/policy_constraints/transmission_interface_limits.csv, columns interface, region_1, region_2, flow_12, flow_21). Applied by solve_network when model_topology: interface_transmission_limits is true, as a per-snapshot cap on the aggregate flow across each interface rather than a path-by-path limit: flow_12 caps exports out of region_1 into region_2, flow_21 caps imports in the opposite direction. Only the import/export Link components added by add_extra_components are constrained, so the caps are inert when imports/exports are disabled.

co2base

\(t_{CO_2}/a\)

float

Reference CO2 budget scaled by a Co2L<x> token in {opts}: Co2L0.05 sets co2limit = 0.05 * co2base. Optional, but required whenever Co2L carries a factor.

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 Co2L keyword in the {opts} wildcard.

co2limit

\(t_{CO_2}/a\)

float

System-wide cap on annual CO2 emissions, added as a global constraint in prepare_network. Only applied when co2limit_enable is true.

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 CH4L keyword in the {opts} wildcard.

gaslimit

MWh thermal

float

Cap on annual gas-fired primary energy from gas carriers (OCGT, CCGT, CHP), added as a global constraint in prepare_network. Only applied when gaslimit_enable is true.

demand:

– bus_allocation

–

One of {population, breakthrough}

How zone-level demand is distributed to individual buses. population (default) weights buses by 2020 Decennial Census county populations (split evenly across each county’s substations, then each substation’s buses). breakthrough uses the legacy nominal-demand column (Pd) from the 2016-vintage Breakthrough Energy grid model.

– profile

–

One of {efs, eia, eer, servm}

Datasource for electrical load data. EFS pulls future state level electrical demand data. EIA pulls historical balancing level electrical demand data. EER pulls future state-level profiles from the EER dataset; when selected, planning_horizons must be one of 2021, 2025, 2030, 2035, 2040, 2045, or 2050 and renewable_weather_years must contain exactly one year from 2007-2013 or 2016-2023. SERVM pulls CPUC SERVM hourly load for the six California load regions (California models only); when selected, planning_horizons must be one of 2026, 2028, 2030, 2032, 2035, 2037, 2040, 2042, or 2045, and each horizon must carry a full 8760-hour snapshot year. Only the Net Load component is dispatched against; the full component split is written to power_zonal_components_s{simpl}.parquet. See the SERVM section of the demand data page.

– scenario:

– – efs_case

–

One of {reference, medium, high}

(UNDER DEVELOPMENT) Extracts EFS data according to level of adoption

– – efs_speed

–

One of {slow, moderate, rapid}

(UNDER DEVELOPMENT) Extracts EFS data according to speed of electrification

– – eer_file

–

One of {demand_EER2025_100by2050.h5, demand_EER2025_Baseline_AEO2023.h5, demand_EER2025_IRAlow.h5}

Selects the EER demand dataset file to download and use when profile is eer.

– – 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 profile is servm. Multiple entries are reserved for stochastic scenarios and currently raise NotImplementedError. Keep equal to the top-level renewable_weather_years so load and renewable profiles share a weather year; a mismatch logs a warning.

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

true or false

Enable electric imports

– representation

store or generator

How out-of-footprint supply is represented. store (default) puts a bottomless Store behind each external zone and PRICES the interface Link. generator puts a priced import Generator (carrier unspecified_imports, carrying co2_emissions) on the external bus, leaves the interface link unpriced, and moves the CPUC contracted out-of-state units behind the boundary so their deliveries are metered against volume_limit and the interface capacity.

– costs

$/MWh

wholesale or <name of carrier> or float

Cost of electric imports from regions outside of model scope. Wholesale will use in monthly wholesales electric prices. float will assign a user specified value. carrier will take average marginal cost of the carrier.

– co2_emissions

CO2/MWh

float

CO2 emissions of electric imports from regions outside of model scope.

– capacity_limit

true or false

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 inf to not enforce volume limits.

– balancing_period

day or week or month or year

Balancing period for electric imports from regions outside of model scope.

exports:

Configure electric exports to regions outside of model scope

– enable

true or false

Enable electric exports

– costs

$/MWh

wholesale or <name of carrier> or float

Cost of electric exports to regions outside of model scope. Wholesale will use in monthly wholesales electric prices. float will assign a user specified value. carrier will take average marginal cost of the carrier.

– capacity_limit

true or false

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 inf to not enforce volume limits.

– balancing_period

day or week or month or year

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 atlite: cutouts: (e.g. era5).

Selects the weather-data source for this technology. Combined with the weather year to pick the cutout file cutouts/usa_{cutout}_{year}.nc (e.g. usa_era5_2019.nc).

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

–

latitude_optimal, flat, or a dict with slope and azimuth

Panel orientation. latitude_optimal tilts panels at the latitude-optimal angle; a custom dict sets tilt (slope) and compass orientation (azimuth, 180 = south) explicitly.

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 true.

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 corine, natura, and cec land screens apply only when renewable: dataset: atlite; with dataset: godeeep they are bypassed in favor of the NREL renewable_land_access exclusions.

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 atlite: cutouts: (e.g. era5).

Selects the weather-data source for this technology. Combined with the weather year to pick the cutout file cutouts/usa_{cutout}_{year}.nc (e.g. usa_era5_2019.nc).

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

– 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 distance is applied (e.g. urban areas).

natura

bool

{true, false}

Switch to exclude Protected Planet natural protection areas. Area is excluded if true.

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 corine, natura, and cec land screens apply only when renewable: dataset: atlite; with dataset: godeeep they are bypassed in favor of the NREL renewable_land_access exclusions.

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 atlite: cutouts: (e.g. era5).

Selects the weather-data source for this technology. Combined with the weather year to pick the cutout file cutouts/usa_{cutout}_{year}.nc (e.g. usa_era5_2019.nc).

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 offwind_floating.

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. [80, 200] (open water).

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 true.

boem_screen

bool

{true, false}

Restrict eligible area to BOEM offshore-wind planning areas. Off by default for fixed-bottom offwind; on by default for offwind_floating.

min_depth

m

float

Minimum water depth (offwind_floating only); sites shallower than this are excluded (60 m by default, the fixed-bottom/floating boundary).

max_depth

m

float

Maximum water depth; deeper sites are excluded (60 m for fixed-bottom offwind, 1300 m for offwind_floating).

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 corine, natura, boem_screen, and depth/shore screens apply only when renewable: dataset: atlite; with dataset: godeeep they are bypassed in favor of the NREL renewable_land_access exclusions (with optional apply_boem_osw overlay).

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 by rule retrieve_godeeep_cf from the sources declared in godeeep_cf_registry (see below).

  • NREL land-access artifacts (10.5281/zenodo.20127899) — avail_{tech}_{access}[_cec|_boem].nc per-cell availability rasters and caps_{tech}_{access}[_cec|_boem].nc per-bus rollups (weight, p_nom_max, potential, average_distance, and underwater_fraction for 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

godeeep_wind_height

Oak mirror

Zenodo

solar_historical_compressed

—

1980–2022

2012 only (20127513)

wind_100m_historical_compressed

"_100m"

1980–2022

not published

wind_125m_historical_compressed

"_125m"

1980–2022

2012 only (20127520)

solar_rcp45hotter_compressed

—

—

2030 / 2040 / 2050 (20127523)

solar_rcp45cooler_compressed

—

—

2030 / 2040 / 2050 (20127562)

solar_rcp85hotter_compressed

—

—

2030 / 2040 / 2050 (20127589)

solar_rcp85cooler_compressed

—

—

2030 / 2040 / 2050 (20127633)

wind_125m_rcp45hotter_compressed

"_125m"

—

not published (record 20127545 returns HTTP 404)

wind_125m_rcp45cooler_compressed

"_125m"

—

2030 / 2040 / 2050 (20127572)

wind_125m_rcp85hotter_compressed

"_125m"

—

2030 / 2040 / 2050 (20127604)

wind_125m_rcp85cooler_compressed

"_125m"

—

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.

  • rcp45hotter is solar-only. The corresponding 125 m wind record was never registered, so the registry declares it with an empty year list; requesting it fails with available 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:

  1. Dataset selection (config.common.yaml):

    renewable:
      dataset: godeeep    # set to atlite for the ERA5 + CORINE workflow
    
  2. 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_horizons wildcard (under scenario:); the historical year comes from renewable_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)
    
  3. 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
    
  4. NREL land-access exclusions (required when renewable.dataset: godeeep; the workflow raises if renewable_land_access is 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

reference

One of {reference, limited, open}; null only valid with dataset: atlite

NREL reV access scenario applied as availability weighting to GODEEEP capacity factors. Required non-null when renewable: dataset: godeeep — the schema and the workflow both raise otherwise. reference is NREL’s central land-access assumption (the default); limited is the most restrictive; open is the most permissive (sensitivity studies). Selects the avail/caps file pair downloaded from Zenodo.

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 _cec file variants. No effect on offshore tech.

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 _boem file variants. No effect on onshore tech.

godeeep_wind_height

–

str (e.g. _100m, _125m)

Hub-height suffix used to construct the raw GODEEEP wind capacity-factor filename (e.g. wind_gen_cf_2030_125m_compressed.nc). Must match a published Zenodo record (wind_<height>_<scenario>_compressed). Ignored for solar.

renewable: godeeep_cf_weighting

capacity

One of {capacity, availability}

How GODEEEP cell capacity factors are weighted up to the s{simpl} cluster bus. capacity (default): availability-weighted within each substation region, then weighted across the cluster’s substations by NREL installable capacity (p_nom_max). availability: a single availability-weighted mean over every cell of the cluster (the behaviour before this key existed). Only read when renewable: dataset: godeeep. Note this is deliberately NOT what pypsa-usa master computes — there the cluster profile is formed in simplify_network, weighting substation p_max_pu by EXISTING p_nom and falling back to an unweighted mean where a cluster has no existing capacity.

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.

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 topology with underground CO2 storage

Sector-less network with underground CO2 storage enabled.#

Sector-based network topology with underground CO2 storage

Sector-based network with underground CO2 storage enabled.#

Sector-less network topology without CCTS

Reference: sector-less network without CCTS.#

Sector-based network topology 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 topology with CO2 storage and transport

Sector-less network with underground CO2 storage and CO2 transport.#

Sector-based network topology with CO2 storage and 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 false.

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 (true) or disable (false) the capability to transport captured CO2 between nodes. The default value is false.

– capital_cost

int

$/mile

Capital cost of building one mile long CO2 pipeline. The default value is 2736000, which assumes a 12-inch diameter and a cost of $228000 per inch for each mile of CO2 pipeline built based on EPA estimation.

– marginal_cost

int

$/t

Marginal cost of transporting one tonne of captured CO2. The default value is 4, which is the average cost of transporting one tonne of captured CO2 based on NETL estimation.

– lifetime

int

year

Lifetime of a CO2 pipeline. The default value is 40, which is the average lifetime of a CO2 pipeline based on NETL estimation.

– discount_rate

float

%

Discount rate of the capital cost of building a network of CO2 pipelines. The default value is 0.07.

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 granularity is set to node, 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, setting granularity to node will render the topography of a sector-less network similar to this.

  • When granularity is set to state, 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, setting granularity to state will render the topography of a sector-less network similar to this.

  • When granularity is set to nation, 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, setting granularity to nation will render the topography of a sector-less network similar to this.

Sector-less network with node-granularity DAC

Sector-less network with DAC at node granularity.#

Sector-less network with state-granularity DAC

Sector-less network with DAC at state granularity.#

Sector-less network with nation-granularity DAC

Sector-less network with DAC at nation granularity.#

For a sector-based model:

  • When granularity is set to node, 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, setting granularity to node will render the topography of a sector-based network similar to this.

  • When granularity is set to state, 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, setting granularity to state will render the topography of a sector-based network similar to this.

  • Given that a granularity set to nation does not make sense in a sector-based model, it defaults to node in this case.

Sector-based network with node-granularity DAC

Sector-based network with DAC at node granularity.#

Sector-based network with state-granularity DAC

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 node.

capital_cost

int

$/tCO2/h

Capital cost of DAC to capture one tonne of CO2 per hour. The default value is 6000000, which is based on the Danish Energy Agency (DEA) estimation.

electricity_input

float

MWh/tCO2

Amount of electricity needed for DAC to capture one tonne of emitted CO2. The default value is 2.5, which is the average energy in MWh needed to capture one tonne of CO2 using electricity only (no heat) based on https://doi.org/10.1557/s43581-024-00091-5 estimation.

lifetime

int

year

Lifetime of DAC. The default value is 20.

discount_rate

float

%

Discount rate of the capital cost of DAC. The default value is 0.07.

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 load_costs uses.

– scenario

–

Moderate | Advanced | Conservative

Global default ATB cost trajectory. Advanced = optimistic / fastest cost decline; Conservative = pessimistic. See Costs.

– model_case

–

Market | R&D

Global default. Market bakes current policy incentives (PTC/ITC) into financing; R&D strips them out for a pure-learning view.

– overrides

Mapping

Optional per-carrier overrides. Keys are pypsa-names (solar, onwind, nuclear, CCGT, 4hr_battery_storage, …); each value may set scenario and/or model_case. Anything unset falls back to the global default.

aeo

EIA AEO fuel-cost scenario.

– scenario

–

reference | high | low

AEO case used to fetch projected fuel costs for the requested year.

social_discount_rate

–

float; e.g. 0.02

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 network.carriers to marginal costs.

– enable

bool

true or false

Add cost for a carbon-dioxide price configured in costs: emission_prices: co2 to marginal_cost of generators (other emission types listed in network.carriers possible as well). Can also be set via the Ep keyword in the {opts} wildcard.

– 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

true or false

Request a monthly carbon-price time series instead of the flat co2 price above (Ept opts keyword). Parsed, but monthly pricing is not yet implemented — it falls back to the static price.

ptc_modifier

Production Tax Credit, subtracted from the marginal cost of the listed carriers.

– {carrier}

$/MWh

float; e.g. onwind: 27.50

Per-carrier PTC value (e.g. onwind, biomass).

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. solar: 0.3

Per-carrier ITC fraction (e.g. solar, offwind_floating, EGS, 4hr_battery_storage, 8hr_PHS).

min_year

Earliest commercial-availability year per carrier; the carrier is excluded from investment periods before this year.

– {carrier}

–

int; e.g. hydrogen_ct: 2040

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: MW, rate: fraction}

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 {simpl} wildcard. Naming trap: this config block feeds the rule named cluster_resources — the historical rule name simplify_network no longer exists.

– 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 {clusters} wildcard.

– 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. build_year, ramp_limit_up, heat_rate) when generators are combined during clustering.

temporal:

Temporal aggregation — the primary temporal-resolution knob for solved networks. Equivalent to (and written by) the nH / nSEG tokens of the {opts} wildcard.

– resolution_elec

–

int hours or false

Resample electricity-only networks to every n hours; false keeps native hourly resolution.

– resolution_sector

–

int hours or false

Resample sector-coupled networks to every n hours; false keeps native hourly resolution.

focus_weights:

– {region_name}

p.u.

float

Optional per-region share of clusters in the form California: 0.5, placing half of all clusters in that region. Fractions must sum to at most 1. Applied by the kmeans algorithm in both cluster_resources and cluster_network; null distributes clusters by the configured weighting.

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 network.lines['s_nom_opt_X'] (where X labels the iteration)

– min_iterations

–

int

Minimum number of solving iterations in between which resistance and reactence (x/r) are updated for branches according to s_nom_opt of the previous run.

– max_iterations

–

int

Maximum number of solving iterations in between which resistance and reactence (x/r) are updated for branches according to s_nom_opt of the previous run.

– 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 rolling_horizon is true).

– 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. gurobi-default, highs-default); the block selected by solver: options is passed verbatim to the solver.

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: section.

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.