gridstate 2.4.1__tar.gz → 2.5.0__tar.gz

{gridstate-2.4.1 → gridstate-2.5.0}/CHANGELOG.md

@@ -9,6 +9,23 @@ 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.5.0 (2026-10-18)
+
+### Behavior changes
+
+- After the run, transit nodes (no `exist_gen` / `exist_load`) whose solved
+  injection exceeds `transit_injection_warn_mva` (new, default 5 MVA; 0 turns
+  it off) are listed in a WARNING: a data conflict, or a generation, load or
+  shunt the model does not describe. Estimates are not affected.
+
+### Feat
+
+- `ipm_transit_balance_weight_factor` (new, default 0 — off): the balance row
+  of a transit node gets the variance median(σ²_data) / factor (never looser
+  than the soft balance). Their injection is known to be zero; with the
+  default soft weight a data conflict spreads over them as a fictitious
+  injection.
+
 ## v2.4.1 (2026-10-18)
 
 ### Behavior changes

{gridstate-2.4.1 → gridstate-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.4.1
+Version: 2.5.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.4.1 → gridstate-2.5.0}/gridstate/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.4.1'
-__version_tuple__ = version_tuple = (2, 4, 1)
+__version__ = version = '2.5.0'
+__version_tuple__ = version_tuple = (2, 5, 0)
 
-__commit_id__ = commit_id = 'g640125491'
+__commit_id__ = commit_id = 'g98bb957af'

{gridstate-2.4.1 → gridstate-2.5.0}/gridstate/pipeline/config.py

@@ -396,6 +396,17 @@ class PipelineConfig:
         "and logged with hints (e.g. the low-voltage root at a node whose V is barely "
         "observable). 0 disables the check.",
     )
+    transit_injection_warn_mva: float = _param(
+        5.0,
+        group=_G_EST,
+        label="Transit injection warning, MVA",
+        control="number",
+        min=0.0,
+        max=1e4,
+        help="After the run, transit nodes (no exist_gen/exist_load) whose solved "
+        "injection exceeds this are listed in a WARNING: a data conflict or an "
+        "undescribed generation, load or shunt. 0 disables the warning.",
+    )
     kkt_solver: str = _param(
         "auto",
         group=_G_EST,
@@ -587,6 +598,18 @@ class PipelineConfig:
         "balance row with variance median(σ²_data) / factor. The box carries the node's "
         "freedom; a loose balance only hides data conflicts as an imbalance. 0 — off.",
     )
+    ipm_transit_balance_weight_factor: float = _param(
+        0.0,
+        group=_G_IPM,
+        label="Balance weight of transit nodes",
+        control="number",
+        min=0.0,
+        max=1e6,
+        depends={"algorithm": "ipm"},
+        help="Transit nodes (no exist_gen/exist_load) get a balance row with variance "
+        "median(σ²_data) / factor. Their injection is known to be zero; a loose balance "
+        "turns data conflicts into a fictitious injection. 0 — off.",
+    )
     ipm_prior_sigma2_bus_equiv_pu: float = _param(
         0.01,
         group=_G_IPM,

{gridstate-2.4.1 → gridstate-2.5.0}/gridstate/pipeline/passes.py

@@ -51,6 +51,7 @@ def _ipm_kwargs(cfg: PipelineConfig) -> dict:
         "balance_weight_factor": cfg.ipm_balance_weight_factor,
         "prior_sigma2_bus_equiv_pu": cfg.ipm_prior_sigma2_bus_equiv_pu,
         "boxed_balance_weight_factor": cfg.ipm_boxed_balance_weight_factor,
+        "transit_balance_weight_factor": cfg.ipm_transit_balance_weight_factor,
         "trust_region_scope": cfg.ipm_trust_region_scope,
         "balance_mode": cfg.ipm_balance_mode,
         "balance_tol_p_mw": cfg.ipm_balance_tol_p_mw,

{gridstate-2.4.1 → gridstate-2.5.0}/gridstate/pipeline/runner.py

@@ -64,6 +64,7 @@ neither :data:`STEPS` nor the manifest and have no ``step_start``):
 
 from __future__ import annotations
 
+import logging
 import time
 from collections.abc import Callable
 from dataclasses import replace
@@ -76,10 +77,14 @@ from gridstate.pipeline.context import Step, _Ctx, _no_solution
 from gridstate.pipeline.steps import STEPS
 from gridstate.resolve_pass import fail_out_of_range, state_range_violation
 from gridstate.result import SEResult
+from gridstate.solution_hints import transit_injection_hints
 from gridstate.state import InitialPoint
 from gridstate.working import Working
 
 
+logger = logging.getLogger(__name__)
+
+
 # Consistency guard between config and derived (the config is used twice): the
 # producer of the plans and the step executor must be gated by ONE config. An
 # enabled step that did not get its plan means the configs diverged (derive
@@ -369,6 +374,10 @@ def run(
         },
     )
 
+    hints = transit_injection_hints(ctx.model.nodes.to_numpy(), cfg.transit_injection_warn_mva)
+    if hints:
+        logger.warning("%s", "\n".join(hints))
+
     _emit(
         on_event,
         {

{gridstate-2.4.1 → gridstate-2.5.0}/gridstate/preprocessing/ipm_setup.py

@@ -511,6 +511,15 @@ def _boxed_balance_masks(
     return boxed[0], boxed[1]
 
 
+def _transit_mask(nodes_arr: np.ndarray, node_ids: list[int]) -> np.ndarray:
+    """Mask over ``node_ids``: transit nodes (neither ``exist_gen`` nor ``exist_load``)."""
+    rows = {int(r["id"]): r for r in nodes_arr}
+    return np.array(
+        [not (bool(rows[nid]["exist_gen"]) or bool(rows[nid]["exist_load"])) for nid in node_ids],
+        dtype=bool,
+    )
+
+
 def _median_measurement_sigma2(sigma2: np.ndarray) -> float | None:
     """Median variance (p.u.²) of the data rows; ``None`` when there are none."""
     positive = sigma2[sigma2 > 1e-15]
@@ -538,6 +547,7 @@ def build_ipm_setup(
     balance_sigma2: float | None = None,
     balance_weight_factor: float = 0.1,
     boxed_balance_weight_factor: float = 0.0,
+    transit_balance_weight_factor: float = 0.0,
     default_box_halfwidth_pu: float = 50.0,
     prior_sigma2_normal_pu: float = 0.0,
     prior_sigma2_bus_equiv_pu: float = 0.01,
@@ -576,6 +586,12 @@ def build_ipm_setup(
             ``median(σ²_data) / boxed_balance_weight_factor`` (never looser than
             the soft one): the box already carries the node's freedom, so a
             loose balance only hides data conflicts as an imbalance. ``0`` — off.
+        transit_balance_weight_factor: balance weight for transit nodes (no
+            ``exist_gen`` / ``exist_load``): their injection is known to be
+            zero, so a loose balance turns data conflicts into a fictitious
+            injection. Their variance is ``median(σ²_data) /
+            transit_balance_weight_factor`` (never looser than the soft one).
+            ``0`` — off.
         default_box_halfwidth_pu: half-width (p.u.) of the default box
             ``[-hw, +hw]`` for an exist_* node with unset bounds.
             Default 50 p.u. (±5 GW/GVAr), deliberately wider than any
@@ -790,6 +806,16 @@ def build_ipm_setup(
             q_rows = sigma2_new[n_old + n_balance : n_old + 2 * n_balance]
             p_rows[boxed_p] = np.minimum(p_rows[boxed_p], boxed_s2)
             q_rows[boxed_q] = np.minimum(q_rows[boxed_q], boxed_s2)
+    if transit_balance_weight_factor > 0.0 and n_balance > 0 and not hard:
+        median_sigma2 = _median_measurement_sigma2(sigma2_old)
+        if median_sigma2 is not None:
+            transit_s2 = min(
+                median_sigma2 / float(transit_balance_weight_factor), balance_sigma2_eff
+            )
+            transit = _transit_mask(nodes_arr, active_ids)
+            for start in (n_old, n_old + n_balance):
+                rows = sigma2_new[start : start + n_balance]
+                rows[transit] = np.minimum(rows[transit], transit_s2)
     if n_prior > 0:
         prior_sigmas = np.concatenate(
             [

{gridstate-2.4.1 → gridstate-2.5.0}/gridstate/solution_hints.py

@@ -6,7 +6,9 @@ wrong. A typical case is a node whose voltage magnitude is barely observable
 problem then has a second, low-voltage root, and a change of the solver path
 can land on it while the solver reports success. :func:`low_voltage_nodes`
 finds such nodes; :func:`low_voltage_hints` and :func:`residual_hints` turn
-the solved state into readable lines for the log.
+the solved state into readable lines for the log. :func:`transit_injection_hints`
+lists transit nodes left with an injection, which points at a data conflict or
+at a node whose generation, load or shunt is not described in the model.
 """
 
 from __future__ import annotations
@@ -162,10 +164,47 @@ def residual_hints(
     return lines
 
 
+def transit_injection_hints(nodes: np.ndarray, threshold_mva: float, *, top: int = 10) -> list[str]:
+    """Transit nodes with a solved injection above ``threshold_mva``, largest first.
+
+    A transit node (active, neither ``exist_gen`` nor ``exist_load``) injects
+    nothing, so ``|p_inj_calc + j·q_inj_calc|`` there is what the estimate
+    could not fit elsewhere. ``nodes`` is a solved node table; empty when no
+    node exceeds the threshold or ``threshold_mva <= 0``.
+    """
+    if threshold_mva <= 0.0 or not len(nodes):
+        return []
+    transit = (
+        nodes["status"].astype(bool)
+        & ~nodes["exist_gen"].astype(bool)
+        & ~nodes["exist_load"].astype(bool)
+    )
+    s_mva = np.hypot(nodes["p_inj_calc"], nodes["q_inj_calc"])
+    hit = np.flatnonzero(transit & np.isfinite(s_mva) & (s_mva > threshold_mva))
+    if not hit.size:
+        return []
+    order = hit[np.argsort(-s_mva[hit])]
+    lines = [
+        f"{hit.size} transit node(s) (no exist_gen/exist_load) inject more than "
+        f"{threshold_mva:g} MVA; a data conflict or an undescribed generation, load or "
+        "shunt at the node:"
+    ]
+    for k in order[:top].tolist():
+        lines.append(
+            f"  node {int(nodes['id'][k])} ({float(nodes['voltage_nominal'][k]):g} kV): "
+            f"P = {float(nodes['p_inj_calc'][k]):.1f} MW, "
+            f"Q = {float(nodes['q_inj_calc'][k]):.1f} MVAr"
+        )
+    if hit.size > top:
+        lines.append(f"  ... and {hit.size - top} more")
+    return lines
+
+
 __all__ = [
     "KIND_NAMES",
     "describe_row",
     "low_voltage_hints",
     "low_voltage_nodes",
     "residual_hints",
+    "transit_injection_hints",
 ]

{gridstate-2.4.1 → gridstate-2.5.0}/gridstate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.4.1
+Version: 2.5.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.4.1 → gridstate-2.5.0}/gridstate.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "2.4.1",
+  "tag": "2.5.0",
   "distance": 0,
-  "node": "g640125491ba6b35d3beb20b4fd33688f9cceb117",
+  "node": "g98bb957af8b143153db7f269753619ec87bf6f6e",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-18"

{gridstate-2.4.1 → gridstate-2.5.0}/tests/test_boxed_balance.py

@@ -209,3 +209,30 @@ def test_compensator_active_power_is_not_a_box_part():
     p_rows, q_rows = _setup(m, boxed_balance_weight_factor=10.0)
     assert p_rows[2] < SOFT
     assert q_rows[2] < SOFT
+
+
+def test_transit_weight_off_by_default():
+    assert PipelineConfig().ipm_transit_balance_weight_factor == 0.0
+
+
+def test_transit_nodes_get_the_weighted_row():
+    # Node order: 1 slack (generation box), 2 transit, 3 and 4 loads with a box.
+    p_rows, q_rows = _setup(_build_net_with_transit(), transit_balance_weight_factor=100.0)
+    tight = 2.5e-4 / 100.0
+    assert np.allclose(p_rows, [SOFT, tight, SOFT, SOFT])
+    assert np.allclose(q_rows, [SOFT, tight, SOFT, SOFT])
+
+
+def test_transit_row_never_looser_than_the_soft_row():
+    p_rows, q_rows = _setup(_build_net_with_transit(), transit_balance_weight_factor=0.01)
+    assert np.allclose(p_rows, SOFT)
+    assert np.allclose(q_rows, SOFT)
+
+
+def test_transit_and_boxed_weights_combine():
+    p_rows, _ = _setup(
+        _build_net_with_transit(),
+        boxed_balance_weight_factor=10.0,
+        transit_balance_weight_factor=100.0,
+    )
+    assert np.allclose(p_rows, [2.5e-5, 2.5e-6, 2.5e-5, 2.5e-5])

{gridstate-2.4.1 → gridstate-2.5.0}/tests/test_numpy_only_runtime.py

@@ -152,7 +152,8 @@ _RUN_SRC = textwrap.dedent(
     from gridstate.pipeline import run, PipelineConfig
 
     working = build_working()
-    cfg = PipelineConfig(materialize=False)
+    # The toy network leaves a transit injection; its WARNING would reach stderr.
+    cfg = PipelineConfig(materialize=False, transit_injection_warn_mva=0.0)
     res = run(working, config=cfg)
     vmax = float(np.max(res.v_pu)) if getattr(res, "v_pu", None) is not None and res.v_pu.size else float("nan")
     print(f"RUN_OK success={bool(res.success)} iters={int(res.iterations)} vmax={vmax:.6f}")

gridstate-2.5.0/tests/test_solution_hints.py

@@ -0,0 +1,98 @@
+"""Plausibility check of the solved state (implausible V/Vnom) and its hints."""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import pytest
+
+from gridstate.api import estimate
+from gridstate.pipeline import PipelineConfig, run
+from gridstate.solution_hints import low_voltage_nodes, transit_injection_hints
+from tests.test_boxed_balance import _build_net_with_transit
+
+
+def test_low_voltage_nodes():
+    v = np.array([1.0, 0.1, np.nan, 0.29, 0.31])
+    assert low_voltage_nodes(v, 0.3).tolist() == [1, 3]
+    assert low_voltage_nodes(v, 0.0).size == 0
+
+
+@pytest.mark.parametrize("algorithm", ["wls", "ipm_pd"])
+def test_implausible_state_is_not_a_success(caplog, algorithm):
+    # A threshold above every solved V flags all nodes: the run is marked failed
+    # and the warning names the nodes with a hint.
+    m = _build_net_with_transit()
+    with caplog.at_level(logging.WARNING, logger="gridstate.api"):
+        res = estimate(
+            m, algorithm=algorithm, include_quality_summary=False, implausible_v_ratio=2.0
+        )
+    assert not res.success
+    assert res.message.startswith("implausible solution: V/Vnom < 2")
+    text = "\n".join(r.getMessage() for r in caplog.records if "implausible" in r.getMessage())
+    assert "node " in text and "p.u.;" in text
+
+
+def test_check_disabled_keeps_the_solver_flag():
+    m = _build_net_with_transit()
+    res = estimate(m, algorithm="ipm_pd", include_quality_summary=False, implausible_v_ratio=0.0)
+    assert res.success
+    assert "implausible" not in res.message
+
+
+def _nodes(p, q, exist_gen=0, exist_load=0, status=True):
+    nodes = np.zeros(
+        len(p),
+        dtype=[
+            ("id", "i8"),
+            ("voltage_nominal", "f8"),
+            ("status", "?"),
+            ("exist_gen", "i1"),
+            ("exist_load", "i1"),
+            ("p_inj_calc", "f8"),
+            ("q_inj_calc", "f8"),
+        ],
+    )
+    nodes["id"] = np.arange(1, len(p) + 1)
+    nodes["voltage_nominal"] = 220.0
+    nodes["status"] = status
+    nodes["exist_gen"] = exist_gen
+    nodes["exist_load"] = exist_load
+    nodes["p_inj_calc"] = p
+    nodes["q_inj_calc"] = q
+    return nodes
+
+
+def test_transit_injection_hints_list_largest_first():
+    nodes = _nodes([3.0, -0.5, 1.0, 0.0], [4.0, 0.2, -9.0, 0.0])
+    lines = transit_injection_hints(nodes, 4.0)
+    assert lines[0].startswith("2 transit node(s)")
+    assert lines[1].startswith("  node 3 (220 kV): P = 1.0 MW, Q = -9.0 MVAr")
+    assert lines[2].startswith("  node 1 ")
+    assert len(lines) == 3
+
+
+def test_transit_injection_hints_skip_marked_and_inactive_nodes():
+    assert transit_injection_hints(_nodes([50.0], [0.0], exist_gen=1), 5.0) == []
+    assert transit_injection_hints(_nodes([50.0], [0.0], exist_load=1), 5.0) == []
+    assert transit_injection_hints(_nodes([50.0], [0.0], status=False), 5.0) == []
+    assert transit_injection_hints(_nodes([50.0], [0.0]), 0.0) == []
+
+
+def test_transit_injection_hints_cap_the_list():
+    lines = transit_injection_hints(_nodes([10.0] * 4, [0.0] * 4), 5.0, top=2)
+    assert lines[-1] == "  ... and 2 more"
+
+
+def test_pipeline_warns_about_transit_injection(caplog):
+    m = _build_net_with_transit()
+    cfg = PipelineConfig(algorithm="ipm_pd", transit_injection_warn_mva=1e-9)
+    with caplog.at_level(logging.WARNING, logger="gridstate.pipeline.runner"):
+        run(m, config=cfg)
+    text = "\n".join(r.getMessage() for r in caplog.records)
+    assert "transit node(s)" in text and "node 2 " in text
+    caplog.clear()
+    with caplog.at_level(logging.WARNING, logger="gridstate.pipeline.runner"):
+        run(m, config=PipelineConfig(algorithm="ipm_pd", transit_injection_warn_mva=0.0))
+    assert not any("transit node(s)" in r.getMessage() for r in caplog.records)

gridstate-2.4.1/tests/test_solution_hints.py

@@ -1,40 +0,0 @@
-"""Plausibility check of the solved state (implausible V/Vnom) and its hints."""
-
-from __future__ import annotations
-
-import logging
-
-import numpy as np
-import pytest
-
-from gridstate.api import estimate
-from gridstate.solution_hints import low_voltage_nodes
-from tests.test_boxed_balance import _build_net_with_transit
-
-
-def test_low_voltage_nodes():
-    v = np.array([1.0, 0.1, np.nan, 0.29, 0.31])
-    assert low_voltage_nodes(v, 0.3).tolist() == [1, 3]
-    assert low_voltage_nodes(v, 0.0).size == 0
-
-
-@pytest.mark.parametrize("algorithm", ["wls", "ipm_pd"])
-def test_implausible_state_is_not_a_success(caplog, algorithm):
-    # A threshold above every solved V flags all nodes: the run is marked failed
-    # and the warning names the nodes with a hint.
-    m = _build_net_with_transit()
-    with caplog.at_level(logging.WARNING, logger="gridstate.api"):
-        res = estimate(
-            m, algorithm=algorithm, include_quality_summary=False, implausible_v_ratio=2.0
-        )
-    assert not res.success
-    assert res.message.startswith("implausible solution: V/Vnom < 2")
-    text = "\n".join(r.getMessage() for r in caplog.records if "implausible" in r.getMessage())
-    assert "node " in text and "p.u.;" in text
-
-
-def test_check_disabled_keeps_the_solver_flag():
-    m = _build_net_with_transit()
-    res = estimate(m, algorithm="ipm_pd", include_quality_summary=False, implausible_v_ratio=0.0)
-    assert res.success
-    assert "implausible" not in res.message