gridstate 2.0.0__tar.gz → 2.2.0__tar.gz

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

@@ -9,6 +9,56 @@ 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.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
+
+- `SEResult.normalized_residuals` (`MeasurementNormalizedResiduals`, exported
+  from the package root): `r_N` and `Ω_ii / σ²_i` of every z-vector
+  measurement by measurement id, in z-vector order. The quality summary keeps
+  the vector it already computes; `worst_residuals` and
+  `near_critical_measurements` still rank and trim it. Rows outside the
+  residual scope (pseudo-measurements under `"real"`) hold `nan`, critical
+  measurements `inf`; `None` when the summary is not computed. Additive, no
+  data contract change (#101)
+
 ## v2.0.0 (2026-10-10)
 
 ### Breaking changes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.0.0
+Version: 2.2.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.0.0 → gridstate-2.2.0}/gridstate/__init__.py

@@ -34,6 +34,7 @@ from gridstate.pipeline import (
 from gridstate.result import (
     Chi2Summary,
     ImbalanceRow,
+    MeasurementNormalizedResiduals,
     NearCriticalRow,
     ResidualRow,
     SEResult,
@@ -84,6 +85,7 @@ __all__ = [
     "Chi2Summary",
     "ImbalanceRow",
     "InitialPoint",
+    "MeasurementNormalizedResiduals",
     "NearCriticalRow",
     "NormalizedResidualReport",
     "ObservabilityReport",

{gridstate-2.0.0 → gridstate-2.2.0}/gridstate/_version.py

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

{gridstate-2.0.0 → gridstate-2.2.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
@@ -98,6 +104,8 @@ 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")
 
 
 def _project_to_interior(
@@ -269,6 +277,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 +343,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 +377,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 +439,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
@@ -442,6 +484,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
 
@@ -552,6 +596,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 +637,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 +663,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 +683,7 @@ def solve_ipm(
         message=message,
         status=status,
         solve_status=solve_status,
+        eq_inf_final=eq_inf,
     )
 
 

gridstate-2.2.0/gridstate/algorithms/ipm_pd.py

@@ -0,0 +1,456 @@
+"""Primal-dual predictor-corrector (Mehrotra) Interior-Point Method for constrained WLS.
+
+The problem of :mod:`gridstate.algorithms.ipm` with two generalisations::
+
+    min_x  ½ Σ_i w_i r_i(x)²                       (data rows, r = z − h(x))
+    s.t.   c(x) = h_E(x) − z_E = 0                 (equality rows E, e.g. hard balance)
+           lo_v ≤ x_v ≤ hi_v                       (variable boxes)
+           lo_j ≤ h_j(x) − z_j ≤ hi_j              (boxes on measurement values)
+
+Every inequality is ``l_k ≤ g_k(x) ≤ u_k`` with ``g_k = x_v`` (variable box)
+or ``g_k = −r_j`` (measurement box; either side may be infinite). Slacks
+``s_l = g − l``, ``s_u = u − g`` and duals ``y_l, y_u ≥ 0`` turn it into the
+perturbed KKT system (Gauss-Newton Hessian ``K = Hᵀ W H``)::
+
+    −Hᵀ W r + Aᵀ λ − G_lᵀ y_l + G_uᵀ y_u = 0
+    c(x) = 0,   g − l − s_l = 0,   u − g − s_u = 0
+    s_l·y_l = σμ,   s_u·y_u = σμ
+
+Newton step. The slack/dual blocks are eliminated per inequality, adding
+``Gᵀ D G`` (``D = y_l/s_l + y_u/s_u``) to ``K``: on the diagonal for a variable
+box, as extra weight of row ``j`` for a measurement box. The equality block is
+the regularised (quasi-definite) KKT ``[K' Aᵀ; A −δI]``; eliminating ``Δλ``
+gives the SPD system ``(K' + ρ AᵀA)·Δx = rhs`` with ``ρ = 1/δ`` and
+``Δλ = ρ·(A Δx + c)``. Its fixed point satisfies ``c = 0`` exactly; ``ρ`` only
+sets how fast the equality is reached. So every step is one normal-equations
+factorization of the usual pattern (:meth:`KKTSolver.factor_normal`).
+
+Iteration (one factorization, two solves)::
+
+    μ      = (s_lᵀy_l + s_uᵀy_u) / N
+    affine predictor:   complementarity target 0 → Δ_aff, α_aff
+    μ_aff  = complementarity after the affine step
+    σ      = 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)
+
+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``.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+
+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.kkt_solver import KKTSolver
+from gridstate.algorithms.status import SolveStatus
+
+
+logger = logging.getLogger(__name__)
+
+
+def _max_step(v: np.ndarray, dv: np.ndarray) -> float:
+    """Largest ``α ∈ [0, 1]`` with ``v + α·dv ≥ 0`` (``v > 0``)."""
+    neg = dv < 0
+    if not np.any(neg):
+        return 1.0
+    return min(1.0, float(np.min(-v[neg] / dv[neg])))
+
+
+Direction = tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]
+
+
+@dataclass
+class _Linearization:
+    """One iteration's linear system: the factorized matrix and the point it was built at.
+
+    Index sets: ``il`` / ``iu`` — constraints with a lower / upper side (into the
+    concatenation of the variable boxes, ``box_idx``, and the measurement boxes,
+    ``mb_rows``); ``eq_rows`` — equality rows. ``y_dual = y_l − y_u`` scattered
+    over all constraints.
+    """
+
+    H: csr_matrix
+    solve: Callable[[np.ndarray], np.ndarray]
+    r: np.ndarray
+    w_data: np.ndarray
+    c: np.ndarray
+    lam: np.ndarray
+    rho: np.ndarray
+    r_l: np.ndarray
+    r_u: np.ndarray
+    s_l: np.ndarray
+    s_u: np.ndarray
+    y_l: np.ndarray
+    y_u: np.ndarray
+    y_dual: np.ndarray
+    il: np.ndarray
+    iu: np.ndarray
+    box_idx: np.ndarray
+    mb_rows: np.ndarray
+    eq_rows: np.ndarray
+
+    def direction(self, rc_l: np.ndarray, rc_u: np.ndarray) -> Direction:
+        """``(Δx, Δs_l, Δs_u, Δy_l, Δy_u, Δλ)`` for the complementarity targets ``rc``."""
+        nb = self.box_idx.size
+        v_k = self.y_dual.copy()
+        v_k[self.il] += (rc_l - self.y_l * self.r_l) / self.s_l
+        v_k[self.iu] -= (rc_u - self.y_u * self.r_u) / self.s_u
+        rows = self.w_data * self.r
+        rows[self.eq_rows] = -self.lam - self.rho * self.c
+        rows[self.mb_rows] += v_k[nb:]
+        rhs = np.asarray(self.H.T @ rows, dtype=np.float64).ravel()
+        rhs[self.box_idx] += v_k[:nb]
+        dx = self.solve(rhs)
+        hdx = np.asarray(self.H @ dx, dtype=np.float64).ravel()
+        gdx = np.concatenate([dx[self.box_idx], hdx[self.mb_rows]])
+        ds_l = gdx[self.il] + self.r_l
+        ds_u = -gdx[self.iu] + self.r_u
+        dy_l = (rc_l - self.y_l * ds_l) / self.s_l
+        dy_u = (rc_u - self.y_u * ds_u) / self.s_u
+        dlam = self.rho * (hdx[self.eq_rows] + self.c)
+        return dx, ds_l, ds_u, dy_l, dy_u, dlam
+
+
+def solve_ipm_pd(
+    x_init: np.ndarray,
+    residual_fn: Callable[[np.ndarray], np.ndarray],
+    jacobian_fn: Callable[[np.ndarray], csr_matrix],
+    r_inv_diag: np.ndarray,
+    *,
+    box_idx: np.ndarray | None = None,
+    box_lo: np.ndarray | None = None,
+    box_hi: np.ndarray | None = None,
+    meas_box_rows: np.ndarray | None = None,
+    meas_box_lo: np.ndarray | None = None,
+    meas_box_hi: np.ndarray | None = None,
+    eq_idx: np.ndarray | None = None,
+    eq_tol: np.ndarray | None = None,
+    mu_init: float = 0.1,
+    mu_min: float = 1e-6,
+    sigma_min: float = 1e-3,
+    fraction_to_boundary: float = 0.99995,
+    step_tol: float = 1e-4,
+    feas_tol: float = 1e-6,
+    max_iter: int = 100,
+    box_eps: float = 1e-3,
+    tr_radius: float = 0.5,
+    huber_c: float = 0.0,
+    huber_mask: np.ndarray | None = None,
+    huber_w_floor: float = 0.05,
+    huber_use_mad: bool = False,
+    huber_adaptive_k: float = 6.0,
+    huber_warmup_iters: int = 5,
+    kkt_solver: KKTSolver | None = None,
+    eq_prox: float = 1e-9,
+    box_prox: float = 1e-6,
+) -> IPMResult:
+    """Mehrotra predictor-corrector IPM (see the module docstring).
+
+    Args:
+        x_init, residual_fn, jacobian_fn, r_inv_diag: as in
+            :func:`gridstate.algorithms.ipm.solve_ipm`; ``r_inv_diag`` of an
+            equality row is its penalty ``ρ``.
+        box_idx, box_lo, box_hi: variable boxes (``lo < hi``, finite).
+        meas_box_rows: rows ``j`` of ``r`` whose value ``h_j − z_j = −r_j`` is
+            bounded by ``[meas_box_lo, meas_box_hi]`` (a side may be ±inf, not
+            both). Rows of ``eq_idx`` are not allowed.
+        eq_idx, eq_tol: equality rows ``h = z`` and their admissible ``|c|`` (p.u.).
+        mu_init: μ0 of the central-path start.
+        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.
+        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
+            generation and load), which change neither the state nor the residuals.
+        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``.
+        tr_radius: cap on ``|αp·Δx|∞`` over the coordinates outside ``box_idx``.
+        huber_*: SHGM-IRLS reweighting of the rows of ``huber_mask``, as in
+            ``solve_ipm``; the adaptive scale is recomputed every iteration
+            (μ changes every iteration).
+        kkt_solver: Newton-system solver (``None`` — scipy).
+        eq_prox: with equality rows, a proximal term ``eq_prox·max(ρ)`` on the
+            diagonal of the box coordinates. A hard balance fixes only the net
+            injection of a node, so the common level of its generation and load
+            is set by the weak barrier curvature alone and the system is
+            numerically singular; the term regularises the step only, the
+            fixed point is unchanged.
+        box_prox: a proximal term ``box_prox·median(r_inv_diag)`` on the diagonal
+            of the box coordinates (with or without equality rows; the larger of
+            the two terms applies). A box variable seen only through a balance row
+            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.
+
+    Returns:
+        :class:`~gridstate.algorithms.ipm.IPMResult`; ``status`` is ``"kkt"`` when
+        every stopping test holds, ``"stalled"`` at ``max_iter``, ``"error"`` on a
+        failed or non-finite solve. ``iterations_outer`` = ``iterations_inner_total``
+        = the number of iterations.
+    """
+    x = np.asarray(x_init, dtype=np.float64)
+    n = x.shape[0]
+    m = int(r_inv_diag.shape[0])
+    solver = kkt_solver if kkt_solver is not None else KKTSolver("scipy")
+
+    box_idx = np.asarray(box_idx if box_idx is not None else [], dtype=np.int64)
+    if box_idx.size:
+        if box_lo is None or box_hi is None:
+            raise ValueError("box_lo and box_hi are required when box_idx is given")
+        b_lo = np.asarray(box_lo, dtype=np.float64)
+        b_hi = np.asarray(box_hi, dtype=np.float64)
+        if np.any(b_lo >= b_hi):
+            raise ValueError("box_lo/box_hi contain pairs with lo >= hi")
+    else:
+        b_lo = b_hi = np.zeros(0)
+    mb_rows = np.asarray(meas_box_rows if meas_box_rows is not None else [], dtype=np.int64)
+    if mb_rows.size:
+        if meas_box_lo is None or meas_box_hi is None:
+            raise ValueError("meas_box_lo and meas_box_hi are required with meas_box_rows")
+        m_lo = np.asarray(meas_box_lo, dtype=np.float64)
+        m_hi = np.asarray(meas_box_hi, dtype=np.float64)
+        if np.any(~np.isfinite(m_lo) & ~np.isfinite(m_hi)) or np.any(m_lo >= m_hi):
+            raise ValueError("every measurement box needs one finite side and lo < hi")
+    else:
+        m_lo = m_hi = np.zeros(0)
+    eq_rows = np.asarray(eq_idx if eq_idx is not None else [], dtype=np.int64)
+    if eq_rows.size:
+        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")
+        if np.intersect1d(eq_rows, mb_rows).size:
+            raise ValueError("an equality row cannot carry a measurement box")
+        eq_tol_arr = np.asarray(eq_tol, dtype=np.float64)
+    else:
+        eq_tol_arr = np.zeros(0)
+
+    nb = box_idx.size
+    lo = np.concatenate([b_lo, m_lo])
+    hi = np.concatenate([b_hi, m_hi])
+    il = np.flatnonzero(np.isfinite(lo))  # constraints with a lower side
+    iu = np.flatnonzero(np.isfinite(hi))  # ... with an upper side
+    n_pairs = il.size + iu.size
+
+    w_base = np.asarray(r_inv_diag, dtype=np.float64).copy()
+    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,
+    )
+
+    huber_mask_arr = (
+        np.asarray(huber_mask, dtype=bool) if huber_mask is not None else np.zeros(m, dtype=bool)
+    )
+    use_huber = huber_c > 0.0 and huber_mask_arr.any()
+    reweighter = HuberReweighter(
+        c=huber_c,
+        mask=huber_mask_arr,
+        sigma=(
+            1.0 / np.sqrt(np.maximum(w_base, 1e-30)) if use_huber else np.ones(m, dtype=np.float64)
+        ),
+        w_floor=huber_w_floor,
+        adaptive_k=huber_adaptive_k,
+        use_mad=huber_use_mad,
+    )
+
+    tr_mask = np.ones(n, dtype=bool)
+    tr_mask[box_idx] = False
+
+    def g_of(xv: np.ndarray, r: np.ndarray) -> np.ndarray:
+        return np.concatenate([xv[box_idx], -r[mb_rows]])
+
+    # ---- start on the central path ----
+    x = _project_to_interior(x, box_idx, b_lo, b_hi, box_eps)
+    r = residual_fn(x)
+    g = g_of(x, r)
+    # Two-sided constraints start at the half-range whatever x is (an infeasible
+    # start, g − l − s_l ≠ 0): an initial point pinned near a bound would
+    # otherwise give a tiny slack and cut every early step to a tiny αp.
+    # One-sided ones start at their distance, floored.
+    two_sided = np.isfinite(lo) & np.isfinite(hi)
+    half = np.where(two_sided, 0.5 * (hi - lo), 0.0)
+    s_l = np.where(two_sided[il], half[il], np.maximum(g[il] - lo[il], 1e-2))
+    s_u = np.where(two_sided[iu], half[iu], np.maximum(hi[iu] - g[iu], 1e-2))
+    mu0 = float(mu_init)
+    y_l = mu0 / s_l
+    y_u = mu0 / s_u
+    lam = np.zeros(eq_rows.size, dtype=np.float64)
+
+    w = w_base
+    mu = mu0 if n_pairs else 0.0
+    step_inf = float("inf")
+    eq_inf = 0.0
+    grad_inf = float("inf")
+    status = "stalled"
+    message = ""
+    it = 0
+    for it in range(max_iter):
+        if use_huber and it >= huber_warmup_iters:
+            reweighter.reset_adaptive()
+            w = w_base * reweighter.weights(r)
+        w_data = np.where(is_eq, 0.0, w)
+        c = -r[eq_rows]
+        r_l = g[il] - lo[il] - s_l
+        r_u = hi[iu] - g[iu] - s_u
+        mu = (float(s_l @ y_l) + float(s_u @ y_u)) / n_pairs if n_pairs else 0.0
+        eq_inf = float(np.max(np.abs(c))) if c.size else 0.0
+        feas_inf = float(np.max(np.abs(np.concatenate([r_l, r_u])))) if n_pairs else 0.0
+        if (
+            it > 0
+            and mu <= mu_min
+            and feas_inf <= feas_tol
+            and bool(np.all(np.abs(c) <= eq_tol_arr))
+            and step_inf <= step_tol
+        ):
+            status = "kkt"
+            break
+        H = jacobian_fn(x)
+        # Row weights of the condensed matrix: data, equality penalty ρ,
+        # measurement-box curvature; box curvature goes on the diagonal.
+        d_k = np.zeros(nb + mb_rows.size)
+        d_k[il] += y_l / s_l
+        d_k[iu] += y_u / s_u
+        w_mat = w_data.copy()
+        w_mat[eq_rows] = rho
+        w_mat[mb_rows] += d_k[nb:]
+        diag = np.zeros(n)
+        diag[box_idx] = d_k[:nb] + prox
+        # Stationarity residual of the current point (for reporting).
+        y_dual = np.zeros(nb + mb_rows.size)
+        y_dual[il] += y_l
+        y_dual[iu] -= y_u
+        row_vec = w_data * r
+        row_vec[eq_rows] -= lam
+        row_vec[mb_rows] += y_dual[nb:]
+        grad = np.asarray(H.T @ row_vec, dtype=np.float64).ravel()
+        grad[box_idx] += y_dual[:nb]
+        grad_inf = float(np.max(np.abs(grad))) if grad.size else 0.0
+        try:
+            solve = solver.factor_normal(H, w_mat, diag=diag if nb else None)
+        except Exception as exc:
+            logger.warning("ipm_pd: kkt factorization failed at iteration %d: %s", it, exc)
+            status, message = "error", f"kkt solve failure (iteration {it})"
+            break
+
+        lin = _Linearization(
+            H=H,
+            solve=solve,
+            r=r,
+            w_data=w_data,
+            c=c,
+            lam=lam,
+            rho=rho,
+            r_l=r_l,
+            r_u=r_u,
+            s_l=s_l,
+            s_u=s_u,
+            y_l=y_l,
+            y_u=y_u,
+            y_dual=y_dual,
+            il=il,
+            iu=iu,
+            box_idx=box_idx,
+            mb_rows=mb_rows,
+            eq_rows=eq_rows,
+        )
+
+        # ---- predictor (affine scaling) ----
+        dx, ds_l, ds_u, dy_l, dy_u, dlam = lin.direction(-s_l * y_l, -s_u * y_u)
+        sigma = 0.0
+        if n_pairs:
+            a_p = min(_max_step(s_l, ds_l), _max_step(s_u, ds_u))
+            a_d = min(_max_step(y_l, dy_l), _max_step(y_u, dy_u))
+            mu_aff = (
+                float((s_l + a_p * ds_l) @ (y_l + a_d * dy_l))
+                + float((s_u + a_p * ds_u) @ (y_u + a_d * dy_u))
+            ) / n_pairs
+            sigma = min(1.0, max(sigma_min, (mu_aff / mu) ** 3)) if mu > 0 else sigma_min
+            # ---- corrector on the same factorization ----
+            # Never centre below the stopping level: complementarity far below
+            # μ_min only drives slacks to zero and the curvature y/s to overflow.
+            target = max(sigma * mu, 0.1 * mu_min)
+            dx, ds_l, ds_u, dy_l, dy_u, dlam = lin.direction(
+                target - s_l * y_l - ds_l * dy_l, target - s_u * y_u - ds_u * dy_u
+            )
+        if not np.all(np.isfinite(dx)):
+            status, message = "error", f"non-finite step (iteration {it})"
+            break
+
+        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 free_inf * a_p > tr_radius:
+            a_p = tr_radius / free_inf
+
+        logger.debug(
+            "ipm_pd it=%d μ=%.2e σ=%.2e αp=%.3f (bound %.3f) αd=%.3f |Δx_free|∞=%.2e "
+            "|Δx|∞=%.2e |c|∞=%.2e feas=%.2e",
+            it,
+            mu,
+            sigma,
+            a_p,
+            a_bound,
+            a_d,
+            free_inf,
+            float(np.max(np.abs(dx))) if dx.size else 0.0,
+            eq_inf,
+            feas_inf,
+        )
+        x = x + a_p * dx
+        s_l = s_l + a_p * ds_l
+        s_u = s_u + a_p * ds_u
+        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)
+        g = g_of(x, r)
+    else:
+        it = max_iter
+
+    w_rep = w.copy()
+    obj = 0.5 * float(r @ (w_rep * r))
+    eq_inf = float(np.max(np.abs(r[eq_rows]))) if eq_rows.size else float("nan")
+    iterations = it if status == "kkt" else min(it + 1, max_iter)
+    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 status == "kkt":
+        message = f"converged (kkt): {detail}"
+        solve_status = SolveStatus.KKT
+    elif status == "error":
+        message = f"{message}: {detail}"
+        solve_status = SolveStatus.ERROR
+    else:
+        message = f"iteration limit: {detail}"
+        solve_status = SolveStatus.MAX_ITER
+    return IPMResult(
+        x=x,
+        success=status == "kkt",
+        objective_data=obj,
+        iterations_outer=iterations,
+        iterations_inner_total=iterations,
+        mu_final=mu,
+        grad_inf_final=grad_inf,
+        message=message,
+        status=status,
+        solve_status=solve_status,
+        eq_inf_final=eq_inf,
+    )
+
+
+__all__ = ["solve_ipm_pd"]