gridoxide

gridoxide is an AC power flow and state estimation tool written in Rust. It solves the power flow equations for an electrical grid with the Newton-Raphson method, using a sparse Jacobian throughout — assembly, factorization, and solve.

📖 Documentation — the full book covers the method, the solver backends, the CGMES importer, and the benchmark results. Its source lives in docs/.

Quick start

Rust — you need the Rust toolchain, nothing else for a default build:

cargo build --release
cargo test

Python:

pip install gridoxide

import gridoxide

model = gridoxide.PowerFlowModel.from_pgm_json("grid.json", backend="klu_native")
model.solve()
print(model.voltage_mag(), model.voltage_ang())

See Building and Running and Python Bindings.

What it does

• Newton-Raphson AC power flow, symmetric and asymmetric, with a sparse Jacobian and symbolic factorization reused across both NR iterations and repeated solves (solver::PersistentSolver) — see Backends and Factorization Reuse.
• Weighted-least-squares state estimation — recovers the most likely grid state from noisy, redundant, partial measurements, with observability analysis and bad-data detection and zero injections enforced as hard constraints rather than high-weight guesses. Validated against power-grid-model's own fixtures; see The State Estimation Problem.
• Five interchangeable linear-solver backends — faer (Scalar), a hand-written block LU (Block), vendored SuiteSparse KLU over FFI (Klu), a from-scratch Rust translation of KLU (KluNative, always built), and Intel oneMKL PARDISO (Pardiso). All five produce identical converged voltages; the choice is purely performance.
• Three input formats — its own JSON, power-grid-model JSON, and CGMES RDF/XML (--features cgmes) with node-breaker reduction, all four phase-tap-changer flavors, 3-winding star resolution, HVDC, and SVC.
• Modeling features beyond the plain formulation — reactive power limits (PV→PQ switching), zero-impedance branches, and multi-island solves with a per-island status report.
• Batched solving over one shared topology, parallel across cores via rayon (batch::BatchSolver).

Feature Comparison is a detailed survey against five other power flow tools, including the gaps gridoxide hasn't closed.

Benchmarks

scripts/bench/README.md is the single source of truth for every benchmark number in this project; Benchmarking and Profiling is a map into it. In short: gridoxide is one of two solvers out of six that converge on all 12 real IEEE/MATPOWER test cases, and its Klu backend is frequently faster than lightsim2grid's own KLU-backed C++ solver on real transmission topology — while power-grid-model remains clearly faster on synthetic radial distribution grids, a real standing gap.

On state estimation the same pattern holds in both directions: gridoxide's Newton-Raphson estimator is the only one of the two that answers at all above 300 buses, where power-grid-model's raises SparseMatrixError on documents its own iterative-linear method estimates from without complaint; on iterative-linear itself power-grid-model is 1.6-2.0x faster across an order of magnitude of problem size, the clearest standing gap on that side. That gap is a convergence-rate one, not a linear-algebra one — gridoxide's iterations are 30-40% cheaper and it takes three times as many of them.

License

gridoxide's own code is Apache-2.0 (LICENSE). A default build always includes src/klu_native/, a from-scratch Rust translation of vendored SuiteSparse AMD/BTF/KLU source, so Cargo.toml's license field is Apache-2.0 AND BSD-3-Clause AND LGPL-2.1-or-later — accurate for every default build, not just an opt-in one.

Building with --features klu compiles the vendored SuiteSparse C itself, adding LGPL relinking obligations for anyone distributing the resulting binary (a klu-dynamic sub-feature exists for that case). Building with --features pardiso dynamically links a locally-installed Intel oneMKL under Intel's own proprietary license; nothing MKL-derived is vendored or shipped by this repo.

See Provenance and Licensing for the full breakdown, and the PROVENANCE.md files under src/klu_native/ and vendor/suitesparse/ for per-file detail.