fix an issue with time overcurrent protection in case soft_overflow_threshold was not 1

Signed-off-by: DONNOT Benjamin <[email protected]>

Author: BDonnot

CHANGELOG.rst

@@ -159,6 +159,10 @@ Native multi agents support:
 - [FIXED] an issue when computing the cascading failure routine, in case multiple iterations were performed, 
   the cooldowns were not updated correctly.
 - [FIXED] cascading failure could be started at the first observation (t=0, just after a reset).
+- [FIXED] a bug when "SOFT_OVERFLOW_THRESHOLD" was not 1.: it also impacted "instantaneous overcurrent protections" 
+  (it was triggered when `flow > SOFT_OVERFLOW_THRESHOLD * HARD_OVERFLOW_THRESHOLD * th_lim`)
+- [FIXED] a bug when "SOFT_OVERFLOW_THRESHOLD" was not 1.: the backend routine to compute the protections 
+  disconnected the lines with a counter based on `flow > th_lim` and not `flow > th_lim * SOFT_OVERFLOW_THRESHOLD`
 - [ADDED] Possibility to disconnect loads, generators and storage units (if proper flag set in the environment).
   See documentation.
 - [ADDED] possibility to set the "thermal limits" when calling `env.reset(..., options={"thermal limit": xxx})`
@@ -177,6 +181,9 @@ Native multi agents support:
   kwargs by using `env.reset(..., options={"init datetime": XXX})`
 - [ADDED] the `ChangeNothing` time series class now supports forecast
 - [ADDED] test coverage on the CI
+- [ADDED] the `obs.timestep_protection_triggered` counter which counts whether or not the 
+  "time overcurrent protection" (soft overflow) will be triggered: lines will be disconnected
+  if `time overcurrent protection > parameters.NB_TIMESTEP_POWERFLOW_ALLOWED`
 - [IMPROVED] possibility to set the injections values with names
   to be consistent with other way to set the actions (*eg* set_bus)
 - [IMPROVED] error messages when creating an action which changes the injections
@@ -209,6 +216,7 @@ Native multi agents support:
 - [IMPROVED] no need to call `self._compute_pos_big_top()` at the end of the implementation of `backend.load_grid()`
 - [IMPROVED] type hints in various files.
 - [IMPROVED] documentation of the backend
+- [IMRPOVED] `SOFT_OVERFLOW_THRESHOLD` can now be lower than 1
 
 [1.10.5] - 2025-03-07
 ------------------------

docs/mdp.rst

@@ -654,7 +654,7 @@ The solver is then called and there are 2 alternatives (again):
    terminal state :math:`s_{\emptyset}` (ignore all the steps bellow)
 #. or a physical solution is found and the process carries out in the next steps
 
-.. _mdp-protection-emulation-step:
+.. _mdp--emulation-step:
 
 Step 5: Emulation of the "protections"
 ++++++++++++++++++++++++++++++++++++++++++

grid2op/Backend/backend.py

@@ -1459,13 +1459,13 @@ def next_grid_state(self,
             return disconnected_during_cf, infos, conv_
 
         # the environment disconnect some powerlines
-        init_time_step_overflow = copy.deepcopy(env._timestep_overflow)
-        counter_increased = np.zeros_like(init_time_step_overflow, dtype=dt_bool)
+        protection_counter = copy.deepcopy(env._protection_counter)
+        counter_increased = np.zeros_like(protection_counter, dtype=dt_bool)
         iter_num = 0
         while True:
             # simulate the cascading failure
             lines_flows = 1.0 * self.get_line_flow()
-            thermal_limits = self.get_thermal_limit() * env._parameters.SOFT_OVERFLOW_THRESHOLD  # SOFT_OVERFLOW_THRESHOLD new in grid2op 1.9.3
+            thermal_limits = self.get_thermal_limit()
             lines_status = self.get_line_status()
 
             # a) disconnect lines on hard overflow (that are still connected)
@@ -1478,12 +1478,12 @@ def next_grid_state(self,
                 # no soft overflow after a reset
                 mask_inc = np.zeros_like(thermal_limits, dtype=dt_bool)
             else: 
-                mask_inc = (lines_flows >= thermal_limits) & lines_status
+                mask_inc = (lines_flows > env._parameters.SOFT_OVERFLOW_THRESHOLD * thermal_limits) & lines_status
                 mask_inc[counter_increased] = False
-            init_time_step_overflow[mask_inc] += 1
+            protection_counter[mask_inc] += 1
             counter_increased[mask_inc] = True
             to_disc[
-                (init_time_step_overflow > env._nb_timestep_overflow_allowed)
+                (protection_counter > env._nb_ts_max_protection_counter)
                 & lines_status
             ] = True
 

grid2op/Environment/_obsEnv.py

@@ -364,13 +364,13 @@ def init(
 
         if time_step >= 1:
             is_overflow = obs.rho > 1.
-            
+            protection_triggered = obs.rho > self._parameters.SOFT_OVERFLOW_THRESHOLD
             # handle the components that depends on the time
             (
                 still_in_maintenance,
                 reconnected,
                 first_ts_maintenance,
-            ) = self._update_vector_with_timestep(time_step, is_overflow)
+            ) = self._update_vector_with_timestep(time_step, is_overflow, protection_triggered)
             if first_ts_maintenance.any():
                 set_status = np.array(self._line_status_me, dtype=dt_int)
                 set_status[first_ts_maintenance] = -1

grid2op/Environment/baseEnv.py

@@ -226,7 +226,16 @@ def foo(manager):
 
         Number of consecutive timesteps each powerline has been on overflow.
 
-    _nb_timestep_overflow_allowed: ``numpy.ndarray``, dtype: int
+    _protection_counter: `numpy.ndarray``, dtype: int
+        .. warning:: /!\\\\ Internal, do not use unless you know what you are doing /!\\\\
+
+        Current state of the delayed protection. It is exacly :attr:`BaseEnv._timestep_overflow` unless
+        :attr:`grid2op.Parameters.Parameters.SOFT_OVERFLOW_THRESHOLD` != 1. 
+        
+        If the soft overflow threshold is different than 1, it counts the number of steps 
+        since the soft overflow threshold is "activated" (flow > limits * soft_overflow_threshold)
+        
+    _nb_ts_max_protection_counter: ``numpy.ndarray``, dtype: int
         .. warning:: /!\\\\ Internal, do not use unless you know what you are doing /!\\\\
 
         Number of consecutive timestep each powerline can be on overflow. It is usually read from
@@ -454,7 +463,8 @@ def __init__(
             self._parameters.NO_OVERFLOW_DISCONNECTION
         )
         self._timestep_overflow: np.ndarray = None
-        self._nb_timestep_overflow_allowed: np.ndarray = None
+        self._protection_counter: np.ndarray = None
+        self._nb_ts_max_protection_counter: np.ndarray = None
         self._hard_overflow_threshold: np.ndarray  = None
 
         # store actions "cooldown"
@@ -767,8 +777,9 @@ def _custom_deepcopy_for_copy(self, new_obj, dict_=None):
         # if True, then it will not disconnect lines above their thermal limits
         new_obj._no_overflow_disconnection = self._no_overflow_disconnection
         new_obj._timestep_overflow = copy.deepcopy(self._timestep_overflow)
-        new_obj._nb_timestep_overflow_allowed = copy.deepcopy(
-            self._nb_timestep_overflow_allowed
+        new_obj._protection_counter = copy.deepcopy(self._protection_counter)
+        new_obj._nb_ts_max_protection_counter = copy.deepcopy(
+            self._nb_ts_max_protection_counter
         )
         new_obj._hard_overflow_threshold = copy.deepcopy(self._hard_overflow_threshold)
 
@@ -1417,7 +1428,7 @@ def _has_been_initialized(self):
         self._times_before_topology_actionable = np.zeros(
             shape=(bk_type.n_sub,), dtype=dt_int
         )
-        self._nb_timestep_overflow_allowed = np.full(
+        self._nb_ts_max_protection_counter = np.full(
             shape=(bk_type.n_line,),
             fill_value=self._parameters.NB_TIMESTEP_OVERFLOW_ALLOWED,
             dtype=dt_int,
@@ -1428,6 +1439,7 @@ def _has_been_initialized(self):
             dtype=dt_float,
         )
         self._timestep_overflow = np.zeros(shape=(bk_type.n_line,), dtype=dt_int)
+        self._protection_counter = np.zeros(shape=(bk_type.n_line,), dtype=dt_int)
 
         # update the parameters
         self.__new_param = self._parameters  # small hack to have it working as expected
@@ -1531,7 +1543,7 @@ def _update_parameters(self):
         )
         self._nb_ts_reco = self._parameters.NB_TIMESTEP_RECONNECTION
 
-        self._nb_timestep_overflow_allowed[
+        self._nb_ts_max_protection_counter[
             :
         ] = self._parameters.NB_TIMESTEP_OVERFLOW_ALLOWED
         self._hard_overflow_threshold[:] = self._parameters.HARD_OVERFLOW_THRESHOLD
@@ -3267,6 +3279,7 @@ def _aux_register_env_converged(self,
         # update the thermal limit, for DLR for example
         self.backend.update_thermal_limit(self)  
         overflow_lines = self.backend.get_line_overflow()
+        current_flows = self.backend.get_line_flow()
         # save the current topology as "last" topology (for connected powerlines)
         # and update the state of the disconnected powerline due to cascading failure
         self._backend_action.update_state(disc_lines)
@@ -3285,6 +3298,11 @@ def _aux_register_env_converged(self,
 
         # set to 0 the number of timestep for lines that are not on overflow
         self._timestep_overflow[~overflow_lines] = 0
+        
+        # update protection counter
+        engaged_protection = current_flows > self.backend.get_thermal_limit() * self._parameters.SOFT_OVERFLOW_THRESHOLD
+        self._protection_counter[engaged_protection] += 1
+        self._protection_counter[~engaged_protection] = 0
 
         # build the topological action "cooldown"
         aff_lines, aff_subs = action.get_topological_impact(_read_from_cache=True)
@@ -3835,7 +3853,8 @@ def _reset_vectors_and_timings(self):
         """
         self._no_overflow_disconnection = self._parameters.NO_OVERFLOW_DISCONNECTION
         self._timestep_overflow[:] = 0
-        self._nb_timestep_overflow_allowed[
+        self._protection_counter[:] = 0
+        self._nb_ts_max_protection_counter[
             :
         ] = self._parameters.NB_TIMESTEP_OVERFLOW_ALLOWED
 
@@ -3990,7 +4009,8 @@ def close(self):
             "_forbid_dispatch_off",
             "_no_overflow_disconnection",
             "_timestep_overflow",
-            "_nb_timestep_overflow_allowed",
+            "_protection_counter",
+            "_nb_ts_max_protection_counter",
             "_hard_overflow_threshold",
             "_times_before_line_status_actionable",
             "_max_timestep_line_status_deactivated",
@@ -4615,7 +4635,7 @@ def __del__(self):
         if hasattr(self, "_BaseEnv__closed") and not self.__closed:
             self.close()
 
-    def _update_vector_with_timestep(self, horizon, is_overflow):
+    def _update_vector_with_timestep(self, horizon, is_overflow, protection_triggered):
         """
         INTERNAL
 
@@ -4671,9 +4691,10 @@ def _update_vector_with_timestep(self, horizon, is_overflow):
         # this is tricky here because I have no model to predict the future... 
         # As i cannot do better, I simply do "if I am in overflow now, i will be later"
         self._timestep_overflow[is_overflow] += (horizon - 1)
+        self._protection_counter[protection_triggered] += (horizon - 1)
         return still_in_maintenance, reconnected, first_ts_maintenance
 
-    def _reset_to_orig_state(self, obs):
+    def _reset_to_orig_state(self, obs: BaseObservation):
         """
         INTERNAL
 
@@ -4736,6 +4757,7 @@ def _reset_to_orig_state(self, obs):
 
         # soft overflow
         self._timestep_overflow[:] = obs.timestep_overflow
+        self._protection_counter[:] = obs.timestep_protection_engaged
 
     def forecasts(self):
         # ensure that the "env.chronics_handler.forecasts" is called at most once per step

grid2op/Environment/maskedEnvironment.py

@@ -16,7 +16,6 @@
 from grid2op.Exceptions import EnvError
 from grid2op.dtypes import dt_bool, dt_float, dt_int
 from grid2op.Space import DEFAULT_N_BUSBAR_PER_SUB, DEFAULT_ALLOW_DETACHMENT
-from grid2op.MakeEnv.PathUtils import USE_CLASS_IN_FILE
 
 
 class MaskedEnvironment(Environment):
@@ -108,7 +107,7 @@ def _make_lines_of_interest(self, lines_of_interest):
     def _reset_vectors_and_timings(self):
         super()._reset_vectors_and_timings()
         self._hard_overflow_threshold[~self._lines_of_interest] = type(self).INF_VAL_THM_LIM
-        self._nb_timestep_overflow_allowed[~self._lines_of_interest] = type(self).INF_VAL_TS_OVERFLOW_ALLOW
+        self._nb_ts_max_protection_counter[~self._lines_of_interest] = type(self).INF_VAL_TS_OVERFLOW_ALLOW
 
     def get_kwargs(self, with_backend=True, with_chronics_handler=True):
         res = {}

grid2op/Episode/EpisodeReboot.py

@@ -20,6 +20,7 @@
 from grid2op.Chronics import GridValue, ChronicsHandler
 from grid2op.Opponent import BaseOpponent
 from grid2op.Environment import Environment
+from grid2op.Observation import BaseObservation
 
 from grid2op.Episode.EpisodeData import EpisodeData
 
@@ -212,7 +213,7 @@ def load(self, backend, agent_path=None, name=None, data=None, env_kwargs={}):
         self._assign_state(current_obs)
         return self.env.get_obs()
 
-    def _assign_state(self, obs):
+    def _assign_state(self, obs: BaseObservation):
         """
         works only if observation store the complete state of the grid...
         """
@@ -229,6 +230,7 @@ def _assign_state(self, obs):
         ) + obs.actual_dispatch.astype(dt_float)
         self.env.current_obs = obs
         self.env._timestep_overflow[:] = obs.timestep_overflow.astype(dt_int)
+        self.env._protection_counter[:] = obs.timestep_protection_engaged.astype(dt_int)
         self.env._times_before_line_status_actionable[
             :
         ] = obs.time_before_cooldown_line.astype(dt_int)

grid2op/Observation/baseObservation.py

@@ -163,6 +163,16 @@ class BaseObservation(GridObjects):
     timestep_overflow: :class:`numpy.ndarray`, dtype:int
         Gives the number of time steps since a powerline is in overflow.
 
+    timestep_protection_engaged: :class:`numpy.ndarray`, dtype:int
+        .. versionadded:: 1.11.0
+        
+        This counts the number of consecutive steps the "Time overcurrent protection" is too high.
+        
+        It is exacly :attr:`BaseObservation.timestep_overflow` unless the parameter
+        :attr:`grid2op.Parameters.Parameters.SOFT_OVERFLOW_THRESHOLD` != 1. 
+        
+        In that case it counts the consecutive steps for which `flow > limit * SOFT_OVERFLOW_THRESHOLD`
+
     time_before_cooldown_line: :class:`numpy.ndarray`, dtype:int
         For each powerline, it gives the number of time step the powerline is unavailable due to "cooldown"
         (see :attr:`grid2op.Parameters.Parameters.NB_TIMESTEP_COOLDOWN_LINE` for more information). 0 means the
@@ -436,7 +446,7 @@ class BaseObservation(GridObjects):
     gen_p_detached: :class:`numpy.ndarray`, dtype:float
     
     storage_p_detached: :class:`numpy.ndarray`, dtype:float
-        
+    
     _shunt_p: :class:`numpy.ndarray`, dtype:float
         Shunt active value (only available if shunts are available) (in MW)
 
@@ -516,6 +526,8 @@ class BaseObservation(GridObjects):
         "load_q_detached",
         "gen_p_detached",
         "storage_p_detached",
+        # better handling of soft_overflow_threshold (>= 1.11.0)
+        "timestep_protection_engaged",
     ]
 
     attr_list_vect = None
@@ -551,6 +563,7 @@ def __init__(self,
 
         cls = type(self)
         self.timestep_overflow = np.empty(shape=(cls.n_line,), dtype=dt_int)
+        self.timestep_protection_engaged = np.empty(shape=(cls.n_line,), dtype=dt_int)
 
         # 0. (line is disconnected) / 1. (line is connected)
         self.line_status = np.empty(shape=cls.n_line, dtype=dt_bool)
@@ -744,6 +757,8 @@ def _aux_copy(self, other : Self) -> None:
             "load_q_detached",
             "gen_p_detached",
             "storage_p_detached",
+            # soft_overflow_threshold
+            "timestep_protection_engaged"
         ]
 
         if type(self).shunts_data_available:
@@ -1376,6 +1391,7 @@ def reset(self) -> None:
         self.time_next_maintenance[:] = 0
         self.duration_next_maintenance[:] = 0
         self.timestep_overflow[:] = 0
+        self.timestep_protection_engaged[:] = 0
 
         # calendar data
         self.year = dt_int(1970)
@@ -1534,6 +1550,7 @@ def set_game_over(self,
 
         # overflow
         self.timestep_overflow[:] = 0
+        self.timestep_protection_engaged[:] = 0
 
         if type(self).shunts_data_available:
             self._shunt_p[:] = 0.0
@@ -2485,6 +2502,7 @@ def get_energy_graph(self) -> networkx.Graph:
             - `cooldown`: the number of step you need to wait before being able to act on this powerline (max over all powerlines)
             - `thermal_limit`: maximum flow allowed on the the powerline (sum over all powerlines)
             - `timestep_overflow`: number of time steps during which the powerline is on overflow (max over all powerlines)
+            - `timestep_protection_engaged`: number of time steps during which the "time overcurrent protection" are triggered (new in version 1.10.0)
             - `p_or`: active power injected at this node at the "origin side" (in MW) (sum over all the powerlines).
             - `p_ex`: active power injected at this node at the "extremity side" (in MW) (sum over all the powerlines).
             - `q_or`: reactive power injected at this node at the "origin side" (in MVAr) (sum over all the powerlines).
@@ -2690,6 +2708,10 @@ def get_energy_graph(self) -> networkx.Graph:
             self.timestep_overflow, "timestep_overflow", lor_bus, lex_bus, graph,
             fun_reduce=max
         )
+        self._add_edges_simple(
+            self.timestep_protection_engaged, "timestep_protection_engaged", lor_bus, lex_bus, graph,
+            fun_reduce=max
+        )
         self._add_edges_simple(
             self.line_or_to_subid,
             "sub_id_or", lor_bus, lex_bus, graph
@@ -2995,6 +3017,7 @@ def _aux_add_lines(self, graph, cls, first_id):
         nodes_prop = [("rho", self.rho),
                       ("connected", self.line_status),
                       ("timestep_overflow", self.timestep_overflow),
+                      ("timestep_protection_engaged", self.timestep_protection_engaged),
                       ("time_before_cooldown_line", self.time_before_cooldown_line),
                       ("time_next_maintenance", self.time_next_maintenance),
                       ("duration_next_maintenance", self.duration_next_maintenance),
@@ -3844,6 +3867,7 @@ def to_dict(self):
         if self._dictionnarized is None:
             self._dictionnarized = {}
             self._dictionnarized["timestep_overflow"] = self.timestep_overflow
+            self._dictionnarized["timestep_protection_engaged"] = self.timestep_protection_engaged
             self._dictionnarized["line_status"] = self.line_status
             self._dictionnarized["topo_vect"] = self.topo_vect
             self._dictionnarized["loads"] = {}
@@ -4398,6 +4422,7 @@ def _update_obs_complete(self, env: "grid2op.Environment.BaseEnv", with_forecast
 
         # get the values related to topology
         self.timestep_overflow[:] = env._timestep_overflow
+        self.timestep_protection_engaged[:] = env._protection_counter
 
         # attribute that depends only on the backend state
         self._update_attr_backend(env.backend)

grid2op/Parameters.py

@@ -624,11 +624,11 @@ def check_valid(self):
             raise RuntimeError(
                 f'Impossible to convert SOFT_OVERFLOW_THRESHOLD to float with error \n:"{exc_}"'
             ) from exc_
-        if self.SOFT_OVERFLOW_THRESHOLD < 1.0:
-            raise RuntimeError(
-                "SOFT_OVERFLOW_THRESHOLD < 1., this should be >= 1. (use env.set_thermal_limit "
-                "to modify the thermal limit)"
-            )
+        # if self.SOFT_OVERFLOW_THRESHOLD < 1.0:
+        #     raise RuntimeError(
+        #         "SOFT_OVERFLOW_THRESHOLD < 1., this should be >= 1. (use env.set_thermal_limit "
+        #         "to modify the thermal limit)"
+        #     )
         if self.SOFT_OVERFLOW_THRESHOLD >= self.HARD_OVERFLOW_THRESHOLD:
             raise RuntimeError(
                 "self.SOFT_OVERFLOW_THRESHOLD >= self.HARD_OVERFLOW_THRESHOLD this would that the"