External-region representations: generator-based imports and boundary-metered CPUC contracted resources

[ktehranchi]

Stacked on #809 (targets its branch to avoid a duplicated diff; retarget to develop once #809 merges). Related: #807.

Motivation

Regionally scoped runs (California) had three overlapping representations of out-of-footprint supply:

1. trim_network — a priced import_{bus} generator at real boundary buses. Dead code: the schema types model_topology.trim as boolean while the code indexes trim_topology['zone'], so it cannot run.
2. add_elec_imports_exports — bottomless Store behind each external flowgate zone, with the import price on the interface links.
3. CPUC contracted out-of-state units (Palo Verde, Intermountain, Hoover, …) attached at California buses in add_electricity — invisible to the import volume cap and interface limits, and the cause of a consense crash in cluster_network (non-extendable remote units sharing (bus, carrier) groups with extendable in-state units, with p_nom_max=inf polluting land-cap sums).

What this does

New module workflow/scripts/external_regions.py — the single home for external-region construction, selected by a new config key electricity.imports.representation:

• store (default): today's behavior, pure code motion — byte-identical construction, protecting existing western/usa configs.
• generator: the external zone is modeled as a place with generation rather than an infinite energy tank. A generic import Generator (carrier unspecified_imports, carrying the import emission factor) sized at the zone's inbound interface capacity and priced with the same machinery; interface links become unpriced transfer capacity; and the CPUC contracted units are attached behind the boundary at the external bus of the flowgate zone they physically sit in (state-matched via membership.csv, largest-interface fallback with a warning). Their deliveries traverse carrier-imports links, so opts/interchange.py (untouched) automatically meters them against volume_limit, bounded by interface capacity.

Design notes (full reasoning in the module docstring):

• Separate {zone}_imports/{zone}_exports buses are load-bearing in generator mode: a shared bus would create a pure arbitrage loop (import generator selling into the export sink).
• Export construction identical in both modes; no double-charge exists on the export side.
• add_electricity now splits remote-contract handling into data derivation vs. network attachment; in generator mode it serializes the unit bundle (remote_units_s{simpl}.pkl) instead of attaching, which also fixes the cluster_network consense crash at the root — the p_nom_extendable: any workaround is removed from the CA config.
• trim_network and model_topology.trim are deleted.

Files

• workflow/scripts/external_regions.py (new): both representations, pricing machinery (moved), zone mapping, public add_external_regions() dispatcher.
• workflow/scripts/add_extra_components.py: −442 lines (moved/deleted), calls the module.
• workflow/scripts/add_electricity.py: remote-contract split + bundle output, gated on the new param.
• workflow/rules/build_electricity.smk, workflow/schemas/config.schema.yaml, config.default.yaml, config.california.yaml, docs/source/configtables/electricity.csv.
• workflow/scripts/test/test_interfaces.py: +12 tests covering both representations, pricing placement, and the zone-mapping rules.

Validation

• Full unit suite: 250 passed; 17 failures are pre-existing glpk not installed solver tests, none related.
• tests/static + tests/docs: 131 passed; DAG dry-run tests (including both California variants): 7 passed.
• CA zone mapping sanity: AZ contracts → p28, NV contracts (Hoover, Copper Mountain, Apex, …) → p13, UT (Intermountain/IPP) → p13 via the documented fallback (no CA-adjacent UT zone in NARIS).

Known behavioral change

With the CA config on generator, contracted out-of-state deliveries now consume the 25% import volume headroom and are bounded by interface capacity — the intent of the design, but a real tightening relative to previous CA runs.

🤖 Generated with Claude Code

[ktehranchi]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved by merging origin/develop into this branch and fixing all conflicts in merge commit d7f8fc9.

[trevorb1]

I haven't looked at the implementation, but I am assuming its good! My question is about supporting two different implementations for the same functionality (I believe its the same, but please correct me if it isn't!). Was there a reason the store/link combo didn't work well?

The reason I implemented it like that (store/link rather than generator) was for emission accounting purposes (ie. easier to track emissions from different sectors). Im not against switching to just generators, but do think it would be good to standardize across the code base!

[ktehranchi]

@trevorb1 So the behavior of the two implementations is actually a little different.

So for my model I needed to have a representation of external buses which have both generic imports generation AND have externally contracted resources (solar, wind, BESS). I also wanted to constrain the amount of total imports different out of state buses in-addition to the total imports from out of state buses.

We could unify the two different implementations by placing a generic link+store for unspecified imports behind other regional buses which also have the contracted resources.....