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.

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

Built distributions (wheels)

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

Total release size: 7.0 MB

Release files / gridoxide-0.2.0.tar.gz

Download URL gridoxide-0.2.0.tar.gz
Size 2.0 MB
Tags Source
SHA-256 checksum
How to use checksums
167db3e544f3ff3b298831fd99e15985a47a3bc955b19491fa590ac8216c0d80
BLAKE2b-256 checksum
How to use checksums
75b376cecfe987412af6fb8343bc7732791b21e108a4c0798ef9a91d119242dd
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 log

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

Download URL gridoxide-0.2.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
32990820e01d38118fd92dbc44f357513304d656da6f630684286cd3d0a423ca
BLAKE2b-256 checksum
How to use checksums
47aba5ee0454c9cf547ca4127af9242881e45c04cad166e2bc7917008ac770cf
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 log

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

Download URL gridoxide-0.2.0-cp312-cp312-win_amd64.whl
Size 1.6 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
9275c57a242cacc39cb2ab9ca6b67c3939eba103595ce25cdcb61451b3711971
BLAKE2b-256 checksum
How to use checksums
c0bcf9cd671d4d1c9cd728ad898629daf4836f6d83de6bc7e921eb9c2e29d2e1
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 log

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

Download URL gridoxide-0.2.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
c9acc97c53ff9e3bcbd9cfba6da8d00ad5b2e003f4dc344bc967b2b226780acc
BLAKE2b-256 checksum
How to use checksums
81e684e7558e2c7f4319b8f27d22fb9d3b7605f3ae5ee332974874ca140daf69
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 log

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