LightSim2Grid 1.0.0rc2__tar.gz → 1.0.0rc3__tar.gz

{lightsim2grid-1.0.0rc2 → lightsim2grid-1.0.0rc3}/CHANGELOG.rst

@@ -123,6 +123,148 @@ TODO: Levenberg-Marquardt damping (a.k.a. Tikhonov-regularized Newton) : adding
 
 [1.0.0] 2026-xx-yy
 --------------------
+- [FIXED] ``TimeSeriesCPP`` solved each step against an **incomplete injection vector**. It does not
+  use the ``Sbus`` the gridmodel builds: it rebuilds its own, per step, out of the four matrices the
+  caller passes to ``compute_Vs`` -- generator and static-generator ACTIVE power, and load active +
+  reactive power -- plus the hvdc term taken from the grid. But ``LSGrid::fillSbus_me`` stamps rather
+  more than that, and everything else was silently dropped:
+  storage units (active AND reactive: absent altogether), REACTIVE_POWER-mode SVCs (absent
+  altogether), the reactive setpoint of a generator whose ``voltage_regulator_on`` is false, a static
+  generator's reactive setpoint, and -- in DC -- the phase-shifter term
+  ``TrafoContainer::hack_Sbus_for_dc_phase_shifter``. The powerflow converged happily on an injection
+  the caller never asked for; on a 4-bus feeder the individual omissions were worth 0.032, 0.052,
+  0.066 and 0.081 pu of voltage error respectively. DC was affected too, since
+  ``compute_one_powerflow`` falls back to the gridmodel's ``Pbus_`` only when NO complex ``Sbus`` is
+  supplied, which is not the ``TimeSeries`` case.
+  The remainder is now **derived rather than enumerated**: the complete per-unit injection the
+  gridmodel just built (``Sbus_`` in ac, ``Pbus_`` in dc) minus the same reconstruction ``compute_Vs``
+  performs, evaluated at the gridmodel's own target values. What is left over is by construction
+  everything the per-step matrices do not carry, so an element type added to ``fillSbus_me`` later is
+  picked up for free -- an enumeration falling behind is precisely what caused this bug.
+  ``ContingencyAnalysisCPP`` (and ``SecurityAnalysis``, which wraps it) was never affected: it passes
+  the gridmodel's own complete ``Sbus_`` straight to the solver.
+- [ADDED] a stale-solver-state case to ``src/tests/test_batch_voltage_control.cpp``: run ``ac_pf``,
+  then change the grid so a bus leaves the solver (which makes the AC maps stale AND too long, worse
+  than merely empty), then ``dc_pf`` (which rebuilds only the DC maps), then a batch -- which inherits
+  the grid's AC algorithm, since ``LSGrid::change_algorithm`` routes a DC type to the separate
+  ``_dc_algo`` slot and so asking the GRID for DC never switches a batch over. The batch must still
+  reproduce a clean single-shot ``ac_pf``, which it does because it works on a copy of the grid whose
+  copy constructor ``reset()`` the solver state and whose ``prepare_solver_input_base`` rebuilds it
+  under ``tell_all_changed()``. Being a C++ test it runs under the valgrind pass of the C++ suite and
+  the ASan/UBSan + Eigen-assertion builds, where a too-long index that stays inside the heap would
+  still be caught.
+- [ADDED] ``src/tests/test_timeseries_sbus.cpp`` and ``lightsim2grid/tests/test_timeseries_sbus.py``:
+  a one-step time series fed the grid's OWN injections must reproduce ``ac_pf`` / ``dc_pf`` exactly.
+  Covers each dropped element kind separately and all of them together, in ac and in dc, plus a
+  multi-step case (the remainder is constant, so it has to reach every row) and a control grid whose
+  whole injection the per-step matrices already covered. Eight of the nine C++ cases fail without the
+  fix.
+- [FIXED] a generator could not remotely regulate a bus that another generator already
+  regulated *locally* -- the grid was refused outright with
+  ``LSGrid::fill_voltage_control_solver_data: generator N regulates bus X which has no voltage (Vm)
+  unknown`` -- even though the configuration is perfectly well posed. Two machines holding one bus
+  simply form a control group: one bordered voltage row, one reactive unknown each, and a sharing
+  row splitting the reactive duty in proportion to their ``qmax - qmin`` ranges, exactly as two
+  *remote* controllers on one bus already did.
+  The cause was the order in which buses are classified. ``GeneratorContainer::fillpv`` knew how to
+  keep a controller's OWN bus out of the PV set (a remote regulator leaves its own bus PQ), but
+  nothing stopped a LOCAL regulator from claiming a bus that somebody else regulated remotely. That
+  bus then had no ``Vm`` unknown, so ``VoltageControl::register_in`` got ``vm_col == -1`` for it, the
+  group's voltage row was never given its ``+1`` entry, and the row came out structurally EMPTY --
+  a singular Jacobian. The check that refused the grid was really reporting the misclassification,
+  not a property of the configuration.
+  Bus classification now runs the other way round: ``LSGrid::get_group_controlled_buses`` collects
+  every bus an active *remote* generator or an active voltage-mode SVC aims at, ``LSGrid::fillpv_pq``
+  keeps those out of PV, and ``fill_voltage_control_solver_data`` enrols the local regulators sitting
+  on them -- generators and voltage-regulating hvdc converter stations alike -- as members of the
+  group. Buses regulated only by things standing on them are deliberately untouched: several machines
+  sharing a bus and all regulating it locally remains the ordinary PV case, with the per-bus reactive
+  redistribution of ``GeneratorContainer::set_q``.
+  Three configurations start working as a result: a remote controller onto a locally regulated bus,
+  a remote controller onto a slack bus pinned by its own generator (the slack generator joins the
+  group and MultiSlack grants the free ``Vm``), and -- separately, by giving the regulated-bus check
+  the ``has_free_q`` escape hatch the controller-bus check already had -- a remote controller onto a
+  slack bus that nothing pins. Disagreeing setpoints between a local and a remote regulator of one
+  bus are now reported by the group's own check (``conflicting voltage setpoints``) rather than as a
+  bus-classification error.
+  Two things stay refused, on purpose. A remote regulator SHARING ITS OWN BUS with a local regulator
+  has no solution at all: whatever reactive power it injects there is absorbed one-for-one by the
+  machine holding that bus' magnitude, so it has no influence on its remote target -- no
+  reclassification can help, and the "its OWN bus has no reactive (Q) equation" error still fires.
+  Voltage-regulating hvdc converter stations take part on the same footing as generators. A VSC
+  station with ``voltage_regulator_on`` pins its own bus through the very same PV path, so it is
+  enrolled into the group whenever a controller claims that bus -- two new controller kinds,
+  ``VoltageControlSolverData::HVDC_SIDE_1`` / ``HVDC_SIDE_2``, with the hvdc LINE id as ``elem_id``
+  and the solved reactive output written back to the station. Its sharing key is a reactive range in
+  MVAr, the same currency as a generator's, so a mixed generator/station group shares reactive power
+  correctly (a group of a local generator, a remote generator and a station splits ``Q`` three ways
+  by range).
+  Note for voltage-mode SVCs: their regulated bus now leaves the PV path as well, which is what makes
+  the classification uniform, but an SVC still has to be the only controller of its bus in v1 (its
+  sharing key is a susceptance range, not a reactive range, so mixed SVC/generator sharing has no
+  defined semantics yet). Such a grid is therefore still refused -- now by that restriction, which
+  names the real limitation.
+- [ADDED] ``src/tests/test_voltage_control_reclassify.cpp`` and
+  ``lightsim2grid/tests/test_voltage_control_reclassify.py``: the classification rule itself, the
+  newly-supported configurations (including the reactive split, and hvdc stations sharing a bus with
+  generators on either end of the line), the ones that must stay refused, and regression guards that
+  several purely local regulators on one bus -- and a lone voltage-regulating station -- still take
+  the classical PV path and produce bit-identical voltages.
+- [FIXED] remote voltage control (remote-regulating generators and voltage-mode SVCs) and the free
+  ``Vm`` unknown of a distributed-slack participant were **silently ignored** by every batch
+  algorithm -- ``TimeSeriesCPP``, ``ContingencyAnalysisCPP`` and ``SecurityAnalysis``, ie everything
+  going through ``BaseBatchSolverSynch``. The powerflow still converged and still returned plausible
+  voltages, they were just the voltages of a grid with no such regulation: a silent wrong answer, not
+  an error. ``LSGrid::ac_pf`` was unaffected.
+  The NR extensions do not receive their data as solver arguments; they reach back into the
+  ``LSGrid`` through the algorithm's ``lsgrid_ptr`` and read its *member* solver-side labelling
+  (``LSGrid::get_free_vm_slack_solver_buses`` for ``Base``,
+  ``LSGrid::fill_hvdc_droop_solver_data`` for ``Hvdc``,
+  ``LSGrid::fill_voltage_control_solver_data`` for ``VoltageControl``).
+  ``ac_pf``/``dc_pf``/``check_solution`` pass those members straight to ``pre_process_solver``, so
+  they are always current there; the batch algorithms own local mapping vectors and pass those
+  instead, against a private *copy* of the grid whose copy constructor ``reset()`` all of it to
+  empty. ``_pre_process_solver_impl`` wrote only the FORWARD map (``id_me_to_ac_solver_``) back onto
+  the grid, so ``id_ac_solver_to_me_`` and ``slack_bus_id_ac_solver_`` stayed empty -- and empty is
+  indistinguishable from "this grid has no controller": ``fill_voltage_control_solver_data`` returns
+  on its ``nb_bus_solver == 0`` guard and ``get_free_vm_slack_solver_buses`` on its ``slack.empty()``
+  one, both without a word. The sync now covers the reverse map and both slack vectors, AC and DC.
+  The ``Hvdc`` angle-droop extension was never affected: it only ever read the forward map, the one
+  that was already synced (there is now a regression test pinning that too).
+  Two consequences worth knowing about. A grid whose voltage-control configuration is not supported
+  in v1 now raises from ``fill_voltage_control_solver_data`` in the batch path as it always did in
+  the single-shot one, where before it was quietly accepted and solved without the regulation. The
+  restriction is on buses whose voltage magnitude is *already determined* -- a controller may not
+  regulate the slack, nor a PV bus pinned by a local regulator, since neither owns a ``Vm`` unknown
+  for the bordered row to act on; several controllers sharing one regulated bus is fine and always
+  was (one voltage row, one ``Q`` column each, plus a sharing row splitting ``Q`` by
+  ``qmax - qmin``). And under
+  ``ContingencyAnalysis``'s ``handle_disconnected_grid`` mode, a contingency that strands a regulated
+  bus is now reported as a ``DIVERGENCE`` instead of converging with the regulation dropped: bus
+  masking is deliberately a value-only edit that must not touch the ``J`` pattern, so the bordered
+  voltage row survives against a bus the mask pins, and the system has no solution. An honest
+  non-result rather than a confident wrong one.
+- [ADDED] ``src/tests/test_batch_voltage_control.cpp``: solves the same grid single-shot through
+  ``LSGrid::ac_pf`` and through ``TimeSeries`` / ``ContingencyAnalysis``, and requires the voltages
+  to agree -- for a remote-regulating generator, two generators sharing one regulated bus, a
+  voltage-mode SVC (flat and sloped), a free-``Vm`` distributed-slack participant, and an hvdc angle
+  droop.
+- [ADDED] ``TimeSeriesCPP`` / ``ContingencyAnalysisCPP`` (and so ``SecurityAnalysis``, which wraps the
+  latter) gained a string-based ``change_algorithm(name)`` overload and a ``get_algo_name()`` accessor,
+  matching what ``LSGrid`` already had (``AlgorithmSelector::change_algorithm(const std::string&)``) --
+  needed to select a plugin solver, or a built-in with no dedicated ``AlgorithmType`` enum member (eg
+  ``NRRefactorRetry_KLU``), for a batch computation, which was previously impossible: only the
+  enum-based overload was exposed, and ``AlgorithmType::Custom`` (what such solvers collapse onto) is
+  rejected by ``change_algorithm(AlgorithmType)``. Also bound ``available_algorithm_names()`` on both
+  classes for the same reason -- previously only ``available_default_algorithms()`` (the enum-only,
+  plugin-blind list) was exposed.
+- [FIXED] two bugs this exposed, both the same "propagate the algorithm via ``AlgorithmType`` instead of
+  by registry name" mistake: (1) ``BaseBatchSolverSynch``'s constructor inherited the source ``LSGrid``'s
+  AC algorithm via ``get_algo_type()`` (the enum), so constructing a ``TimeSeries`` /
+  ``ContingencyAnalysis`` / ``SecurityAnalysis`` from a grid running a plugin or no-enum-member solver
+  raised immediately; (2) ``ContingencyAnalysis``'s multi-threaded path (``nb_thread > 1``) rebuilt each
+  per-thread solver the same lossy way. Both now propagate by name (``get_algo_name()`` /
+  ``get_algo().get_name()``). See ``test_batch_algorithm_solver_selection.py`` for the regression tests.
 - [ADDED] closed the last two gaps in the benchmark narrative-generation work above:
 
   - ``benchmarks/benchmark_grid_size.py`` gained a ``generate_narrative`` (recycling vs no-recycling,
@@ -1636,6 +1778,73 @@ TODO: Levenberg-Marquardt damping (a.k.a. Tikhonov-regularized Newton) : adding
   before the class was renamed from ``SecurityAnalysis``.
 - [FIXED] translated the last remaining French comments in ``pyproject.toml`` to English,
   for consistency with the rest of the (English-only) documentation and codebase.
+- [ADDED] ``ContingencyAnalysisCPP.violation_threshold`` (mirrored by the python
+  ``ContingencyAnalysis.violation_threshold``): a ``float`` in ``]0., 1.]``, default
+  ``1.0``, applied to every check performed when ``compute_limit_violations`` is ``True``,
+  so that near-limit situations can be reported before they actually breach 100% of a
+  limit. It is the fraction of the usable range still considered acceptable, so lowering it
+  makes every check stricter (more violations reported, never fewer). Each of the three
+  checks owns one interval, running from a "healthy" anchor to the limit that can be
+  violated, and the threshold moves that limit towards its anchor -- one linear
+  interpolation, ``effective_limit = threshold * limit + (1 - threshold) * anchor``, for all
+  three:
+
+  - ``CURRENT``: anchor ``0``, limit ``limit_a`` -- violates when
+    ``value >= threshold * limit_a``. A line's usable range really is ``[0, limit_a]``, so
+    this reduces to plainly scaling the limit;
+  - ``LOW_VOLTAGE``: anchor ``vn_kv``, limit ``vmin_kv`` -- violates when
+    ``v <= threshold * vmin + (1 - threshold) * vn``;
+  - ``HIGH_VOLTAGE``: anchor ``vn_kv``, limit ``vmax_kv`` -- violates when
+    ``v >= threshold * vmax + (1 - threshold) * vn``.
+
+  A voltage bound has no natural "zero" end, which is why the bus nominal voltage is used as
+  its anchor (operating limits are conventionally expressed as +/- x% of it). Anchoring both
+  voltage checks there -- rather than on each other -- keeps them independent: the
+  ``LOW_VOLTAGE`` verdict never depends on ``vmax_kv`` and vice versa. It also means the two
+  effective bounds converge towards the anchor from their own side and can never cross, so
+  no bus is ever reported as both too low and too high (the sole exception being a band
+  fully collapsed onto nominal, ``vmin == vn == vmax``, where a bus sitting exactly at
+  nominal satisfies both and is reported once, as ``LOW_VOLTAGE``). The anchor is the
+  nominal voltage *clamped into* ``[vmin_kv, vmax_kv]``: a band is not required to bracket
+  it -- a 380 kV level declared with an operating range of ``[390, 450]`` kV is ordinary
+  practice on the European 400 kV network -- and clamping keeps each bound moving inwards
+  only, without rejecting such a grid. Where the band does bracket the nominal voltage (the
+  overwhelmingly common case) the clamp does nothing.
+
+  The reported ``LimitViolation.value`` / ``.limit`` are never rescaled (still the value
+  reached and the limit as configured); only the test deciding whether to report is shifted.
+  The default ``1.0`` reproduces the previous, threshold-less behaviour (modulo the strict
+  ``>`` / ``<`` comparisons becoming ``>=`` / ``<=``, which only differ if a value lands
+  exactly on its limit). A value outside ``]0., 1.]`` (or ``NaN``) is rejected. Like
+  ``nb_thread`` / ``handle_disconnected_grid`` this is a plain runtime knob affecting only
+  the next ``compute()``, with one asymmetry: *lowering* it discards any already-computed
+  results (they would under-report), while *raising* it keeps them (a stricter result is a
+  superset of a looser one). Unlike ``compute_limit_violations``, neither case clears the
+  registered contingencies.
+- [ADDED] a bus configured with a minimum voltage above its maximum
+  (``vmin_kv > vmax_kv``, see ``LSGrid.set_bus_voltage_limits``) now raises a
+  ``RuntimeError`` during a ``ContingencyAnalysis`` limit-violation check, instead of being
+  silently reported as an arbitrary one of ``LOW_VOLTAGE`` / ``HIGH_VOLTAGE``. That is a
+  genuine input error, and the only way the two effective voltage bounds can end up crossed
+  (see ``violation_threshold`` above).
+- [ADDED] ``src/tests/test_powerflow_algorithm.cpp``: a C++ (Catch2) test suite for the
+  Newton-Raphson system itself (``src/core/powerflow_algorithm/NRSystem*``) and its
+  ``MultiSlack`` / ``VoltageControl`` / ``Hvdc`` extensions. It drives an ``NRSystem``
+  phase by phase, the way ``NRAlgo::compute_pf`` does, and checks the internal
+  consistency the grid-level tests cannot see: the augmented Jacobian is square and
+  matches ``total_state_variables()``, every bus -> row / column map stays in range and
+  agrees with the ledger's registration pair lists, no Jacobian row or column is
+  structurally empty (which is how an unresolved feature entry shows up), a
+  ``status_droop`` flip changes values but not the sparsity pattern (so a linear solver
+  may reuse its symbolic factorization), bus masking is a pure value-level edit, and
+  ``clear_jacobian`` leaves a system that rebuilds bit-identically.
+- [ADDED] two jobs in ``.github/workflows/sanitizers.yml`` running the C++ (Catch2) test
+  suite under ASan + UBSan and under re-enabled Eigen / libstdc++ assertions
+  (``__SANITIZE=1`` / ``__DEBUG_ASSERTS=1``). The suite already ran under valgrind
+  (``cpp_unit_tests.yml``), but an index that is wrong while still inside its allocation
+  is invisible to both valgrind and ASan -- only the assertion build catches it. The test
+  binary itself (not just ``lightsim2grid_core``) is now compiled and linked with the
+  sanitizer flags, see ``src/tests/CMakeLists.txt``.
 
 [0.13.1]  2026-04-21
 --------------------

{lightsim2grid-1.0.0rc2 → lightsim2grid-1.0.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: lightsim2grid
-Version: 1.0.0rc2
+Version: 1.0.0rc3
 Summary: LightSim2grid implements a c++ backend targeting the Grid2Op platform.
 Author-Email: Benjamin Donnot <benjamin.donnot@rte-france.com>
 Classifier: Development Status :: 4 - Beta

{lightsim2grid-1.0.0rc2 → lightsim2grid-1.0.0rc3}/lightsim2grid/__init__.py

@@ -6,7 +6,7 @@
 # SPDX-License-Identifier: MPL-2.0
 # This file is part of LightSim2grid, LightSim2grid implements a c++ backend targeting the Grid2Op platform.
 
-__version__ = "1.0.0.rc2"
+__version__ = "1.0.0.rc3"
 
 __all__ = [
     "newtonpf",

{lightsim2grid-1.0.0rc2 → lightsim2grid-1.0.0rc3}/lightsim2grid/contingencyAnalysis.py

@@ -232,6 +232,72 @@ class ContingencyAnalysis(object):
         self.computer.compute_limit_violations = val  # this clears the C++-side results / contingencies
         self.clear()  # keep the python-side bookkeeping (contingency order / names) in sync
 
+    @property
+    def violation_threshold(self):
+        """Threshold (a ``float`` in ``]0., 1.]``, default ``1.0``) applied to every
+        limit-violation check performed when `compute_limit_violations` is `True`. It is the
+        fraction of the usable range that is still considered acceptable, so lowering it
+        makes every check stricter (more violations reported, never fewer).
+
+        Each of the three checks owns one interval, running from a "healthy" anchor to the
+        limit that can be violated, and the threshold moves that limit towards its anchor --
+        a linear interpolation, identical for all three::
+
+            effective_limit = threshold * limit + (1 - threshold) * anchor
+
+        ==============  ========  =========  ===============================================
+        check           anchor    limit      violates when
+        ==============  ========  =========  ===============================================
+        CURRENT         0         limit_a    ``value >= threshold * limit_a``
+        LOW_VOLTAGE     vn_kv     vmin_kv    ``v <= threshold * vmin + (1 - threshold) * vn``
+        HIGH_VOLTAGE    vn_kv     vmax_kv    ``v >= threshold * vmax + (1 - threshold) * vn``
+        ==============  ========  =========  ===============================================
+
+        A line's usable range really is ``[0, limit_a]``, so its anchor is ``0`` and the rule
+        reduces to scaling the limit. A voltage bound has no such natural "zero" end, so the
+        bus nominal voltage is used instead (operating limits are conventionally expressed as
+        +/- x% of it), **clamped into** ``[vmin_kv, vmax_kv]`` for the rare real-world band
+        that does not bracket it. Either way each acceptable interval keeps a width of exactly
+        ``threshold`` times its original one.
+
+        Anchoring both voltage checks on ``vn_kv`` -- rather than on each other -- keeps them
+        **independent**: the ``LOW_VOLTAGE`` verdict depends on ``vmin_kv``, ``vn_kv`` and the
+        threshold alone, so setting ``vmax_kv`` (or leaving it at ``NaN``) can never change
+        it, and vice versa. The two effective bounds also converge towards ``vn_kv`` from
+        their own side and can never cross, so no bus is ever both too low and too high.
+
+        A bus with inconsistent limits (``vmin_kv > vmax_kv``) raises a ``RuntimeError``
+        rather than being reported as an arbitrary one of the two types. The
+        reported ``value`` / ``limit`` are never rescaled by the threshold; only the test
+        deciding whether to report is shifted.
+
+        The default ``1.0`` reproduces the previous, threshold-less behaviour. Like
+        `nb_thread` / `handle_disconnected_grid`, this is a plain runtime knob: it only
+        affects the next `run` / `run_ac` / `run_dc`. *Lowering* it invalidates any
+        already-computed results (the registered contingencies are kept, so it is enough to
+        run again); *raising* it back up does not.
+        """
+        return self.computer.violation_threshold
+
+    @violation_threshold.setter
+    def violation_threshold(self, val):
+        try:
+            val = float(val)
+        except (TypeError, ValueError):
+            raise ValueError("The `violation_threshold` attribute must be a real number.")
+        if not (0. < val <= 1.):
+            raise ValueError("The `violation_threshold` attribute must be in the range "
+                             f"]0., 1.] (got {val}).")
+        if val < self.computer.violation_threshold:
+            # mirrors the c++-side `set_violation_threshold`, which calls
+            # `clear_results_only()` when the threshold is tightened (results computed under
+            # the previous, looser threshold would silently under-report). Without resetting
+            # the python-side cache too, `self.__computed` would stay True while the c++-side
+            # results are gone, and the next `run()` would skip recomputing and then index
+            # empty result arrays. Keep the registered contingencies (with_contlist=False).
+            self.clear(with_contlist=False)
+        self.computer.violation_threshold = val
+
     @property
     def nb_thread(self):
         """Number of OS threads used to solve the contingencies (default: 1).