Methodology

The benchmarks crate is a non-shipping workspace member that drives tellegen’s public API over the PGLib-OPF corpus for validation and timing. It never vendors the corpus and reads it from $PGLIB_OPF_PATH, skipping when the path is absent.

Corpus

PGLib-OPF v23.07 at $PGLIB_OPF_PATH: 66 base, 66 congested (api/), and 66 small-angle (sad/) MATPOWER files, spanning a range of bus counts at baseMVA 100. PGLib data is CC BY 4.0 (see References).

What is driven

Per (case, variant): parse (through powerio), build DcNetwork / AcNetwork, then

• DC OPF: solve_prebuilt (objective, dispatch, LMPs);
• conic SOCWR: socwr_opf (objective, gap, W-space primals);
• AC power flow: ac_pf (convergence, residual);
• sensitivities: the typed engines (AcNewton / ConicKkt with sensitivity) and the solve_json front door, which carries the DC sensitivities.

Timing

The engine exposes iteration traces and residuals rather than wall time, so the harness times the public calls itself, per stage (parse / build / solve / sensitivity). Solves run single-threaded for clean timing.

Metrics

1. OPF correctness vs the published reference: the DC objective, the SOCWR relaxation lower bound, and the SOC gap, rolled up into a per-case reproduction verdict (see Validation).
2. Sensitivity parity: adjoint equals forward, and central finite differences against the analytic columns, classified per parity class (see the sensitivity contract).
3. Feasibility / convergence: per-case status, interior-point iterations, residuals.
4. Performance: wall time per stage, and a scaling curve against bus count.
5. Coverage: a per-case status table, including the size caps applied by the harness flags.

Baselines

Correctness is checked against two independent baselines:

• the published PGLib reference solves (PowerModels.jl with IPOPT), tabulated per case and variant in $PGLIB_OPF_PATH/BASELINE.md; and
• finite differences, which validate the analytic sensitivity columns by perturbing the public network fields.

Reproducibility

The solves are deterministic, so the figures reproduce on a fixed toolchain. The harness writes results.json (one record per (case, variant)) and results.csv. With its book flag it also writes the markdown snapshot to docs/src/benchmark-results.md. That file is generated by running the harness; it is not checked in, and the published figures are whatever the current run produces. To regenerate it:

cargo run -p benchmarks --release -- [flags]