gridstate

Power-system State Estimation in pure Python.

gridstate reconstructs the most likely operating state of an electrical network from SCADA telemetry and a topology model: voltage magnitudes and angles at every bus, plus the derived quantities — branch power flows, currents and nodal injections.

The estimator is implemented on top of numpy and scipy only — there are no proprietary or vendor dependencies. Input and output cross a single, explicit, versioned data contract (a .npz file), so the package is fully self-contained and decoupled from any particular network-model format.

 measurements (value + σ)        ┌──────────────────────┐        V, δ  (state)
 topology, impedances, taps  ──► │  gridstate.run_se    │ ──►   P, Q, I (branches)
 (SEInput, .npz contract)        │  WLS / IPM estimator │        injections, residuals
                                 └──────────────────────┘        (SEOutput contract)

Status

Pre-alpha. The core pipeline runs end to end:

p.u. conversion of the working model (gridstate.units);
bus-admittance assembly Ybus / Yf / Yt (gridstate.ybus);
measurement vector z, weights R, measurement index (gridstate.z_vector);
WLS Gauss–Newton solve — measurement function h(E), Jacobian H = ∂h/∂E, step ΔE = (HᵀR⁻¹H)⁻¹HᵀR⁻¹r (gridstate.algebra, gridstate.algorithms.wls), with SHGM-IRLS robust re-weighting;
IPM interior-point estimator as an alternative solver;
result write-back (V, δ, branch P/Q, currents, injections) into the output contract;
validation: χ² test (gridstate.validation.chi2_test), bad-data removal by normalized residuals / rn_max (gridstate.validation.bad_data), observability analysis (gridstate.validation.observability).

Tests: 445 passing on Python 3.10–3.12, dependency-free (numpy/scipy only).

Installation

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Runtime dependencies are just numpy>=1.24 and scipy>=1.10. Python 3.10+.

Quick start

The public boundary is a .npz data-contract file. Load it, run the estimator, read the results:

from gridstate import load_se_input_npz, run_se

# 1. Load a state-estimation input contract (working model + precomputed plans).
se_input = load_se_input_npz("path/to/case.npz")

# 2. Run the estimator (WLS by default; production pipeline defaults applied).
out = run_se(se_input)

print(out.success, out.iterations, out.objective_value)

# 3. Read per-object results from the output contract.
bus = out.node(node_id=1001)        # {'voltage_magnitude': ..., 'voltage_angle': ..., ...}
flow = out.branch(branch_id=42)     # {'power_from_p': ..., 'current_from': ..., ...}

run_se returns an SEOutput: structured arrays nodes / branches / measurements (id + result columns) plus convergence scalars (success, iterations, objective_value, algorithm) and the state vectors v_pu / delta_rad.

To estimate from a model you already hold in memory, wrap it with load_se_input(model) (skips the format-dependent input stages) or call the lower-level estimate(model, algorithm="wls", ...) directly.

Data contract

Input and output are governed by an explicit, versioned schema (gridstate.contract):

SE_INPUT / SE_OUTPUT — table/column declarations with roles (INPUT / WORKING / OUTPUT) for nodes, branches, measurements, generators, and the raw side tables.
CONTRACT_VERSION follows SemVer; is_data_compatible(...) gates whether a given .npz can be consumed.
load_se_input_npz / save_se_input round-trip the contract to disk.
validate_input(...) checks a model against the contract and fails early on missing required columns or an incompatible version.

This contract is what lets gridstate stand alone: the estimator never depends on a concrete external network-model class — only on the data it declares it needs.

Validation

from gridstate import chi2_analysis, remove_bad_data, analyze_observability

report = analyze_observability(se_input.model)
assert report.is_observable, report.diagnostics

chi2 = chi2_analysis(se_input.model, chi2_prob_false=0.05)
if chi2.bad_data_present:
    cleaned = remove_bad_data(se_input.model, rn_max_threshold=3.0)
    print("removed measurements:", cleaned.removed_meas_ids)

Public API

Exported from the top-level package:

Symbol	Purpose
`run_se`, `run_pipeline`	run the estimation pipeline (contract / direct)
`estimate`	low-level single-solve entry point
`load_se_input_npz`, `load_se_input`, `save_se_input`	data-contract I/O
`SEInput`, `SEOutput`, `SEResult`	input / output / detailed result objects
`PipelineConfig`, `pipeline_manifest`	pipeline configuration & step manifest
`chi2_analysis`, `remove_bad_data`, `analyze_observability`	validation

Development

make install-dev    # editable install + dev/test extras + pre-commit hooks
make test           # pytest tests/
make lint           # ruff check + ruff format --check
make type-check     # mypy gridstate
make check          # format + lint + type-check + test

Continuous integration (lint, the 3.10–3.12 test matrix, and a build) runs on GitHub Actions; see .github/workflows/.

License

gridstate is released under the MIT License — see LICENSE.

The estimation core (WLS/IPM linear algebra, χ² test and bad-data detection) is adapted from pandapower, which is distributed under the BSD 3-Clause License. The full third-party notice and the list of adapted files are reproduced in the "Third-Party Software Notices" section of LICENSE.

Metadata

Release files for gridstate 1.12.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 gridstate 1.12.0
File	Size	Uploaded	Provenance
gridstate-1.12.0.tar.gz	430.5 kB	Sep 29, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for gridstate 1.12.0
File	Interpreter	ABI	Platform	Reset
gridstate-1.12.0-py3-none-any.whl 291.0 kB Sep 29, 2026 With provenance	Python 3	none	any	Details

Total release size: 721.4 kB

Release files / gridstate-1.12.0.tar.gz

Download URL	gridstate-1.12.0.tar.gz
Size	430.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`a383e6bc586418b0776964c094ee2190c17d801eba9327d1703ba4f275c2ddb6`
BLAKE2b-256 checksum How to use checksums	`a4f56cdc8a048529c3cc720da4431eb578566d2cd9a6ad9e9c2878d33aa16926`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Genajoin/gridstate
Publishing commit: github.com/Genajoin/gridstate/tree/8f89a6a294137810b2f9f0870ace22d5cd4244d5

Workflow

Publishing configuration: github.com/Genajoin/gridstate/blob/8f89a6a294137810b2f9f0870ace22d5cd4244d5/.github/workflows/release.yml
Publishing logs: github.com/Genajoin/gridstate/actions/runs/36572298378/attempts/1

Artifact

Subject: gridstate-1.12.0.tar.gz
SHA-256 checksum: a383e6bc586418b0776964c094ee2190c17d801eba9327d1703ba4f275c2ddb6 Verifying attestations

Release files / gridstate-1.12.0-py3-none-any.whl

Download URL	gridstate-1.12.0-py3-none-any.whl
Size	291.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b60663bb04387d794e59afb36546963b47655dddd60dc48c6535ff5f1911031a`
BLAKE2b-256 checksum How to use checksums	`8eab57c99dcad19c52db158e42367cb81053de01483e7d0147cba6e382904b58`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Genajoin/gridstate
Publishing commit: github.com/Genajoin/gridstate/tree/8f89a6a294137810b2f9f0870ace22d5cd4244d5

Workflow

Publishing configuration: github.com/Genajoin/gridstate/blob/8f89a6a294137810b2f9f0870ace22d5cd4244d5/.github/workflows/release.yml
Publishing logs: github.com/Genajoin/gridstate/actions/runs/36572298378/attempts/1

Artifact

Subject: gridstate-1.12.0-py3-none-any.whl
SHA-256 checksum: b60663bb04387d794e59afb36546963b47655dddd60dc48c6535ff5f1911031a Verifying attestations

Security for gridstate 1.12.0

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for gridstate-1.12.0.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Genajoin/gridstate
Publishing commit: github.com/Genajoin/gridstate/tree/8f89a6a294137810b2f9f0870ace22d5cd4244d5

Workflow

Publishing configuration: github.com/Genajoin/gridstate/blob/8f89a6a294137810b2f9f0870ace22d5cd4244d5/.github/workflows/release.yml
Publishing logs: github.com/Genajoin/gridstate/actions/runs/36572298378/attempts/1

Artifact

Subject: gridstate-1.12.0.tar.gz
SHA-256 checksum: a383e6bc586418b0776964c094ee2190c17d801eba9327d1703ba4f275c2ddb6 Verifying attestations

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.