feat: California configuration on CPUC SERVM 2026 demand (weights, demand profile, import caps, CA config, benchmark)

docs/source/config-configuration.md

@@ -91,8 +91,13 @@ network is aggregated to. `transmission_network` chooses between the ReEDS zonal
 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` applies
-NARIS2024 inter-regional transfer capacity limits and requires the ReEDS backbone.
+`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 {ref}`spatial` for a worked California example
+(`workflow/repo_data/config/config.california.yaml`) at both REeDS-zone and county resolution.
 
 ```{eval-rst}
 .. literalinclude:: ../../workflow/repo_data/config/config.default.yaml

docs/source/config-spatial.md

@@ -35,6 +35,49 @@ model_topology:
 
 Alternatively, you can use the code reeds_state: 'CA' option to achieve the same result by specifying the entire state.
 
+A complete, maintained California configuration ships with the repository as
+`workflow/repo_data/config/config.california.yaml`. It pairs the footprint below with CPUC
+SERVM demand, the RESOLVE CAISO interface limits, and enabled imports/exports:
+
+```yaml
+scenario:
+   interconnect: [western]
+   planning_horizons: [2030, 2035, 2040, 2045]  # CPUC SERVM forecast years
+   clusters: [4]                                # p8, p9, p10, p11
+   simpl: [75]
+
+model_topology:
+   transmission_network: 'reeds'
+   topological_boundaries: 'reeds_zone'
+   interface_transmission_limits: true          # RESOLVE CAISO interface caps
+   include:
+      reeds_state: ['CA']
+```
+
+`clusters` is pinned to 4 because the ReEDS zonal backbone cannot be clustered below the
+number of zones in the footprint, and California holds exactly four.
+
+To run the same footprint at **county resolution**, switch `topological_boundaries` to
+`county` and raise `clusters` to 58 — the number of California counties, and the number of
+`p06xxx` nodes in the county NARIS interface table. `simpl: ['county']` selects the
+county-FIPS fast path in `cluster_simpl`, so the resource layer is built directly on county
+boundaries (a numeric `simpl` of at least 58 also works if you want more resource zones than
+transmission nodes):
+
+```yaml
+scenario:
+   clusters: [58]        # 58 California counties
+   simpl: ['county']     # county-FIPS fast path
+
+model_topology:
+   topological_boundaries: 'county'
+```
+
+`add_extra_components` switches from the balancing-area NARIS flowgate file to the county one
+(`transmission_capacity_init_AC_county_NARIS2024.csv`) automatically when
+`topological_boundaries` is `county` — no other key needs changing. `config.california.yaml`
+carries this same block as a commented alternative.
+
 In addition to filtering by `reeds_zone` and `reeds_state`, you can filter by `reeds_ba`, `trans_reg`, and `nerc_reg` shown graphically below.
 
 

docs/source/configtables/electricity.csv

@@ -2,13 +2,18 @@
 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."
 ,,,
@@ -24,7 +29,7 @@ erm:,,,Energy Reserve Margin settings (used when ERM opt is enabled). Ensures su
 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``), paired with ``model_topology: interface_transmission_limits``. Reserved setting — not currently consumed by the workflow."
+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."
 ,,,
 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,:math:`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."
@@ -33,12 +38,13 @@ gaslimit,MWh thermal,float,"Cap on annual gas-fired primary energy from gas carr
 ,,,
 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``}","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."
+-- 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``, ``fast``}",(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 <https://www.eia.gov/outlooks/aeo/data/browser/>`_,(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.

docs/source/configtables/run.csv

@@ -1,6 +1,8 @@
-,Unit,Values,Description
-name,--,any string,Specify a name for your run. Results will be stored under this name.
-disable_progrssbar,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
+,Unit,Values,Description
+name,--,any string,Specify a name for your run. Results will be stored under this name.
+disable_progrssbar,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."