Methodology

The benchmarks crate is a private 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), the harness parses a PowerIO module and declares the calculation as DcOpfInstance, AcOpfInstance, or AcPfInstance. It then drives the same typed facade available to downstream consumers:

• DC OPF: solve_instance (objective, dispatch, LMPs);
• conic SOCWR: solve_ac_instance (objective, gap, W-space primals);
• AC power flow: solve_ac_pf_instance (convergence, residual);
• sensitivities: the same typed solve entries in forward and adjoint modes.

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 on one thread 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 harness records the source revision, toolchain, dependency versions, host, and invocation used for each run. It 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. The repository keeps that generated snapshot, and a rerun can be compared with its recorded provenance:

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