gridstate 2.0.0__tar.gz → 2.1.0__tar.gz

{gridstate-2.0.0 → gridstate-2.1.0}/CHANGELOG.md

@@ -9,6 +9,19 @@ types of the merged pull requests; breaking and behavior-changing items are
 listed separately under "Breaking changes" and "Behavior changes". A release is
 cut by tagging the merged main commit; the version is derived from that tag.
 
+## v2.1.0 (2026-10-14)
+
+### Feat
+
+- `SEResult.normalized_residuals` (`MeasurementNormalizedResiduals`, exported
+  from the package root): `r_N` and `Ω_ii / σ²_i` of every z-vector
+  measurement by measurement id, in z-vector order. The quality summary keeps
+  the vector it already computes; `worst_residuals` and
+  `near_critical_measurements` still rank and trim it. Rows outside the
+  residual scope (pseudo-measurements under `"real"`) hold `nan`, critical
+  measurements `inf`; `None` when the summary is not computed. Additive, no
+  data contract change (#101)
+
 ## v2.0.0 (2026-10-10)
 
 ### Breaking changes

{gridstate-2.0.0 → gridstate-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.0.0
+Version: 2.1.0
 Summary: Power system State Estimation: pure-Python WLS/IPM on numpy/scipy, input via a versioned file contract (npz).
 Author-email: Evgeny Istomin <gena@alpisto.eu>
 License: MIT

{gridstate-2.0.0 → gridstate-2.1.0}/gridstate/__init__.py

@@ -34,6 +34,7 @@ from gridstate.pipeline import (
 from gridstate.result import (
     Chi2Summary,
     ImbalanceRow,
+    MeasurementNormalizedResiduals,
     NearCriticalRow,
     ResidualRow,
     SEResult,
@@ -84,6 +85,7 @@ __all__ = [
     "Chi2Summary",
     "ImbalanceRow",
     "InitialPoint",
+    "MeasurementNormalizedResiduals",
     "NearCriticalRow",
     "NormalizedResidualReport",
     "ObservabilityReport",

{gridstate-2.0.0 → gridstate-2.1.0}/gridstate/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.0.0'
-__version_tuple__ = version_tuple = (2, 0, 0)
+__version__ = version = '2.1.0'
+__version_tuple__ = version_tuple = (2, 1, 0)
 
-__commit_id__ = commit_id = 'g145919a37'
+__commit_id__ = commit_id = 'g2560497db'

{gridstate-2.0.0 → gridstate-2.1.0}/gridstate/api.py

@@ -39,7 +39,7 @@ from gridstate.quality_summary import (
     top_worst_imbalance,
     top_worst_residuals,
 )
-from gridstate.result import SEResult, extract_output_tables
+from gridstate.result import MeasurementNormalizedResiduals, SEResult, extract_output_tables
 from gridstate.state import (
     InitialPoint,
     StateLayout,
@@ -414,7 +414,8 @@ def _populate_quality_summary(
     near_critical: float = NEAR_CRITICAL_THRESHOLD,
 ) -> None:
     """Fill ``result.chi2 / worst_residuals / worst_imbalance /
-    observability_warnings / near_critical_measurements`` after
+    observability_warnings / near_critical_measurements /
+    normalized_residuals`` after
     ``write_results_to_model``.
 
     All errors in the summary are swallowed into the logs: report quality is not an indicator of
@@ -476,6 +477,11 @@ def _populate_quality_summary(
                 is_pseudo=is_pseudo_z,
                 network_pu=network_pu,
             )
+            result.normalized_residuals = MeasurementNormalizedResiduals(
+                measurement_id=np.asarray(meas_index.meas_id, dtype=np.int64).copy(),
+                normalized_residual=np.asarray(normalized.rn, dtype=np.float64).copy(),
+                omega_ratio=np.asarray(normalized.omega_ratio, dtype=np.float64).copy(),
+            )
         result.worst_imbalance = top_worst_imbalance(model, n=top_n)
         result.observability_warnings = observability_warnings_from_H(
             H,

{gridstate-2.0.0 → gridstate-2.1.0}/gridstate/result.py

@@ -13,7 +13,8 @@ canonical Output contract for external adapters (UI/CLI): they join Input +
 p.u./radians — for debugging and tests.
 
 The additional quality fields (``chi2``, ``worst_residuals``,
-``worst_imbalance``, ``observability_warnings``) are filled by ``estimate()``
+``worst_imbalance``, ``observability_warnings``, ``normalized_residuals``) are
+filled by ``estimate()``
 after ``write_results_to_model``: a structured summary for backward-compatible
 diagnostics (it used to be assembled ad hoc by an example script).
 """
@@ -119,6 +120,31 @@ class ResidualRow:
     is_pseudo: bool = False
 
 
+@dataclass
+class MeasurementNormalizedResiduals:
+    """Normalized residuals of every z-vector measurement, by measurement id.
+
+    The full vector behind ``worst_residuals`` / ``near_critical_measurements``:
+    those lists rank and trim it, this one keeps every row so that an adapter
+    can show ``r_N`` next to each measurement. Arrays are parallel, in z-vector
+    order; pseudo-measurements are in the vector only under
+    ``quality_summary_scope="all"``.
+
+    Attributes:
+        measurement_id: (m,) ``Measurement.id`` of the z-vector rows.
+        normalized_residual: (m,) ``|r| / √Ω_ii``; ``inf`` for a critical
+            measurement (numerically non-positive ``Ω_ii``); ``nan`` for a row
+            outside the residual scope (a pseudo-measurement under ``"real"``).
+        omega_ratio: (m,) ``Ω_ii / σ²_i`` (1: fully redundant, 0: critical);
+            below the near-critical threshold ``r_N`` is numerically
+            unreliable. ``nan`` where ``normalized_residual`` is ``nan``.
+    """
+
+    measurement_id: np.ndarray
+    normalized_residual: np.ndarray
+    omega_ratio: np.ndarray
+
+
 @dataclass
 class NearCriticalRow:
     """A measurement whose ``Ω_ii`` is a small fraction of its variance.
@@ -316,6 +342,10 @@ class SEResult:
             ``False``; with ``quality_summary_scope="all"`` they take part
             and are marked by ``is_pseudo`` (the pipeline always uses
             ``"real"``).
+        normalized_residuals: ``r_N`` and ``Ω_ii / σ²_i`` of every z-vector
+            measurement (:class:`MeasurementNormalizedResiduals`), the
+            untrimmed source of ``worst_residuals``; ``None`` if the summary
+            was not computed.
     """
 
     model: Working
@@ -353,6 +383,7 @@ class SEResult:
     worst_imbalance: list[ImbalanceRow] = field(default_factory=list)
     observability_warnings: list[int] = field(default_factory=list)
     near_critical_measurements: list[NearCriticalRow] = field(default_factory=list)
+    normalized_residuals: MeasurementNormalizedResiduals | None = None
 
 
 def label_for_kind(kind_code: int) -> str:

{gridstate-2.0.0 → gridstate-2.1.0}/gridstate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.0.0
+Version: 2.1.0
 Summary: Power system State Estimation: pure-Python WLS/IPM on numpy/scipy, input via a versioned file contract (npz).
 Author-email: Evgeny Istomin <gena@alpisto.eu>
 License: MIT

gridstate-2.1.0/gridstate.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.1.0",
+  "distance": 0,
+  "node": "g2560497dba010646abc135557a9a2e7eea0c6f80",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-14"
+}

{gridstate-2.0.0 → gridstate-2.1.0}/tests/test_result_quality_summary.py

@@ -19,6 +19,7 @@ from gridstate.api import estimate
 from gridstate.result import (
     Chi2Summary,
     ImbalanceRow,
+    MeasurementNormalizedResiduals,
     ResidualRow,
     SEResult,
 )
@@ -96,6 +97,7 @@ def test_seresult_quality_summary_disabled() -> None:
     assert res.worst_residuals == []
     assert res.worst_imbalance == []
     assert res.observability_warnings == []
+    assert res.normalized_residuals is None
 
 
 def test_seresult_backward_compat_default_construction() -> None:
@@ -186,3 +188,37 @@ def test_worst_residuals_scope_all_keeps_pseudo() -> None:
     top = res.worst_residuals[0]
     assert top.measurement_id == 900
     assert top.is_pseudo is True
+
+
+def test_normalized_residuals_vector_covers_every_measurement() -> None:
+    """The full r_N vector holds every z row and agrees with the trimmed top."""
+    m, _, _ = _three_bus_with_clean_measurements()
+    res = estimate(m, tolerance=1e-10, quality_summary_top_n=2)
+
+    vec = res.normalized_residuals
+    assert isinstance(vec, MeasurementNormalizedResiduals)
+    n_meas = sum(1 for me in m.measurements if me.status)
+    assert vec.measurement_id.shape == (n_meas,)
+    assert vec.normalized_residual.shape == vec.omega_ratio.shape == (n_meas,)
+    assert len(set(vec.measurement_id.tolist())) == n_meas
+
+    rn_by_id = dict(zip(vec.measurement_id.tolist(), vec.normalized_residual.tolist(), strict=True))
+    assert len(res.worst_residuals) == 2
+    for row in res.worst_residuals:
+        assert rn_by_id[row.measurement_id] == row.normalized_residual
+
+
+def test_normalized_residuals_vector_pseudo_outside_scope_is_nan() -> None:
+    """Under scope="real" a pseudo row stays in the vector with nan r_N."""
+    m = _with_pseudo_outlier()
+    res = estimate(m, tolerance=1e-10)
+    vec = res.normalized_residuals
+    assert vec is not None
+    ids = vec.measurement_id.tolist()
+    assert 900 in ids
+    pos = ids.index(900)
+    assert np.isnan(vec.normalized_residual[pos])
+    assert np.isnan(vec.omega_ratio[pos])
+    real = np.ones(len(ids), dtype=bool)
+    real[pos] = False
+    assert not np.isnan(vec.normalized_residual[real]).any()

gridstate-2.0.0/gridstate.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.0.0",
-  "distance": 0,
-  "node": "g145919a379eaaa66ca9713822fc7ff19d40a2349",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-10"
-}