gridstate 2.7.0__tar.gz → 2.9.0__tar.gz

{gridstate-2.7.0 → gridstate-2.9.0}/.gitignore

@@ -100,3 +100,6 @@ tests/test_data/**/*.log
 
 # Local-only specs / extracted material
 .specs/
+
+# Library: no lock file in the repository
+uv.lock

{gridstate-2.7.0 → gridstate-2.9.0}/CHANGELOG.md

@@ -9,6 +9,62 @@ 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.9.0 (2026-10-18)
+
+### Feat
+
+- `pseudo_voltage_scope` (`add_pseudo_measurements(voltage_scope=...)`): the
+  nodes whose pseudo-V prior keeps its σ. `"all"` (default) keeps the current
+  behavior. `"generation"` keeps it only at the slack and the nodes with
+  generation (`exist_gen` or an active generator); elsewhere the prior variance
+  is multiplied by `v_out_of_scope_loose_factor` (default 1e4, σ × 100) and the
+  prior stays for observability only. A prior at the nominal V on a load node
+  without a V measurement pulls its estimate down, and the solver makes up the
+  difference with the load Q. `"none"` loosens every pseudo-V prior, the slack
+  and the generation nodes included: V is then held by the network, the
+  measurements and the voltage limits (meant for `ipm` / `ipm_pd`). The step
+  reports `v_priors_loose` in both modes.
+
+### Fix
+
+- The UI manifest showed the IPM settings (balance modes, balance weights and
+  the BUS-equivalent prior) only for `algorithm="ipm"`, although `ipm_pd` uses
+  them too. Their `depends` is now `{"algorithm": ["ipm", "ipm_pd"]}`: a list
+  value in `depends` means "one of". `ipm_trust_region_scope` acts in the
+  primal solver only and keeps `{"algorithm": "ipm"}`.
+
+## v2.8.0 (2026-10-18)
+
+### Behavior changes
+
+- `init="flat"` starts V consistent with the transformer ratios instead of
+  1 p.u. everywhere: `log V` from a least squares over the branches
+  (`log V_to − log V_from = −log k`, weight `1/|z|`, `log V_slack = 0`). A node
+  whose nominal voltage does not match its transformer ratio (or an off-nominal
+  tap on a low-impedance branch) no longer starts with a mismatch of hundreds
+  of p.u. Applies to every algorithm; without off-nominal ratios the start is
+  unchanged. WLS on an ill-conditioned model may converge to a neighbouring
+  solution (on the test models p95 |ΔV| against the reference within 0.05 kV).
+- `ipm_pd` voltage guard on by default (`ipm_voltage_guard` /
+  `voltage_guard`, ignored by other algorithms): every node V is kept within a
+  box from its `voltage_min` / `voltage_max` (unset or implausible limits fall
+  back to 0.55 / 1.8 p.u., 0.7–1.5 p.u. with neither set) and one step changes
+  V by at most 20 %, an angle by at most 0.6 rad and a branch angle difference
+  by at most 0.35 rad. Where a node limit is active the estimate sits on it.
+
+### Fix
+
+- `ipm_pd` with the global hard balance no longer collapses a generator node
+  into the low-voltage power-flow branch from a flat start (V → 0, the node
+  angle undetermined, a formally converged V ≈ 0.2 p.u.).
+
+### Feat
+
+- `solve_ipm_pd`: `state_box_*` (barrier boxes on state coordinates that stay
+  under the trust region and the stopping test, without box damping) and the
+  `step_rel_*` / `step_abs_*` / `step_diff_*` step limits.
+- `gridstate.state.tap_consistent_voltages`.
+
 ## v2.7.0 (2026-10-18)
 
 ### Behavior changes

{gridstate-2.7.0 → gridstate-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridstate
-Version: 2.7.0
+Version: 2.9.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.7.0 → gridstate-2.9.0}/gridstate/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.7.0'
-__version_tuple__ = version_tuple = (2, 7, 0)
+__version__ = version = '2.9.0'
+__version_tuple__ = version_tuple = (2, 9, 0)
 
-__commit_id__ = commit_id = 'g9810ca9e9'
+__commit_id__ = commit_id = 'gaa9a1ec6e'

{gridstate-2.7.0 → gridstate-2.9.0}/gridstate/algorithms/ipm_pd.py

@@ -172,6 +172,37 @@ class _Linearization:
         return dx, ds_l, ds_u, dy_l, dy_u, dlam
 
 
+def _step_cap(
+    dx: np.ndarray,
+    x: np.ndarray,
+    rel_idx: np.ndarray,
+    rel_max: float,
+    abs_idx: np.ndarray,
+    abs_max: float,
+    pair_i: np.ndarray,
+    pair_j: np.ndarray,
+    diff_max: float,
+) -> float:
+    """Largest primal step length allowed by the per-coordinate step limits."""
+    cap = math.inf
+    if rel_max > 0.0 and rel_idx.size:
+        d = np.abs(dx[rel_idx])
+        lim = rel_max * np.abs(x[rel_idx])
+        k = d > 0.0
+        if k.any():
+            cap = min(cap, float(np.min(lim[k] / d[k])))
+    if abs_max > 0.0 and abs_idx.size:
+        d_max = float(np.max(np.abs(dx[abs_idx])))
+        if d_max > 0.0:
+            cap = min(cap, abs_max / d_max)
+    if diff_max > 0.0 and pair_i.size:
+        dz = np.append(dx, 0.0)
+        d_max = float(np.max(np.abs(dz[pair_i] - dz[pair_j])))
+        if d_max > 0.0:
+            cap = min(cap, diff_max / d_max)
+    return cap
+
+
 @dataclass
 class _Merit:
     """The merit ``φ`` of one iteration (see the module docstring); ``mu`` is the target ``σμ``."""
@@ -249,6 +280,15 @@ def solve_ipm_pd(
     eq_prox: float = 1e-9,
     box_prox: float = 1e-6,
     box_prox_max: float = 1e-2,
+    state_box_idx: np.ndarray | None = None,
+    state_box_lo: np.ndarray | None = None,
+    state_box_hi: np.ndarray | None = None,
+    step_rel_idx: np.ndarray | None = None,
+    step_rel_max: float = 0.0,
+    step_abs_idx: np.ndarray | None = None,
+    step_abs_max: float = 0.0,
+    step_diff_pairs: tuple[np.ndarray, np.ndarray] | None = None,
+    step_diff_max: float = 0.0,
 ) -> IPMResult:
     """Mehrotra predictor-corrector IPM (see the module docstring).
 
@@ -297,6 +337,17 @@ def solve_ipm_pd(
             conflicts into the residuals and make this markedly worse. ``0``
             reweights to the end.
         kkt_solver: Newton-system solver (``None`` — scipy).
+        state_box_idx, state_box_lo, state_box_hi: barrier boxes on state
+            coordinates (e.g. V). Unlike ``box_idx`` they stay under the trust
+            region and the stopping test and get no box damping: the box only
+            keeps the iteration away from an inadmissible region (V → 0, where
+            the node angle is undetermined).
+        step_rel_idx, step_rel_max: ``|αp·Δx_i| ≤ step_rel_max·|x_i|`` on these
+            coordinates (``0`` — off).
+        step_abs_idx, step_abs_max: ``|αp·Δx_i| ≤ step_abs_max`` (``0`` — off).
+        step_diff_pairs, step_diff_max: ``|αp·(Δx_i − Δx_j)| ≤ step_diff_max`` for
+            each pair ``(i, j)``; an index ``-1`` stands for a fixed zero (the
+            slack angle). ``0`` — off.
         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
@@ -335,6 +386,28 @@ def solve_ipm_pd(
             raise ValueError("box_lo/box_hi contain pairs with lo >= hi")
     else:
         b_lo = b_hi = np.zeros(0)
+    n_var_box = box_idx.size
+    if state_box_idx is not None and np.size(state_box_idx):
+        if state_box_lo is None or state_box_hi is None:
+            raise ValueError("state_box_lo and state_box_hi are required with state_box_idx")
+        sb_lo = np.asarray(state_box_lo, dtype=np.float64)
+        sb_hi = np.asarray(state_box_hi, dtype=np.float64)
+        if np.any(sb_lo >= sb_hi):
+            raise ValueError("state_box_lo/state_box_hi contain pairs with lo >= hi")
+        box_idx = np.concatenate([box_idx, np.asarray(state_box_idx, dtype=np.int64)])
+        b_lo = np.concatenate([b_lo, sb_lo])
+        b_hi = np.concatenate([b_hi, sb_hi])
+    var_box_idx = box_idx[:n_var_box]
+    rel_idx = np.asarray(step_rel_idx if step_rel_idx is not None else [], dtype=np.int64)
+    abs_idx = np.asarray(step_abs_idx if step_abs_idx is not None else [], dtype=np.int64)
+    if step_diff_pairs is not None:
+        # -1 -> the appended zero coordinate.
+        pair_i = np.asarray(step_diff_pairs[0], dtype=np.int64)
+        pair_j = np.asarray(step_diff_pairs[1], dtype=np.int64)
+        pair_i = np.where(pair_i < 0, n, pair_i)
+        pair_j = np.where(pair_j < 0, n, pair_j)
+    else:
+        pair_i = pair_j = np.zeros(0, dtype=np.int64)
     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:
@@ -386,7 +459,8 @@ def solve_ipm_pd(
     )
 
     tr_mask = np.ones(n, dtype=bool)
-    tr_mask[box_idx] = False
+    tr_mask[var_box_idx] = False
+    prox_on = np.arange(nb) < n_var_box
     tr_pos = np.flatnonzero(tr_mask)
     limiters: dict[int, int] = {}
     limiting_rows: dict[int, int] = {}
@@ -456,7 +530,9 @@ 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] + max(eq_prox_abs, box_scale * w_median)
+        diag[box_idx] = d_k[:nb] + np.where(
+            prox_on, max(eq_prox_abs, box_scale * w_median), eq_prox_abs
+        )
         # Stationarity residual of the current point (for reporting).
         y_dual = np.zeros(nb + mb_rows.size)
         y_dual[il] += y_l
@@ -568,6 +644,14 @@ def solve_ipm_pd(
         # 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
+        # The step limits shorten the step like the search below, after
+        # step_inf has measured the Newton step.
+        a_p = min(
+            a_p,
+            _step_cap(
+                dx, x, rel_idx, step_rel_max, abs_idx, step_abs_max, pair_i, pair_j, step_diff_max
+            ),
+        )
         a_full = a_p
         r_new = None
         # A direction that does not descend (inconsistent slacks of a nonlinear

{gridstate-2.7.0 → gridstate-2.9.0}/gridstate/api.py

@@ -55,6 +55,7 @@ from gridstate.state import (
     flat_start,
     flat_start_with_box,
     pack,
+    tap_consistent_voltages,
     unpack,
     unpack_full,
 )
@@ -120,7 +121,9 @@ def estimate(
             ``"ipm_pd"`` (the same problem by the primal-dual Mehrotra
             predictor-corrector, :mod:`gridstate.algorithms.ipm_pd`).
         init: initial guess strategy:
-            - ``"flat"`` — V=1 p.u., δ=0 for all nodes;
+            - ``"flat"`` — δ=0 for all nodes, V consistent with the
+              transformer ratios (:func:`gridstate.state.tap_consistent_voltages`;
+              1 p.u. without off-nominal ratios);
             - ``"results"`` — take the current ``voltage_magnitude``/``voltage_angle``
               from ``model``;
             - ``"slack"`` — V=V_slack for all nodes, δ=0.
@@ -651,7 +654,9 @@ def _initial_state_from_mode(
 ) -> np.ndarray:
     """``e_init`` of the ``init`` strategy alone."""
     if init == "flat":
-        return flat_start(layout)
+        e = flat_start(layout)
+        e[layout.offset_v : layout.offset_v + layout.n_bus] = tap_consistent_voltages(network_pu)
+        return e
 
     if init == "results":
         nodes_arr = model.nodes.to_numpy()
@@ -684,6 +689,66 @@ def _initial_state_from_mode(
     raise ValueError(f"Unknown init mode init={init!r}")
 
 
+# Voltage guard of ipm_pd (``voltage_guard=True``): node V box in p.u. of the
+# nominal voltage and the per-iteration step limits.
+_VG_LO_MIN = 0.5  # voltage_min below this share of nominal is ignored ...
+_VG_LO_FALLBACK = 0.55  # ... and replaced by this
+_VG_HI_MAX = 2.0  # voltage_max above this share of nominal is ignored ...
+_VG_HI_FALLBACK = 1.8  # ... and replaced by this
+_VG_BOTH_UNSET = (0.7, 1.5)  # neither limit set
+_VG_V_STEP_REL = 0.2  # |αp·ΔV| ≤ 0.2·V
+_VG_DELTA_STEP = 0.6  # |αp·Δδ| ≤ 0.6 rad
+_VG_BRANCH_DELTA_STEP = 0.35  # |αp·(Δδ_i − Δδ_j)| ≤ 0.35 rad over a branch
+
+
+def _voltage_guard_kwargs(
+    model: Working, network_pu: NetworkPU, layout: StateLayout
+) -> dict[str, Any]:
+    """``solve_ipm_pd`` kwargs of the voltage guard: V boxes and step limits.
+
+    The box of a node comes from its ``voltage_min`` / ``voltage_max`` (kV): a
+    limit that is unset (0) or implausible (below half / above twice the
+    nominal) falls back to 0.55 / 1.8 p.u.; with neither limit set the box is
+    0.7…1.5 p.u. It keeps the iteration out of the collapsed region (V → 0,
+    where the node angle is undetermined); the step limits keep one Newton
+    step from crossing into it.
+    """
+    nodes = model.nodes.to_numpy()
+    id_to_pos = id_to_pos_map(network_pu.bus_ids)
+    n = network_pu.n_bus
+    umin = np.zeros(n)
+    umax = np.zeros(n)
+    for row in nodes[nodes["status"]]:
+        pos = id_to_pos.get(int(row["id"]))
+        if pos is not None:
+            umin[pos] = float(row["voltage_min"])
+            umax[pos] = float(row["voltage_max"])
+    vn = np.asarray(network_pu.bus_vn_kv, dtype=np.float64)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        lo_pu = np.where(vn > 0, umin / vn, 0.0)
+        hi_pu = np.where(vn > 0, umax / vn, 0.0)
+    lo = np.where((umin > 0) & (lo_pu >= _VG_LO_MIN), lo_pu, _VG_LO_FALLBACK)
+    hi = np.where((umax > 0) & (hi_pu <= _VG_HI_MAX), hi_pu, _VG_HI_FALLBACK)
+    unset = (umin <= 0) & (umax <= 0)
+    lo[unset], hi[unset] = _VG_BOTH_UNSET
+    bad = lo >= hi
+    lo[bad], hi[bad] = _VG_LO_FALLBACK, _VG_HI_FALLBACK
+    v_idx = np.arange(layout.offset_v, layout.offset_v + n, dtype=np.int64)
+    delta_of = np.full(n, -1, dtype=np.int64)
+    delta_of[layout.non_slack_idx] = layout.offset_delta + np.arange(n - 1)
+    return {
+        "state_box_idx": v_idx,
+        "state_box_lo": lo,
+        "state_box_hi": hi,
+        "step_rel_idx": v_idx,
+        "step_rel_max": _VG_V_STEP_REL,
+        "step_abs_idx": delta_of[layout.non_slack_idx],
+        "step_abs_max": _VG_DELTA_STEP,
+        "step_diff_pairs": (delta_of[network_pu.from_idx], delta_of[network_pu.to_idx]),
+        "step_diff_max": _VG_BRANCH_DELTA_STEP,
+    }
+
+
 def _run_ipm(
     model: Working,
     network_pu: NetworkPU,
@@ -712,6 +777,7 @@ def _run_ipm(
     role_estimates: dict[int, float] | None = None,
     hint_iterations: int = 100,
     huber_threshold: str = "fixed",
+    voltage_guard: bool = True,
     **ipm_kwargs: Any,
 ) -> IPMResult:
     """IPM mode: extends the state vector with box-vars and solves the primal log-barrier WLS.
@@ -751,6 +817,10 @@ def _run_ipm(
     than ``hint_iterations`` iterations (``0`` — no iteration trigger) logs a
     WARNING with convergence hints (:mod:`gridstate.ipm_hints`).
 
+    ``voltage_guard`` (``"ipm_pd"`` only, ignored by ``"ipm"``): node V boxes
+    from ``voltage_min`` / ``voltage_max`` and per-step limits on V/δ (see
+    :func:`_voltage_guard_kwargs`).
+
     ``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
@@ -866,6 +936,7 @@ def _run_ipm(
             huber_warmup_iters=2,
             huber_adaptive_k=0.0 if huber_threshold == "fixed" else 2.0,
             kkt_solver=kkt,
+            **(_voltage_guard_kwargs(model, network_pu, layout_ipm) if voltage_guard else {}),
         )
         pd_result = result
         if result.solve_status is not SolveStatus.KKT:

{gridstate-2.7.0 → gridstate-2.9.0}/gridstate/pipeline/config.py

@@ -10,7 +10,9 @@ the UI manifest (:func:`gridstate.pipeline.manifest`):
 * ``help``: hint text;
 * ``control``: UI control hint (``"switch"`` / ``"number"`` / ``"select"``);
 * ``min`` / ``max``: bounds (numbers); ``choices``: allowed values (select);
-* ``depends``: show only when another field equals a value (e.g. ``algorithm=ipm``).
+* ``depends``: show only when every named field matches: a scalar value means
+  equality, a list means one of its values (e.g. ``algorithm`` in
+  ``["ipm", "ipm_pd"]``).
 
 ``choices`` / ``min`` / ``max`` are enforced: :meth:`PipelineConfig.validate`
 runs on construction and at the start of a run.
@@ -79,6 +81,8 @@ _G_MODE = "Режим (нагрузка/генерация)"
 _G_CASCADE = "Каскад и статусы"
 _G_PSEUDO = "Псевдо-измерения"
 _G_EST = "Оценка состояния"
+# Algorithms that read the IPM settings (``depends`` of the IPM group).
+_IPM_SOLVERS = ["ipm", "ipm_pd"]
 _G_IPM = "IPM"
 _G_POST = "Пост-обработка"
 
@@ -313,6 +317,24 @@ class PipelineConfig:
             "measurements."
         ),
     )
+    pseudo_voltage_scope: Literal["all", "generation", "none"] = _param(
+        "all",
+        group=_G_PSEUDO,
+        label="Узлы с псевдо-U",
+        control="select",
+        choices=["all", "generation", "none"],
+        depends={"add_pseudo": True},
+        help="Nodes without a V measurement whose pseudo-V prior keeps its σ. "
+        "all — every node (default); generation — only the slack and the nodes "
+        "with generation (exist_gen or an active generator), which can hold their "
+        "voltage. Elsewhere the prior is loosened (σ × 100) and stays for "
+        "observability only: a prior at the nominal V on a load node pulls its "
+        "estimate down and the solver makes up the difference with the load Q. "
+        "none — every pseudo-V prior is loosened, the slack and the generation "
+        "nodes included: V is held by the network, the measurements and the "
+        "voltage limits. Meant for ipm/ipm_pd (their barrier keeps V within the "
+        "limits); with WLS V of an unmeasured area rests on the loosened prior.",
+    )
     unobservable_v_sigma_frac: float = _param(
         0.02,
         group=_G_PSEUDO,
@@ -502,7 +524,7 @@ class PipelineConfig:
         control="number",
         min=1e-4,
         max=1e6,
-        depends={"algorithm": "ipm"},
+        depends={"algorithm": _IPM_SOLVERS},
         help="Меньше → balance мягче. default 0.1. Soft balance only (ipm_balance_mode=soft).",
     )
     ipm_balance_mode: str = _param(
@@ -511,7 +533,7 @@ class PipelineConfig:
         label="Balance mode",
         control="select",
         choices=["soft", "hard"],
-        depends={"algorithm": "ipm"},
+        depends={"algorithm": _IPM_SOLVERS},
         help="soft — the nodal P/Q balance is a weighted pseudo-measurement "
         "(ipm_balance_weight_factor); hard — an equality constraint enforced with "
         "Lagrange multipliers (ipm: method of multipliers; ipm_pd: regularised KKT) "
@@ -552,6 +574,16 @@ class PipelineConfig:
         "min_value/max_value set is kept within [min_value, max_value] as an "
         "inequality of the interior-point problem. Default OFF.",
     )
+    ipm_voltage_guard: bool = _toggle(
+        True,
+        group=_G_IPM,
+        label="Voltage guard (ipm_pd)",
+        help="ipm_pd only (ignored otherwise): every node V is kept within a box "
+        "from its voltage_min/voltage_max (unset or implausible limits fall back "
+        "to 0.55/1.8 p.u. of nominal, 0.7..1.5 with neither set), and one step "
+        "changes V by at most 20 %, an angle by at most 0.6 rad and a branch "
+        "angle difference by at most 0.35 rad. Default ON.",
+    )
     ipm_injection_roles: bool = _toggle(
         False,
         group=_G_IPM,
@@ -593,7 +625,7 @@ class PipelineConfig:
         control="number",
         min=0.0,
         max=1e6,
-        depends={"algorithm": "ipm"},
+        depends={"algorithm": _IPM_SOLVERS},
         help="Nodes whose injection range is fully set by their generation/load boxes get a "
         "balance row with variance median(σ²_data) / factor. The box carries the node's "
         "freedom; a loose balance only hides data conflicts as an imbalance. 0 — off.",
@@ -605,7 +637,7 @@ class PipelineConfig:
         control="number",
         min=0.0,
         max=1e6,
-        depends={"algorithm": "ipm"},
+        depends={"algorithm": _IPM_SOLVERS},
         help="Transit nodes (no exist_gen/exist_load) get a balance row with variance "
         "median(σ²_data) / factor. Their injection is known to be zero; a loose balance "
         "turns data conflicts into a fictitious injection. 0 — off.",
@@ -616,7 +648,7 @@ class PipelineConfig:
         label="Balance mode of transit nodes",
         control="select",
         choices=["soft", "hard"],
-        depends={"algorithm": "ipm"},
+        depends={"algorithm": _IPM_SOLVERS},
         help="soft — the balance of a transit node (no exist_gen/exist_load) is a "
         "weighted row like the others (ipm_transit_balance_weight_factor); hard — an "
         "equality constraint to ipm_transit_balance_tol_p_mw / _q_mvar, the other "
@@ -649,7 +681,7 @@ class PipelineConfig:
         control="number",
         min=0.0,
         max=10.0,
-        depends={"algorithm": "ipm"},
+        depends={"algorithm": _IPM_SOLVERS},
         help="default 0.01 p.u.².",
     )
     ipm_trust_region_scope: str = _param(
@@ -659,7 +691,8 @@ class PipelineConfig:
         control="select",
         choices=["all", "state"],
         depends={"algorithm": "ipm"},
-        help="Coordinates whose Newton step is bounded by the trust region (0.5 p.u.). "
+        help="Primal ipm only (with ipm_pd: its fallback solve). "
+        "Coordinates whose Newton step is bounded by the trust region (0.5 p.u.). "
         "all — the whole state vector, generation/load box variables included "
         "(the previous default); state (default) — V and δ only: a box variable "
         "that has to move far no longer shrinks the V/δ step (boxes stay protected "

{gridstate-2.7.0 → gridstate-2.9.0}/gridstate/pipeline/manifest.py

@@ -26,6 +26,11 @@ def manifest(config: PipelineConfig | type[PipelineConfig] | None = None) -> dic
     toggle list), grouped by ``group``. It takes the defaults from here instead
     of hard-coding them.
 
+    ``depends`` maps field names to the values under which the control is shown;
+    every entry must match. A scalar value matches by equality, a list matches
+    any of its values: ``{"algorithm": ["ipm", "ipm_pd"]}`` shows the control
+    for both IPM solvers.
+
     ``config`` selects the source of defaults and of the iterated fields:
 
     * ``None`` (default) -- ``PipelineConfig()``, the library defaults;

{gridstate-2.7.0 → gridstate-2.9.0}/gridstate/pipeline/passes.py

@@ -61,6 +61,7 @@ def _ipm_kwargs(cfg: PipelineConfig) -> dict:
         "balance_tol_q_mvar": cfg.ipm_balance_tol_q_mvar,
         "fixed_injection_from_input": cfg.ipm_fixed_injection_from_input,
         "measurement_bounds": cfg.ipm_measurement_bounds,
+        "voltage_guard": cfg.ipm_voltage_guard,
         "injection_roles": cfg.ipm_injection_roles,
         "hint_iterations": cfg.ipm_hint_iterations,
         "huber_threshold": cfg.ipm_huber_threshold,

{gridstate-2.7.0 → gridstate-2.9.0}/gridstate/pipeline/preparation.py

@@ -236,6 +236,7 @@ def _s_add_pseudo(ctx: _Ctx) -> dict:
             unmeasured_gen_p_nodes=ctx.released_injections.get("P", frozenset()),
             unmeasured_gen_q_nodes=ctx.released_injections.get("Q", frozenset()),
             loosen_unknown_load=ctx.cfg.loosen_unknown_load_pseudo,
+            voltage_scope=ctx.cfg.pseudo_voltage_scope,
         )
         or {}
     )

{gridstate-2.7.0 → gridstate-2.9.0}/gridstate/preprocessing/pseudo_measurements.py

@@ -5,7 +5,10 @@ unobservable, so the gain matrix becomes singular. To avoid this, for every
 active node without a `V/P_inj/Q_inj` measurement we add a weak prior:
 
 * `V ≈ V_nominal` (either `V_magnitude` from the loaded model, or `vzd`
-  for a PV node) with σ=10% of Vnom (slack 0.1%, PV 5%).
+  for a PV node) with σ=10% of Vnom (slack 0.1%, PV 5%). With
+  ``voltage_scope="generation"`` the V prior of a node that cannot hold its
+  voltage (no generation, not the slack) is loosened to an observability prior;
+  with ``voltage_scope="none"`` every V prior is.
 * `P_inj = pg - pn`, `Q_inj = qg - qn` from the node table (for transit
   nodes this gives 0). σ depends on the node type and empty-model detection.
 """
@@ -13,7 +16,7 @@ active node without a `V/P_inj/Q_inj` measurement we add a weak prior:
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 import numpy as np
 
@@ -70,6 +73,11 @@ class PseudoMeasConfig:
     # Loosen the P/Q injection prior of a node with load but no load data (no
     # box, nothing materialized) when the injection is fixed by measurements.
     loosen_unknown_load: bool = False
+    # Nodes whose V prior keeps its σ (generation and slack nodes, or none);
+    # ``None`` = every node. Outside it the V prior variance is multiplied by
+    # ``v_out_of_scope_loose_factor``.
+    v_scope_nodes: frozenset[int] | None = None
+    v_out_of_scope_loose_factor: float = 1e4
 
 
 def _generation_range_variance(row: np.void, lo_col: str, hi_col: str, fallback: float) -> float:
@@ -216,6 +224,7 @@ def _build_pseudo_rows(
     n_zinj_added = 0
     n_unobs_v = 0
     n_unknown_load = 0
+    n_v_loose = 0
 
     new_rows: list[dict] = []
     for row in nodes_arr:
@@ -261,6 +270,11 @@ def _build_pseudo_rows(
                 # nodes (degree=1, empty-model P_inj σ=100) 10% allowed the SE
                 # to drag V down to 0.3-0.5 p.u.: the pseudo-V did not hold the anchor.
                 sigma = (0.05 * vn) ** 2
+            if config.v_scope_nodes is not None and nid not in config.v_scope_nodes:
+                # Outside the scope a prior at the nominal or input V would pull
+                # the estimate there; keep it for observability only.
+                sigma *= config.v_out_of_scope_loose_factor
+                n_v_loose += 1
             new_rows.append(
                 pseudo_node_measurement(ids.next(), nid, KIND_VOLTAGE, v_prior_value, float(sigma))
             )
@@ -335,6 +349,8 @@ def _build_pseudo_rows(
         "unobservable_v_tight": n_unobs_v,
         "unknown_load_loose": n_unknown_load,
     }
+    if config.v_scope_nodes is not None:
+        stats["v_priors_loose"] = n_v_loose
     return new_rows, stats
 
 
@@ -411,6 +427,8 @@ def add_pseudo_measurements(
     unmeasured_gen_p_nodes: frozenset[int] = frozenset(),
     unmeasured_gen_q_nodes: frozenset[int] = frozenset(),
     loosen_unknown_load: bool = False,
+    voltage_scope: Literal["all", "generation", "none"] = "all",
+    v_out_of_scope_loose_factor: float = 1e4,
 ) -> dict:
     """Augment the model with pseudo-measurements to remove under-observability.
 
@@ -480,10 +498,26 @@ def add_pseudo_measurements(
             at both ends of every incident branch) that prior's variance is
             multiplied by ``boundary_inj_loose_factor``. Typical nodes: cut ends of
             lines leaving the model and substations of neighbouring systems.
+        voltage_scope: nodes whose V prior keeps its σ. ``"all"`` (default):
+            every node. ``"generation"``: only the nodes that can hold their
+            voltage, i.e. the slack and the nodes with generation (``exist_gen``
+            or an active generator); elsewhere the V prior variance is multiplied
+            by ``v_out_of_scope_loose_factor``. A V prior at the nominal (or
+            input) V on a load node without a V measurement pulls the estimate
+            there, and the solver makes up the difference with the load Q.
+            ``"none"``: every V prior is loosened, the slack and the generation
+            nodes included; V is then held by the network, the measurements and
+            the voltage limits. Meant for ``ipm`` / ``ipm_pd``, whose barrier
+            keeps V within the limits; WLS has no such bound, and V of a node seen
+            by no measurement rests on the loosened prior alone.
+        v_out_of_scope_loose_factor: variance multiplier of the V prior outside
+            ``voltage_scope``. Default 1e4 (σ × 100) keeps the prior in the
+            system only for observability.
 
     Returns:
         ``{"v_priors_added": N, "zero_inj_added": N, "unobservable_v_tight": N,
-        "unknown_load_loose": N}`` — counters.
+        "unknown_load_loose": N}`` — counters, plus ``"v_priors_loose": N`` with
+        ``voltage_scope`` other than ``"all"``.
     """
     nodes_arr = model.nodes.to_numpy()
     meas_arr = model.measurements.to_numpy()
@@ -496,6 +530,21 @@ def add_pseudo_measurements(
     ):
         node_load_props = extract_node_load_props_from_model(model)
 
+    if voltage_scope not in ("all", "generation", "none"):
+        raise ValueError(
+            f"voltage_scope={voltage_scope!r} is not one of ['all', 'generation', 'none']"
+        )
+    v_scope_nodes: frozenset[int] | None = None
+    if voltage_scope == "generation":
+        gen = model.generators.to_numpy()
+        holds_v = nodes_arr["exist_gen"].astype(bool)
+        holds_v |= nodes_arr["node_type"] == int(NodeType.SLACK)
+        v_scope_nodes = frozenset(
+            nodes_arr["id"][holds_v].tolist() + gen["node_id"][gen["status"].astype(bool)].tolist()
+        )
+    elif voltage_scope == "none":
+        v_scope_nodes = frozenset()
+
     config = PseudoMeasConfig(
         add_zero_injections=add_zero_injections,
         slack_voltage_sigma_frac=slack_voltage_sigma_frac,
@@ -510,6 +559,8 @@ def add_pseudo_measurements(
         unmeasured_gen_p_nodes=frozenset(unmeasured_gen_p_nodes),
         unmeasured_gen_q_nodes=frozenset(unmeasured_gen_q_nodes),
         loosen_unknown_load=loosen_unknown_load,
+        v_scope_nodes=v_scope_nodes,
+        v_out_of_scope_loose_factor=v_out_of_scope_loose_factor,
     )
 
     new_rows, stats = _add_pseudo_measurements_on_arrays(