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.6.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.6.0
File Size Uploaded Provenance Actions
gridoxide-0.6.0.tar.gz 2.2 MB With provenance Details for gridoxide-0.6.0.tar.gz

Built distributions (wheels)

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

Total release size: 10.4 MB

Release files / gridoxide-0.6.0.tar.gz

Download URL gridoxide-0.6.0.tar.gz
Size 2.2 MB
Tags Source
SHA-256 checksum
How to use checksums
48d75aba3b9be319dd5032220637696a601808c19c168404ae723699d50b7b39
BLAKE2b-256 checksum
How to use checksums
c98337d6dea306dde91f01bf07110defaad60922d28fbe126a5fbd25c2acf29d
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 12, 2026.

Transparency log

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

Download URL gridoxide-0.6.0-cp314-cp314-macosx_11_0_arm64.whl
Size 2.4 MB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
4ddf18136947430d9a8a7432c965b9a5b6a4a245dd6e4482f6962a29b86b5919
BLAKE2b-256 checksum
How to use checksums
65f095c7263fb4e140d090e3852894438416378301393c03f6a3b51e4dfc9ca7
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 12, 2026.

Transparency log

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

Download URL gridoxide-0.6.0-cp312-cp312-win_amd64.whl
Size 2.6 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
329e9321ac08d9e8f4ff478309518b9cedc76526d25c6980d6dd0960b11b6a08
BLAKE2b-256 checksum
How to use checksums
bd20a1b599ca379eac047d8b92203e44a0b4d02252785b8a33bdb77f7cd94ded
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 12, 2026.

Transparency log

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

Download URL gridoxide-0.6.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 3.2 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
f73a905f11db36b494d18115e7fd14ba42f08365bb79893156d0d8ee06e51375
BLAKE2b-256 checksum
How to use checksums
07fad71aac18ff4245292a7fc3086d2f4c5db4f383e90996f201d4c4569b9979
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 12, 2026.

Transparency log

Security for gridoxide 0.6.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.6.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 12, 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