Example California Model#
PyPSA-USA ships a maintained, runnable California-only configuration at
workflow/repo_data/config/config.california.yaml. It is a sparse overlay on the layered base
config and is run in place, with --configfile repo_data/config/config.california.yaml; it is
not copied into workflow/config/ by init_pypsa_usa.sh, which seeds only the three
per-user files (config.default.yaml, config.api.yaml, config.slurm.yaml). This page is
the reference for that configuration: what data goes into it, which weather years are
available for each ingredient, and which simplifications the results carry.
The model is a California carve-out of the Western Interconnection, not a standalone
network. The footprint is the four California ReEDS zones (p8, p9, p10, p11); the rest
of WECC is not modelled as buses but as external import/export regions at the footprint
boundary — as shipped, an import generator behind an unpriced interface link (see
Trade with the rest of WECC). Load is the
California Public Utilities Commission’s 2026 Integrated Resource Planning hourly forecast,
produced with the SERVM production-cost model.
Running it#
cd workflow
# full pipeline (build + solve + figures)
uv run snakemake -j1 --configfile repo_data/config/config.california.yaml
# data model only, no solver
uv run snakemake data_model -j1 --configfile repo_data/config/config.california.yaml
The first build downloads one ~118 MB SERVM load CSV per planning horizon from
files.cpuc.ca.gov (retrieve_cpuc_servm_load), the CPUC Baseline Generator List workbook
(retrieve_cpuc_baseline_generators), and the GODEEEP / NREL land-access artifacts from
Zenodo. Imports are priced at a flat imports: costs: 60 $/MWh, so no EIA key is needed
for import prices; the wholesale setting is available but the EIA series it pulls is
retail-priced (issue #807). Exports are left
at the base default exports: costs: wholesale, which does call the EIA API, so a key in
workflow/config/config.api.yaml (or $EIA_API_KEY) is still required unless exports are
given a flat price too.
Scenario settings as shipped: interconnect: western, simpl: 75, clusters: 4,
ll: v1.0, opts: REM-3h, planning_horizons: [2030, 2035, 2040, 2045], foresight: perfect,
sector: "" (electricity only).
Data inventory#
Ingredient |
Source |
Where it enters |
Location |
|---|---|---|---|
Demand |
CPUC SERVM 2026 IRP hourly load — 6 California load regions, 9 forecast years, 25 stacked weather years, |
|
|
Demand → bus mapping |
2020 Decennial Census county population, routed through the SERVM region map |
|
|
Existing fleet |
PUDL |
|
|
Unit-commitment parameters |
WECC Anchor Data Set thermal tables, merged onto the EIA fleet and clamped to per-carrier bounds |
|
|
Renewable profiles |
GODEEEP capacity factors, weighted by NREL reV land-access availability |
|
Zenodo (see Weather years) |
Transmission backbone |
ReEDS/NARIS zonal network |
|
|
Trade capacity |
NARIS AC flowgate ratings on the footprint boundary |
|
|
Trade interface caps |
CPUC RESOLVE aggregate CAISO interface limits |
|
|
Trade prices |
Imports: flat $60/MWh. Exports: EIA wholesale electricity prices for the weather year ( |
|
flat value in the config; EIA API ( |
Out-of-state contracts |
CPUC ledger of physically out-of-state units serving California load (75 rows, 11,173 MW) |
|
|
Emissions limit |
CARB 2022 Scoping Plan AB 32 trajectory, annual 2025-2050, import emissions factor 0.428 tCO2/MWh |
|
|
Benchmark reference |
CPUC Baseline Generator List ( |
|
|
Costs |
NREL ATB ( |
|
see Costs |
Demand regions#
SERVM reports six California load regions, mapped onto PyPSA-USA balancing areas by
workflow/repo_data/CPUC/servm_region_map.csv: PGE→CISO-PGAE, SCE→CISO-SCE,
SDGE→CISO-SDGE, IID→IID, LADWP→LDWP, and NCNC→BANC + TIDC. Four balancing
areas carry a blank region and are deliberately dropped with a log message rather than
hard-failing: CISO-VEA (a Nevada footprint) and the California slivers served by PACW
(Siskiyou/Del Norte/Modoc), WALC (Colorado River) and NEVP (Tahoe/CalNeva), none of which
the CPUC California-region files cover. An unknown balancing area still raises.
Only the Net Load component is dispatched against. The full component split is preserved on
the subsector index level and written to
resources/<run>/demand/{interconnect}/power_zonal_components_s{simpl}.parquet. See the
SERVM section of the demand page for the full treatment.
Weather years#
Load and renewable profiles are selected by two independent keys, and they must be kept in step. Setting them to different years decorrelates load from wind and solar, which understates both peak net load and the flexibility requirement.
Demand#
electricity: demand: scenario: servm_weather_years selects one of the 25 weather years
(2000-2024) stacked inside each SERVM forecast-year file. It takes a list with exactly one
entry; multiple entries are reserved for stochastic scenarios and currently raise
NotImplementedError, because the demand output path is not weather-year specific. A mismatch
against the top-level renewable_weather_years is permitted but logs a warning in
build_electrical_demand.
The forecast year is separate and comes from scenario: planning_horizons, which must be
drawn from the nine published SERVM years — 2026, 2028, 2030, 2032, 2035, 2037, 2040, 2042,
2045. SERVM demand is not interpolated or AEO-scaled between them.
Renewables#
Which renewable years are available depends on renewable_scenarios:
Climate scenarios (
rcp45hotter,rcp45cooler,rcp85hotter,rcp85cooler) are indexed by the planning horizon, not by a weather year. One Zenodo record per(tech, scenario)publishes exactly three horizons: 2030, 2040 and 2050.renewable_weather_yearsis not consulted for the profile.historicalis indexed byrenewable_weather_years[0]. Every historical year flows through the same screened NREL land-access path (renewable_land_access, plus optional_cec/_boemoverlays); availability depends on which registry source holds the compressed per-cell file:
Source (first match wins) |
Solar |
Wind 100 m |
Wind 125 m |
|---|---|---|---|
Local (Oak) mirror, SHA256-verified |
1980-2022 |
1980-2022 |
1980-2022 |
Zenodo records |
2012 |
— |
2012 |
A (dataset, year) combination no configured source declares fails at snakemake parse time
with the available years listed — no fallback, no default hub height, no nearest-year
substitution (issue #803 is resolved by the
mirror; the interim unscreened bus-aggregated fallback is retired). This makes every SERVM
demand weather year 2000–2022 pairable with a screened renewable profile of the same year;
SERVM years 2023–2024 currently have no matching GODEEEP profile.
Note
config.california.yaml ships with renewable_scenarios: ['historical'] and
planning_horizons: [2030, 2035, 2040, 2045], precisely so that all four SERVM horizons can
be modelled: historical profiles are indexed by the weather year, not by the horizon. If you
switch to a climate scenario (rcp45hotter, rcp45cooler, rcp85hotter, rcp85cooler) you
must also restrict planning_horizons to [2030, 2040] — only 2030, 2040 and 2050 are
published per (tech, scenario), and the registry fails at parse time for 2035 and 2045.
Spatial resolution#
The footprint is set once, by model_topology: include: reeds_state: ['CA'] (equivalently
reeds_zone: ['p8','p9','p10','p11']). Two transmission resolutions are supported, and
config.california.yaml carries the second as a commented alternative block.
|
|
|
NARIS flowgate file |
|---|---|---|---|
|
|
|
|
|
|
|
|
clusters cannot go below the number of zones in the footprint, which is why the zonal case is
pinned to 4. The county case is pinned to 58 because the county NARIS interface table carries
exactly 58 p06xxx nodes. add_extra_components swaps the flowgate file automatically from
topological_boundaries; no other key changes. See Spatial Configuration for the
simpl/clusters split.
Unit commitment#
conventional: unit_commitment: true is on by default in this configuration, and
solving: options: linearized_unit_commitment: true relaxes the binary commitment variables —
the model is an LP, not a MILP. With opts: REM-3h the problem also runs at 3-hour resolution.
Commitment parameters (min_up_time, min_down_time, ramp_limit_up, ramp_limit_down,
start_up_cost, minimum_load_mw) come from the WECC Anchor Data Set thermal tables merged
onto the EIA fleet in build_powerplants. sanitize_uc_parameters then clamps every
committable row to per-carrier bounds (UC_BOUNDS, one band per carrier drawn from
NREL/EPRI/Intertek cycling literature and CAISO/WECC ADS typicals), filling missing values with
the carrier default and logging clamp/fill counts per carrier and parameter. The binding
invariant is minimum_load_mw / p_nom <= min(summer_derate, winter_derate): a larger stable
minimum than the seasonal derate would leave the unit no feasible output above zero.
add_electricity re-clips the same fields as a second line of defence, and only committable
units are allowed to carry a non-zero p_min_pu (on a non-committable generator p_min_pu is
an unconditional must-run).
Clustering aggregates commitment attributes deliberately: start_up_cost sums (the aggregate
starts as one unit, so a capacity-weighted average would understate cycling cost by roughly the
member count), ramp limits and stable minima take capacity-weighted averages, and committable
takes any.
Trade with the rest of WECC#
California is not modelled as an island. electricity: imports and electricity: exports are
both enabled, adding an external bus per neighbouring flowgate zone ({zone}_imports,
{zone}_exports) and trade links from those buses into the footprint.
The shipped representation is imports: representation: generator. Each external
{zone}_imports bus carries a generic import generator (carrier unspecified_imports)
rated at that zone’s total inbound interface capacity and priced by imports: costs
(the flat $60/MWh above); the imports-carrier links from the external bus into the
footprint are unpriced and rated at the NARIS flowgate capacity, so the price sits on the
generator and the link is pure transfer capacity. The CPUC-contracted out-of-state units are
attached at that same external bus, i.e. behind the model boundary, so their deliveries
traverse an imports link and are metered against the interface and volume caps below.
Import CO2 (imports: co2_emissions: 0.428 tCO2/MWh) is carried by the
unspecified_imports carrier, and the imports carrier is set to zero — PyPSA attributes
primary-energy emissions to generators and stores, never to links, so nothing is
double-counted.
The alternative is representation: store (the base default): the external bus carries a
bottomless Store on the imports carrier instead of a generator, the links into the
footprint are the priced element, and the contracted units are attached at California buses,
where they look like in-state generation and bypass both trade caps. Both modes keep the link
carriers imports/exports untouched, and the export half is identical in both: the negative
export price stays on the export link, the absorbing Store behind it is free, and exported
energy is assigned zero emissions. Imports and exports deliberately use separate external
buses, so the priced import generator cannot sell straight into the export sink.
Three bounds apply to trade.
Per-path capacity —
capacity_limit: truerates each link from the NARIS AC flowgate table for the activetopological_boundaries.Aggregate interface caps —
interface_transmission_limits: trueadds one per-snapshot constraint per interface and direction from the RESOLVE table:Interface
inside (
region_1)outside (
region_2)flow_12MW (export)flow_21MW (import)CA_NWp9, p10, p11
p2, p5, p6, p7, p8
3,592
9,269
CA_SWp9, p10, p11
p12, p13, p25, p27, p28, p30
10,901
10,463
CAISO_Importsp9, p10, p11
all of the above
9,728
10,208
Annual volume —
volume_limit: 25withbalancing_period: yearcaps imported (and separately exported) energy at 25 % of total demand, roughly CAISO’s historical net-import share.
The import emissions factor co2_emissions: 0.428 tCO2/MWh is the same one the CA_AB32
rows carry.
Details of both constraint formulations are in Interface transmission limits and Import and export volume limits.
Policy inputs#
opts: [REM-3h] activates regional emissions limits and 3-hour temporal resolution. The
CA_AB32 rows of config/policy_constraints/regional_Co2_limits.csv give an annual CO2 budget
for California from the 2022 CARB Scoping Plan, from 46.6 MtCO2 in 2025 down to 8.68 MtCO2 in
2045, with imported energy charged at 0.428 tCO2/MWh.
Note
The layered base config (config.default.yaml) carries SAFE_reservemargin,
SAFE_regional_reservemargins and erm; config.california.yaml does not override them and
neither is active as shipped, because opts is REM-3h.
The energy reserve margin is real: an ERM token in {opts} dispatches
add_ERM_constraints in solve_network, so opts: REM-ERM-3h binds it against the
electricity: erm settings.
There is no SAFE constraint on develop. A SAFE token only sets
config["solving"]["constraints"]["SAFE"] = True in _helpers.py, and nothing reads that
flag — no solve-time constraint exists. The SAFE_* keys are therefore currently dead;
treat them as reserved until a planning-reserve constraint is implemented.
technology_capacity_targets.csv and portfolio_standards.csv are wired in but carry mostly
ReEDS-derived and example rows; see Policies.
CPUC baseline benchmark#
run: benchmark_cpuc: true adds benchmark_cpuc_baseline to the workflow targets, writing
results/<run>/cpuc_benchmark/cpuc_capacity_benchmark.csv and a deviation heatmap. It compares
installed capacity in resources/powerplants/powerplants.csv against the CPUC Baseline
Generator List, by region and technology, per horizon.
The rule is deliberately network-free, so a fleet benchmark never drags in a network build.
run: benchmark_cpuc_horizons: [2026] is the shipped default: 2026 is the only pure
fleet-vs-fleet comparison, since the CPUC list is a baseline that stays roughly static at later
years while the model expands. An empty list falls back to scenario: planning_horizons.
Two reconciliations happen before the sides are comparable.
Region. EIA reports every CAISO plant under the single code
CISOwith no sub-BA split, so the benchmark runs at the coarsest resolution both sides support:CAISO(CPUC PGE + SCESDGE vs. model
CISO),LADWP(vs.LDWP),IID, andNCNC(vs.BANC+TIDC). The model side is additionally restricted tostate == "CA", because EIA’sCISOalso covers the NevadaCISO-VEAfootprint. The collapse lives inservm_benchmark_regions.csv.
Technology. Both sides map into a shared
compare_categoryviaservm_tech_map.csv, which carries asidecolumn so one file documents both directions. Anything unmapped becomes its ownUNMAPPED:<name>row — a category is never silently dropped.
Both sides are filtered by the same vintage rule: in service by December 31 of the horizon and not retired by then.
The EXCLUDED row#
Rows of the CPUC list whose physical resource sits outside California are split off before
scoring and reported on a pseudo-region row, EXCLUDED: out-of-state contracted, broken down
by technology. Its model_mw and delta columns are blank: these are contractual ledger
entries that a physically located model cannot carry, so reporting them as model shortfall
would be misleading.
Setting electricity: remote_contracted_resources: enable: true adds the EIA-identifiable
subset of exactly those units back into the model. servm_out_of_state_units.csv holds 75
rows totalling 11,172.8 MW, of which 9 rows / 2,210.0 MW have no eia_plant_id and are
skipped with a summary warning (leaving 66 rows / 8,962.8 MW eligible; rows whose EIA plants
have no live generator in powerplants.csv are skipped too, and each unit’s p_nom is
min(capmax_mw, live plant capacity)).
Where those units land depends on electricity: imports: representation. Under the shipped
generator mode they are not attached at California buses: add_electricity serializes
them into a bundle and add_extra_components attaches them at the external {zone}_imports
buses — behind the model boundary — so their output crosses an imports link and is metered
against the interface and volume caps. Under store mode they are attached directly at the
California bus derived from the contracting SERVM region, inside the footprint and outside
both caps. The benchmark keeps scoring them on the EXCLUDED row
regardless, because it reads powerplants.csv rather than the network. When the option is
on, the MW on that row is what has been added back. See
Out-of-State Contracted Resources for the attachment rules and
their four deliberate simplifications.
Known caveats#
Demand calendar and timezone
SERVM strips are in fixed Pacific Standard Time (UTC−8) with no DST transition. This is not stated in the source files; it was established empirically from the behind-the-meter PV solar-noon centroid. The strips are rolled forward 8 hours to UTC.
SERVM lays each year’s 8760 hours on a synthetic calendar that starts on a Monday, so weekday-versus-weekend hours do not line up with the real weekdays of the planning horizon.
For a leap weather year the SERVM strip contains February 29 and omits December 31, while PyPSA-USA’s snapshots do the opposite. Every hour after February therefore lands one calendar day earlier than in the source file. The strip is mapped positionally onto the network’s own snapshots, so each planning horizon must carry exactly 8760 snapshots — a truncated snapshot window cannot be used with
profile: servm.
Footprint
The California slivers served by
PACW,WALCandNEVP, and the NevadaCISO-VEAfootprint, carry no SERVM load and are dropped.p8appears in theregion_2list of every RESOLVE interface row but is itself a California zone. In a California-only model it is inside the network, so the internalp8-p9AC corridor (~300 MW in the ReEDS/NARIS balancing-area table) carries no trade links and escapes theCAISO_Importscap. Simultaneous CAISO imports are understated by roughly that amount. This is documented rather than corrected.
Fleet and benchmark comparability
Gas Cogen/CHPis a CPUC-only category. EIA technology descriptions have no CHP concept, so California gas cogeneration lands inCCGT/OCGTby prime mover. Expect the model to be short inGas Cogen/CHPand long in the two gas buckets by roughly the same amount.Demand ResponseandPumping Loadare CPUC-only resources with no PyPSA-USA counterpart; they are kept as rows withmodel_mw == 0.The CPUC
Capmax MWcolumn is nameplate capacity as SERVM sees it, while the model side totalsp_nom. Seasonal derates are applied downstream inadd_electricity, not inpowerplants.csv, so the benchmark compares nameplate to nameplate — but any summer-rating comparison against a third source will not line up with either.honor_planned_retirements: truedrops units at their EIA planned retirement date as of the first investment period, so the fleet is smaller than an all-existing-units inventory.
Not implemented
conventional: ambient_derate(CPUC SERVM unit-specific hourly thermal derates) is a reserved phase-2 option.enable: trueraisesNotImplementedError. When it lands it replaces the EIA-860 seasonal derate rather than stacking on it — stacking an ambient derate on a seasonal derate, or on a UCAP-derated capacity credit, double-counts the same thermal deficiency.servm_weather_yearswith more than one entry (stochastic weather scenarios) raisesNotImplementedError.