{"data":{"kind":"file","path":"README.md","version_id":"k0heirvvmgabagumanlfgunk","entry":{"name":"README.md","path":"README.md","is_directory":false,"size":8178,"modified_at":"2026-07-07T04:50:51.923000","content_hash":"9f0210a744b2408f6f2ae1a6336b036da44669308f51e6750dd07863378210da"},"entries":[],"content":"# dcopf-grid-verifiers\n\nDC Optimal Power Flow (DC-OPF) RL environment with transmission line limits. Successor to a merit-order economic dispatch environment: this version adds network physics (bus angles, line reactances, MW flow limits), so pure merit-order reasoning fails on a measured **46% of instances** — the network-unconstrained least-cost dispatch actually violates a line limit, and congestion forces out-of-merit dispatch. That is exactly what naive LLM reasoning gets wrong.\n\n## Why this environment is hard to reward-hack\n\nThe dominant hack in dispatch tasks is quoting an impossibly cheap dispatch that violates physics. Here, the optimality reward is **hard-gated on a physics feasibility check**: given a proposed dispatch, bus angles are uniquely determined (slack-referenced B-theta solve), so power balance, generator bounds, and every line flow are verified before any optimality credit is granted. An infeasible answer scores 0 on optimality no matter how cheap it claims to be.\n\nThe gate is red-teamed in `tests/test_validation.py` (6 attack tests): the infeasible-cheap dispatch, garbage output, the subtler `NaN`/`Infinity` JSON attack (`json.loads` accepts these literals, and NaN defeats any comparison-based check because every comparison against NaN is `False`), and the tolerance-rent attack (under-serving load inside the ±0.5 MW feasibility tolerance to come in *below* the LP optimum — residual violations are settled at a 2× penalty price, real imbalance-market style, and below-optimum cost is penalized symmetrically). Non-finite values are rejected at parse *and* inside the physics check itself.\n\n## Ground truth validation\n\nTwo independent implementations of the same DC-OPF formulation must agree (cross-implementation validation — both share DC power-flow physics; this catches modeling and coding errors, not model-form error):\n\n- **Primary:** B-theta LP formulation solved with `scipy.optimize.linprog` (HiGHS)\n- **Cross-check:** `pandapower.rundcopp` on the same networks (separately implemented modeling path: ohmic line parameters, current-based ratings)\n\nValidation run (300 randomly generated instances, seeds 0–299 — the full default dataset):\n\n| Metric | Result |\n|---|---|\n| Objective mismatches (>0.1% rel and >$1/h abs) | **0 / 300** |\n| Worst relative objective gap | 6.9e-10 |\n| pandapower non-convergence | 1 / 300 (test fails if >2%) |\n| Merit-order dispatch infeasible (violates a line limit) | **137 / 300 (46%)** |\n| Instances with a binding line at optimum | 142 / 300 (47%) |\n| Median congestion cost premium (congested subset) | 9.2% |\n\nThe distribution behind these numbers is measured and tuned, not inherited — see [CALIBRATION.md](CALIBRATION.md) for the metric definitions, the parameter sweep, and the rationale for the chosen configuration.\n\n## Baseline results\n\n50 instances (seeds 0–49), 1 rollout each, default sampling, July 2026:\n\n| Model | total | format | feasibility | optimality | congestion |\n|---|---|---|---|---|---|\n| claude-haiku-4-5 (6k tokens) | **0.520** | 1.000 | 0.520 | 0.432 | 0.480 |\n| claude-opus-4-8 (16k tokens) | **0.901** | 0.920 | 0.900 | 0.898 | 0.900 |\n\n> **Reproducing this: pass `--max-tokens`.** Anthropic endpoints default to 4096 output tokens, at which frontier rollouts truncate mid-derivation and the score collapses to ~0.5 (measured). Use `--max-tokens 16000` for Opus-class, `6000` for Haiku-class, with `-r 1`.\n\nReading: the weak model formats perfectly but only 52% of its dispatches survive\nthe physics check — it loses on feasibility, not parsing. The frontier model\nreaches 90% feasibility and, *when feasible, averages 0.998 optimality* — its\nremaining gap is reasoning budget (4/50 rollouts truncated at 16k tokens) and\noccasional congestion misreads. Frontier reasoning-token demand is itself part\nof the task's difficulty: at 6k tokens, half of the frontier model's rollouts\ntruncate before emitting an answer.\n\nReproduce:\n\n```bash\nvf-eval dcopf-grid-verifiers -p anthropic -m claude-haiku-4-5-20251001 -n 50 -r 1 --max-tokens 6000 --save-results\nvf-eval dcopf-grid-verifiers -p anthropic -m claude-opus-4-8 -n 50 -r 1 --max-tokens 16000 --save-results\n```\n\n## Example failure (claude-haiku-4-5, from the baseline run)\n\n> *\"...I need to solve the AC power flow equations. After careful analysis of the feasible region, the optimal dispatch appears to be: P0 = 15.2 MW, P1 = 90.3 MW, P2 = 86.7 MW. This satisfies: Total: 192.2 OK, Bounds: All within limits OK\"*\n\nThe model verifies generation balance and generator bounds, then declares victory — but never solves the network. Its dispatch drives **Line 0 to -44.4 MW against a 39.6 MW limit** (and it mistakes this DC problem for AC power flow). Feasibility reward: **0**. Confident, well-formatted, and physically impossible — exactly the failure mode the environment exists to catch.\n\n## Rewards (weighted rubric)\n\n| Reward | Weight | Description |\n|---|---|---|\n| `format_reward` | 0.10 | Parseable `{\"dispatch_mw\": [...]}` with correct arity, finite values only |\n| `feasibility_reward` | 0.30 | Passes physics check: balance, gen bounds, all line limits |\n| `optimality_reward` | 0.50 | Gated on feasibility; `exp(-5 × relative cost gap)` vs LP optimum |\n| `congestion_reward` | 0.10 | Gated on feasibility; credits correctly loading binding lines to 90–100% of limit |\n\n## Usage\n\n```bash\n# local install\npip install -e \".[crosscheck]\"\n\n# run validation harness (solver cross-check + reward gate tests)\nN_INSTANCES=200 python tests/test_validation.py\n\n# measure the instance-difficulty distribution / re-run the calibration sweep\npython calibration/measure.py --n 300\n\n# evaluate a model via verifiers CLI (give frontier models room to reason —\n# see the warning under the Baseline table; -r 1 to match the published numbers)\nvf-eval dcopf-grid-verifiers -p anthropic -m <model> -n 50 -r 1 --max-tokens 16000\n```\n\n```python\nimport verifiers as vf\nenv = vf.load_environment(\"dcopf-grid-verifiers\", num_examples=300)\n```\n\n## Instance generation\n\nRandom connected networks (spanning tree + loop edges, 4–8 buses), 2–4 generators, loads on ~2/3 of buses. Generator costs are drawn from a **tiered merit stack** (baseload / mid-merit / peaker) rather than a flat distribution, so congestion is economically sharp: when a constrained corridor blocks a cheap remote unit, an expensive *local* unit must run — the mechanism behind real-world locational price separation. Units are modeled as fully flexible committed capacity (low Pmin — a deliberate no-unit-commitment stylization, documented with its measured difficulty trade-off in CALIBRATION.md). Line limits are drawn from a bimodal (tight/loose) distribution bounded to physically possible values (no rating above total system load, 15 MW floor) and calibrated so ~46% of instances defeat network-unconstrained merit-order dispatch (measured, see [CALIBRATION.md](CALIBRATION.md)). Every generated instance is solved at generation time; infeasible draws are rejected. Fully deterministic per seed.\n\nThe congestion rate is deliberately oversampled relative to a real N-1-planned grid, where binding congestion is far rarer: a realistic sample would be ~90% trivial merit-order instances and would not exercise the skill being tested.\n\n## The vertical\n\n- [economic-dispatch](https://github.com/JWilksBooth/economic-dispatch) — merit-order control rung (frontier-saturated by design).\n- **dcopf-grid-verifiers** (this) — congestion / space.\n- [multiperiod-dispatch](https://github.com/JWilksBooth/multiperiod-dispatch) — ramp coupling / time; shipped, 74% defeat per-period merit order.\n- [n1-contingency-dispatch](https://github.com/JWilksBooth/n1-contingency-dispatch) — N-1 security / uncertainty; shipped, 68% defeat the plain OPF optimum.\n- [nodal-pricing-lmp](https://github.com/JWilksBooth/nodal-pricing-lmp) — LMP price-formation / dual space; shipped, 44% out-of-band.\n\nRobotics vertical (same validation discipline): [robot-cycle-time](https://github.com/JWilksBooth/robot-cycle-time) (motion), [bimanual-chore-scheduling](https://github.com/JWilksBooth/bimanual-chore-scheduling) (orchestration).\n","encoding":"utf-8","truncated":false,"total_bytes":8178},"status":null}