Translate the new-format network tables to buses and links

[nick-gorman]

This PR does two things: it adds the translator that turns the new-format network tables into PyPSA buses and links, and it uses those tables to pilot a "wildcard" convention for sparse inputs — implemented end-to-end so there is a concrete example to react to before deciding whether to adopt it more broadly.

src/ispypsa/
├── translator/
│   ├── network.py            → network tables → buses + links (+ link_timeslice_limits)
│   └── helpers.py            → _resolve_wildcards, the generic wildcard resolver
└── validation/schemas/
    ├── network_transmission_path_limits.yaml           → wildcard keys, nan_fill, coverage rules
    ├── network_expansion_options.yaml                  → wildcard keys, pairing rule
    └── network_transmission_path_expansion_costs.yaml  → wildcard keys, nan_fill, coverage rules
tests/test_translator/
├── test_network.py            → buses/links coverage incl. wildcard and guard cases
└── test_translator_helpers.py → _resolve_wildcards unit coverage

The translation

network.py consumes network_geography, network_transmission_paths, network_transmission_path_limits, network_expansion_options and network_transmission_path_expansion_costs, and produces:

• one bus per modelled geography (REZ buses only when REZs are modelled as discrete nodes),
• one existing link per transmission path,
• expansion links per investment period, from the unified options/costs tables.

Flow paths and REZ connections run through one pipeline — both are just paths.

A link's p_nom is the larger of its forward and reverse capacities; every directional, per-demand-condition limit is expressed per unit of that in a link_timeslice_limits table (forward limits as p_max_pu, reverse as p_min_pu), which pypsa_build later expands into per-snapshot series:

network_transmission_path_limits:
    path_id  direction  timeslice             capacity
    CQ-NQ    forward    qld_peak_demand       1200
    CQ-NQ    forward    qld_winter_reference  1400
    CQ-NQ    reverse    qld_peak_demand       1440
    CQ-NQ    reverse    qld_winter_reference  1910

links (abridged):
    name            p_nom  p_min_pu  p_max_pu
    CQ-NQ_existing  1910   0.0       1.0       # p_nom = max over both directions

link_timeslice_limits:
    name            attribute  timeslice             value
    CQ-NQ_existing  p_max_pu   qld_peak_demand        0.628   # 1200/1910
    CQ-NQ_existing  p_max_pu   qld_winter_reference   0.733
    CQ-NQ_existing  p_min_pu   qld_peak_demand       -0.754   # -1440/1910
    CQ-NQ_existing  p_min_pu   qld_winter_reference  -1.0

Design choices worth knowing before reading the diff:

• p_nom as the max of both directions keeps every per-unit limit in [-1, 1], so no timeslice can credit a link above its physical rating.
• The static p_min_pu/p_max_pu on each link are inert defaults (0.0/1.0); the real limits live entirely in link_timeslice_limits under a coverage contract (Translator timeslice implementation notes (decisions from staging PR #121) #123) — every snapshot is covered by a named-timeslice row or a blank-timeslice fallback.
• Expansion links start at p_nom 0 and are individually unbounded; the expansion-limit custom constraints (ispypsa.translator.constraints) cap the total built across a path's links. Asymmetric options set p_max_pu/p_min_pu in the option's forward/reverse proportion.

The wildcard proposal (feedback wanted)

The three sparse tables (limits, expansion options, expansion costs) accept blank key cells as wildcards, resolved most-specific-wins, with blank value cells taking a schema-declared nan_fill:

network_transmission_path_limits (blank cells are wildcards):
    path_id  direction  timeslice  capacity
    CQ-NQ    forward               1500
    CQ-NQ    reverse               1000
                                   800       # table-wide default

resolved against modelled paths {CQ-NQ, Q1-NQ}:
    path_id  direction  timeslice  capacity
    CQ-NQ    forward               1500      # its own rows win (fewest wildcards)
    CQ-NQ    reverse               1000
    Q1-NQ    forward               800       # inherits the table-wide default
    Q1-NQ    reverse               800

_resolve_wildcards in translator/helpers.py is the generic resolver; the three schema files document the convention (wildcard keys, *_resolve_unambiguously and coverage rules, nan_fill). The validation rules are declarative-only for now — two runtime guards in network.py stand in for the option-pairing rule until schema validation lands.

This is deliberately a reference implementation. The same convention could apply to most sparse ISPyPSA tables (build costs, fuel prices, generator properties); the question for review is whether it earns its keep as a uniform way to express defaults and sparse overrides, or whether it's over-engineering that will be hard to apply consistently. Either way, concrete code seemed a better basis for that call than an abstract proposal.

Scope note

The translation code is dark — nothing calls it until the orchestrator PR, so there's no change to production behaviour. This PR is stacked on #129 (the transmission_default_limit rename) and targets that branch as its base; once #129 merges it retargets to main.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
src/ispypsa/translator/helpers.py	100.00% <100.00%> (ø)
src/ispypsa/translator/network.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.