gridstate 2.3.0__tar.gz → 2.4.0__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.3.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.3.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.3.0'
-__version_tuple__ = version_tuple = (2, 3, 0)
+__version__ = version = '2.4.0'
+__version_tuple__ = version_tuple = (2, 4, 0)
 
-__commit_id__ = commit_id = 'gef79dd7f7'
+__commit_id__ = commit_id = 'g81767e831'

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

{gridstate-2.3.0 → gridstate-2.4.0}/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.0}/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.0}/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.0}/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.0/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",
+]

{gridstate-2.3.0 → gridstate-2.4.0}/gridstate/pipeline/config.py

@@ -94,6 +94,19 @@ class PipelineConfig:
         label="Нормализация X короткозамыкателей",
         help="volt-aware X_pu для R=X=0 ветвей (убирает β-выбросы dV_max на LV).",
     )
+    breaker_x_pu: float | None = _param(
+        None,
+        group=_G_INPUT,
+        label="Breaker X, p.u.",
+        control="number",
+        min=1e-6,
+        max=1e-1,
+        depends={"normalize_breakers": True},
+        help="X of a breaker branch given by the input format's marker (R=0, X=1 Ohm). "
+        "Unset (default): X = 110·min_x·Vnom Ohm with min_x = 4e-6 (≈0.044/Vnom p.u.: "
+        "8.8e-5 at 500 kV, 4e-4 at 110 kV). A number: that X in p.u. on any voltage "
+        "class. Breaker branches with any other X are taken from the model as they are.",
+    )
     apply_voltage_nominal: bool = _toggle(
         False,
         group=_G_INPUT,
@@ -372,6 +385,17 @@ class PipelineConfig:
         max=500,
         help="default региональной модели 80.",
     )
+    implausible_v_ratio: float = _param(
+        0.3,
+        group=_G_EST,
+        label="Implausible V/Vnom",
+        control="number",
+        min=0.0,
+        max=0.9,
+        help="A solved state with V/Vnom below this at any node is marked not converged "
+        "and logged with hints (e.g. the low-voltage root at a node whose V is barely "
+        "observable). 0 disables the check.",
+    )
     kkt_solver: str = _param(
         "auto",
         group=_G_EST,

{gridstate-2.3.0 → gridstate-2.4.0}/gridstate/pipeline/passes.py

@@ -84,6 +84,7 @@ def _estimate_kwargs(cfg: PipelineConfig, *, init: str, **overrides: Any) -> dic
         "reconcile_balance": cfg.reconcile_balance,
         "reconcile_respect_bounds": cfg.reconcile_respect_bounds,
         "success_policy": cfg.success_policy,
+        "implausible_v_ratio": cfg.implausible_v_ratio,
     }
     kw.update(overrides)
     if cfg.algorithm in ("ipm", "ipm_pd"):

{gridstate-2.3.0 → gridstate-2.4.0}/gridstate/pipeline/preparation.py

@@ -46,7 +46,7 @@ from gridstate.topology import (
 
 
 def _s_normalize_breakers(ctx: _Ctx) -> dict:
-    return dict(normalize_breaker_reactance(ctx.model) or {})
+    return dict(normalize_breaker_reactance(ctx.model, eps_pu=ctx.cfg.breaker_x_pu) or {})
 
 
 def _s_voltage_nominal(ctx: _Ctx) -> dict:

{gridstate-2.3.0 → gridstate-2.4.0}/gridstate/post_processing.py

@@ -34,6 +34,7 @@ from gridstate.algebra.base import (
     BaseAlgebra,
 )
 from gridstate.bounds import is_reactive_only_generation, resolve_bounds
+from gridstate.load_characteristics import QUANTITY_P, QUANTITY_Q, segment_factor, segment_plan
 from gridstate.measurement_ids import ANTI_OVERSHOOT_ID_BASE, IdAllocator
 from gridstate.preprocessing.meas_rows import pseudo_node_measurement
 from gridstate.resolve_pass import (
@@ -618,6 +619,14 @@ def apply_load_characteristic(model: Working) -> dict[str, int]:
     no binding). For PQ-const models (a0=1, a1=a2=0, b0=1, b1=b2=0) the recomputation
     yields exactly ``load_*_nominal``.
 
+    A characteristic with rows in ``load_characteristic_segments`` for P (resp.
+    Q) is piecewise: the segment containing ``V_pu`` (a value on a boundary
+    belongs to the lower segment) replaces the quadratic P (resp. Q) row, with
+    a polynomial up to ``V_pu⁴`` (see :mod:`gridstate.load_characteristics`).
+    A piecewise P (Q) is applied only where the nominal ``load_p`` (``load_q``)
+    is positive; elsewhere the estimate is kept. The quadratic rows keep their
+    previous behaviour.
+
     Applied **only in the WLS mode** (see ``gridstate/api.py::estimate``)
     after ``write_node_estimates_from_inj``. The IPM box vars already account for
     V at the final state — no repeated recomputation is needed.
@@ -637,6 +646,12 @@ def apply_load_characteristic(model: Working) -> dict[str, int]:
               ``load_characteristics`` table (a dangling reference).
             * ``no_load_models`` — 1 if the model has no
               ``load_characteristics`` table (then zeros are returned).
+            * ``piecewise_p`` / ``piecewise_q`` — loads recomputed through a
+              piecewise P / Q characteristic.
+
+    Raises:
+        ValueError: ``load_characteristic_segments`` violates the contract
+            (unknown ``load_model_id``, bad ``quantity``, non-increasing ``v_lo``).
     """
     out = {
         "updated": 0,
@@ -644,6 +659,8 @@ def apply_load_characteristic(model: Working) -> dict[str, int]:
         "skipped_no_load": 0,
         "skipped_bad_sxn": 0,
         "no_load_models": 0,
+        "piecewise_p": 0,
+        "piecewise_q": 0,
     }
 
     # The source of the load-characteristic coefficients is the ``load_characteristics`` table; nodes carry
@@ -662,6 +679,9 @@ def apply_load_characteristic(model: Working) -> dict[str, int]:
     b0 = np.asarray(coeff["coeff_q_b0"], dtype=np.float64)
     b1 = np.asarray(coeff["coeff_q_b1"], dtype=np.float64)
     b2 = np.asarray(coeff["coeff_q_b2"], dtype=np.float64)
+    seg_coll = getattr(model, "load_characteristic_segments", None)
+    seg_arr = seg_coll.to_numpy() if seg_coll is not None else None
+    plan = segment_plan(seg_arr, n_lm) if seg_arr is not None else {}
 
     for row in nodes_arr:
         if not bool(row["status"]):
@@ -699,6 +719,20 @@ def apply_load_characteristic(model: Working) -> dict[str, int]:
 
         load_p_est = load_p_nom * factor_p
         load_q_est = load_q_nom * factor_q
+        seg_p = plan.get((idx, QUANTITY_P))
+        if seg_p is not None:
+            if load_p_nom > 0.0:
+                load_p_est = load_p_nom * segment_factor(*seg_p, v_pu)
+                out["piecewise_p"] += 1
+            else:
+                load_p_est = float(row["load_p_estimated"])
+        seg_q = plan.get((idx, QUANTITY_Q))
+        if seg_q is not None:
+            if load_q_nom > 0.0:
+                load_q_est = load_q_nom * segment_factor(*seg_q, v_pu)
+                out["piecewise_q"] += 1
+            else:
+                load_q_est = float(row["load_q_estimated"])
 
         try:
             model.nodes.update(