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

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.

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.1.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.1.0
File Size Uploaded Provenance Actions
gridoxide-0.1.0.tar.gz 2.0 MB With provenance Details for gridoxide-0.1.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for gridoxide 0.1.0
File Interpreter ABI Platform Actions
gridoxide-0.1.0-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for gridoxide-0.1.0-cp314-cp314-macosx_11_0_arm64.whl
gridoxide-0.1.0-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for gridoxide-0.1.0-cp312-cp312-win_amd64.whl
gridoxide-0.1.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 CPython 3.9 Linux glibc 2.17+ x86-64 Details for gridoxide-0.1.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Total release size: 6.8 MB

Release files / gridoxide-0.1.0.tar.gz

Download URL gridoxide-0.1.0.tar.gz
Size 2.0 MB
Tags Source
SHA-256 checksum
How to use checksums
5331dbc09425c4c4ba94fb1e36d5ea6292e63fa24874e8dd0c494c89acac1a49
BLAKE2b-256 checksum
How to use checksums
e8768fedfe92a0e1489d6af999b53be47773c9efb1341bd5a883f7afa8841456
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 24, 2026.

Transparency log

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

Download URL gridoxide-0.1.0-cp314-cp314-macosx_11_0_arm64.whl
Size 1.3 MB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
ef5ac6a4130985b28444e290081134903a37d06b12ab169b438a627eb99e4c7d
BLAKE2b-256 checksum
How to use checksums
1cb5a6e088b4318eaf0c630ed669fa641bbab86ecfad8e3e59ab4d27841f95fa
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 24, 2026.

Transparency log

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

Download URL gridoxide-0.1.0-cp312-cp312-win_amd64.whl
Size 1.6 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
7984572f33a73a0dc5d80d5784455e05511c980a7646458b93e603746741bcdd
BLAKE2b-256 checksum
How to use checksums
c7626d7d29891177759773d29ebd88f0c73f24b5d2e8938195af4da5c8433308
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 24, 2026.

Transparency log

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

Download URL gridoxide-0.1.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 2.0 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
ead8425cea4381c3cb6575328545c3bd1c4dbdd0fe7d23ae592265870e645796
BLAKE2b-256 checksum
How to use checksums
cfe7976937c8539801cff4cbefd2ff96c350d33cc43e0a6534b6abc849b32afe
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 24, 2026.

Transparency log

Security for gridoxide 0.1.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.1.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 24, 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