gridstate 2.2.0__tar.gz → 2.4.0__tar.gz

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

@@ -9,6 +9,53 @@ 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.4.0 (2026-10-17)
+
+### Behavior changes
+
+- Breaker branches marked by the input format (R = 0, X = 1 Ohm) get
+  X = 110·min_x·Vn Ohm with min_x = 4e-6 (≈ 0.044/Vn p.u.) instead of a fixed
+  1e-3 p.u.; `breaker_x_pu` (new) sets a fixed p.u. value instead. Estimates
+  move on models carrying the marker (≤ 4.5e-3 p.u. V with `ipm_pd` on the
+  test models) (#115)
+- A solved state with V/Vnom below `implausible_v_ratio` (new, default 0.3)
+  at any node is marked not converged whatever the solver reports, with a
+  WARNING listing the nodes and hints; a non-converged WLS solve logs its
+  largest normalized residuals (#114, #115)
+
+### Feat
+
+- Piecewise static load characteristics: optional input table
+  `load_characteristic_segments` (contract 3.2.0) with per-segment
+  coefficients up to V⁴ for P and Q; `apply_load_characteristic` uses it in
+  place of the quadratic row; without the table nothing changes (#113, #115)
+
+## 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.2.0
+Version: 2.4.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.2.0 → gridstate-2.4.0}/gridstate/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.2.0'
-__version_tuple__ = version_tuple = (2, 2, 0)
+__version__ = version = '2.4.0'
+__version_tuple__ = version_tuple = (2, 4, 0)
 
-__commit_id__ = commit_id = 'g06a6dcf24'
+__commit_id__ = commit_id = 'g81767e831'

{gridstate-2.2.0 → gridstate-2.4.0}/gridstate/algorithms/ipm.py

@@ -46,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
@@ -106,6 +106,26 @@ class IPMResult:
     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(
@@ -450,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
@@ -536,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
@@ -551,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,
@@ -584,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.
@@ -684,6 +721,7 @@ def solve_ipm(
         status=status,
         solve_status=solve_status,
         eq_inf_final=eq_inf,
+        step_limiters=limiters,
     )
 
 

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

@@ -33,6 +33,22 @@ Iteration (one factorization, two solves)::
     σ      = clamp((μ_aff/μ)³, σ_min, 1)
     corrector:          target σμ − Δs_aff·Δy_aff, same factor → Δ
     αp, αd = separate fraction-to-boundary steps (τ = 0.99995) for (x, s) and (λ, y)
+    αp     ← Armijo backtracking on the merit φ (below)
+
+Step selection. The fraction-to-boundary rule alone lets the iteration cycle
+on weakly determined directions (e.g. an unmeasured unit with a wide box):
+long steps along them change neither the state estimate nor the residuals by
+much, yet they never settle. The primal step is therefore backtracked on the
+merit of the iteration (weights, ``λ`` and the target ``σμ`` fixed)::
+
+    φ(x, s) = ½ Σ w r² + λᵀc + ½ Σ ρ c² − σμ Σ log s + ν (‖g − l − s_l‖₁ + ‖u − g − s_u‖₁)
+
+with ``ν ≥ 2·max y`` kept non-decreasing. At consistent slacks the pure
+centering direction (target ``σμ − s·y``) is the Newton step on ``φ`` with the
+positive definite primal-dual Hessian, hence a descent direction; the
+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.
 
 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
@@ -42,6 +58,7 @@ distance for a one-sided one), ``y = μ0/s``; the initial point need not satisfy
 from __future__ import annotations
 
 import logging
+import math
 from collections.abc import Callable
 from dataclasses import dataclass
 
@@ -49,7 +66,7 @@ import numpy as np
 from scipy.sparse import csr_matrix
 
 from gridstate.algebra.estimators import HuberReweighter
-from gridstate.algorithms.ipm import IPMResult, _project_to_interior
+from gridstate.algorithms.ipm import IPMResult, _count, _project_to_interior
 from gridstate.algorithms.kkt_solver import KKTSolver
 from gridstate.algorithms.status import SolveStatus
 
@@ -65,6 +82,20 @@ def _max_step(v: np.ndarray, dv: np.ndarray) -> float:
     return min(1.0, float(np.min(-v[neg] / dv[neg])))
 
 
+def _blocking_constraint(
+    s_l: np.ndarray, ds_l: np.ndarray, s_u: np.ndarray, ds_u: np.ndarray
+) -> tuple[int, bool]:
+    """Position (in ``il`` or ``iu``) of the slack that first reaches zero, and whether it is lower."""
+    with np.errstate(divide="ignore"):
+        rl = np.where(ds_l < 0, -s_l / ds_l, np.inf)
+        ru = np.where(ds_u < 0, -s_u / ds_u, np.inf)
+    kl = int(np.argmin(rl)) if rl.size else -1
+    ku = int(np.argmin(ru)) if ru.size else -1
+    if ku < 0 or (kl >= 0 and rl[kl] <= ru[ku]):
+        return kl, True
+    return ku, False
+
+
 Direction = tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]
 
 
@@ -120,6 +151,44 @@ class _Linearization:
         return dx, ds_l, ds_u, dy_l, dy_u, dlam
 
 
+@dataclass
+class _Merit:
+    """The merit ``φ`` of one iteration (see the module docstring); ``mu`` is the target ``σμ``."""
+
+    w_data: np.ndarray
+    lam: np.ndarray
+    rho: np.ndarray
+    eq_rows: np.ndarray
+    mu: float
+    nu: float
+    lo_l: np.ndarray
+    hi_u: np.ndarray
+    il: np.ndarray
+    iu: np.ndarray
+
+    def value(self, r: np.ndarray, g: np.ndarray, s_l: np.ndarray, s_u: np.ndarray) -> float:
+        c = -r[self.eq_rows]
+        phi = 0.5 * float(r @ (self.w_data * r)) + float(self.lam @ c)
+        phi += 0.5 * float(c @ (self.rho * c))
+        if self.mu > 0.0:
+            phi -= self.mu * (float(np.sum(np.log(s_l))) + float(np.sum(np.log(s_u))))
+        phi += self.nu * (
+            float(np.sum(np.abs(g[self.il] - self.lo_l - s_l)))
+            + float(np.sum(np.abs(self.hi_u - g[self.iu] - s_u)))
+        )
+        return phi
+
+    def slope(
+        self, lin: _Linearization, hdx: np.ndarray, ds_l: np.ndarray, ds_u: np.ndarray
+    ) -> float:
+        """Directional derivative of :meth:`value` along a direction at the linearization point."""
+        d = -float((self.w_data * lin.r) @ hdx)
+        d += float((self.lam + self.rho * lin.c) @ hdx[self.eq_rows])
+        d -= self.mu * (float(np.sum(ds_l / lin.s_l)) + float(np.sum(ds_u / lin.s_u)))
+        d -= self.nu * (float(np.sum(np.abs(lin.r_l))) + float(np.sum(np.abs(lin.r_u))))
+        return d
+
+
 def solve_ipm_pd(
     x_init: np.ndarray,
     residual_fn: Callable[[np.ndarray], np.ndarray],
@@ -138,6 +207,10 @@ def solve_ipm_pd(
     mu_min: float = 1e-6,
     sigma_min: float = 1e-3,
     fraction_to_boundary: float = 0.99995,
+    armijo_c: float = 1e-4,
+    armijo_backtrack: float = 0.5,
+    armijo_max: int = 10,
+    max_search_failures: int = 20,
     step_tol: float = 1e-4,
     feas_tol: float = 1e-6,
     max_iter: int = 100,
@@ -168,6 +241,12 @@ def solve_ipm_pd(
         mu_min: stop once the complementarity μ is below it (with the other tests).
         sigma_min: lower clamp of the centering parameter σ.
         fraction_to_boundary: τ of the step-length rule.
+        armijo_c, armijo_backtrack, armijo_max: Armijo backtracking of the
+            primal step on the merit (see the module docstring); at most
+            ``armijo_max`` trial points, ``0`` disables the search.
+        max_search_failures: stop (``"stalled"``) once this many iterations found
+            no sufficient decrease: the iteration is not converging and the
+            remaining budget would be spent for nothing.
         step_tol: stop once the last primal step ``|αp·Δx|∞`` over the coordinates
             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
@@ -195,7 +274,8 @@ def solve_ipm_pd(
 
     Returns:
         :class:`~gridstate.algorithms.ipm.IPMResult`; ``status`` is ``"kkt"`` when
-        every stopping test holds, ``"stalled"`` at ``max_iter``, ``"error"`` on a
+        every stopping test holds, ``"stalled"`` at ``max_iter`` or after
+        ``max_search_failures``, ``"error"`` on a
         failed or non-finite solve. ``iterations_outer`` = ``iterations_inner_total``
         = the number of iterations.
     """
@@ -267,6 +347,9 @@ def solve_ipm_pd(
 
     tr_mask = np.ones(n, dtype=bool)
     tr_mask[box_idx] = False
+    tr_pos = np.flatnonzero(tr_mask)
+    limiters: dict[int, int] = {}
+    limiting_rows: dict[int, int] = {}
 
     def g_of(xv: np.ndarray, r: np.ndarray) -> np.ndarray:
         return np.concatenate([xv[box_idx], -r[mb_rows]])
@@ -287,6 +370,10 @@ def solve_ipm_pd(
     y_l = mu0 / s_l
     y_u = mu0 / s_u
     lam = np.zeros(eq_rows.size, dtype=np.float64)
+    nu = 0.0
+    n_centering = 0
+    n_ls_fail = 0
+    stop_search = False
 
     w = w_base
     mu = mu0 if n_pairs else 0.0
@@ -388,21 +475,87 @@ def solve_ipm_pd(
             status, message = "error", f"non-finite step (iteration {it})"
             break
 
+        # ---- merit backtracking ----
+        mu_t = target if n_pairs else 0.0
+        nu = max(nu, 2.0 * float(max(np.max(y_l, initial=0.0), np.max(y_u, initial=0.0))))
+        merit = _Merit(
+            w_data=w_data,
+            lam=lam,
+            rho=rho,
+            eq_rows=eq_rows,
+            mu=mu_t,
+            nu=nu,
+            lo_l=lo[il],
+            hi_u=hi[iu],
+            il=il,
+            iu=iu,
+        )
+        slope = merit.slope(lin, H @ dx, 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
+            # whenever the slacks are consistent.
+            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)
+            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
+                slope = slope_c
+                n_centering += 1
+
         tau = fraction_to_boundary
         a_p = min(_max_step(s_l, ds_l / tau), _max_step(s_u, ds_u / tau)) if n_pairs else 1.0
         a_d = min(_max_step(y_l, dy_l / tau), _max_step(y_u, dy_u / tau)) if n_pairs else 1.0
         free_inf = float(np.max(np.abs(dx[tr_mask]))) if tr_mask.any() else 0.0
         a_bound = a_p
+        if a_bound < 1.0:
+            k, lower = _blocking_constraint(s_l, ds_l, s_u, ds_u)
+            if k >= 0:
+                kc = int(il[k] if lower else iu[k])
+                if kc < nb:
+                    _count(limiters, int(box_idx[kc]))
+                else:
+                    _count(limiting_rows, int(mb_rows[kc - nb]))
         if free_inf * a_p > tr_radius:
             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
+        a_full = a_p
+        r_new = None
+        # A direction that does not descend (inconsistent slacks of a nonlinear
+        # measurement box) is taken unsearched, as without the merit.
+        if slope < 0.0 and armijo_max > 0:
+            phi0 = merit.value(r, g, s_l, s_u)
+            for _ in range(armijo_max):
+                x_try = x + a_p * dx
+                r_try = residual_fn(x_try)
+                s_l_try = s_l + a_p * ds_l
+                s_u_try = s_u + a_p * ds_u
+                phi = merit.value(r_try, g_of(x_try, r_try), s_l_try, s_u_try)
+                r_new = r_try
+                if math.isfinite(phi) and phi <= phi0 + armijo_c * a_p * slope:
+                    break
+                a_p *= armijo_backtrack
+                r_new = None
+            else:
+                n_ls_fail += 1
+                if n_ls_fail >= max_search_failures:
+                    stop_search = True
+            if r_new is None:
+                # No sufficient decrease: keep the last (shortest) trial step.
+                a_p /= armijo_backtrack
+        if (a_p < a_full or a_full < a_bound) and tr_pos.size:
+            _count(limiters, int(tr_pos[np.argmax(np.abs(dx[tr_pos]))]))
 
         logger.debug(
-            "ipm_pd it=%d μ=%.2e σ=%.2e αp=%.3f (bound %.3f) αd=%.3f |Δx_free|∞=%.2e "
+            "ipm_pd it=%d μ=%.2e σ=%.2e αp=%.3f (before search %.3f, bound %.3f) αd=%.3f |Δx_free|∞=%.2e "
             "|Δx|∞=%.2e |c|∞=%.2e feas=%.2e",
             it,
             mu,
             sigma,
             a_p,
+            a_full,
             a_bound,
             a_d,
             free_inf,
@@ -416,9 +569,10 @@ def solve_ipm_pd(
         y_l = y_l + a_d * dy_l
         y_u = y_u + a_d * dy_u
         lam = lam + a_d * dlam
-        step_inf = a_p * free_inf
-        r = residual_fn(x)
+        r = residual_fn(x) if r_new is None else r_new
         g = g_of(x, r)
+        if stop_search:
+            break
     else:
         it = max_iter
 
@@ -429,12 +583,17 @@ def solve_ipm_pd(
     detail = f"it={iterations}, μ={mu:.2e}, |step|∞={step_inf:.2e}, |grad|∞={grad_inf:.2e}" + (
         f", |c_eq|∞={eq_inf:.2e}" if eq_rows.size else ""
     )
+    if n_centering or n_ls_fail:
+        detail += f", centering={n_centering}, search failures={n_ls_fail}"
     if status == "kkt":
         message = f"converged (kkt): {detail}"
         solve_status = SolveStatus.KKT
     elif status == "error":
         message = f"{message}: {detail}"
         solve_status = SolveStatus.ERROR
+    elif stop_search:
+        message = f"no merit decrease: {detail}"
+        solve_status = SolveStatus.STALLED
     else:
         message = f"iteration limit: {detail}"
         solve_status = SolveStatus.MAX_ITER
@@ -450,6 +609,8 @@ def solve_ipm_pd(
         status=status,
         solve_status=solve_status,
         eq_inf_final=eq_inf,
+        step_limiters=limiters,
+        limiting_rows=limiting_rows,
     )
 
 

{gridstate-2.2.0 → gridstate-2.4.0}/gridstate/api.py

@@ -28,6 +28,7 @@ from gridstate.algorithms.status import (
     success_from_status,
 )
 from gridstate.algorithms.wls import solve_wls
+from gridstate.ipm_hints import has_dominant_limiter, ipm_convergence_hints
 from gridstate.post_processing import (
     apply_load_characteristic,
     reconcile_node_balance,
@@ -47,6 +48,7 @@ from gridstate.quality_summary import (
     top_worst_residuals,
 )
 from gridstate.result import MeasurementNormalizedResiduals, SEResult, extract_output_tables
+from gridstate.solution_hints import low_voltage_hints, low_voltage_nodes, residual_hints
 from gridstate.state import (
     InitialPoint,
     StateLayout,
@@ -99,6 +101,7 @@ def estimate(
     quality_summary_rn_refine_below: float = SELINV_REFINE_BELOW,
     quality_summary_near_critical: float = NEAR_CRITICAL_THRESHOLD,
     success_policy: SuccessPolicy = "legacy",
+    implausible_v_ratio: float = 0.3,
     **ipm_kwargs: Any,
 ) -> SEResult:
     """Run state estimation for a model and telemetry.
@@ -180,6 +183,13 @@ def estimate(
             :func:`gridstate.algorithms.status.success_from_status`
             (``kkt`` or ``mu_schedule_done`` only). ``solve_status`` and
             ``objective_wls`` are reported under both policies.
+        implausible_v_ratio: a solved state with ``V/Vnom`` below it at any
+            node is not a usable estimate whatever the solver reports (e.g. the
+            low-voltage root at a node whose V is barely observable):
+            ``success`` becomes ``False``, the message names the nodes and a
+            WARNING lists hints (:mod:`gridstate.solution_hints`). ``0``
+            disables the check. A WLS solve that does not converge logs its
+            largest normalized residuals.
         **ipm_kwargs: IPM-mode knobs, ignored for WLS. ``trust_region_scope``
             (``"state"`` default | ``"all"``) selects the coordinates the IPM
             trust region is measured on (see ``_run_ipm``); everything else is
@@ -309,6 +319,30 @@ def estimate(
     )
     if success_policy == "status" and not success:
         message = f"solve status {solve_status.value}: {message}"
+    low_v = low_voltage_nodes(v_pu, implausible_v_ratio)
+    if low_v.size:
+        ids = network_pu.bus_ids[low_v][:5].tolist()
+        more = ", ..." if low_v.size > 5 else ""
+        note = (
+            f"implausible solution: V/Vnom < {implausible_v_ratio:g} at "
+            f"{low_v.size} node(s) {ids}{more}"
+        )
+        success = False
+        message = f"{note}; {message}" if message else note
+        hints = low_voltage_hints(
+            low_v, v_pu=v_pu, network_pu=network_pu, meas_index=meas_index, z=z
+        )
+        logger.warning("%s %s:\n%s", algorithm, note, "\n".join(hints))
+    elif not success and algorithm == "wls" and z.shape[0]:
+        algebra = BaseAlgebra(ybus, yf, yt, meas_index, layout, network_pu)
+        hints = residual_hints(
+            z - algebra.evaluate_h(v_pu, delta),
+            np.sqrt(floored_sigma2(r_matrix.diagonal())),
+            meas_index=meas_index,
+            network_pu=network_pu,
+        )
+        if hints:
+            logger.warning("wls did not converge (%s):\n%s", message, "\n".join(hints))
     write_results_to_model(model, v_pu, delta, network_pu, yf=yf, yt=yt, ybus=ybus)
     # 7. Post-processing of measurements: estimated_si/value/residual.
     write_measurement_estimates(
@@ -676,6 +710,8 @@ def _run_ipm(
     measurement_bounds: bool = False,
     injection_roles: bool = False,
     role_estimates: dict[int, float] | None = None,
+    hint_iterations: int = 100,
+    huber_threshold: str = "fixed",
     **ipm_kwargs: Any,
 ) -> IPMResult:
     """IPM mode: extends the state vector with box-vars and solves the primal log-barrier WLS.
@@ -710,7 +746,18 @@ def _run_ipm(
     variables; ``role_estimates`` (when given) receives the estimate of each
     part row in MW / MVAr by measurement id, ``nan`` for a part row folded into a
     net injection.
+
+    A solve that does not converge, falls back from ``ipm_pd`` or takes more
+    than ``hint_iterations`` iterations (``0`` — no iteration trigger) logs a
+    WARNING with convergence hints (:mod:`gridstate.ipm_hints`).
+
+    ``huber_threshold`` (``"ipm_pd"`` only): ``"fixed"`` keeps the Huber
+    threshold at ``huber_c``; ``"adaptive"`` raises it to ``k·median|r/σ|``,
+    recomputed every iteration, so the estimate follows the solver path. The
+    primal IPM keeps its adaptive threshold (recomputed once per outer step).
     """
+    if huber_threshold not in ("fixed", "adaptive"):
+        raise ValueError(f"huber_threshold={huber_threshold!r} is not one of fixed/adaptive")
     if measurement_bounds and solver != "ipm_pd":
         raise ValueError("measurement_bounds requires algorithm='ipm_pd'")
     if trust_region_scope not in ("all", "state"):
@@ -780,6 +827,7 @@ def _run_ipm(
         return algebra.evaluate_jacobian(v, delta)
 
     eq_idx = setup.balance_rows if setup.balance_tol is not None else None
+    pd_result: IPMResult | None = None
     if solver == "ipm_pd":
         mb_rows = mb_lo = mb_hi = None
         if measurement_bounds and measurements is not None:
@@ -807,20 +855,24 @@ def _run_ipm(
             eq_tol=setup.balance_tol,
             mu_init=1.0,
             step_tol=max(tolerance, 1e-4),
-            max_iter=max(max_iterations, 100),
+            # 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),
             tr_radius=0.5,
             huber_c=huber_c,
             huber_mask=huber_mask,
             huber_w_floor=huber_w_floor,
             huber_use_mad=huber_use_mad,
             huber_warmup_iters=2,
-            huber_adaptive_k=2.0,
+            huber_adaptive_k=0.0 if huber_threshold == "fixed" else 2.0,
             kkt_solver=kkt,
         )
+        pd_result = result
         if result.solve_status is not SolveStatus.KKT:
-            # The primal-dual iteration has no merit line search and may cycle
-            # on a weakly determined direction; the primal solver's Armijo
-            # search does not. Measurement boxes have no primal counterpart.
+            # Safety net: on a weakly determined direction (e.g. an unmeasured
+            # unit with a wide box) the primal-dual iteration can still crawl
+            # past its limit. Measurement boxes have no primal counterpart.
             logger.warning(
                 "ipm_pd did not converge (%s), falling back to the primal IPM", result.message
             )
@@ -863,6 +915,26 @@ def _run_ipm(
         if solver == "ipm_pd":
             result.message = f"ipm_pd fallback to ipm ({pd_message}): {result.message}"
 
+    slow: IPMResult | None = None
+    if pd_result is not None and pd_result is not result:
+        slow, reason = pd_result, "ipm_pd fell back to the primal IPM"
+    elif not result.success:
+        slow, reason = result, f"not converged ({result.status})"
+    elif 0 < hint_iterations < result.iterations_inner_total and has_dominant_limiter(
+        result, result.iterations_inner_total
+    ):
+        slow, reason = result, f"{result.iterations_inner_total} iterations > {hint_iterations}"
+    if slow is not None:
+        hints = ipm_convergence_hints(
+            setup=setup,
+            network_pu=network_pu,
+            result=slow,
+            residual=residual_fn(result.x),
+            iterations=slow.iterations_inner_total,
+        )
+        if hints:
+            logger.warning("%s convergence hints (%s):\n%s", solver, reason, "\n".join(hints))
+
     # Extract the box-vars and write them into the node table (MW/MVAr = p.u. * BASE_MVA).
     _, _, pgen, qgen, pnag, qnag = unpack_full(result.x, layout_ipm)
 

{gridstate-2.2.0 → gridstate-2.4.0}/gridstate/contract/__init__.py

@@ -26,6 +26,7 @@ from gridstate.contract.tables import (
     BRANCHES,
     BRANCHES_OUTPUT,
     GENERATORS,
+    LOAD_CHARACTERISTIC_SEGMENTS,
     LOAD_CHARACTERISTICS,
     MEASUREMENTS,
     MEASUREMENTS_OUTPUT,
@@ -70,6 +71,7 @@ __all__ = [
     "CONTRACT_VERSION_KEY",
     "GENERATORS",
     "LOAD_CHARACTERISTICS",
+    "LOAD_CHARACTERISTIC_SEGMENTS",
     "MEASUREMENTS",
     "MEASUREMENTS_OUTPUT",
     "NODES",