gridstate 2.3.0__tar.gz → 2.4.1__tar.gz

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

@@ -9,6 +9,49 @@ 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.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
+
+- 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

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

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

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

{gridstate-2.3.0 → gridstate-2.4.1}/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.3.0 → gridstate-2.4.1}/gridstate/api.py

@@ -48,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,
@@ -100,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.
@@ -181,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
@@ -310,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(

{gridstate-2.3.0 → gridstate-2.4.1}/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",

{gridstate-2.3.0 → gridstate-2.4.1}/gridstate/contract/tables.py

@@ -670,6 +670,41 @@ LOAD_CHARACTERISTICS = TableSchema(
     ),
 )
 
+# Piecewise segments of the static load characteristics, one row per segment.
+# Optional: a (characteristic, quantity) pair with segments replaces its quadratic
+# coefficients of LOAD_CHARACTERISTICS; a pair without segments keeps them.
+LOAD_CHARACTERISTIC_SEGMENTS = TableSchema(
+    name="load_characteristic_segments",
+    key=("load_model_id", "quantity", "v_lo"),
+    doc=(
+        "Piecewise P(V)/Q(V) load characteristics: segment k of a (load_model_id, quantity) "
+        "pair applies for v_lo[k] < V ≤ v_lo[k+1] (V = |V|/Vnom; a value on a boundary "
+        "belongs to the lower segment); the first segment extends to V = 0 whatever its "
+        "v_lo. Factor = c0 + c1·V + c2·V² + c3·V³ + c4·V⁴ (1.0 = nominal)."
+    ),
+    columns=(
+        ColumnSpec(
+            "load_model_id",
+            "i4",
+            Role.KEY,
+            doc="Characteristic (load_characteristics.id, 0-based); must exist there.",
+        ),
+        ColumnSpec("quantity", "i1", Role.KEY, doc="0 = P, 1 = Q."),
+        ColumnSpec(
+            "v_lo",
+            "f8",
+            Role.KEY,
+            doc="Lower bound of |V|/Vnom; strictly increasing within a pair; "
+            "treated as -inf for the first segment.",
+        ),
+        ColumnSpec("c0", "f8", Role.INPUT, doc="Coefficient of V⁰."),
+        ColumnSpec("c1", "f8", Role.INPUT, doc="Coefficient of V¹."),
+        ColumnSpec("c2", "f8", Role.INPUT, doc="Coefficient of V²."),
+        ColumnSpec("c3", "f8", Role.INPUT, doc="Coefficient of V³."),
+        ColumnSpec("c4", "f8", Role.INPUT, doc="Coefficient of V⁴."),
+    ),
+)
+
 # Shunt devices (reactors/capacitor banks), per device. The core aggregates the active ones
 # into node.shunt_g/b for the Y-bus (a numeric step, replacing apply_reactors_to_node_shunt) and
 # in the future switches steps (group_id/step — reserved).
@@ -708,7 +743,8 @@ SHUNTS = TableSchema(
 class SEInputSchema:
     """Input contract schema: a set of tables (roles KEY/INPUT/WORKING).
 
-    The domain tables ``tap_steps``/``load_characteristics``/``shunts`` are
+    The domain tables ``tap_steps``/``load_characteristics``/``shunts``/
+    ``load_characteristic_segments`` are
     format-agnostic numeric inputs (tap changer position selection, unit conversion,
     aggregation of shunts are done in an external data source). Input-only
     (roles KEY/INPUT).
@@ -721,6 +757,7 @@ class SEInputSchema:
     tap_steps: TableSchema
     load_characteristics: TableSchema
     shunts: TableSchema
+    load_characteristic_segments: TableSchema
 
     def tables(self) -> tuple[TableSchema, ...]:
         """All tables in the order of field declaration (single source — the dataclass)."""
@@ -748,6 +785,7 @@ SE_INPUT = SEInputSchema(
     tap_steps=TAP_STEPS,
     load_characteristics=LOAD_CHARACTERISTICS,
     shunts=SHUNTS,
+    load_characteristic_segments=LOAD_CHARACTERISTIC_SEGMENTS,
 )
 
 SE_OUTPUT = SEOutputSchema(

{gridstate-2.3.0 → gridstate-2.4.1}/gridstate/contract/validate.py

@@ -18,6 +18,7 @@ from typing import Any
 
 from gridstate.contract.tables import SE_INPUT, Role, SEInputSchema
 from gridstate.contract.version import CONTRACT_VERSION_KEY, check_compatibility
+from gridstate.load_characteristics import segment_problems
 
 
 @dataclass(frozen=True)
@@ -25,7 +26,7 @@ class ValidationIssue:
     """A single input validation problem."""
 
     table: str
-    kind: str  # "missing_column" | "missing_table" | "version_incompatible"
+    kind: str  # "missing_column" | "missing_table" | "version_incompatible" | "invalid_rows"
     detail: str
     column: str | None = None
 
@@ -75,6 +76,20 @@ def _available_columns(source: Any, table_name: str) -> set[str] | None:
     return set(names or ())
 
 
+#: Input tables a source may omit (added in a minor contract version).
+_OPTIONAL_TABLES = frozenset({"load_characteristic_segments"})
+
+
+def _table_array(source: Any, table_name: str) -> Any:
+    """The structured array of table ``table_name`` (``None`` if absent)."""
+    if isinstance(source, Mapping):
+        return source.get(table_name)
+    collection = getattr(source, table_name, None)
+    if collection is None or not hasattr(collection, "to_numpy"):
+        return None
+    return collection.to_numpy()
+
+
 def _data_version(source: Any, explicit: str | None) -> str | None:
     """Data contract version: explicit > ``metadata[contract_version]`` > None."""
     if explicit is not None:
@@ -128,6 +143,8 @@ def validate_input(
     for table in schema.tables():
         available = _available_columns(source, table.name)
         if available is None:
+            if table.name in _OPTIONAL_TABLES:
+                continue
             report.add(
                 ValidationIssue(table.name, "missing_table", "table is missing from the input")
             )
@@ -143,6 +160,13 @@ def validate_input(
                     )
                 )
 
+    # --- row-level rules of the piecewise load characteristics ---
+    segments = _table_array(source, "load_characteristic_segments")
+    if segments is not None and len(segments) > 0:
+        lc = _table_array(source, "load_characteristics")
+        for problem in segment_problems(segments, 0 if lc is None else len(lc)):
+            report.add(ValidationIssue("load_characteristic_segments", "invalid_rows", problem))
+
     if strict:
         report.raise_if_invalid()
     return report

{gridstate-2.3.0 → gridstate-2.4.1}/gridstate/contract/version.py

@@ -48,7 +48,9 @@ from dataclasses import dataclass
 # explicit legacy path ``load_se_input_npz(path, trusted=True)``.
 # 3.1.0 (MINOR): the optional derived table ``telemetry_bounds``
 #   (``DerivedInputs.telemetry_bounds``).
-CONTRACT_VERSION = "3.1.0"
+# 3.2.0 (MINOR): the optional input table ``load_characteristic_segments``
+#   (piecewise load characteristics).
+CONTRACT_VERSION = "3.2.0"
 
 # Major of the data the explicit legacy path of the ``.npz`` loader still reads
 # (``load_se_input_npz(path, trusted=True)``).

{gridstate-2.3.0 → gridstate-2.4.1}/gridstate/ipm_hints.py

@@ -25,34 +25,16 @@ import numpy as np
 
 from gridstate.algorithms.ipm import IPMResult
 from gridstate.preprocessing.ipm_setup import IPMSetup
+from gridstate.solution_hints import KIND_NAMES, describe_row, residual_hints
 from gridstate.units import BASE_MVA, NetworkPU
 from gridstate.z_vector import (
     KIND_BOX_PRIOR_PGEN,
     KIND_BOX_PRIOR_PNAG,
     KIND_BOX_PRIOR_QGEN,
     KIND_BOX_PRIOR_QNAG,
-    KIND_NODE_BALANCE_P,
-    KIND_NODE_BALANCE_Q,
 )
 
 
-#: Row kinds by name (``MeasurementType`` plus the rows the IPM setup appends).
-_KIND_NAMES = {
-    0: "P flow",
-    1: "Q flow",
-    2: "V",
-    3: "I",
-    4: "P injection",
-    5: "Q injection",
-    KIND_NODE_BALANCE_P: "P balance",
-    KIND_NODE_BALANCE_Q: "Q balance",
-    KIND_BOX_PRIOR_PGEN: "Pgen",
-    KIND_BOX_PRIOR_QGEN: "Qgen",
-    KIND_BOX_PRIOR_PNAG: "Pload",
-    KIND_BOX_PRIOR_QNAG: "Qload",
-}
-
-
 def _box_sections(setup: IPMSetup) -> list[tuple[int, int, np.ndarray]]:
     lay = setup.layout
     return [
@@ -120,7 +102,7 @@ class _Context:
             for bkind, _off, _pos in _box_sections(self.setup):
                 rows = self.rows(pos, bkind)
                 if rows.size and not self.is_role[rows].any():
-                    free_parts.append(_KIND_NAMES[bkind])
+                    free_parts.append(KIND_NAMES[bkind])
             label = f"node {node} {var} ({n_nbr} neighbour node{'s' if n_nbr != 1 else ''})"
             if n_nbr <= 1 and free_parts:
                 hint = (
@@ -135,7 +117,7 @@ class _Context:
         lo = float(self.setup.box_lo[k]) * BASE_MVA if k is not None else float("nan")
         hi = float(self.setup.box_hi[k]) * BASE_MVA if k is not None else float("nan")
         measured, sigma = self.box_variable_state(pos, kind)
-        name = _KIND_NAMES[kind]
+        name = KIND_NAMES[kind]
         label = f"node {node} {name} range [{lo:.1f}, {hi:.1f}]"
         if measured:
             label += ", measured"
@@ -151,17 +133,7 @@ class _Context:
 
     def describe_row(self, row: int) -> str:
         mi = self.setup.meas_index
-        kind = int(mi.kind[row])
-        name = _KIND_NAMES.get(kind, f"kind {kind}")
-        okind, opos = int(mi.object_kind[row]), int(mi.object_pos[row])
-        if okind == 1:
-            side = "from" if int(mi.branch_side[row]) == 0 else "to"
-            obj = f"branch {int(self.net.branch_ids[opos])} ({side})"
-        else:
-            obj = f"node {self.node_id(opos)}"
-        mid = int(mi.meas_id[row])
-        what = "part measurement" if self.is_role[row] else ("measurement" if mid > 0 else "row")
-        return f"{name} {what} {mid} at {obj}" if mid > 0 else f"{name} {what} at {obj}"
+        return describe_row(mi, self.net, row, part=bool(self.is_role[row]))
 
 
 def _top(counts: Mapping[int, int], n: int, floor: float) -> list[tuple[int, int]]:
@@ -240,17 +212,18 @@ def ipm_convergence_hints(
         lines.extend(f"  {label}" for _, label in weak[:top])
 
     sigma = ctx.sigma
-    rn = np.abs(residual) / np.where(sigma > 0, sigma, np.inf)
-    if setup.balance_tol is not None:
-        # Equality rows: their σ is a penalty, not a measurement error.
-        rn[setup.balance_rows] = 0.0
-    order = np.argsort(-rn)[:top]
-    if order.size and rn[order[0]] > 0:
-        lines.append("largest normalized residuals |r|/σ:")
-        for i in order.tolist():
-            kind = int(setup.meas_index.kind[i])
-            r_txt = f"{residual[i]:.4f} p.u." if kind in (2, 3) else f"{residual[i] * BASE_MVA:.2f}"
-            lines.append(f"  {ctx.describe_row(i)}: {rn[i]:.1f}σ (r = {r_txt})")
+    lines.extend(
+        residual_hints(
+            residual,
+            sigma,
+            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,
+            part_rows=setup.role_rows,
+            top=top,
+        )
+    )
 
     outside: list[tuple[float, str]] = []
     for row in setup.role_rows.tolist():

gridstate-2.4.1/gridstate/load_characteristics.py

@@ -0,0 +1,99 @@
+"""Piecewise static load characteristics (``load_characteristic_segments``).
+
+A characteristic may define, separately for P and Q (``quantity`` 0 / 1), a set
+of segments: segment ``k`` applies for ``v_lo[k] < V ≤ v_lo[k+1]``
+(``V = |V|/Vnom``; a value on a boundary belongs to the lower segment), the
+first one extends to ``V = 0`` whatever its ``v_lo``. The load factor on a
+segment is ``c0 + c1·V + c2·V² + c3·V³ + c4·V⁴`` (1.0 = nominal).
+"""
+
+from __future__ import annotations
+
+from itertools import pairwise
+
+import numpy as np
+
+
+#: ``quantity`` codes of ``load_characteristic_segments``.
+QUANTITY_P = 0
+QUANTITY_Q = 1
+
+#: ``(load_model_id, quantity) → (boundaries, coefficients)``: the upper
+#: boundaries of all segments but the last (``v_lo[1:]``, increasing) and the
+#: ``(n_segments, 5)`` coefficient matrix.
+SegmentPlan = dict[tuple[int, int], tuple[np.ndarray, np.ndarray]]
+
+
+def segment_problems(segments: np.ndarray, n_models: int) -> list[str]:
+    """Contract violations of a ``load_characteristic_segments`` table (empty = valid).
+
+    ``n_models`` is the number of rows of ``load_characteristics`` (ids are
+    0-based positions).
+    """
+    problems: list[str] = []
+    if len(segments) == 0:
+        return problems
+    ids = np.asarray(segments["load_model_id"], dtype=np.int64)
+    qty = np.asarray(segments["quantity"], dtype=np.int64)
+    v_lo = np.asarray(segments["v_lo"], dtype=np.float64)
+    unknown = sorted(set(ids[(ids < 0) | (ids >= n_models)].tolist()))
+    if unknown:
+        problems.append(f"load_model_id not in load_characteristics: {unknown}")
+    bad_q = sorted(set(qty[(qty != QUANTITY_P) & (qty != QUANTITY_Q)].tolist()))
+    if bad_q:
+        problems.append(f"quantity must be 0 (P) or 1 (Q), got {bad_q}")
+    coeffs = np.column_stack([np.asarray(segments[f"c{k}"], dtype=np.float64) for k in range(5)])
+    if not np.all(np.isfinite(coeffs)):
+        problems.append("non-finite coefficients")
+    order = np.lexsort((v_lo, qty, ids))
+    for a, b in pairwise(order):
+        # The first segment's v_lo is ignored, so only later bounds must be
+        # finite; equal bounds make an empty segment.
+        same_pair = ids[a] == ids[b] and qty[a] == qty[b]
+        if same_pair and (not np.isfinite(v_lo[b]) or v_lo[b] <= v_lo[a]):
+            problems.append(
+                f"v_lo must be finite and strictly increasing within "
+                f"(load_model_id={ids[a]}, quantity={qty[a]})"
+            )
+    return problems
+
+
+def segment_plan(segments: np.ndarray, n_models: int) -> SegmentPlan:
+    """Group the segments by ``(load_model_id, quantity)``.
+
+    Raises:
+        ValueError: the table violates the contract (see :func:`segment_problems`).
+    """
+    problems = segment_problems(segments, n_models)
+    if problems:
+        raise ValueError("invalid load_characteristic_segments: " + "; ".join(problems))
+    plan: SegmentPlan = {}
+    if len(segments) == 0:
+        return plan
+    ids = np.asarray(segments["load_model_id"], dtype=np.int64)
+    qty = np.asarray(segments["quantity"], dtype=np.int64)
+    v_lo = np.asarray(segments["v_lo"], dtype=np.float64)
+    coeffs = np.column_stack([np.asarray(segments[f"c{k}"], dtype=np.float64) for k in range(5)])
+    order = np.lexsort((v_lo, qty, ids))
+    for key in sorted(set(zip(ids.tolist(), qty.tolist(), strict=True))):
+        rows = order[(ids[order] == key[0]) & (qty[order] == key[1])]
+        plan[key] = (v_lo[rows][1:].copy(), coeffs[rows].copy())
+    return plan
+
+
+def segment_factor(bounds: np.ndarray, coeffs: np.ndarray, v: float) -> float:
+    """Load factor at ``v`` (``bounds`` / ``coeffs`` of one plan entry)."""
+    # Number of upper bounds strictly below v: on a boundary, the lower segment.
+    k = int(np.searchsorted(bounds, v, side="left"))
+    c = coeffs[k]
+    return float(c[0] + v * (c[1] + v * (c[2] + v * (c[3] + v * c[4]))))
+
+
+__all__ = [
+    "QUANTITY_P",
+    "QUANTITY_Q",
+    "SegmentPlan",
+    "segment_factor",
+    "segment_plan",
+    "segment_problems",
+]