Release Notes#
v1.0.0 (2026-10-05)#
v1.0.0 restructures the workflow around early spatial aggregation (“simplify-early”) and modernizes the repository layout. If you are migrating a workflow or custom configuration from v0.9.0 or an earlier checkout, these are the changes you will notice:
Workflow restructuring#
simplify_networkwas split and the DAG reordered. The old single rule becameaggregate_to_substations(topology-only reduction to substations) followed bycluster_resources(kmeans/modularity clustering to{simpl}zones). Renewable profiles, demand construction, andadd_electricitynow run after clustering, at{simpl}resolution instead of nodal resolution. This cuts peak memory of the heavy rules several-fold and speeds up the data pipeline substantially. See Workflow.HAC clustering was removed. Supported clustering algorithms are
kmeansandmodularity. The config sectionclustering: simplify_network:keeps its historical name but feeds thecluster_resourcesrule.EGS supply curves are remapped through the cluster busmap. A new
aggregate_egsrule converts substation-keyed NREL EGS supply curves to cluster buses (capacity-weighted means for intensive quantities, sums for extensive ones).
Repository layout#
resources/is organized category-first:networks/,busmaps/,profiles/,geospatial/,costs/,prices/,demand/,powerplants/, … — instead of per-interconnect flat folders. File names are unchanged.Unused config keys and never-read rule parameters were removed. The canonical config templates live in
workflow/repo_data/config/and the workflow loads its whole layered base from there;workflow/config/is untracked and holds only the per-user files (config.api.yaml,config.slurm.yaml, your own scenario configs) seeded byinit_pypsa_usa.sh.config.cluster.yamlwas renamedconfig.slurm.yaml. The old name collided with the{clusters}wildcard and theclustering:section while only ever describing the job scheduler. Its dead per-rule{rule}: {walltime: ...}blocks are gone; the single top-levelwalltime:block is the one the rules actually read. Rename your copy underworkflow/config/to keep your account and partition settings.Scenario configs are overlays, not forks.
config.default.yamlis itself a loaded layer, so a--configfileonly needs the keys it changes, and every top-level key is now owned by exactly one layered file. A full copy still works — it simply overrides every key it repeats. See Configuration.The merged configuration is validated against
workflow/schemas/config.schema.yamlat parse time. A misspelled key inside a closed section (electricity:,model_topology:,clustering:,solving:, …) now fails immediately instead of silently falling back to a default several rules later.The EIA API key can be supplied as
$EIA_API_KEY, which takes precedence overconfig/config.api.yamland keeps the key out of your files entirely.renewable_land_accessnow defaults toreference. The shipped templates previously pairedrenewable.dataset: godeeepwith a null land-access setting, a combinationbuild_renewable_profilesrejects — no shipped config could build renewable profiles from a clean checkout. The default is NREL’s central land-access assumption; expectretrieve_nrel_exclusion_artifactjobs in every godeeep DAG. Null remains valid only withdataset: atlite.
Correctness fixes validated by an equivalence harness#
The refactor was validated by a pipeline-equivalence harness comparing the restructured DAG against the pre-refactor baseline on a California test system. The harness caught and the line fixes four real bugs, all of which also affected the old pipeline or would have silently shifted results:
Demand disaggregation conservation error (state totals now conserved exactly).
Hydro plants dropped during attachment under some clusterings.
Transmission
length_factorapplied twice in capital costs.Empty renewable profiles attached as zero-output generators.
The full engineering change-log, including per-change expected effects on model
results, is maintained in the repository at
docs/CHANGELOG-v1-epic.md.
California / CPUC SERVM#
New demand source
electricity: demand: profile: servm— CPUC SERVM 2026 IRP hourly load for the six California load regions (PGE, SCE, SDGE, IID, LADWP, NCNC), retrieved per forecast year from files.cpuc.ca.gov. Nine forecast years are published (2026, 2028, 2030, 2032, 2035, 2037, 2040, 2042, 2045) andplanning_horizonsis restricted to them.electricity: demand: scenario: servm_weather_yearspicks one weather year out of the stacked 2000-2024 record. OnlyNet Loadis dispatched; the full component split is written to a new component-resolved zonal artifact (power_zonal_components_s{simpl}.parquet), which is now produced for every demand profile. See CPUC SERVM (California).SERVM load-allocation weights — a new
build_servm_load_weightsrule composes the base→substation→cluster busmaps into a fractional(SERVM region, bus)table, so a cluster that straddles two regions (Los Angeles County holds both LDWP and CISO-SCE buses) receives the sum of its share of each.Interface transmission limits are live.
model_topology: interface_transmission_limitsandelectricity: transmission_interface_limitswere previously dead keys. They now apply the RESOLVE interface table as a per-snapshot cap on the aggregate flow across each interface. The constraint scopes to the import/export links, so it is inert when trade is disabled; the resulting understatement forregion_2entries inside the footprint (notablyp8in California-only runs) is documented in Transmission.New maintained config
config.california.yaml— a runnable California-only model on SERVM demand with the CAISO interface caps and imports/exports enabled, at REeDS-zone resolution (clusters: 4) with a commented county-resolution alternative (clusters: 58,simpl: county).Phase-2 hook
conventional: ambient_derate— reserved for CPUC SERVM unit-specific ambient-temperature derates. It is not implemented; enabling it raisesNotImplementedErrorinadd_electricity. When it lands it replaces the EIA-860 seasonal derate rather than stacking on it.
Documentation#
New Model Description section (Workflow, Networks & Components, Custom Constraints, Network Schema).
Configuration-reference pages are regenerated from the live config templates and guarded by tests; both workflow DAG diagrams were regenerated from the current rule graph.
Breaking changes since 2026-08-31#
The GenX-style operational reserve constraint was removed (
6eacc8cc).add_operational_reserve_marginand itsGenerator-preserve bound are gone fromopts/reserves.py, along with the call insolve_network, theelectricity: operational_reserveblock inconfig.default.yaml, its schema entry and its config-table rows. The formulation was never verified against its implementation. No{opts}token was involved — it was triggered byelectricity: operational_reserve: activate: true— so a config that still carries anelectricity: operational_reserve:block now fails schema validation at parse time (electricity:is a closed section); delete the block. The energy reserve margin (ERMtoken,add_ERM_constraints) is unchanged and is the active resource-adequacy mechanism.
Correctness fixes since 2026-08-31#
Portfolio standards (
RPS) worked at all only in the unit tests (7da43cb1).add_RPS_constraintsreadsnakemake.params.planning_horizons, whichrule solve_networknever declared, so theRPStoken raisedAttributeErrorin the workflow; the horizons now come fromn.investment_periods, which is also correct underforesight: myopic.ReEDS CES trajectories were silently dropped (
bc2131d4).ces_fraction.csvis wide (st, 2010, ..., 2050); after melting, itsplanning_horizonvalues were strings and were filtered out against integer horizons, so 0 of 359 CES rows survived and no ReEDS CES target was ever enforced. RPS rows, already long with integer years, were unaffected. Expect CES targets to start binding.One empty RPS zone no longer cancels the remaining RPS constraints (
6b1732ee). A zone with no eligible generators returned from the whole function, dropping every remaining (zone, horizon, carrier) constraint; it now logs a warning and continues.Land-use limits subtract existing and frozen capacity from the potential (
46be26d7,43096a8a).p_nom_maxfrombuild_renewable_profilesis a gross land potential, and nothing was subtracted from it. Underforesight: myopic,freeze_prior_periodsmakes each horizon’s builds non-extendable, so those MW left the constraint’s left-hand side while the right-hand side kept the full potential and the same land could be built on again every horizon. The right-hand side is now the group potential net of the non-extendable capacity of the same carrier and land region that is active in the period (peak across the modelled periods), clipped at zero, and exhausted groups are named in a warning. This changes results for myopic multi-horizon runs (less renewable headroom in later horizons); perfect-foresight runs whoseland_regiongenerators are all extendable are unchanged. See Land-use limits.Vintaged bidirectional links are now coupled (
e4305b15).add_itlsnames future-horizon interface links<interface>_fwd_<year>/<interface>_rev_<year>, but the pairing regex was anchored on_fwd/_revat the end of the name, so those links were made extendable without the equal-expansion constraint and a multi-horizon solve could build one direction only, at half the capital cost of a line. Pairing now happens within a vintage.Heat-pump cooling links are back in the dispatch constraint (
b6607b0d, sector studies only). The selection looked for a-coolingsuffix whilebuild_heatnames the links<heating link>-cool, so it matched nothing and the dispatch constraint collapsed into PyPSA’s own capacity bound — heating and cooling could each run at full capacity in the same snapshot although they are one physical unit.electricity: transmission_interface_limitsis now actually read (4754bc5b).solve_networkandsolve_network_validationhard-coded the interface-limits CSV path, so pointing the key at another file had no effect. The shipped default path is unchanged, so existing configs resolve the same file and results are unaffected.
Trade with external regions#
Generator-based imports and boundary-metered CPUC contracted resources (#810). A new
electricity: imports: representationkey selects how the world outside the footprint is represented.store(the default) is the previous behaviour: a bottomlessStoreon each external bus feeding priced links into the footprint.generatorinstead puts a priced import generator (carrierunspecified_imports, rated at the zone’s inbound interface capacity) on the external bus and leaves the links into the footprint unpriced, and it attaches California’s CPUC-contracted out-of-state units at that external bus — behind the model boundary — so their deliveries are metered against the import volume and interface caps instead of looking like in-state generation. Import CO2 moves onto theunspecified_importscarrier. The external-region code moved out ofadd_extra_components.pyinto a newworkflow/scripts/external_regions.py.config.california.yamlshipsrepresentation: generatorand prices imports at a flatcosts: 60$/MWh, because the EIAwholesaleseries is retail-priced (#807). See Example California Model.
Performance, environment and tooling#
EIA API responses are cached on disk (
8443b1be).DataExtractor._request_eia_datamemoises every response under$EIA_CACHE_DIR(defaultdata/eia/cache, relative toworkflow/, already gitignored), keyed on the API-key-stripped, parameter-sorted URL, so the key never lands in a cache file and the directory is shareable. Every EIA consumer (fuel costs, demand, trade, emissions, …) benefits; cache failures are logged and never fatal, and non-200 responses are not cached.build_fuel_pricesonly calls the EIA API when dynamic fuel pricing is on (b8eca6d3). A default power-only run hasconventional: dynamic_fuel_price: enable: falseand never reads the state gas/coal price tables, but the script fetched them anyway whenever a key was present. The EIA key is therefore no longer needed for a default run; Installation lists the features that do need it.The unused
AC_expcarrier was dropped (b68d2502) along withadd_itls’ ignoredexpansionargument and the carrier’s colour entries in two validation maps. No link, constraint or figure changes.Benchmark directives on every rule, plus Slurm resource tooling (#809). Eleven rules — including
cluster_resourcesandadd_extra_components— had nobenchmark:directive, so snakemake recorded no wall time or peak RSS for them. Benchmark paths mirror each rule’s log path and carry every wildcard.run_slurm.shnow takes a list of overlay configs and runs each as its ownsnakemake --clusterinvocation;slurm_submit.shwrapssbatchbecause several rules compute a floatmem_mb, whichsbatch --memrejects;collect_benchmarks.shandreport_benchmarks.pyturn the results into per-rule memory and walltime recommendations.The conda environment was re-pinned so it solves again (#802). After the PyPSA v1 migration bumped pandas to 3.0.5 and geopandas to 1.1.4,
workflow/envs/environment.yamlno longer solved on conda-forge and micromamba died at environment-creation time. pytables, lxml, python, rasterio, dask, tsam and others are re-pinned against pyproject;numpystays at 1.26.0. The uv/pyproject.tomlpath was never affected.
Documentation since 2026-08-31#
Every custom constraint in Custom Constraints was rewritten in a uniform let / s.t. form and corrected against the implementation; the Operational reserves section was removed with the constraint. The default technology-capacity targets and the REC trading zones are now mapped, and the
{simpl}/{clusters}figures were regenerated.
Earlier releases#
For changes prior to the v1 line, see the GitHub releases page.