Skip to main content

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 .m case directly, solving the problem MATPOWER's runpf solves; bus_numbers() names each bus. See Reading MATPOWER Input.

  • gridoxide.matpower (needs pip install gridoxide[matpower]) — converts a raw MATPOWER case (.m or .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 active source.
  • model.solve() — runs Newton-Raphson from a flat/linear-initial-guess start; raises RuntimeError if it doesn't converge within max_iter iterations.
  • model.reset() — discards the cached symbolic factorization; call before the next solve() 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, needs MKLROOT set).

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 (solve_sweep) 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_sweep(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=False drops 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=True makes each source'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.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gridoxide 0.4.0
File Size Uploaded Provenance Actions
gridoxide-0.4.0.tar.gz 2.2 MB With provenance Details for gridoxide-0.4.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for gridoxide 0.4.0
File Interpreter ABI Platform Actions
gridoxide-0.4.0-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for gridoxide-0.4.0-cp314-cp314-macosx_11_0_arm64.whl
gridoxide-0.4.0-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for gridoxide-0.4.0-cp312-cp312-win_amd64.whl
gridoxide-0.4.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.4.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Total release size: 7.2 MB

Release files / gridoxide-0.4.0.tar.gz

Download URL gridoxide-0.4.0.tar.gz
Size 2.2 MB
Tags Source
SHA-256 checksum
How to use checksums
7755e12dc027dd27b29141475d62579a3a73f12cc2236d532ecbfd52d7257142
BLAKE2b-256 checksum
How to use checksums
6de5444141ce992139fd9d32e99bea5b90e2802ba829eb4c68d5be7cba4b7c13
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 Nov 7, 2026.

Transparency log

Release files / gridoxide-0.4.0-cp314-cp314-macosx_11_0_arm64.whl

Download URL gridoxide-0.4.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
88ee37f83c4aaef67a6ba15a75e5637efaf2621b6207de3aec447adbb06c8a38
BLAKE2b-256 checksum
How to use checksums
ba046b5b62f58f988394f11be82866ee88493b3af1725a90832dd9dd1990d9e2
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 Nov 7, 2026.

Transparency log

Release files / gridoxide-0.4.0-cp312-cp312-win_amd64.whl

Download URL gridoxide-0.4.0-cp312-cp312-win_amd64.whl
Size 1.7 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
2c19530211c6d563e47aced6affc46dbd5f67014532e482302879f25ea8349ec
BLAKE2b-256 checksum
How to use checksums
f61fdcf54a7c556e31b329a26645285c727bf3d1981984764ccc1440602cb023
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 Nov 7, 2026.

Transparency log

Release files / gridoxide-0.4.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL gridoxide-0.4.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
bc93e494671beb09e6cd142487361da25228f4ac2e13d2268f4a0e7965f84fb5
BLAKE2b-256 checksum
How to use checksums
83de2a2ecc3bd78a49cab1c3fa08437a5fb0abac8014953e1e2900a6ad896974
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 Nov 7, 2026.

Transparency log

Security for gridoxide 0.4.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.

Select from 4 files

Attestation for gridoxide-0.4.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 Nov 7, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page