gridoxide
Python bindings for gridoxide, a Rust AC power flow and
state estimation solver, both Newton-based with a sparse Jacobian (via
faer).
Grids are loaded from power-grid-model (PGM) JSON input files. Repeated solves against the same topology reuse a cached symbolic factorization, so scenario sweeps and time-series runs only pay the fill-reducing-ordering cost once.
Install
pip install gridoxide
Prebuilt wheels are published for Linux (x86_64), Windows, and macOS (arm64).
Quickstart
import gridoxide
model = gridoxide.PowerFlowModel.from_pgm_json("grid.json", backend="scalar")
model.solve()
print(model.voltage_mag()) # per-unit voltage magnitude, one entry per node
print(model.voltage_ang()) # voltage angle in radians, one entry per node
grid.json is a PGM-format input file, e.g.:
{
"version": "1.0",
"type": "input",
"is_batch": false,
"attributes": {},
"data": {
"node": [
{"id": 1, "u_rated": 10500.0},
{"id": 2, "u_rated": 10500.0}
],
"line": [
{"id": 3, "from_node": 1, "to_node": 2, "from_status": 1, "to_status": 1,
"r1": 0.25, "x1": 0.2, "c1": 1e-06, "tan1": 0.0,
"r0": 0.25, "x0": 0.2, "c0": 1e-06, "tan0": 0.0, "i_n": 1000.0}
],
"sym_load": [
{"id": 9, "node": 2, "status": 1, "type": 0, "p_specified": 10000.0, "q_specified": 2000.0}
],
"source": [
{"id": 4, "node": 1, "status": 1, "u_ref": 1.0, "sk": 1e10, "rx_ratio": 0.1, "z01_ratio": 1.0}
]
}
}
Reusing factorization across repeated solves
PowerFlowModel wraps gridoxide's PersistentSolver: construct one per topology, then call .solve()
as many times as needed. Only the first call pays for symbolic factorization; later calls only need
values (p_specified/q_specified) to change, not the topology.
model = gridoxide.PowerFlowModel.from_pgm_json("grid.json", backend="scalar")
for scenario in scenarios:
apply_scenario(model, scenario) # e.g. edit and re-load p/q values
model.solve()
results.append(model.voltage_mag())
Call model.reset() if the topology itself changes between solves (not just bus values).
Building input grids
Two helpers produce or convert PGM JSON, so a working grid doesn't require hand-writing one:
-
gridoxide.generate_grid— generates a synthetic radial MV/LV distribution grid at any scale, no extra dependencies needed:from gridoxide.generate_grid import generate generate(target_nodes=2200, seed=42, out_path="grid.json") # ~2,600 nodes
or from the shell:
gridoxide-generate-grid grid.json --target-nodes 2200 --seed 42. -
PowerFlowModel.from_matpower("case14.m")reads a MATPOWER.mcase directly, solving the problem MATPOWER'srunpfsolves;bus_numbers()names each bus. See Reading MATPOWER Input. -
gridoxide.matpower(needspip install gridoxide[matpower]) — converts a raw MATPOWER case (.mor.mat) into PGM JSON, for tools that read PGM. It cannot carry a case exactly: PGM's slack is a source behind an impedance, and its transformers hold phase shifts in 30° steps only:from gridoxide.matpower import convert convert("case14.m", "case14.json")
or
gridoxide-matpower case14.m case14.json.
gridoxide deliberately has no pandapower-based converter: it would need the full pandapower +
power-grid-model-io dependency chain, and gridoxide.matpower already covers the same real-world
test-case grids straight from their original MATPOWER source files without it. If you already have a
pandapower.pandapowerNet object and pandapower installed, see
scripts/bench/convert_pandapower_case.py
in the main repo for a standalone (not part of this package) converter.
API
PowerFlowModel.from_pgm_json(path, backend="scalar", tol=1e-6, max_iter=20, s_base_va=1e6, freq_hz=50.0)— loads a PGM JSON file and builds the Y-bus admittance matrix.model.n_nodes— number of buses, including one virtual slack bus per activesource.model.solve()— runs Newton-Raphson from a flat/linear-initial-guess start; raisesRuntimeErrorif it doesn't converge withinmax_iteriterations.model.reset()— discards the cached symbolic factorization; call before the nextsolve()if the topology has changed.model.voltage_mag()/model.voltage_ang()— per-bus results in node order (per-unit magnitude, radians).
Backends
backend selects the linear solver used inside the Newton-Raphson Jacobian:
| Backend | Notes |
|---|---|
"klu_native" (default) |
From-scratch Rust translation of SuiteSparse KLU, always available in this wheel; about six times faster than "scalar" on large networks. |
"scalar" |
Sparse LU via faer, no special build requirements. |
"block" |
Block-structured variant of the same solver (one 2×2 block per bus); faster on some topologies. |
Two additional backends exist in the source tree but are not included in the published wheel, since they need extra system dependencies at build time — build gridoxide from source with the matching Cargo feature to use them:
"klu"— links vendored SuiteSparse C directly (--features python,klu)."pardiso"— Intel oneMKL's PARDISO solver (--features python,pardiso, needsMKLROOTset).
Batched power flow on an NVIDIA GPU
Not in the published wheel either: GpuBatchSolver needs a build with --features python,gpu, with
cuDSS 1.0 or later (CUDSS_DIR) and the CUDA 12 toolkit, or the image docker/gpu/Dockerfile builds. It
solves solve_batch's scenarios and solve_contingencies' outage lists on the GPU, every scenario to
its own convergence, from the model's last solve():
model = gridoxide.PowerFlowModel.from_matpower("case9241pegase.m")
model.solve()
gpu = gridoxide.GpuBatchSolver(model, capacity=1024) # keeps its analysis for every later call
results = gpu.solve_batch(scenarios) # one BatchResult per scenario, as on the CPU
outages = gpu.solve_contingencies([[b] for b in range(model.n_branches)])
Outages that split the network are solved on the CPU. On an A100 the GPU pays only on large networks and
large batches; the CPU's solve_batch on all cores is faster on most cases.
State estimation
StateEstimationModel recovers the most likely grid state from measurements, rather than computing
voltages from known injections. Its input is a PGM document carrying sym_voltage_sensor and/or
sym_power_sensor entries — and notably it does not need p_specified on its loads or u_ref on
its sources, since those are quantities the estimator solves for rather than inputs it consumes.
import gridoxide
model = gridoxide.StateEstimationModel.from_pgm_json("grid_with_sensors.json")
model.solve()
print(model.voltage_mag()) # per-unit magnitude, one entry per bus
print(model.voltage_ang()) # radians
print(model.residuals()) # z - h(x), one per measurement
print(model.objective) # J(x) = 1/2 r^T W r
A converged estimate is not automatically a trustworthy one, so two analyses come with it:
# What the measurements fail to determine, as (bus, "angle" | "magnitude").
# Empty means fully observable. Entries beyond the physical node count are
# gridoxide's own synthesized buses (one virtual slack bus per source), which
# are expected whenever a source's own power is unmeasured.
print(model.observability())
# (chi_squared, degrees_of_freedom, p_value, [(measurement_index, normalized_residual), ...])
# p below 0.05 conventionally means the measurements are not merely noisy;
# a normalized residual above 3 conventionally identifies the culprit.
print(model.bad_data())
from_pgm_json takes the same backend, tol, max_iter, s_base_va and freq_hz arguments as
PowerFlowModel. Every backend produces the same estimate — the gain matrix is an ordinary square
sparse system — so the choice is performance only.
From a MATPOWER case
A .m case is read by the same reader PowerFlowModel.from_matpower uses, with no conversion to PGM
in between, so phase shifts and transformer line charging are exactly the case's. Measurements are
given in MATPOWER's own terms: buses by number, branches by their 0-based row in mpc.branch, values
and sigmas in per unit (|V|) or MW and MVAr.
measurements = [
("vm", 1, 1.06, 0.004), # |V| at bus 1, p.u.
("p_inj", 2, 18.3, 0.5), # injection at bus 2, MW, generation less load
("q_inj", 2, 30.9, 0.5), # MVAr
("p_from", 0, 156.9, 3.2), # flow at the from end of branch row 0, MW
("q_to", 0, 27.6, 0.7), # at its to end, MVAr ("p_to" likewise)
# ...
]
model = gridoxide.StateEstimationModel.from_matpower("case14.m", measurements)
model.solve()
The case's reference bus is the angle reference; its magnitude is estimated like any other bus's. No bus is held at zero injection: a bus without load or generator injects what its measurements say.
Options on a PGM document
zero_injection=Falsedrops the constraint that holds every node without a load or generator at exactly zero injection, as power-grid-model does. What remains is plain weighted least squares, which is what most textbook estimators solve. A node without sensors is then unobservable.ideal_sources=Truemakes eachsource's node the slack, with no impedance behind it, instead of power-grid-model's virtual bus behind the source impedance. A sensor on the source then reads part of its node's injection. Symmetric only.
License
gridoxide's own code is Apache-2.0. A default build (and this published wheel) also always bundles
crates/gridoxide-sparse/src/klu_native/, a from-scratch Rust translation of vendored SuiteSparse AMD/BTF/KLU source
(BSD-3-Clause for the AMD-derived pieces, LGPL-2.1-or-later for the BTF/KLU-derived pieces) — see the
main README's License section for the full breakdown.
Metadata
Release files for gridoxide 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gridoxide-0.3.0.tar.gz | 2.1 MB | With provenance | Details for gridoxide-0.3.0.tar.gz |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gridoxide-0.3.0-cp314-cp314-macosx_11_0_arm64.whl | CPython 3.14 | CPython 3.14 | macOS 11.0+ ARM64 | Details for gridoxide-0.3.0-cp314-cp314-macosx_11_0_arm64.whl |
| gridoxide-0.3.0-cp312-cp312-win_amd64.whl | CPython 3.12 | CPython 3.12 | Windows x86-64 | Details for gridoxide-0.3.0-cp312-cp312-win_amd64.whl |
| gridoxide-0.3.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | CPython 3.9 | CPython 3.9 | Linux glibc 2.17+ x86-64 | Details for gridoxide-0.3.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
Total release size: 7.1 MB
Release files / gridoxide-0.3.0.tar.gz
| Download URL | gridoxide-0.3.0.tar.gz |
|---|---|
| Size | 2.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b18fb9acd04380660ce711d30a48f3df593b7c1cdab64ce3abe72de3539f6a92
|
|
BLAKE2b-256 checksum How to use checksums |
27f5b4e559fe9476ba97bc5acadb89aa8c09dd1c9e34afa6f7b1d5ded68d55f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / gridoxide-0.3.0-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | gridoxide-0.3.0-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4a405972b6174c8c88286b9734652f77e58becefe0660ca2b4808009eb2165fb
|
|
BLAKE2b-256 checksum How to use checksums |
7bd51ec07ad22f25758f8387eae6d3b4b44d4453b41a6e728016c91210028add
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / gridoxide-0.3.0-cp312-cp312-win_amd64.whl
| Download URL | gridoxide-0.3.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d24b21ca659a22e96d2378676c28869c9a54bb8c0311db6728dc34d33422d495
|
|
BLAKE2b-256 checksum How to use checksums |
52256bd367bd536d9cd42593d493cc2c7e59d64968abbf5774654e19b0e4e457
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / gridoxide-0.3.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | gridoxide-0.3.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
6ecfb8e79685acf598de33d1781c803804ced1ac103a1e3b1e3162812b8972b3
|
|
BLAKE2b-256 checksum How to use checksums |
7eeb5a6efb96919c7ccc0b77e992caf061374bb646dbaf6de4047cc4aefac93f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logSecurity for gridoxide 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 4 files in this release have been uploaded with provenance metadata.
Attestation for gridoxide-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.