gridstate 2.5.0__tar.gz → 2.6.0__tar.gz

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

@@ -9,6 +9,24 @@ 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.6.0 (2026-10-18)
+
+### Behavior changes
+
+- `ipm_pd` gets the 300-iteration budget with equality rows too (it was 100
+  before the primal fallback), including the global `ipm_balance_mode="hard"`:
+  with the adaptive box damping and the measurement-space stopping test of
+  v2.4.1 the long budget converges where the short one fell back.
+
+### Feat
+
+- `ipm_transit_balance_mode` (new, default `soft`): `hard` makes the P and Q
+  balance rows of transit nodes (no `exist_gen` / `exist_load`) equality
+  constraints of the solver, to `ipm_transit_balance_tol_p_mw` (new, default
+  0.01) / `ipm_transit_balance_tol_q_mvar` (new, default 0.1); the other
+  balance rows stay soft. The global hard balance overrides it. `IPMSetup`
+  gains `eq_rows` / `eq_tol`.
+
 ## v2.5.0 (2026-10-18)
 
 ### Behavior changes

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

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

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

{gridstate-2.5.0 → gridstate-2.6.0}/gridstate/api.py

@@ -826,7 +826,7 @@ def _run_ipm(
         delta, v, _pg, _qg, _pn, _qn = unpack_full(x, layout_ipm)
         return algebra.evaluate_jacobian(v, delta)
 
-    eq_idx = setup.balance_rows if setup.balance_tol is not None else None
+    eq_idx = setup.eq_rows
     pd_result: IPMResult | None = None
     if solver == "ipm_pd":
         mb_rows = mb_lo = mb_hi = None
@@ -852,13 +852,12 @@ def _run_ipm(
             meas_box_lo=mb_lo,
             meas_box_hi=mb_hi,
             eq_idx=eq_idx,
-            eq_tol=setup.balance_tol,
+            eq_tol=setup.eq_tol,
             mu_init=1.0,
             step_tol=max(tolerance, 1e-4),
             # Weakly determined units need up to ~260 iterations with separate
-            # injection parts; a hard balance does not converge in that budget
-            # either way, so it keeps the short one before the fallback.
-            max_iter=max(max_iterations, 100 if eq_idx is not None else 300),
+            # injection parts, with or without equality rows.
+            max_iter=max(max_iterations, 300),
             tr_radius=0.5,
             huber_c=huber_c,
             huber_mask=huber_mask,
@@ -910,7 +909,7 @@ def _run_ipm(
             huber_adaptive_k=2.0,
             kkt_solver=kkt,
             eq_idx=eq_idx,
-            eq_tol=setup.balance_tol,
+            eq_tol=setup.eq_tol,
         )
         if solver == "ipm_pd":
             result.message = f"ipm_pd fallback to ipm ({pd_message}): {result.message}"

{gridstate-2.5.0 → gridstate-2.6.0}/gridstate/ipm_hints.py

@@ -219,7 +219,7 @@ def ipm_convergence_hints(
             meas_index=setup.meas_index,
             network_pu=network_pu,
             # Equality rows: their σ is a penalty, not a measurement error.
-            skip=setup.balance_rows if setup.balance_tol is not None else None,
+            skip=setup.eq_rows,
             part_rows=setup.role_rows,
             top=top,
         )

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

@@ -610,6 +610,38 @@ class PipelineConfig:
         "median(σ²_data) / factor. Their injection is known to be zero; a loose balance "
         "turns data conflicts into a fictitious injection. 0 — off.",
     )
+    ipm_transit_balance_mode: str = _param(
+        "soft",
+        group=_G_IPM,
+        label="Balance mode of transit nodes",
+        control="select",
+        choices=["soft", "hard"],
+        depends={"algorithm": "ipm"},
+        help="soft — the balance of a transit node (no exist_gen/exist_load) is a "
+        "weighted row like the others (ipm_transit_balance_weight_factor); hard — an "
+        "equality constraint to ipm_transit_balance_tol_p_mw / _q_mvar, the other "
+        "balance rows stay soft. No effect when ipm_balance_mode=hard.",
+    )
+    ipm_transit_balance_tol_p_mw: float = _param(
+        0.01,
+        group=_G_IPM,
+        label="Transit balance tolerance P, MW",
+        control="number",
+        min=1e-6,
+        max=1e3,
+        depends={"ipm_transit_balance_mode": "hard"},
+        help="Admissible |P injection| of a transit node under the hard transit balance.",
+    )
+    ipm_transit_balance_tol_q_mvar: float = _param(
+        0.1,
+        group=_G_IPM,
+        label="Transit balance tolerance Q, MVAr",
+        control="number",
+        min=1e-6,
+        max=1e3,
+        depends={"ipm_transit_balance_mode": "hard"},
+        help="Admissible |Q injection| of a transit node under the hard transit balance.",
+    )
     ipm_prior_sigma2_bus_equiv_pu: float = _param(
         0.01,
         group=_G_IPM,

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

@@ -52,6 +52,9 @@ def _ipm_kwargs(cfg: PipelineConfig) -> dict:
         "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,
+        "transit_balance_mode": cfg.ipm_transit_balance_mode,
+        "transit_balance_tol_p_mw": cfg.ipm_transit_balance_tol_p_mw,
+        "transit_balance_tol_q_mvar": cfg.ipm_transit_balance_tol_q_mvar,
         "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.5.0 → gridstate-2.6.0}/gridstate/preprocessing/ipm_setup.py

@@ -282,6 +282,11 @@ class IPMSetup:
     # ``balance_tol`` holds the admissible |imbalance| per balance row in p.u.
     # ``None`` in the soft mode.
     balance_tol: np.ndarray | None = None
+    # Rows the solver enforces as equalities and their admissible |c| (p.u.):
+    # every balance row in the hard mode, the transit balance rows with
+    # ``transit_balance_mode="hard"``; ``None`` — no equality rows.
+    eq_rows: np.ndarray | None = None
+    eq_tol: np.ndarray | None = None
     # ``injection_roles``: rows of ``z`` that measure a box variable directly
     # (a generation / load part of a node injection) and their measurement ids;
     # ``role_dropped_ids`` — part rows folded back into a net injection row.
@@ -556,6 +561,9 @@ def build_ipm_setup(
     hard_balance_rho_factor: float = 1e3,
     balance_tol_p_mw: float = 1.0,
     balance_tol_q_mvar: float = 10.0,
+    transit_balance_mode: str = "soft",
+    transit_balance_tol_p_mw: float = 0.01,
+    transit_balance_tol_q_mvar: float = 0.1,
     fixed_injection_from_input: bool = False,
     injection_roles: bool = False,
     measurements: _ArrayCollection | None = None,
@@ -628,6 +636,14 @@ def build_ipm_setup(
         hard_balance_rho_factor: see ``balance_mode``.
         balance_tol_p_mw, balance_tol_q_mvar: admissible |imbalance| of a hard
             P / Q balance row (MW / MVAr).
+        transit_balance_mode: ``"soft"`` (default) — the balance rows of transit
+            nodes (no ``exist_gen`` / ``exist_load``) are weighted like the
+            others (see ``transit_balance_weight_factor``); ``"hard"`` — they are
+            equality constraints with the penalty of ``balance_mode="hard"``,
+            the other balance rows stay soft. Ignored when ``balance_mode`` is
+            already ``"hard"``.
+        transit_balance_tol_p_mw, transit_balance_tol_q_mvar: admissible
+            |injection| of a transit node in the hard transit mode (MW / MVAr).
         fixed_injection_from_input: the balance row of a node carries the
             input injection of its parts without a box variable (no
             ``exist_gen`` / ``exist_load``) as a fixed term instead of zero.
@@ -732,6 +748,11 @@ def build_ipm_setup(
     if balance_mode not in ("soft", "hard"):
         raise ValueError(f"balance_mode={balance_mode!r} is not one of ['soft', 'hard']")
     hard = balance_mode == "hard"
+    if transit_balance_mode not in ("soft", "hard"):
+        raise ValueError(
+            f"transit_balance_mode={transit_balance_mode!r} is not one of ['soft', 'hard']"
+        )
+    transit_hard = transit_balance_mode == "hard" and not hard and n_balance > 0
 
     # ---- Prior measurements: z=0, individual σ². Only for box-vars with σ²>0 ----
     pgen_prior_arr = np.asarray(pgen_sec.prior_s2, dtype=np.float64)
@@ -816,6 +837,12 @@ def build_ipm_setup(
             for start in (n_old, n_old + n_balance):
                 rows = sigma2_new[start : start + n_balance]
                 rows[transit] = np.minimum(rows[transit], transit_s2)
+    transit_eq = np.zeros(0, dtype=np.int64)
+    if transit_hard:
+        transit = _transit_mask(nodes_arr, active_ids)
+        pos = np.flatnonzero(transit)
+        transit_eq = np.concatenate([n_old + pos, n_old + n_balance + pos]).astype(np.int64)
+        sigma2_new[transit_eq] = _adaptive_balance_sigma2(sigma2_old, hard_balance_rho_factor)
     if n_prior > 0:
         prior_sigmas = np.concatenate(
             [
@@ -893,6 +920,31 @@ def build_ipm_setup(
         meas_id=new_meas_id,
     )
 
+    balance_tol = (
+        np.concatenate(
+            [
+                np.full(n_balance, balance_tol_p_mw / BASE_MVA),
+                np.full(n_balance, balance_tol_q_mvar / BASE_MVA),
+            ]
+        )
+        if hard
+        else None
+    )
+    eq_rows: np.ndarray | None = None
+    eq_tol: np.ndarray | None = None
+    if hard:
+        eq_rows = np.arange(n_old, n_old + 2 * n_balance, dtype=np.int64)
+        eq_tol = balance_tol
+    elif transit_eq.size:
+        n_t = transit_eq.size // 2
+        eq_rows = transit_eq
+        eq_tol = np.concatenate(
+            [
+                np.full(n_t, transit_balance_tol_p_mw / BASE_MVA),
+                np.full(n_t, transit_balance_tol_q_mvar / BASE_MVA),
+            ]
+        )
+
     return IPMSetup(
         layout=layout,
         box_idx_in_state=box_idx_arr,
@@ -907,16 +959,9 @@ def build_ipm_setup(
         meas_index=meas_index_aug,
         balance_start=n_old,
         n_balance=n_balance,
-        balance_tol=(
-            np.concatenate(
-                [
-                    np.full(n_balance, balance_tol_p_mw / BASE_MVA),
-                    np.full(n_balance, balance_tol_q_mvar / BASE_MVA),
-                ]
-            )
-            if hard
-            else None
-        ),
+        balance_tol=balance_tol,
+        eq_rows=eq_rows,
+        eq_tol=eq_tol,
         role_rows=np.arange(role_start, n_new, dtype=np.int64),
         role_meas_ids=role_ids.astype(np.int64),
         role_dropped_ids=np.asarray(

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

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

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

{gridstate-2.5.0 → gridstate-2.6.0}/tests/test_ipm_balance_modes.py

@@ -75,6 +75,52 @@ def test_unknown_balance_mode_is_rejected():
         _setup(_build_net_with_transit(), balance_mode="strict")
 
 
+def test_transit_hard_mode_makes_only_transit_rows_equalities():
+    # Node order 1..4: node 2 is the transit node.
+    setup = _setup(
+        _build_net_with_transit(),
+        transit_balance_mode="hard",
+        transit_balance_tol_p_mw=0.02,
+        transit_balance_tol_q_mvar=0.2,
+        hard_balance_rho_factor=1e3,
+    )
+    assert setup.balance_tol is None
+    assert setup.eq_rows is not None and setup.eq_tol is not None
+    np.testing.assert_array_equal(setup.eq_rows, [2 + 1, 2 + N_BALANCE + 1])
+    np.testing.assert_allclose(setup.eq_tol, [0.02 / BASE_MVA, 0.2 / BASE_MVA])
+    sigma2 = setup.r_matrix.diagonal()[2 : 2 + 2 * N_BALANCE]
+    soft = _setup(_build_net_with_transit()).r_matrix.diagonal()[2 : 2 + 2 * N_BALANCE]
+    is_eq = np.zeros(2 * N_BALANCE, dtype=bool)
+    is_eq[[1, N_BALANCE + 1]] = True
+    assert np.allclose(sigma2[is_eq], 2.5e-4 / 1e3)
+    np.testing.assert_array_equal(sigma2[~is_eq], soft[~is_eq])
+
+
+def test_soft_modes_have_no_equality_rows():
+    setup = _setup(_build_net_with_transit(), transit_balance_weight_factor=10.0)
+    assert setup.eq_rows is None and setup.eq_tol is None
+
+
+def test_global_hard_mode_overrides_the_transit_mode():
+    setup = _setup(
+        _build_net_with_transit(),
+        balance_mode="hard",
+        balance_tol_p_mw=2.0,
+        transit_balance_mode="hard",
+        transit_balance_tol_p_mw=0.02,
+    )
+    assert setup.eq_rows is not None and setup.eq_tol is not None
+    np.testing.assert_array_equal(setup.eq_rows, setup.balance_rows)
+    np.testing.assert_array_equal(setup.eq_tol, setup.balance_tol)
+
+
+def test_unknown_transit_balance_mode_is_rejected():
+    with pytest.raises(ValueError, match="transit_balance_mode"):
+        _setup(_build_net_with_transit(), transit_balance_mode="strict")
+    with pytest.raises(ValueError, match="ipm_transit_balance_mode"):
+        PipelineConfig(algorithm="ipm_pd", ipm_transit_balance_mode="strict")
+
+
 def test_fixed_injection_from_input():
     m = _build_net_with_transit()
     # Transit node 2 gets a non-estimated load and generation.
@@ -131,6 +177,26 @@ def test_hard_balance_closes_the_estimated_imbalance(algorithm: str):
     assert imb_p <= 0.1 and imb_q <= 0.1
 
 
+@pytest.mark.parametrize("algorithm", ["ipm", "ipm_pd"])
+def test_transit_hard_balance_zeroes_the_transit_injection(algorithm: str):
+    # Soft, the transit node 2 absorbs the data conflict (≈ 4 MW / 14 MVAr).
+    soft = _build_net_with_transit()
+    estimate(soft, algorithm=algorithm, reconcile_balance=False, include_quality_summary=False)
+    n_soft = soft.nodes.to_numpy()
+    assert abs(n_soft["p_inj_calc"][1]) > 1.0 and abs(n_soft["q_inj_calc"][1]) > 1.0
+    m = _build_net_with_transit()
+    res = estimate(
+        m,
+        algorithm=algorithm,
+        reconcile_balance=False,
+        include_quality_summary=False,
+        transit_balance_mode="hard",
+    )
+    assert res.success
+    n = m.nodes.to_numpy()
+    assert abs(n["p_inj_calc"][1]) <= 0.01 and abs(n["q_inj_calc"][1]) <= 0.1
+
+
 def test_ipm_pd_close_to_ipm():
     results = {}
     for algorithm in ("ipm", "ipm_pd"):
@@ -170,6 +236,7 @@ def test_measurement_bounds_require_ipm_pd():
 def test_config_defaults_and_ranges():
     cfg = PipelineConfig(algorithm="ipm_pd")
     assert cfg.ipm_balance_mode == "soft"
+    assert cfg.ipm_transit_balance_mode == "soft"
     assert not cfg.ipm_measurement_bounds and not cfg.ipm_fixed_injection_from_input
     # The soft balance weight may now exceed the median measurement weight tenfold.
     dataclasses.replace(cfg, ipm_balance_weight_factor=1e3)