gridstate 2.1.0__tar.gz → 2.3.0__tar.gz

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

@@ -9,6 +9,69 @@ 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.3.0 (2026-10-17)
+
+### Behavior changes
+
+- `ipm_pd` uses a fixed Huber threshold `c_eff = huber_c` by default
+  (`ipm_huber_threshold="fixed"`). The previous per-iteration adaptive raise
+  made the estimate depend on the solver path; `"adaptive"` restores it. On
+  regional models the quality is unchanged; `ipm_pd` estimates move slightly
+  (≤ 6e-5 p.u. V on the test models). `wls` / `ipm` are unaffected (#111)
+- `ipm_pd` selects its step by Armijo backtracking on a merit function
+  (barrier objective, augmented Lagrangian of the equality rows, slack
+  penalty). It now converges on weakly determined cases (e.g. unmeasured
+  units with a wide box under `injection_roles`) that needed the primal
+  fallback; `ipm_pd` estimates can move slightly. The pipeline's `ipm_pd`
+  iteration limit is 300 (100 under a hard balance); the solve stops after
+  `max_search_failures` iterations without merit decrease (#106)
+
+### Feat
+
+- Convergence hints: a solve that does not converge, falls back from
+  `ipm_pd`, or takes more than `ipm_hint_iterations` iterations with a
+  dominant step limiter logs a WARNING naming the limiting nodes / variables
+  (with a suggestion), loose unmeasured box variables, the largest normalized
+  residuals and part measurements outside their range. `IPMResult` gains
+  `step_limiters` / `limiting_rows` (#110)
+
+## v2.2.0 (2026-10-17)
+
+All new behaviour is opt-in; with the defaults the results are unchanged.
+
+### Feat
+
+- `algorithm="ipm_pd"`: Mehrotra predictor-corrector interior-point solver;
+  predictor and corrector share one factorization per iteration
+  (`KKTSolver.factor_normal`). About 5× less solver time than `ipm` on large
+  models, with closely matching estimates. A solve that does not reach its
+  KKT test is redone by the primal IPM from the same start (#103)
+- `balance_mode="hard"` (`ipm_balance_mode`): node balance rows become
+  equality constraints in both IPM solvers (method of multipliers,
+  quasi-definite step) with P / Q tolerances `balance_tol_p_mw` /
+  `balance_tol_q_mvar`. Experimental: it does not converge on every real
+  model yet (#103)
+- `fixed_injection_from_input` (`ipm_fixed_injection_from_input`): the input
+  injection of node parts without a box variable enters the balance as a
+  fixed term. Experimental (#103)
+- `measurement_bounds` (`ipm_measurement_bounds`, `ipm_pd` only):
+  `min_value` / `max_value` bound the estimated value of any measurement as
+  an inequality (#103)
+- `injection_roles` (`ipm_injection_roles`, `ipm` / `ipm_pd`): node injection
+  rows tagged `source_code` `"inj_gen"` / `"inj_load"`
+  (`SOURCE_INJ_GEN` / `SOURCE_INJ_LOAD`) measure the generation / load box
+  variable directly; the node box is narrowed by the measurement box, the
+  unmeasured part of a measured node gets a prior, and the net row stays only
+  where a measured part has no box variable. The telemetry kernel emits the
+  part rows when the mode is on; `release_load_only_injections` and
+  `widen_generation_only_injections` are skipped in it (#103)
+- `DerivedInputs.telemetry_bounds` (derived table `telemetry_bounds`):
+  optional plausible ranges of telemetry values, written by the telemetry
+  kernel into `min_value` / `max_value` (summed over components for
+  injection rows, generation minus load for the net row). Data contract
+  3.1.0, additive (#103)
+- `ipm_balance_weight_factor` accepts values up to 1e6 (was 10) (#103)
+
 ## v2.1.0 (2026-10-14)
 
 ### Feat

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

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

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

{gridstate-2.1.0 → gridstate-2.3.0}/gridstate/algorithms/ipm.py

@@ -33,6 +33,12 @@ changing the sparse structure. The step is limited to ``α_max·(1−ε)`` so th
 
 Sanity property: with ``box_idx=[]`` the IPM is equivalent to Gauss-Newton WLS
 (the barrier is zero, the outer loop makes a single pass).
+
+Equality rows (``eq_idx``, e.g. hard nodal balance) are handled by the method
+of multipliers: such a row ``c = h − z = −r`` enters Φ as
+``½ρ (r − λ/ρ)²`` (``ρ`` — its ``r_inv_diag`` entry, ``λ`` — its multiplier),
+and after every outer step ``λ ← λ + ρ·c``. At the fixed point ``c = 0``
+exactly, whatever ``ρ``; the Newton systems stay the normal equations.
 """
 
 from __future__ import annotations
@@ -40,7 +46,7 @@ from __future__ import annotations
 import logging
 import math
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 import numpy as np
 from scipy.sparse import csr_matrix
@@ -98,6 +104,28 @@ class IPMResult:
     message: str = ""
     status: str = "error"
     solve_status: SolveStatus = SolveStatus.ERROR
+    # max |c| over the equality rows at the final point (p.u.); nan without them.
+    eq_inf_final: float = float("nan")
+    # Diagnostics of slow solves (see :mod:`gridstate.ipm_hints`): state index →
+    # number of iterations whose step that coordinate limited (it set the
+    # trust-region clip or the boundary rule, or dominated a step the line
+    # search cut).
+    step_limiters: dict[int, int] = field(default_factory=dict)
+    # ipm_pd only: measurement-box row → iterations whose step its bound limited.
+    limiting_rows: dict[int, int] = field(default_factory=dict)
+
+
+def _count(counts: dict[int, int], key: int) -> None:
+    counts[key] = counts.get(key, 0) + 1
+
+
+def _blocking(cur: np.ndarray, step: np.ndarray, lo: np.ndarray, hi: np.ndarray) -> int:
+    """Position of the coordinate that first reaches its bound along ``step`` (−1: none)."""
+    with np.errstate(divide="ignore", invalid="ignore"):
+        ratio = np.where(step < 0, (lo - cur) / step, np.where(step > 0, (hi - cur) / step, np.inf))
+    ratio = np.where(ratio > 0, ratio, np.inf)
+    k = int(np.argmin(ratio)) if ratio.size else -1
+    return k if k >= 0 and np.isfinite(ratio[k]) else -1
 
 
 def _project_to_interior(
@@ -269,6 +297,10 @@ def solve_ipm(
     huber_adaptive_k: float = 6.0,
     huber_warmup_iters: int = 5,
     kkt_solver: KKTSolver | None = None,
+    eq_idx: np.ndarray | None = None,
+    eq_tol: np.ndarray | None = None,
+    eq_extra_outer: int = 10,
+    eq_prox: float = 1e-9,
 ) -> IPMResult:
     """Primal log-barrier IPM for box-constrained WLS.
 
@@ -331,6 +363,17 @@ def solve_ipm(
             symbolic factorization between iterations (see
             ``gridstate.algorithms.kkt_solver``). ``None`` — scipy spsolve
             (the former behaviour, bit for bit).
+        eq_idx: rows of ``r`` that are equality constraints ``h = z`` (method of
+            multipliers, see the module docstring). ``None`` — none.
+        eq_tol: admissible ``|c|`` per row of ``eq_idx`` (p.u.). Once the μ
+            schedule is done, up to ``eq_extra_outer`` further outer steps at
+            ``μ_min`` update the multipliers until every row is within it.
+        eq_prox: with equality rows, a proximal term ``eq_prox·max(ρ)`` added to
+            the diagonal of the box coordinates of the Newton matrix. Equalities
+            on the net injection leave the common level of a node's generation
+            and load to the weak barrier curvature, which makes the matrix
+            numerically singular; the term shortens such steps only and does not
+            move the stationary point.
 
     Returns:
         ``IPMResult``.
@@ -354,6 +397,23 @@ def solve_ipm(
             raise ValueError("box_lo/box_hi contain pairs with lo >= hi")
 
     has_box = box_idx.size > 0
+    eq_rows = np.asarray(eq_idx, dtype=np.int64) if eq_idx is not None else None
+    has_eq = eq_rows is not None and eq_rows.size > 0
+    if has_eq:
+        assert eq_rows is not None
+        if eq_tol is None or np.shape(eq_tol) != eq_rows.shape:
+            raise ValueError("eq_tol must give one tolerance per row of eq_idx")
+        eq_tol_arr = np.asarray(eq_tol, dtype=np.float64)
+        # Target shift λ/ρ of the equality rows; residuals below are r − shift.
+        eq_shift = np.zeros(eq_rows.size, dtype=np.float64)
+        raw_residual_fn = residual_fn
+        eq_prox_diag = np.zeros(x_init.shape[0], dtype=np.float64)
+        eq_prox_diag[box_idx] = eq_prox * float(np.max(r_inv_diag[eq_rows]))
+
+        def residual_fn(x: np.ndarray) -> np.ndarray:
+            r_eff: np.ndarray = np.array(raw_residual_fn(x), dtype=np.float64)
+            r_eff[eq_rows] -= eq_shift
+            return r_eff
 
     solver = kkt_solver if kkt_solver is not None else KKTSolver("scipy")
 
@@ -399,6 +459,8 @@ def solve_ipm(
         mu = 0.0
 
     outer_iter = 0
+    eq_extra = 0
+    eq_inf = float("nan")
     schedule_done = False
     # Termination status only (never fed back into the iteration).
     outer_exhausted = False
@@ -408,6 +470,15 @@ def solve_ipm(
     # it, so the next iteration (and the final objective) reuse it instead of
     # calling residual_fn again at the same point.
     r_at_x: np.ndarray | None = None
+    limiters: dict[int, int] = {}
+    tr_pos = np.flatnonzero(tr_mask) if tr_mask is not None else None
+
+    def _dominant(step: np.ndarray) -> int:
+        """State index of the largest step component inside the trust region."""
+        if tr_pos is None:
+            return int(np.argmax(np.abs(step)))
+        return int(tr_pos[np.argmax(np.abs(step[tr_pos]))]) if tr_pos.size else 0
+
     for outer_iter in range(outer_max):
         any_inner_step = False  # Lazy outer: if no step was made → break.
         # inner exited by tolerance (grad/step < inner_tol) — a stationary
@@ -442,6 +513,8 @@ def solve_ipm(
             grad_data = -np.asarray(HtRinv @ r, dtype=np.float64).ravel()
 
             grad_b, hess_b = _barrier_grad_hess(x, box_idx, box_lo, box_hi, mu)
+            if has_eq:
+                hess_b = hess_b + eq_prox_diag
             grad = grad_data + grad_b
             grad_inf = float(np.max(np.abs(grad))) if grad.size else 0.0
 
@@ -492,6 +565,7 @@ def solve_ipm(
                 step_inf_raw = float(np.max(np.abs(dx_tr))) if dx_tr.size else 0.0
             if step_inf_raw > tr_radius:
                 dx = dx * (tr_radius / step_inf_raw)
+                _count(limiters, _dominant(dx))
             step_inf = float(np.max(np.abs(dx))) if dx.size else 0.0
             if step_inf < inner_tol:
                 inner_converged = True
@@ -507,6 +581,11 @@ def solve_ipm(
                 fraction_to_boundary,
             )
             alpha = min(alpha_max, 1.0) if math.isfinite(alpha_max) else 1.0
+            if alpha < 1.0:
+                k = _blocking(x[box_idx], dx[box_idx], box_lo, box_hi)
+                if k >= 0:
+                    _count(limiters, int(box_idx[k]))
+            alpha_first = alpha
 
             phi_cur = 0.5 * float(r @ (R_inv @ r)) + _barrier_value(
                 x,
@@ -540,6 +619,8 @@ def solve_ipm(
                     break
 
             iter_inner_total += 1
+            if not accepted or alpha < alpha_first:
+                _count(limiters, _dominant(dx))
             if not accepted:
                 inner_stalled = True
                 # No admissible step found — the outer loop will increase μ and try again.
@@ -552,6 +633,24 @@ def solve_ipm(
             r_at_x = r_accepted
             any_inner_step = True
 
+        if has_eq:
+            assert eq_rows is not None and r_at_x is not None
+            # Constraint value c = −r_raw = −(r_eff + shift); λ/ρ ← λ/ρ + c.
+            raw_eq = r_at_x[eq_rows] + eq_shift
+            eq_inf = float(np.max(np.abs(raw_eq)))
+            eq_ok = bool(np.all(np.abs(raw_eq) <= eq_tol_arr))
+            if (mu <= mu_min or not has_box) and (eq_ok or eq_extra >= eq_extra_outer):
+                schedule_done = True
+                break
+            if not any_inner_step and not inner_converged:
+                break  # stuck: the multiplier update would not move x either
+            eq_shift = eq_shift - raw_eq
+            r_at_x = r_at_x.copy()
+            r_at_x[eq_rows] = raw_eq - eq_shift
+            if mu <= mu_min or not has_box:
+                eq_extra += 1
+                continue
+
         if not has_box:
             break  # WLS mode: a single outer pass.
 
@@ -575,6 +674,11 @@ def solve_ipm(
 
     # Final residual/objective
     r_final = r_at_x if r_at_x is not None else residual_fn(x)
+    if has_eq:
+        assert eq_rows is not None
+        r_final = r_final.copy()
+        r_final[eq_rows] += eq_shift  # report the true residual of the equality rows
+        eq_inf = float(np.max(np.abs(r_final[eq_rows])))
     obj_data = 0.5 * float(r_final @ (R_inv @ r_final))
 
     kkt = grad_inf < max(1e-2, inner_tol * 100)
@@ -596,6 +700,8 @@ def solve_ipm(
             f"outer={outer_iter + 1}, inner_total={iter_inner_total}, "
             f"μ_final={mu:.2e}, |grad|∞={grad_inf:.2e}"
         )
+        if has_eq:
+            detail += f", |c_eq|∞={eq_inf:.2e}"
         if status == "kkt":
             message = f"converged (kkt): {detail}"
         elif status == "completed":
@@ -614,6 +720,8 @@ def solve_ipm(
         message=message,
         status=status,
         solve_status=solve_status,
+        eq_inf_final=eq_inf,
+        step_limiters=limiters,
     )