feat: pandapower interop — IEC 60909 short-circuit + AC validation of the optimiser

[harrysalmon]

Summary

Adds an opt-in pandapower interop layer (src/nopywer/pp_interop/) that:

1. Converts a PowerGrid to a pandapowerNet via to_pandapower(grid) — the conversion runs once and produces a PandapowerGrid handle that subsequent calc functions reuse.
2. Computes IEC 60909 prospective short-circuit current at every bus (compute_short_circuit) — useful for sizing breaker breaking capacity and verifying RCD/breaker trip conditions.
3. Runs balanced AC power flow (compute_power_flow) and a side-by-side compare_with_tree_walk helper that diffs the existing analyze.py tree walk against pandapower's Newton-Raphson AC truth.

Pandapower is an optional dependency (pip install nopywer[pandapower]); import nopywer works without it. A modern extra is added for users who want pandas≥3.0 / numpy≥2.4 without pandapower (the two extras are declared as conflicting in [tool.uv] because pandapower 3.4 caps both).

Reading order for reviewers

research/pandapower/REVIEWING.md is a 25-min reader's guide with reading order, run-it-yourself recipe, and a "decisions worth pushing back on" section that pre-empts the eight design choices most likely to provoke a comment (git pin, dep floors, module name, GeoJSON schema, etc.).

The 7 numbered docs in research/pandapower/ cover background, intersection between the two domain models, porting tradeoffs, the wider opportunity menu, and the findings from running the validator on the 2025 fixture.

Headline finding

Running the validator on tests/fixtures/input_nodes.geojson (the 2025 event, 51 nodes / 50 cables) shows the tree-walk under-reports voltage drop by up to 12 percentage points at high-stress nodes:

Node	Tree-walk vdrop	AC vdrop	Δ
glitch	26.91 %	39.09 %	+12.18 pp
oasis_playground	26.52 %	38.53 %	+12.01 pp
belly_town	26.17 %	37.91 %	+11.74 pp

Mean voltage Δ across all 51 buses: 7.8 V; max 28 V at glitch.

The gap is one-sided (tree walk always under-reports) and grows with drop magnitude. Cause: constant-power loads at low voltage draw more current → bigger drop → more current → … The tree walk computes I at nominal V₀ and never sees the feedback. AC iterates to the equilibrium.

This is exactly the validator that PR #5's MILP optimiser docstring asks for: "validate critical layouts with a detailed power-flow check". Full write-up in research/pandapower/07_optimiser_validation_findings.md.

Commits

1. docs(research) — 9 research docs (~1100 lines), no code.
2. feat(pp_interop) — conversion layer + IEC 60909 short-circuit. Adds i_sc_ka field to PowerNode. SC tests.
3. feat(pp_interop) — AC power flow + tree-walk validator. Loads in to_pandapower. End-to-end script under scripts/. PF tests.
4. chore(deps) — pins pandapower to the merge commit of e2nIEE/pandapower#2860 which fixes a CoW/read-only bug breaking runpp under pandas≥2.3. Released 3.4.0 is one day too old; no 3.4.1 yet.

Each commit leaves the tree in a working state.

Test plan

• uv sync --extra pandapower && uv run pytest — 44/44 pass (33 existing untouched + 11 new)
• uv run python scripts/validate_optimiser_with_runpp.py — converges, reports the divergence above
• uv sync --extra modern — installs cleanly without pandapower, gives pandas 3.x / numpy 2.4+
• import nopywer works without the pandapower extra installed (lazy import inside pp_interop)
• Existing tests unchanged — only added

What this PR does NOT do

• No CLI flag — validation runs through the script. Folding into nopywer-analyze is a thin wrapper, deliberately deferred.
• No frontend changes — GeoJSON gains an i_sc_ka field (default 0.0) that app.js ignores.
• No optimiser changes — validation runs after the optimiser, doesn't feed back into it. Closing that loop is in research/pandapower/06_extended_opportunities.md.
• No runpp_3ph (per-phase asymmetric flow). Balanced runpp is enough to demonstrate the linearisation gap. Asymmetric is opportunity §3 in the same doc.

🤖 Generated with Claude Code