gridstate 2.4.0__tar.gz → 2.5.0__tar.gz

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

@@ -9,6 +9,45 @@ 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
+
+- `ipm_pd`: the proximal term on the box-variable diagonal adapts to the step
+  length: ×10 after a step αp < 0.1, up to `box_prox_max` (new, default 1e-2 of
+  the median weight), ÷10 after αp ≥ 0.5, down to `box_prox`. It damps the step
+  only; the fixed point is unchanged. Estimates on the test models move by
+  ≤ 1.6e-8 p.u. V with unchanged iteration counts.
+- `ipm_pd`: a second stopping test, `fit_tol` (new, default 1e-2): the step moves
+  no data row by more than that fraction of its sigma (the μ, feasibility and
+  equality tests still apply).
+
+### Fix
+
+- `ipm_pd` no longer runs into its iteration limit and the primal fallback when
+  box variables are seen only through near-zero-weight rows (loads with
+  effectively free injections): such directions have barrier curvature only,
+  their steps dwarf the box and the boundary rule cut every step to a tiny αp.
+  A state the data do not determine no longer keeps the V/δ step test from
+  passing (it could move, or cycle, without changing any estimate).
+
 ## v2.4.0 (2026-10-17)
 
 ### Behavior changes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.4.0
+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.0 → 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.0'
-__version_tuple__ = version_tuple = (2, 4, 0)
+__version__ = version = '2.5.0'
+__version_tuple__ = version_tuple = (2, 5, 0)
 
-__commit_id__ = commit_id = 'g81767e831'
+__commit_id__ = commit_id = 'g98bb957af'

{gridstate-2.4.0 → gridstate-2.5.0}/gridstate/algorithms/ipm_pd.py

@@ -50,6 +50,19 @@ corrector's second-order term may spoil descent, and then the centering
 direction is taken instead (one more solve on the same factor). The dual step
 keeps its own fraction-to-boundary length.
 
+Adaptive box regularisation. A box variable seen only through rows of
+negligible weight (a load whose injection row is a near-zero-weight pseudo
+measurement) or through a combination the data do not resolve (a reactive flow
+circulating between two such loads) has no curvature but the barrier's, and
+the Newton step along it is orders of magnitude longer than the box. The
+fraction-to-boundary rule then cuts every step to ``αp ≪ 1``, the
+complementarity stops decreasing and the iteration crawls to its limit. The
+proximal term on the box diagonal is therefore raised tenfold after every
+step shorter than 0.1 (up to ``box_prox_max``) and lowered tenfold after
+every step of 0.5 or longer (down to ``box_prox``). The term damps the step
+only, so the fixed point is unchanged; a well-scaled problem takes long steps
+and keeps the base term.
+
 Start on the central path: ``s`` = half-range of a two-sided constraint (the
 distance for a one-sided one), ``y = μ0/s``; the initial point need not satisfy
 ``g − l = s``.
@@ -96,6 +109,14 @@ def _blocking_constraint(
     return ku, False
 
 
+# Adaptive box regularisation (see the module docstring): a primal step shorter
+# than _PROX_SHORT raises the term by _PROX_GROW, one of _PROX_LONG or longer
+# lowers it by the same factor.
+_PROX_SHORT = 0.1
+_PROX_LONG = 0.5
+_PROX_GROW = 10.0
+
+
 Direction = tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]
 
 
@@ -212,6 +233,7 @@ def solve_ipm_pd(
     armijo_max: int = 10,
     max_search_failures: int = 20,
     step_tol: float = 1e-4,
+    fit_tol: float = 1e-2,
     feas_tol: float = 1e-6,
     max_iter: int = 100,
     box_eps: float = 1e-3,
@@ -225,6 +247,7 @@ def solve_ipm_pd(
     kkt_solver: KKTSolver | None = None,
     eq_prox: float = 1e-9,
     box_prox: float = 1e-6,
+    box_prox_max: float = 1e-2,
 ) -> IPMResult:
     """Mehrotra predictor-corrector IPM (see the module docstring).
 
@@ -251,6 +274,11 @@ def solve_ipm_pd(
             outside ``box_idx`` (V/δ) is below it. Box variables may still move
             along directions the data do not see (the common level of a node's
             generation and load), which change neither the state nor the residuals.
+        fit_tol: alternatively, stop once that step moves no data row by more
+            than ``fit_tol`` of its sigma (``max √w·|H·αp·Δx|``). A state the data
+            do not determine (a node behind loads whose injection rows carry
+            near-zero weight) can keep moving, or cycle, without changing any
+            estimated measurement; the fit has converged all the same.
         feas_tol: admissible primal infeasibility of the inequalities (p.u.).
         max_iter: iteration limit (one factorization each).
         box_eps: margin from the bounds when projecting ``x_init``.
@@ -271,6 +299,9 @@ def solve_ipm_pd(
             has no curvature along that common level but the barrier's, so a
             cold start produces huge box steps cut to tiny ``αp`` by the boundary
             rule; the term bounds those steps without moving the fixed point.
+        box_prox_max: ceiling of the adaptive box term (same units as
+            ``box_prox``, see the module docstring); a value not above
+            ``box_prox`` keeps the term fixed.
 
     Returns:
         :class:`~gridstate.algorithms.ipm.IPMResult`; ``status`` is ``"kkt"`` when
@@ -325,10 +356,9 @@ def solve_ipm_pd(
     is_eq = np.zeros(m, dtype=bool)
     is_eq[eq_rows] = True
     rho = w_base[eq_rows]
-    prox = max(
-        eq_prox * float(np.max(rho)) if rho.size else 0.0,
-        box_prox * float(np.median(w_base[~is_eq])) if (~is_eq).any() else 0.0,
-    )
+    eq_prox_abs = eq_prox * float(np.max(rho)) if rho.size else 0.0
+    w_median = float(np.median(w_base[~is_eq])) if (~is_eq).any() else 0.0
+    box_scale = box_prox
 
     huber_mask_arr = (
         np.asarray(huber_mask, dtype=bool) if huber_mask is not None else np.zeros(m, dtype=bool)
@@ -378,6 +408,7 @@ def solve_ipm_pd(
     w = w_base
     mu = mu0 if n_pairs else 0.0
     step_inf = float("inf")
+    fit_inf = float("inf")
     eq_inf = 0.0
     grad_inf = float("inf")
     status = "stalled"
@@ -399,7 +430,7 @@ def solve_ipm_pd(
             and mu <= mu_min
             and feas_inf <= feas_tol
             and bool(np.all(np.abs(c) <= eq_tol_arr))
-            and step_inf <= step_tol
+            and (step_inf <= step_tol or fit_inf <= fit_tol)
         ):
             status = "kkt"
             break
@@ -413,7 +444,7 @@ def solve_ipm_pd(
         w_mat[eq_rows] = rho
         w_mat[mb_rows] += d_k[nb:]
         diag = np.zeros(n)
-        diag[box_idx] = d_k[:nb] + prox
+        diag[box_idx] = d_k[:nb] + max(eq_prox_abs, box_scale * w_median)
         # Stationarity residual of the current point (for reporting).
         y_dual = np.zeros(nb + mb_rows.size)
         y_dual[il] += y_l
@@ -490,7 +521,8 @@ def solve_ipm_pd(
             il=il,
             iu=iu,
         )
-        slope = merit.slope(lin, H @ dx, ds_l, ds_u)
+        hdx = H @ dx
+        slope = merit.slope(lin, hdx, ds_l, ds_u)
         if slope >= 0.0 and n_pairs:
             # The corrector's second-order term can spoil descent; the pure
             # centering direction is a Newton step on the merit and descends
@@ -498,9 +530,11 @@ def solve_ipm_pd(
             dx_c, ds_l_c, ds_u_c, dy_l_c, dy_u_c, dlam_c = lin.direction(
                 target - s_l * y_l, target - s_u * y_u
             )
-            slope_c = merit.slope(lin, H @ dx_c, ds_l_c, ds_u_c)
+            hdx_c = H @ dx_c
+            slope_c = merit.slope(lin, hdx_c, ds_l_c, ds_u_c)
             if slope_c < 0.0 and np.all(np.isfinite(dx_c)):
                 dx, ds_l, ds_u, dy_l, dy_u, dlam = dx_c, ds_l_c, ds_u_c, dy_l_c, dy_u_c, dlam_c
+                hdx = hdx_c
                 slope = slope_c
                 n_centering += 1
 
@@ -521,6 +555,7 @@ def solve_ipm_pd(
             a_p = tr_radius / free_inf
         # The stopping test measures the Newton step, not how far the search cut it.
         step_inf = a_p * free_inf
+        fit_inf = a_p * float(np.max(np.sqrt(w_data) * np.abs(hdx))) if m else 0.0
         a_full = a_p
         r_new = None
         # A direction that does not descend (inconsistent slacks of a nonlinear
@@ -563,6 +598,11 @@ def solve_ipm_pd(
             eq_inf,
             feas_inf,
         )
+        if box_prox_max > box_prox:
+            if a_p < _PROX_SHORT:
+                box_scale = min(box_scale * _PROX_GROW, box_prox_max)
+            elif a_p >= _PROX_LONG:
+                box_scale = max(box_scale / _PROX_GROW, box_prox)
         x = x + a_p * dx
         s_l = s_l + a_p * ds_l
         s_u = s_u + a_p * ds_u

{gridstate-2.4.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → gridstate-2.5.0}/gridstate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.4.0
+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.5.0/gridstate.egg-info/scm_version.json

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

{gridstate-2.4.0 → 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.0 → gridstate-2.5.0}/tests/test_ipm_pd.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from types import SimpleNamespace
+from typing import Any
 
 import numpy as np
 import pytest
@@ -148,6 +149,68 @@ def test_equality_rows_with_a_box_free_common_level() -> None:
         assert out.x[1] - out.x[2] == pytest.approx(0.7, abs=1e-5)
 
 
+def test_pd_adaptive_box_prox_keeps_the_fixed_point(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Every step counts as short, so the box term climbs to its ceiling and stays
+    # there: the iteration is damped, the solution is not. Rows 1-2 see the box
+    # variables (g, l) only through near-zero weights, as a free load does.
+    import gridstate.algorithms.ipm_pd as pd_mod
+
+    A = np.array([[1.0, 0.0, 0.0], [1.0, -1.0, 1.0], [0.0, 0.0, 1.0], [1.0, 0.0, 0.0]])
+    z = np.array([0.7, 0.0, 3.0, 0.75])
+    w = np.array([1.0, 1e-8, 1e-8, 1.0])
+    res, jac = _linear(A, z)
+    kw: dict[str, Any] = {
+        "box_idx": np.array([1, 2]),
+        "box_lo": np.array([-50.0, -50.0]),
+        "box_hi": np.array([50.0, 50.0]),
+        "step_tol": 1e-9,
+        "max_iter": 300,
+    }
+    fixed = solve_ipm_pd(np.zeros(3), res, jac, w, box_prox_max=0.0, **kw)
+    monkeypatch.setattr(pd_mod, "_PROX_SHORT", 2.0)
+    damped = solve_ipm_pd(np.zeros(3), res, jac, w, box_prox_max=1.0, **kw)
+    assert fixed.success and damped.success
+    assert damped.x[0] == pytest.approx(0.725, abs=1e-6)
+    np.testing.assert_allclose(damped.x[0], fixed.x[0], atol=1e-6)
+
+
+def test_pd_adaptive_box_prox_is_inactive_on_long_steps() -> None:
+    # A well-scaled problem takes long steps: the ceiling never comes into play.
+    rng = np.random.default_rng(4)
+    A = rng.normal(size=(8, 3))
+    z = rng.normal(size=8)
+    res, jac = _linear(A, z)
+    kw: dict[str, Any] = {
+        "box_idx": np.array([2]),
+        "box_lo": np.array([-5.0]),
+        "box_hi": np.array([5.0]),
+    }
+    base = solve_ipm_pd(np.zeros(3), res, jac, np.ones(8), box_prox_max=0.0, **kw)
+    adaptive = solve_ipm_pd(np.zeros(3), res, jac, np.ones(8), **kw)
+    assert base.iterations_outer == adaptive.iterations_outer
+    np.testing.assert_array_equal(base.x, adaptive.x)
+
+
+def test_pd_fit_tol_stops_once_the_estimates_settle() -> None:
+    # x1 enters only a row of negligible weight: once the measured x0 has
+    # settled, the remaining steps move x1 alone and no estimate noticeably.
+    z = np.array([1.0, 1.2, 3.0])
+    w = np.array([1.0, 1.0, 1e-12])
+
+    def residual_fn(x: np.ndarray) -> np.ndarray:
+        return z - np.array([x[0], x[0], np.sinh(x[1])])
+
+    def jacobian_fn(x: np.ndarray) -> csr_matrix:
+        return csr_matrix(np.array([[1.0, 0.0], [1.0, 0.0], [0.0, np.cosh(x[1])]]))
+
+    kw: dict[str, Any] = {"step_tol": 1e-12, "max_iter": 60}
+    by_fit = solve_ipm_pd(np.zeros(2), residual_fn, jacobian_fn, w, **kw)
+    by_step = solve_ipm_pd(np.zeros(2), residual_fn, jacobian_fn, w, fit_tol=0.0, **kw)
+    assert by_fit.success and by_step.success
+    assert by_fit.iterations_outer < by_step.iterations_outer
+    assert by_fit.x[0] == pytest.approx(1.1, abs=1e-9)
+
+
 def test_pd_merit_search_stops_gauss_newton_overshoot() -> None:
     # h = atan(x), z = 0 from x0 = 1.5: the Gauss-Newton step −(1 + x²)·atan(x)
     # overshoots and the full-step iteration diverges; the merit search does not.
@@ -157,7 +220,9 @@ def test_pd_merit_search_stops_gauss_newton_overshoot() -> None:
     def jacobian_fn(x: np.ndarray) -> csr_matrix:
         return csr_matrix(np.array([[1.0 / (1.0 + x[0] ** 2)]]))
 
-    kw = {"tr_radius": 1e6, "step_tol": 1e-10, "max_iter": 50}
+    # fit_tol off: far out on the plateau of atan a diverging step barely moves
+    # the estimate, and this test is about the search, not the stopping rule.
+    kw = {"tr_radius": 1e6, "step_tol": 1e-10, "fit_tol": 0.0, "max_iter": 50}
     no_search = solve_ipm_pd(
         np.array([1.5]), residual_fn, jacobian_fn, np.ones(1), armijo_max=0, **kw
     )

{gridstate-2.4.0 → 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.0/gridstate.egg-info/scm_version.json

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