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())

Chat — gridmcp is an MCP server that lets an LLM chat find, summarise and solve the networks in a directory. Install the VS Code extension, or register it with any other client:

claude mcp add gridoxide -- uvx --from gridoxide-mcp gridmcp

See Building and Running, Python Bindings and MCP Server.

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.
• Two linear power flows, both first-class modes rather than internal warm starts: DC (Bθ) — real, lossless, one factorization and no iterations, with phase shifters, both of powsybl's susceptance variants, and PTDF/LODF sensitivity factors for contingency screening — and the constant-admittance linearization, which keeps resistance and produces voltage magnitudes (power-grid-model's CalculationMethod.linear). Either can also warm-start Newton.
• 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.
• RMS (phasor-domain) dynamic simulation (--features dynamics) — what the network does over time after a fault, rather than at one instant. The differential-algebraic system is solved simultaneously, one Newton per step over machine states and network voltages together, with classical, transient and subtransient machines, exciters, governors and stabilizers, and scheduled faults, trips and load steps. Reads its own JSON, PSS/E .dyr and Dynawo .dyd/.par. Gated against the equal-area criterion's closed-form critical clearing time and against Dynawo's own published answer for Kundur's Example 13.2 — see The RMS Simulation Problem.
• Small-signal (modal) analysis on the same system — eigenvalues, damping ratios, participation factors naming the states each mode belongs to, and mode shapes saying how the rotors move, from the very Jacobian blocks the time-domain solve already assembles. Dense below a couple of thousand states; past that, sparse shift-invert Arnoldi takes over and returns the modes near a named frequency without ever forming the state matrix — 20 480 states in under 15 s, and cross-checked against ARPACK on the identical operator. With eigenvalue sensitivities: how far a mode moves, and how much damping it gains, per unit of a machine parameter. See Small-Signal Analysis.
• 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 and N-1/N-k contingency screening over one shared topology, parallel across cores via rayon. AC contingencies keep the symbolic factorization across a whole outage sweep (batch::BatchSolver::solve_contingencies, 2.0–2.7x single-threaded before parallelism); in DC a whole batch shares a single numeric factorization (linear::batch::DcBatchSolver, 9–55x per scenario), and outages need no re-solve at all — N-1 via DcSensitivity::outage_flows, N-k via the generalized multi_outage_flows.

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 crates/gridoxide-sparse/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 crates/gridoxide-sparse/src/klu_native/ and crates/gridoxide-sparse/vendor/suitesparse/ for per-file detail.