LightSim2Grid 1.1.0__tar.gz → 1.2.0__tar.gz

{lightsim2grid-1.1.0 → lightsim2grid-1.2.0}/CHANGELOG.rst

@@ -3,6 +3,14 @@ Change Log
 
 [TODO]
 --------
+- ``ScenarioSweep.set_topo_actions`` still refuses, each a value-level extension to write: an
+  element named in both a ``set_contingency_*`` mask and the action; moving or reactivating a
+  slack participant, a generator on a slack bus, or one in a voltage-control group (disconnecting
+  them works); a branch with one end open put back on; the DC algorithm; ``keep_jacobian``
+  with a generator moved or reactivated.
+- OpenLoadFlow-style outer loops (reactive limits, slack limits, hvdc saturation) as a
+  non-default ``NROuter_*`` algorithm, keeping one ``analyze`` per solve or batch: assessed in
+  ``docs/dev_notes/outer_loops_fixed_sparsity.md``, nothing implemented.
 - Control limits are detected but never **enforced**: ``compute_physical_violations`` reports a
   distributed-slack machine past ``get_min_p`` / ``get_max_p`` (``GenPCheck``) and a bus past its
   reactive capability (``BusQCheck``), but no algorithm reads a limit, so the solve still
@@ -204,6 +212,234 @@ TODO: a "combine mode" axis for ``ScenarioSweepCPP`` choosing between the curren
       contingency) and a cartesian one ("every registered contingency x every
       injection profile").
 
+
+[1.2.0] 2026-10-12
+--------------------
+- [BREAKING] (C++ / plugins) ``BaseAlgo`` gains the virtual ``distributes_slack()`` (false unless
+  overridden, which ``redistribute_slack`` requires) and ``set_voltage_control_v_set`` takes an
+  ``Eigen::Ref``: plugins must be rebuilt, and update their overrides.
+- [FIXED] ``ScenarioSweep.set_contingency_gens``: masking every generator of a bus a
+  voltage-regulating storage unit also holds turned that bus PQ.
+- [FIXED] ``ScenarioSweep.modify_gen_v``: a generator a row disconnects no longer has to agree
+  with the set-point of the generators left on its bus.
+- [ADDED] a documentation page for the light environment (``docs/light_env.rst``) and a
+  benchmark against grid2op (``benchmarks/light_env.py``).
+- [FIXED] light environment: the ``Protections`` setters accept float32 and read-only arrays.
+- [ADDED] ``ScenarioSweep.set_topo_actions``: one topological action per row (disconnections,
+  reconnections, a bus split or merged), still on one symbolic analysis. Refusals under [TODO].
+- [ADDED] light environment: ``LightEnv.init_actions`` registers checked topological actions,
+  which ``step(act_id)`` plays with grid2op-like cooldowns.
+- [FIXED] light environment: the protections looped for ever after an overflow disconnection,
+  and never reset the overflow counter of a line back in its limits.
+- [ADDED] light environment: ``LightEnvObservation``, read-only views on the env's state with no
+  copy, returned by ``reset`` / ``step``.
+- [ADDED] light environment: ``LightEnv`` can be copied cheaply (``copy`` / ``deepcopy``), and
+  moved in C++.
+- [FIXED] light environment: the reward and ``info["survival_time"]`` were integer divisions.
+- [BREAKING] ``BINARY_FORMAT_VERSION`` 11 -> 18: ``SvcContainer`` serializes the standby automaton
+  and the ``can_be_pv`` flag of each SVC, the generators and storage units their "can participate
+  in the slack" weight and overshoot, the converter stations their ``can_be_pv`` flag, the hvdc
+  lines their AC-emulation frozen flag, the grid its remote voltage control range. Files of
+  format 11 no longer load.
+- [BREAKING] Operational limit checks ignore a value on its limit up to ``violation_rel_tol``
+  (new, default ``1e-9``; ``rel_tol`` of ``LSGrid.get_violations``). They used ``>=`` /
+  ``<=``, so the last bit of rounding decided.
+- [BREAKING] ``LSGrid.consider_only_main_component()`` now redistributes by default the
+  set-points the islanding takes out on the remaining slack units (``redistribute_slack=True``)
+  and returns a ``SlackRedistributionReport``. Pass ``False`` for the previous behaviour, as the
+  grid2op backend and ``init_from_pypowsybl`` do.
+- [BREAKING] ``BINARY_FORMAT_VERSION`` 10 -> 11: ``GeneratorContainer`` serializes the
+  ``can_be_pv`` flag. A file saved with format 10 must be re-exported.
+- [BREAKING] ``LSGrid.get_Ybus_solver()`` / ``get_dcYbus_solver()`` return a read-only view of the
+  grid's matrix, not a copy, valid until a powerflow rebuilds it. Use ``.copy()`` to keep it or
+  to pass it to an algorithm's ``compute_pf``.
+- [ADDED] Batch classes: ``compute_branch_results()``, P and Q at both ends of every branch per
+  row, ``(nb_rows, nb_branch, 4)``; ``get_row_solve_times()`` / ``get_row_nb_iter()``.
+- [IMPROVED] The ``init_from_*`` loaders select ``NR_KLU`` / ``DC_KLU`` when KLU is compiled in
+  (``NR_SparseLU`` / ``DC_SparseLU`` before); batch classes built from the grid follow.
+- [ADDED] Docs: reusing one ``ScenarioSweep`` across scenarios, and threads vs processes.
+- [ADDED] Batch classes: ``compute_gen_results`` / ``get_gen_results()``, generator P and Q per row
+  by the rules of ``get_gen_res`` (shared with ``LSGrid.compute_results``, not reimplemented).
+- [ADDED] ``LSGrid.get_gen_slack_shares()``: each generator's share of the distributed slack.
+- [ADDED] ``ScenarioSweepCPP`` / ``ContingencyAnalysisCPP``: ``get_Ybus(row)`` / ``get_dcYbus(row)``,
+  the admittance matrix a row was solved with.
+- [FIXED] ``compute_branch_results`` / ``get_gen_results`` with ``set_topo_actions``: a branch or
+  generator the row moves, reconnects or reactivates was reported on its base bus, or as off.
+- [FIXED] DC batch: disconnecting a half-open branch edited Bbus, where DC never stamped it.
+- [FIXED] DC batch: a bus whose regulating generators a row disconnects kept their voltage
+  setpoint as its magnitude (``dc_pf`` gives the starting one), which skewed the currents.
+- [FIXED] A DC batch row that edits no admittance, right after one that did, was solved on the
+  previous row's matrix: adding the branches back did not ask for a refactorization.
+- [FIXED] DC flows of a phase shifter in the batch flows and in the current-limit checks (batch and
+  ``LSGrid.get_violations``): the shift term had the wrong sign and no ``sn_mva`` scaling.
+- [FIXED] A DC batch row disconnecting a phase shifter kept its shift injections in Pbus.
+- [FIXED] DC ``ContingencyAnalysis`` / ``ScenarioSweep`` with ``nb_thread > 1`` crashed (segfault):
+  a fresh worker's solver had no internal Bbus yet when the first outage edited it.
+- [FIXED] DC batch with ``handle_disconnected_grid``: rows were solved with a stale Pbus (the base
+  case's, or the first row's), ignoring per-row injections and the slack pre-pass.
+- [FIXED] ``LSGrid`` pickling converts its state one element at a time: the single huge tuple cast
+  overflowed MSVC (C1067) and OOM-killed gcc 8 on ``binding_lsgrid.cpp``.
+- [FIXED] ``bake_outer_loops`` no longer freezes a unit at its reactive limit whose bus still has a
+  regulating unit with headroom (OpenLoadFlow switches buses, not units).
+- [FIXED] The controllers holding a remote bus share it with the other generators of their bus counted
+  in that bus' key, as OpenLoadFlow does.
+- [FIXED] A unit OpenLoadFlow capped well beyond its active limit stays there in the slack pre-pass
+  until the shift has used that up (``set_gen_can_participate_slack_overshoot``, from the bake).
+- [FIXED] An SVC carrying a standby automaton has its susceptance range shifted by the automaton's
+  ``b0`` (``init_from_pypowsybl`` and ``bake_outer_loops``), as OpenLoadFlow holds that ``b0`` apart.
+- [FIXED] ``bake_outer_loops`` freezes a generator with too small a reactive range sharing its
+  regulated bus with a controller OpenLoadFlow keeps; it was left regulating.
+- [FIXED] ``init_from_pypowsybl`` reads an hvdc line's ``hvdcOperatorActivePowerRange`` as its
+  active power limit per direction, like OpenLoadFlow, instead of ``max_p``.
+- [FIXED] ``init_from_pypowsybl`` reads the reactive limits of a VSC converter station with a
+  capability curve at its target P; it was left unlimited.
+- [FIXED] ``bake_saturated_voltage_control`` no longer freezes a unit OpenLoadFlow still regulates
+  with some reactive headroom left, only one at its limit.
+- [FIXED] ``bake_outer_loops`` applied the standby automaton to non-regulating SVCs and checked the
+  SVC's own bus: OpenLoadFlow arms it on voltage-mode SVCs only and monitors their regulated bus.
+- [FIXED] ``bake_outer_loops`` froze a voltage-mode SVC within the saturation tolerance of its limit
+  even when OpenLoadFlow held its target: SVCs now follow the generators' rule.
+- [FIXED] The PQ -> PV release check skipped a ``can_be_pv`` generator frozen a hair inside its
+  reactive limit (the bake keeps the output it had): it required its setpoint within ``tol_mva``
+  of the limit. A flagged generator is now pinned at the nearer of its limits.
+- [FIXED] ``bake_outer_loops`` took a standby SVC OpenLoadFlow switched on for an idle one (its bus
+  sits at the setpoint, inside the thresholds). It is read off the SVC's output now, and marked as
+  no longer standby.
+- [FIXED] ``bake_outer_loops``: a unit dispatched at ``max_p`` / ``min_p`` got a ``target_p`` a
+  round-off outside it, so OpenLoadFlow left it out of the slack of the baked grid.
+- [FIXED] ``handle_disconnected_grid``: the PQ -> PV release check (``LOW_VOLTAGE_AT_MIN_Q`` /
+  ``HIGH_VOLTAGE_AT_MAX_Q``) reported a ``can_be_pv`` generator stranded outside the main
+  component when the bus it regulates stayed in it. A stranded machine is now skipped, as when
+  the contingency disconnects it (one contingency at a time).
+- [FIXED] ``handle_disconnected_grid``: a contingency stranding the bus a voltage-control group
+  regulates while some of its controllers stay in the main component ran every Newton iteration
+  before being reported as ``DIVERGENCE`` (the frozen magnitude of the stranded bus cannot reach
+  the set-point). It is now skipped before the solve (``NOT_SIMULATED``), as the one contingency
+  at a time path refuses it ("regulates a disconnected bus"). A group with only some of its
+  controllers stranded is still solved: the live ones hold the bus and share among themselves.
+- [FIXED] ``handle_disconnected_grid`` diverged on a contingency stranding every controller of a
+  voltage-control group of several controllers (*eg* two generators of a plant behind its
+  step-up transformer, both regulating its high voltage bus remotely): only a group of one
+  controller was handled. Such a group now leaves the solve (its controllers produce no
+  reactive power) and its regulated bus, still in the main component, becomes a plain PQ bus,
+  as when the controllers are disconnected. Same Jacobian structure for every row.
+- [FIXED] ``handle_disconnected_grid`` (``ContingencyAnalysis`` / ``ScenarioSweep``) chose its
+  reference slack bus mixing the grid and the solver bus numberings, and the choice never
+  reached the solver. On a grid where they differ (disconnected or fused buses), a contingency
+  islanding a slack-participating generator could be skipped (``NOT_SIMULATED``) for no reason,
+  and one stranding the solver's real reference was not. The reference is now chosen in solver
+  numbering and is the one the solver uses; ``pick_reference_slack`` returns a slack bus
+  (gridmodel id) and has no effect on the next ``compute``.
+- [FIXED] a reference slack bus forced with ``LSGrid.set_reference_slack_bus`` was lost by
+  ``LSGrid.copy()``, so by the batch algorithms, which work on a copy of the grid. The batch
+  now always keeps it as its reference (the contingencies that strand it are skipped);
+  ``pick_reference_slack`` still suggests the automatic choice.
+- [FIXED] ``LSGrid.consider_only_main_component`` left the generators / storage units stranded
+  outside the main component in the distributed slack: the next powerflow raised
+  "One of the slack bus is disconnected". A disconnected slack unit now takes no share until it is
+  reconnected (and a forced reference slack bus outside the main component is cleared), as
+  OpenLoadFlow only distributes the slack on the main component.
+- [FIXED] the DC algorithms' ``get_error()`` stayed ``NotInitError`` after a converged ``dc_pf``
+  (the status was only written on failure): it now reports ``NoError``, as the AC ones do.
+- [FIXED] the DC active-power imbalance handed to the generator p-limit check
+  (``compute_physical_violations``) was summed over every bus, the ones masked by
+  ``handle_disconnected_grid`` included; it is now summed over the solved buses only, as the
+  DC solver does.
+- [FIXED] the OLF-style slack redistribution (``LSGrid.redistribute_active_power``,
+  ``consider_only_main_component(redistribute_slack=True)``, the batch algorithms'
+  ``redistribute_slack``) could push a unit across 0 MW: a discharging storage unit, or a
+  generator with ``min_p < 0``, was driven to a negative injection by a negative mismatch
+  (and a charging one to a positive injection by a positive mismatch). OpenLoadFlow never
+  changes the sign of a unit's injection: 0 MW is now a bound on the side the unit is not on.
+- [FIXED] the power an islanding takes out (``consider_only_main_component``, and the batch
+  algorithms with ``handle_disconnected_grid``) did not count the HVDC converter stations
+  stranded outside the main component: a contingency islanding the converter of a large
+  export left its whole consumption to the unbounded distributed slack of the powerflow, past
+  every ``[min_p, max_p]`` and 0 MW bound. The stranded stations' setpoints are now part of
+  ``mismatch_mw`` and redistributed like a stranded load / generator (the line's converter
+  that stays in the main component keeps injecting, as before).
+- [FIXED] ``ContingencyAnalysis``: changing ``handle_disconnected_grid`` or
+  ``redistribute_slack`` after a computation returned the previous results.
+- [ADDED] ``LSGrid.set_hvdc_ac_emulation_frozen``: an hvdc line frozen at its AC-emulation limit is
+  reported (``HVDC_AC_EMULATION_RELEASE``) when its droop asks for less (from the bake).
+- [ADDED] ``LSGrid.set_remote_voltage_control_vm_range``: a generator holding a remote bus from an
+  unrealistic own-bus voltage is reported (``LOW_VOLTAGE_REMOTE_CONTROL`` /
+  ``HIGH_VOLTAGE_REMOTE_CONTROL``), as OpenLoadFlow's robust remote voltage control switches it to
+  PQ; ``init_from_pypowsybl`` sets the range of the installed OpenLoadFlow (it differs by version).
+- [ADDED] ``bake_outer_loops(bake_hvdc_ac_emulation_limits=True)`` freezes an AC-emulation hvdc line
+  OpenLoadFlow saturated to a fixed setpoint at its limit.
+- [ADDED] ``LSGrid.cap_slack_at_active_limits``: OpenLoadFlow's slack rule on a solved grid -- a unit
+  the solve pushes past an active limit leaves the slack there, and the grid is re-solved.
+- [ADDED] ``LSGrid.set_hold_frozen_regulators``: a frozen (``can_be_pv``) remote regulator keeps
+  its seat in its voltage-control group, held at its frozen output -- same solution, releasable by
+  value.
+- [ADDED] Physical check of the idle SVCs under a standby automaton (``LSGrid.set_svc_standby``):
+  a regulated bus outside the automaton's thresholds, which OpenLoadFlow's
+  ``MonitoringVoltageOuterLoop`` answers by switching the SVC on, is reported as
+  ``LOW_VOLTAGE_SVC_STANDBY`` / ``HIGH_VOLTAGE_SVC_STANDBY`` on the new ``ViolationElementType.SVC``.
+- [ADDED] ``bake_outer_loops`` also returns the standby SVCs it left idle, and
+  ``init_from_pypowsybl(can_be_pv=...)`` flags them with their thresholds.
+- [ADDED] The PQ -> PV release check for the SVCs: ``LSGrid.set_svc_can_be_pv`` flags a fixed-Q SVC
+  an outer loop froze at a reactive limit, reported as ``LOW_VOLTAGE_AT_MIN_Q`` /
+  ``HIGH_VOLTAGE_AT_MAX_Q`` on the SVC. ``bake_outer_loops`` returns the SVCs it froze at a limit.
+- [ADDED] ``LSGrid.set_gen_can_participate_slack`` / ``set_storage_can_participate_slack``: a unit
+  left out of the slack only because it sat at an active limit takes part in the redistribution
+  pre-pass, away from that limit, as OpenLoadFlow lets it. ``bake_outer_loops(...,
+  return_details=True)`` returns the units OLF capped, for ``init_from_pypowsybl(can_participate_slack=...)``.
+- [ADDED] a unit flagged ``can_participate_slack`` (every slack unit is) and out of the slack
+  because it sat at an active limit goes back into it once its set-point moves off that limit.
+- [ADDED] The PQ -> PV release check for the VSC converter stations: ``LSGrid.set_hvdc_can_be_pv``
+  (``ConverterStationInfo.can_be_pv``), reported on the HVDC line, ``side`` the station's end.
+  ``bake_outer_loops`` returns the stations it froze at a reactive limit, in ``can_be_pv``.
+- [ADDED] ``LSGrid.set_keep_vinit_at_group_controlled_buses`` (and the batch algorithms'
+  ``keep_vinit_at_group_controlled_buses``), off by default: a bus regulated remotely or by an
+  SVC keeps its starting magnitude instead of its set-point, so step damping can reach it gradually.
+- [ADDED] ``LSGrid.redistribute_active_power(mismatch_mw)``: shares a known active-power
+  imbalance on the generators and storage units of the distributed slack as OpenLoadFlow's
+  ``DistributedSlack`` outer loop does, with their ``[min_p, max_p]`` bounds (a saturated unit
+  leaves the pool, and the distributed slack).
+- [ADDED] ``redistribute_slack`` (off by default) on ``ContingencyAnalysis`` and
+  ``ScenarioSweep``: the same OLF-style bounded redistribution of the power a row loses (a
+  generator contingency, or an island cut off with ``handle_disconnected_grid``) before its
+  powerflow, the saturated units leaving that row's distributed slack.
+- [ADDED] ``LSGrid.get_physical_violations(ac=True, tol_mva=1e-4)``: the physical-limit checks of
+  the batch algorithms (``compute_physical_violations``: reactive capability of the voltage
+  controllers, hvdc max power, generators / storage units pushed past their p limits by the
+  slack) on the grid's own last ``ac_pf`` / ``dc_pf``.
+- [ADDED] ``LSGrid.get_violations(threshold=1., ac=True)``: the operational limit checks of the
+  batch algorithms (``compute_limit_violations``: bus voltages against ``[vmin, vmax]``, branch
+  currents on both sides against their thermal limits) on the grid's own last ``ac_pf`` /
+  ``dc_pf``. The checks moved to ``batch_algorithm/OperationalCheck.hpp`` (same code, same
+  namespace).
+- [ADDED] ``LSGrid.set_gen_can_be_pv`` / ``GenInfo.can_be_pv``: a per-generator flag (False by
+  default, never read by a powerflow) saying that a PQ machine is one an outer loop pinned at
+  a reactive limit, so that its PQ -> PV release can be checked. Kept by ``copy``, pickle and
+  the binary format.
+- [ADDED] the PQ -> PV direction of OpenLoadFlow's ``ReactiveLimits`` loop as a physical
+  check: a PQ generator flagged ``can_be_pv``, sitting at its ``min_q`` (resp. ``max_q``),
+  whose regulated bus is below (resp. above) its target voltage would regulate again. Reported
+  as ``LOW_VOLTAGE_AT_MIN_Q`` / ``HIGH_VOLTAGE_AT_MAX_Q`` on the ``GENERATOR`` (``value`` and
+  ``limit`` in kV) by ``LSGrid.get_physical_violations`` (new ``tol_vm_pu`` argument) and by
+  the batch algorithms' ``compute_physical_violations`` (new ``physical_violation_tol_vm_pu``
+  property); AC only, never enforced.
+- [ADDED] ``bake_outer_loops`` returns the ids of the generators it froze at a reactive
+  limit, and ``init_from_pypowsybl(can_be_pv=...)`` flags them (``LightsimResultNetwork.
+  get_generators`` shows the flag in a ``can_be_pv`` column), so that a lightsim2grid solve
+  of the baked grid reports the ones an outer loop would release again.
+- [IMPROVED] ``bake_outer_loops`` is faster on large grids: the capability-curve extrapolation is
+  vectorised and the bus frame is read once per bake instead of once per step. Same result.
+- [IMPROVED] reading the batteries' ``activePowerControl`` extension (pypowsybl <= 1.16.1) goes
+  through a JIIDM export restricted to it: ``bake_outer_loops`` and ``init_from_pypowsybl``
+  are much faster on large grids with batteries. Same result.
+- [IMPROVED] ``ScenarioSweep.redistribute_slack`` also shares, before each row's powerflow, the
+  active imbalance its ``modify_gen_p`` / ``modify_sgen_p`` / ``modify_load_p`` create against
+  the grid's own targets.
+- [IMPROVED] ``LSGrid.get_Ybus()``, ``get_dcYbus()`` and ``get_Bf()`` relabel the solver matrix in
+  one pass instead of sorting it again: several times faster on large grids.
+- [IMPROVED] The sparse matrices a getter builds (``get_Ybus``, ``get_dcYbus``, ``get_Bf``,
+  ``get_Bf_solver``, the batch ``get_Ybus(row)`` / ``get_dcYbus(row)``) reach python without a copy.
+
+
 [1.1.0] 2026-09-21
 --------------------
 - [BREAKING] ``BINARY_FORMAT_VERSION`` 4 -> 10: bus connectivity is no longer serialized (it is
@@ -680,6 +916,11 @@ DCLineInfo                       res_theta_ex_deg         res_theta2_deg
 - [IMPROVED] refactoring of the c++ side container element to reduce
   code (for "one end" elements such as loads, generators, static generators and shunts)
 
+[0.10.1.post1] 2025-02-xx
+----------------------------
+- [FIXED] compatibility issue with pypowsybl 1.10.0 version
+  ("rho" attribute is now computed directly by pypowsybl in the trafo dataframe).
+  
 [0.10.1] 2025-01-04
 ----------------------------
 - [FIXED] some timings on the benchmarks were not measured at the right time

{lightsim2grid-1.1.0 → lightsim2grid-1.2.0}/CLAUDE.md

@@ -285,6 +285,20 @@ fallback is a switch on every `LinearSolverPolicy` (`set_refactor_fallback`), an
 algorithms turn it on whenever they mask buses or switch PV / PQ, because those edits can
 move a pivot that KLU's fixed pivot sequence then finds at zero.
 
+### `BaseAlgo` is a plugin interface
+
+External solvers are loaded at run time as plugins deriving from `BaseAlgo`
+(`docs/solver_plugin.rst`), and the plugin ABI tag only checks Eigen's configuration, not
+`BaseAlgo`'s layout. So a change to its virtual methods (one added, removed, or re-signed)
+comes with, in the same PR:
+
+- the three example plugins in `examples/` (`external_algorithm`, `lm_algorithm`,
+  `dist_slack_algorithm`) brought up to date -- a new capability hook overridden where the
+  plugin has the capability, a new forwarding hook forwarded -- built against the installed
+  package and their `test_plugin.py` run, as the `test_plugin_against_installed` CI job does;
+- `docs/solver_plugin.rst` describing the hook, if a plugin author has to act on it;
+- a `[BREAKING] (C++ / plugins)` changelog entry.
+
 ### Batch algorithms
 
 `src/core/batch_algorithm/BaseBatchSweep.hpp` is one class template with **four**

{lightsim2grid-1.1.0 → lightsim2grid-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: lightsim2grid
-Version: 1.1.0
+Version: 1.2.0
 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.1.0 → lightsim2grid-1.2.0}/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.1.0"
+__version__ = "1.2.0"
 
 __all__ = [
     "newtonpf",
@@ -134,6 +134,14 @@ __all__.append("ContinuationPowerFlow")
 __all__.append("run_cpf")
 __all__.append("continuationPowerflow")
 
+try:
+    from lightsim2grid.lightEnv import LightEnv  # noqa: F401
+    __all__.append("LightEnv")
+    __all__.append("lightEnv")
+except ImportError as exc_:  # noqa: F841
+    # grid2op is not installed, the LightEnv module will not be available
+    pass
+
 try:
     from lightsim2grid.rewards import N1ContingencyReward  # noqa: F401
     __all__.append("rewards")

{lightsim2grid-1.1.0 → lightsim2grid-1.2.0}/lightsim2grid/contingencyAnalysis.py

@@ -44,8 +44,14 @@ class PreContingencyResult:
     limit_violations: List[LimitViolation]
     #: the PHYSICAL limits this case's solution leaves, when
     #: `ContingencyAnalysis.compute_physical_violations` is on (an empty list otherwise): a
-    #: bus needing reactive power its machines do not have (LOW_Q / HIGH_Q), an angle-droop
-    #: hvdc line beyond what its converters can transmit (HIGH_P), or a generator the
+    #: bus needing reactive power its machines do not have (LOW_Q / HIGH_Q), a PQ generator
+    #: flagged as pinned at a reactive limit that would regulate again (LOW_VOLTAGE_AT_MIN_Q /
+    #: HIGH_VOLTAGE_AT_MAX_Q), an idle SVC flagged as carrying a standby automaton that would
+    #: switch it on (LOW_VOLTAGE_SVC_STANDBY / HIGH_VOLTAGE_SVC_STANDBY), a generator holding a
+    #: remote bus from an unrealistic voltage on its own bus (LOW_VOLTAGE_REMOTE_CONTROL /
+    #: HIGH_VOLTAGE_REMOTE_CONTROL), an angle-droop hvdc line beyond what its converters can
+    #: transmit (HIGH_P), one flagged as frozen at its limit whose droop would ask for less
+    #: (HVDC_AC_EMULATION_RELEASE), or a generator the
     #: distributed slack pushed outside its active power limits (LOW_P / HIGH_P). Kept apart from
     #: `limit_violations` because it is a different KIND of statement: every entry here has
     #: `category == ViolationCategory.PHYSICAL` -- a state the grid cannot reach -- where
@@ -206,6 +212,24 @@ class ContingencyAnalysis(object):
             raise ValueError("The `init_from_n_powerflow` attribute must be a boolean.")
         self.computer.init_from_n_powerflow = bool(val)
 
+    @property
+    def keep_vinit_at_group_controlled_buses(self):
+        """Whether the buses a voltage-control group regulates (regulated from elsewhere, by
+        an SVC, or by several controllers at least one of which is remote) keep the magnitude
+        of the starting voltage instead of being set to their set-point before each solve.
+        The solution is the same; with ``MaxVoltageChange`` damping it can be reached in far
+        fewer iterations. Defaults to the grid's own setting (see
+        :func:`lightsim2grid.lightsim2grid_cpp.LSGrid.set_keep_vinit_at_group_controlled_buses`),
+        ``False`` unless set there.
+        """
+        return self.computer.keep_vinit_at_group_controlled_buses
+
+    @keep_vinit_at_group_controlled_buses.setter
+    def keep_vinit_at_group_controlled_buses(self, val: bool):
+        if bool(val) != val:
+            raise ValueError("The `keep_vinit_at_group_controlled_buses` attribute must be a boolean.")
+        self.computer.keep_vinit_at_group_controlled_buses = bool(val)
+
     @property
     def handle_disconnected_grid(self):
         """Whether a contingency that splits the grid into several connected components is
@@ -223,7 +247,37 @@ class ContingencyAnalysis(object):
     def handle_disconnected_grid(self, val: bool):
         if bool(val) != val:
             raise ValueError("The `handle_disconnected_grid` attribute must be a boolean.")
-        self.computer.handle_disconnected_grid = bool(val)
+        val = bool(val)
+        if val != self.computer.handle_disconnected_grid:
+            # the results kept by get_flows / run were computed with the other value
+            self.clear(with_contlist=False)
+        self.computer.handle_disconnected_grid = val
+
+    @property
+    def redistribute_slack(self):
+        """Whether the active power a contingency loses (the elements of the island it cuts
+        off, simulated with :attr:`handle_disconnected_grid`) is first shared on the remaining
+        units of the distributed slack as OpenLoadFlow's ``DistributedSlack`` outer loop does:
+        proportionally to their weight, each one clamped to its ``[min_p, max_p]`` and never
+        crossing 0 MW, a clamped unit leaving the pool (and that contingency's distributed
+        slack), the powerflow then
+        only sharing what is left (the change in the losses) on the units that can still move.
+        Default: ``False``. Needs ``LSGrid.set_gen_p_limits`` / ``set_storage_p_limits`` to
+        clamp anything. Same as ``LSGrid.consider_only_main_component(redistribute_slack=True)``,
+        contingency by contingency. Needs an algorithm with a distributed slack: ``compute``
+        refuses it with a single-slack one (``NRSing_*``, Gauss-Seidel).
+        """
+        return self.computer.redistribute_slack
+
+    @redistribute_slack.setter
+    def redistribute_slack(self, val: bool):
+        if bool(val) != val:
+            raise ValueError("The `redistribute_slack` attribute must be a boolean.")
+        val = bool(val)
+        if val != self.computer.redistribute_slack:
+            # the results kept by get_flows / run were computed with the other value
+            self.clear(with_contlist=False)
+        self.computer.redistribute_slack = val
 
     @property
     def compute_limit_violations(self):
@@ -262,9 +316,9 @@ class ContingencyAnalysis(object):
         ==============  ========  =========  ===============================================
         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``
+        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
@@ -285,6 +339,10 @@ class ContingencyAnalysis(object):
         reported ``value`` / ``limit`` are never rescaled by the threshold; only the test
         deciding whether to report is shifted.
 
+        On top of the effective limit, a value must clear the relative margin
+        `violation_rel_tol` (default ``1e-9``) to be reported, so a value on its limit up to
+        rounding is not a violation.
+
         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
@@ -312,6 +370,45 @@ class ContingencyAnalysis(object):
             self.clear(with_contlist=False)
         self.computer.violation_threshold = val
 
+    @property
+    def violation_rel_tol(self):
+        """Relative tolerance (a ``float`` in ``[0., 1.[``, default ``1e-9``) of every
+        limit-violation check performed when `compute_limit_violations` is `True`: a value
+        is reported only when it is beyond its effective limit (see `violation_threshold`)
+        by more than this fraction of that limit::
+
+            CURRENT        value > threshold * limit_a * (1 + violation_rel_tol)
+            LOW_VOLTAGE    v     < low_eff  * (1 - violation_rel_tol)
+            HIGH_VOLTAGE   v     > high_eff * (1 + violation_rel_tol)
+
+        It is there for the values that sit ON their limit by construction, typically a bus
+        a generator regulates exactly at its ``vmax``: a solve leaves such a value a few ulps
+        on either side of the limit, and with a bare ``>`` the last bit of rounding decided
+        whether it was reported (the one-contingency-at-a-time solve, the batch and
+        gpusim2grid disagreed). ``1e-9`` is about 0.4 mV on a 400 kV bus. ``0.`` gives the
+        bare strict comparisons. The reported ``value`` / ``limit`` are unaffected.
+
+        Like `violation_threshold`, it only affects the next `run` / `run_ac` / `run_dc`;
+        changing it (either way) invalidates any already-computed results, the registered
+        contingencies being kept.
+        """
+        return self.computer.violation_rel_tol
+
+    @violation_rel_tol.setter
+    def violation_rel_tol(self, val):
+        try:
+            val = float(val)
+        except (TypeError, ValueError):
+            raise ValueError("The `violation_rel_tol` attribute must be a real number.")
+        if not (0. <= val < 1.):
+            raise ValueError("The `violation_rel_tol` attribute must be in the range "
+                             f"[0., 1.[ (got {val}).")
+        if val != self.computer.violation_rel_tol:
+            # the c++ side clears its results on any change (a larger tolerance drops
+            # recorded violations as surely as a smaller one adds some)
+            self.clear(with_contlist=False)
+        self.computer.violation_rel_tol = val
+
     @property
     def compute_physical_violations(self):
         """Whether every converged contingency reports the PHYSICAL limits its solution
@@ -320,9 +417,9 @@ class ContingencyAnalysis(object):
         does reach and should not sit in). Default: ``False``. See
         :func:`get_physical_violations` and `ContingencyResult.physical_violations`.
 
-        Three checks, each a condition a PowSyBl OpenLoadFlow outer loop acts on, and none
-        enforced here (nothing is switched PV -> PQ, no droop is clamped, no machine leaves
-        the slack distribution, no contingency is re-solved):
+        Each check is a condition a PowSyBl OpenLoadFlow outer loop acts on, and none
+        enforced here (nothing is switched PV -> PQ or back, no droop is clamped, no machine
+        leaves the slack distribution, no contingency is re-solved):
 
         * the **reactive capability** of every bus whose voltage is held by machines
           (``LOW_Q`` / ``HIGH_Q`` on the ``BUS``): did it need more reactive power than the
@@ -330,9 +427,36 @@ class ContingencyAnalysis(object):
           stations and voltage-mode SVCs can produce? Per bus, not per machine -- the split between the
           machines of one bus is a sharing convention rather than something the solver
           decides. OpenLoadFlow's ``ReactiveLimits``.
+        * the **release** of every PQ generator flagged as pinned at a reactive limit
+          (``LOW_VOLTAGE_AT_MIN_Q`` / ``HIGH_VOLTAGE_AT_MAX_Q`` on the ``GENERATOR``, see
+          :func:`lightsim2grid.network.LSGrid.set_gen_can_be_pv`): does the bus it would
+          regulate sit below its target while the machine absorbs all it can (or above it
+          while it produces all it can)? The other direction, PQ -> PV, of the same
+          ``ReactiveLimits`` loop. ``value`` and ``limit`` in kV, compared with
+          :attr:`physical_violation_tol_vm_pu`. A grid with no flagged generator reports
+          nothing here.
+        * the **switch on** of every idle SVC flagged as carrying a standby automaton
+          (``LOW_VOLTAGE_SVC_STANDBY`` / ``HIGH_VOLTAGE_SVC_STANDBY`` on the ``SVC``, see
+          :func:`lightsim2grid.network.LSGrid.set_svc_standby`): does the bus it regulates
+          sit outside the automaton's voltage thresholds? OpenLoadFlow's
+          ``MonitoringVoltageOuterLoop``. ``value`` and ``limit`` in kV, compared with
+          :attr:`physical_violation_tol_vm_pu`. A grid with no flagged SVC reports nothing
+          here.
+        * the **own bus** of every generator regulating a remote bus, when a realistic range
+          is set (``LOW_VOLTAGE_REMOTE_CONTROL`` / ``HIGH_VOLTAGE_REMOTE_CONTROL`` on the
+          ``GENERATOR``, see
+          :func:`lightsim2grid.network.LSGrid.set_remote_voltage_control_vm_range`): does
+          holding the remote target take it outside that range? OpenLoadFlow's
+          ``ReactiveLimits``, in its robust remote voltage control mode. ``value`` and
+          ``limit`` in kV, compared with :attr:`physical_violation_tol_vm_pu`.
         * the **active power** of every angle-droop ("AC emulation") hvdc line still in the
           linear regime (``HIGH_P`` on the ``HVDC``): did ``p0 + k.(theta1 - theta2)`` leave
           ``pmax_1to2_mw`` / ``pmax_2to1_mw``? OpenLoadFlow's ``HvdcAcEmulationLimits``.
+        * the **release** of every angle-droop hvdc line flagged as frozen at its active
+          power limit (``HVDC_AC_EMULATION_RELEASE`` on the ``HVDC``, see
+          :func:`lightsim2grid.network.LSGrid.set_hvdc_ac_emulation_frozen`): would its droop
+          ask for less than that limit? The other half of the same ``HvdcAcEmulationLimits``
+          loop. ``side`` the direction it is frozen in, ``value`` and ``limit`` in MW.
         * the **active power** of every generator and every storage unit carrying the
           **distributed slack** (``LOW_P`` / ``HIGH_P`` on the ``GENERATOR`` /
           ``STORAGE``): the slack is solved inside the
@@ -348,10 +472,11 @@ class ContingencyAnalysis(object):
 
         Independent of `compute_limit_violations`: either can be on without the other (though
         `run` still requires `compute_limit_violations`, and fills `physical_violations` only
-        when this one is on too). The two active-power checks work in DC; the reactive one
-        needs an AC algorithm that publishes its per-bus mismatch (every built-in AC algorithm
-        does) and `run` / `compute_V` raise for one that does not. Changing this flag invalidates any
-        computed result but keeps the registered contingencies.
+        when this one is on too). The active-power checks (the hvdc ones and the slack one) work
+        in DC; the reactive one and the voltage ones need an AC algorithm that publishes its per-bus mismatch (every
+        built-in AC algorithm does) and `run` / `compute_V` raise for one that does not.
+        Changing this flag invalidates any computed result but keeps the registered
+        contingencies.
         """
         return self.computer.compute_physical_violations
 
@@ -372,7 +497,8 @@ class ContingencyAnalysis(object):
     def physical_violation_tol_mva(self):
         """Absolute slack on every comparison :attr:`compute_physical_violations` makes, so
         that an element resting exactly on its limit is not reported over solver noise: a
-        violation needs ``value > limit + tol`` (or ``value < limit - tol`` for ``LOW_Q``).
+        violation needs ``value > limit + tol`` (or ``value < limit - tol`` for ``LOW_Q`` and
+        ``HVDC_AC_EMULATION_RELEASE``).
         Default: ``1e-4``. In MVA -- one noise floor for both halves, MW and MVAr being the
         same scale.
 
@@ -395,6 +521,33 @@ class ContingencyAnalysis(object):
         self.computer.physical_violation_tol_mva = val  # validates, and drops base case + results
         self.clear(with_contlist=False)
 
+    @property
+    def physical_violation_tol_vm_pu(self):
+        """The same as :attr:`physical_violation_tol_mva`, in pu, for the comparisons
+        :attr:`compute_physical_violations` makes on a voltage: the PQ -> PV release check
+        reports a flagged PQ generator (``LSGrid.set_gen_can_be_pv``) whose regulated bus
+        is below (at ``min_q``) or above (at ``max_q``) its target by more than this
+        (``LOW_VOLTAGE_AT_MIN_Q`` / ``HIGH_VOLTAGE_AT_MAX_Q``), and the standby SVC check a
+        flagged idle SVC (``LSGrid.set_svc_standby``) whose regulated bus is outside its
+        automaton's thresholds by more than this (``LOW_VOLTAGE_SVC_STANDBY`` /
+        ``HIGH_VOLTAGE_SVC_STANDBY``), and the remote voltage control check a remote
+        controller whose own bus is outside the realistic range by more than this
+        (``LOW_VOLTAGE_REMOTE_CONTROL`` / ``HIGH_VOLTAGE_REMOTE_CONTROL``). Default: ``1e-4``. Changing it invalidates any
+        previously-computed results.
+        """
+        return self.computer.physical_violation_tol_vm_pu
+
+    @physical_violation_tol_vm_pu.setter
+    def physical_violation_tol_vm_pu(self, val):
+        try:
+            val = float(val)
+        except (TypeError, ValueError):
+            raise ValueError("The `physical_violation_tol_vm_pu` attribute must be a real number.")
+        if val == self.computer.physical_violation_tol_vm_pu:
+            return
+        self.computer.physical_violation_tol_vm_pu = val  # validates, and drops base case + results
+        self.clear(with_contlist=False)
+
     def get_physical_violations(self):
         """Per contingency, in the C++-side order (`my_defaults()`): the list of
         :class:`LimitViolation` of the physical limits that contingency's solution leaves.