[tsybinae]

AgentiGrid: correct ExaGO -> GridKit conversion for ACTIVSg10k, keep full precision in GridKit checks

Follow-up to #147 (Initial implementation of transient analysis with AgentiGrid). Changes are in AgentiGrid only; ExaGO and GridKit code are untouched.

Why

A GridKit case built from an ExaGO solution (--from-exago, or the fault screen with "start_from": "latest_steady_state") did not start at ExaGO's operating point on ACTIVSg10k. ExaGO's -save_output (opflowout.m / pflowout.m) writes 3,562 of 12,706 branches with fbus and tbus swapped. It keeps the tap ratio and phase shift, which belong to the original from bus. 476 of these branches are off-nominal transformers. GridKit puts the tap on bus1, so the converted case had those taps on the wrong winding.

Changes

Converter (gridkit_engine/from_exago.py)

• exago_branch_directions() (new), called in build_from_exago() after exago_shifts_to_degrees(). For every in-service transformer with a tap or phase shift, it computes the from-end flow from ExaGO's solved voltages with the tap on either side, and keeps the direction that matches ExaGO's reported Pf/Qf. Lines (tap 1, no shift) are left as written. The fix is recorded in the conversion notes.
• Static generation (ACTIVSg10k). *_static_gen_* LoadZIP injections are kept unchanged, and ExaGO's load at those buses is rebuilt net of them (STATIC_GEN_CASES).
• Rounding of Pg. Pg within 0.01 MW of Pmin/Pmax is set to the limit (ExaGO writes Pg with 2 decimals). A unit at its Tgov1 valve limit is set just inside it.
• Machine ordering. Machines are paired with MATPOWER generator rows in file order, not by numeric unit id. A numeric sort broke at buses with 10 or more units.

Full precision in GridKit checks

• criteria.py.
  • New num() helper: a rounded value followed by its full value in brackets, e.g. highest 1.100 pu [1.1003587455398696 pu].
  • New CheckResult.data: every number of a check, unrounded.
  • Applied to angle stability, voltage recovery, the ComEd envelope, final voltage, damping and the steady-state check. The final-voltage check now also keeps the highest final Vm and its bus, which were previously only in rounded text.
• journal.py. Each check's data is written to the journal.
• agent_loop.py.
  • The base-case journal entry stores the steady-state numbers in rows.
  • The summary table the LLM sees shows full values in brackets, as does the fault duration in the verdict text.
• validation.py. Clearing-time messages show full values.

Other

• exago_parsers/matpower_parser.py. Reads .m files with errors="replace", so non-UTF-8 bytes in comments do not reject a case.
• tests/gridkit/test_from_exago.py. New tests for:
  • radian phase shifts;
  • static_gen handling for the 10k case and other cases;
  • machine pairing in file order;
  • Pmin/Pmax snapping;
  • valve-limit snapping.

Verification (ACTIVSg10k)

• Transformer directions. On an ExaGO OPFLOW solution, exago_branch_directions() flips exactly 476 transformers.
  • The chosen direction matches ExaGO's flow within 0.001 MVA; the rejected one is off by at least 1.74 MVA.
  • The 5 phase shifters are unaffected.
  • The converted case equals a hand-corrected reference case: same branches, buses and devices.
• No-fault GridKit run on the corrected case.
  • Vm at t = 0 within 0.00002 pu of ExaGO;
  • angles move at most 0.004 deg and voltages at most 0.00001 pu over 15 s;
  • 60.00 Hz throughout;
  • run time 13 - 18 s, against 126 s before.
  • The AgentiGrid base-case check passes.
• AgentiGrid fault screen (bus 70030, two ACOPF voltage bands). The GridKit outputs are byte-for-byte identical to hand-run GridKit on the same inputs, and the agent's verdicts match the hand analysis.
• Tests. tests/gridkit: 114 passed, 3 failed. The 3 failures are unrelated.

With help of Claude Code