improve documentation for redispatching failed vs illegal vs ambiguous

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

Author: BDonnot

CHANGELOG.rst

@@ -100,6 +100,16 @@ Native multi agents support:
 - add detachment
 - add change_bus / set_bus
 
+[1.11.1] - 2025-xx-yy
+--------------------------
+- [BREAKING] the `info` returned argument of `env.step(...)` function
+  does not have the unclear `is_redispatching_illegal` key. This key has been
+  replaced (without any change to its signification) with `failed_redispatching`
+- [IMPROVED] clarity of the `failed_redispatching` key of the `info` returned value
+  of the `env.step` function (previously called `is_redispatching_illegal` which 
+  was not clear)
+
+
 [1.11.0] - 2025-04-14
 -----------------------
 - [BREAKING] Change for `FromMultiEpisodeData` that disables the caching by default

grid2op/Environment/baseEnv.py

@@ -36,7 +36,8 @@
 from grid2op.typing_variables import N_BUSBAR_PER_SUB_TYPING
 from grid2op.Exceptions import (Grid2OpException,
                                 EnvError,
-                                InvalidRedispatching,
+                                IllegalRedispatching,
+                                ImpossibleRedispatching,
                                 GeneratorTurnedOffTooSoon,
                                 GeneratorTurnedOnTooSoon,
                                 AmbiguousActionRaiseAlert,
@@ -78,7 +79,7 @@
 )
 
 
-BASE_TXT_COPYRIGHT = """# Copyright (c) 2019-2020, RTE (https://www.rte-france.com)
+BASE_TXT_COPYRIGHT = """# Copyright (c) 2019-2025, RTE (https://www.rte-france.com)
 # See AUTHORS.txt
 # This Source Code Form is subject to the terms of the Mozilla Public License, version 2.0.
 # If a copy of the Mozilla Public License, version 2.0 was not distributed with this file,
@@ -87,7 +88,13 @@
 # This file is part of Grid2Op, Grid2Op a testbed platform to model sequential decision making in power systems.
 
 # THIS FILE HAS BEEN AUTOMATICALLY GENERATED BY "env.generate_classes()"
-# WE DO NOT RECOMMEND TO ALTER IT IN ANY WAY
+# WE DO NOT RECOMMEND TO ALTER IT IN ANY WAY.
+# THIS INCLUDES, BUT IS NOT LIMITED TO: 
+# - MODIFY IT
+# - DELETE IT
+# - MOVE IT
+# - RENAME IT
+
 """
 
 class BaseEnv(GridObjects, RandomObject, ABC):
@@ -2067,6 +2074,7 @@ def _get_already_modified_gen(self, action):
         return self._already_modified_gen
 
     def _prepare_redisp(self, action, new_p, already_modified_gen):
+        cls = type(self)
         # trying with an optimization method
         except_ = None
         info_ = []
@@ -2082,10 +2090,10 @@ def _prepare_redisp(self, action, new_p, already_modified_gen):
         ):
             return valid, except_, info_
         # check that everything is consistent with pmin, pmax:
-        if (self._target_dispatch > self.gen_pmax - self.gen_pmin).any():
+        if (self._target_dispatch > cls.gen_pmax - cls.gen_pmin).any():
             # action is invalid, the target redispatching would be above pmax for at least a generator
-            cond_invalid = self._target_dispatch > self.gen_pmax - self.gen_pmin
-            except_ = InvalidRedispatching(
+            cond_invalid = self._target_dispatch > cls.gen_pmax - cls.gen_pmin
+            except_ = IllegalRedispatching(
                 "You cannot ask for a dispatch higher than pmax - pmin  [it would be always "
                 "invalid because, even if the sepoint is pmin, this dispatch would set it "
                 "to a number higher than pmax, which is impossible]. Invalid dispatch for "
@@ -2094,10 +2102,10 @@ def _prepare_redisp(self, action, new_p, already_modified_gen):
             )
             self._target_dispatch -= redisp_act_orig
             return valid, except_, info_
-        if (self._target_dispatch < self.gen_pmin - self.gen_pmax).any():
+        if (self._target_dispatch < cls.gen_pmin - cls.gen_pmax).any():
             # action is invalid, the target redispatching would be below pmin for at least a generator
-            cond_invalid = self._target_dispatch < self.gen_pmin - self.gen_pmax
-            except_ = InvalidRedispatching(
+            cond_invalid = self._target_dispatch < cls.gen_pmin - cls.gen_pmax
+            except_ = IllegalRedispatching(
                 "You cannot ask for a dispatch lower than pmin - pmax  [it would be always "
                 "invalid because, even if the sepoint is pmax, this dispatch would set it "
                 "to a number bellow pmin, which is impossible]. Invalid dispatch for "
@@ -2110,13 +2118,13 @@ def _prepare_redisp(self, action, new_p, already_modified_gen):
         # i can't redispatch turned off generators [turned off generators need to be turned on before redispatching]
         if (redisp_act_orig[np.abs(new_p) <= 1e-7]).any() and self._forbid_dispatch_off:
             # action is invalid, a generator has been redispatched, but it's turned off
-            except_ = InvalidRedispatching(
+            except_ = IllegalRedispatching(
                 "Impossible to dispatch a turned off generator"
             )
             self._target_dispatch -= redisp_act_orig
             return valid, except_, info_
 
-        if self._forbid_dispatch_off is True:
+        if self._forbid_dispatch_off:
             redisp_act_orig_cut = 1.0 * redisp_act_orig
             redisp_act_orig_cut[np.abs(new_p) <= 1e-7] = 0.0
             if (redisp_act_orig_cut != redisp_act_orig).any():
@@ -2148,7 +2156,7 @@ def _make_redisp(self, already_modified_gen, new_p):
 
     def _compute_dispatch_vect(self, already_modified_gen, new_p):        
         except_ = None
-        
+        cls = type(self)
         # handle the case where there are storage or redispatching
         # action or curtailment action on the "init state"
         # of the grid
@@ -2162,8 +2170,8 @@ def _compute_dispatch_vect(self, already_modified_gen, new_p):
             | (np.abs(self._actual_dispatch) >= 1e-7)
             | (self._target_dispatch != self._actual_dispatch)
         )
-        gen_participating[~self.gen_redispatchable] = False
-        if type(self).detachment_is_allowed:
+        gen_participating[~cls.gen_redispatchable] = False
+        if cls.detachment_is_allowed:
             gen_participating[self._backend_action.get_gen_detached()] = False
         incr_in_chronics = new_p - (
             self._gen_activeprod_t_redisp - self._actual_dispatch
@@ -2172,16 +2180,16 @@ def _compute_dispatch_vect(self, already_modified_gen, new_p):
         # check if the constraints are violated
         ## total available "juice" to go down (incl ramp and pmin / pmax)
         p_min_down = (
-            self.gen_pmin[gen_participating]
+            cls.gen_pmin[gen_participating]
             - self._gen_activeprod_t_redisp[gen_participating]
         )
-        avail_down = np.maximum(p_min_down, -self.gen_max_ramp_down[gen_participating])
+        avail_down = np.maximum(p_min_down, -cls.gen_max_ramp_down[gen_participating])
         ## total available "juice" to go up (incl. ramp and pmin / pmax)
         p_max_up = (
-            self.gen_pmax[gen_participating]
+            cls.gen_pmax[gen_participating]
             - self._gen_activeprod_t_redisp[gen_participating]
         )
-        avail_up = np.minimum(p_max_up, self.gen_max_ramp_up[gen_participating])
+        avail_up = np.minimum(p_max_up, cls.gen_max_ramp_up[gen_participating])
         except_ = self._detect_infeasible_dispatch(
             incr_in_chronics[gen_participating], avail_down, avail_up
         )
@@ -2192,21 +2200,21 @@ def _compute_dispatch_vect(self, already_modified_gen, new_p):
                 and self._parameters.ALLOW_DISPATCH_GEN_SWITCH_OFF
             ):
                 gen_participating_tmp = self.gen_redispatchable
-                if type(self).detachment_is_allowed:
+                if cls.detachment_is_allowed:
                     gen_participating_tmp[self._backend_action.get_gen_detached()] = False
                 p_min_down_tmp = (
-                    self.gen_pmin[gen_participating_tmp]
+                    cls.gen_pmin[gen_participating_tmp]
                     - self._gen_activeprod_t_redisp[gen_participating_tmp]
                 )
                 avail_down_tmp = np.maximum(
-                    p_min_down_tmp, -self.gen_max_ramp_down[gen_participating_tmp]
+                    p_min_down_tmp, -cls.gen_max_ramp_down[gen_participating_tmp]
                 )
                 p_max_up_tmp = (
-                    self.gen_pmax[gen_participating_tmp]
+                    cls.gen_pmax[gen_participating_tmp]
                     - self._gen_activeprod_t_redisp[gen_participating_tmp]
                 )
                 avail_up_tmp = np.minimum(
-                    p_max_up_tmp, self.gen_max_ramp_up[gen_participating_tmp]
+                    p_max_up_tmp, cls.gen_max_ramp_up[gen_participating_tmp]
                 )
                 except_tmp = self._detect_infeasible_dispatch(
                     incr_in_chronics[gen_participating_tmp],
@@ -2404,7 +2412,7 @@ def f(init):
                     "Redispatching automaton terminated with error (no more information available "
                     'at this point):\n"{}"'.format(res.message)
                 )
-                except_ = InvalidRedispatching(error_dispatch)
+                except_ = ImpossibleRedispatching(error_dispatch)
         return except_
 
     def _detect_infeasible_dispatch(self, incr_in_chronics, avail_down, avail_up):
@@ -2431,7 +2439,7 @@ def _detect_infeasible_dispatch(self, incr_in_chronics, avail_down, avail_up):
                 pmax="pmax",
                 max_ramp_up="max_ramp_up",
             )
-            except_ = InvalidRedispatching(msg)
+            except_ = ImpossibleRedispatching(msg)
         elif sum_move < avail_down_sum:
             # infeasible because not enough is asked
             msg = DETAILED_REDISP_ERR_MSG.format(
@@ -2447,7 +2455,7 @@ def _detect_infeasible_dispatch(self, incr_in_chronics, avail_down, avail_up):
                 pmax="pmin",
                 max_ramp_up="max_ramp_down",
             )
-            except_ = InvalidRedispatching(msg)
+            except_ = ImpossibleRedispatching(msg)
         return except_
 
     def _update_actions(self):
@@ -3116,7 +3124,7 @@ def _aux_apply_redisp(self,
                           except_: List[Exception],
                           powerline_status):
         cls = type(self)
-        is_illegal_redisp = False
+        failed_redisp = False
         is_done = False
         is_illegal_reco = False
 
@@ -3136,7 +3144,7 @@ def _aux_apply_redisp(self,
             _ = action.get_topological_impact(powerline_status, _store_in_cache=True, _read_from_cache=False)
             if cls.dim_alerts:
                 action.raise_alert = orig_action.raise_alert
-            is_illegal_redisp = True
+            failed_redisp = True
             except_.append(except_tmp)
 
             if cls.n_storage > 0:
@@ -3170,11 +3178,12 @@ def _aux_apply_redisp(self,
             _ = res_action.get_topological_impact(powerline_status, _store_in_cache=True, _read_from_cache=False)
             if cls.dim_alerts:
                 res_action.raise_alert = action.raise_alert
-            is_illegal_redisp = True
+            failed_redisp = True
+            
             except_.append(except_tmp)
             is_done = True
             except_.append(
-                InvalidRedispatching(
+                ImpossibleRedispatching(
                     "Game over due to infeasible redispatching state. "
                     'The routine used to compute the "next state" has diverged. '
                     "This means that there is no way to compute a physically valid generator state "
@@ -3183,7 +3192,7 @@ def _aux_apply_redisp(self,
                     "a generator would be damaged in real life. This is a game over."
                 )
             )
-            return res_action, is_illegal_redisp, is_illegal_reco, is_done
+            return res_action, failed_redisp, is_illegal_reco, is_done
 
         # check the validity of min downtime and max uptime
         except_tmp = self._handle_updown_times(gen_up_before, self._actual_dispatch)
@@ -3198,7 +3207,7 @@ def _aux_apply_redisp(self,
         else:
             res_action = action
             # self._backend_action.set_redispatch(self._actual_dispatch)
-        return res_action, is_illegal_redisp, is_illegal_reco, is_done
+        return res_action, failed_redisp, is_illegal_reco, is_done
 
     def _aux_update_backend_action(self,
                                    action: BaseAction,
@@ -3514,7 +3523,9 @@ def step(self, action: BaseAction) -> Tuple[BaseObservation,
                       that it is disconnected just after, 2 that it's disconnected just after etc.)
                     - "is_illegal" (``bool``) whether the action given as input was illegal
                     - "is_ambiguous" (``bool``) whether the action given as input was ambiguous.
-                    - "is_dispatching_illegal" (``bool``) was the action illegal due to redispatching
+                    - "failed_redispatching" (``bool``) has the redispatching part of this action (or any previous one) 
+                      lead to infeasibility. If `True` it can means that either the redispatching part of the
+                      action has been completely ignored or that the environment is over.
                     - "is_illegal_reco" (``bool``) was the action illegal due to a powerline reconnection
                     - "reason_alarm_illegal" (``None`` or ``Exception``) reason for which the alarm is illegal
                       (it's None if no alarm are raised or if the alarm feature is not used)
@@ -3584,7 +3595,7 @@ def step(self, action: BaseAction) -> Tuple[BaseObservation,
         is_done = False
         is_illegal = False
         is_ambiguous = False
-        is_illegal_redisp = False
+        failed_redisp = False
         is_illegal_reco = False
         reason_alarm_illegal = None
         self._is_alarm_illegal = False
@@ -3703,7 +3714,7 @@ def step(self, action: BaseAction) -> Tuple[BaseObservation,
                 res_disp = self._aux_apply_redisp(
                     action, new_p, new_p_th, gen_curtailed, except_, powerline_status
                 )
-                action, is_illegal_redisp, is_illegal_reco, is_done = res_disp
+                action, failed_redisp, is_illegal_reco, is_done = res_disp
 
             self._time_redisp += time.perf_counter() - beg__redisp
 
@@ -3769,7 +3780,7 @@ def step(self, action: BaseAction) -> Tuple[BaseObservation,
             "disc_lines": self._disc_lines,
             "is_illegal": is_illegal,
             "is_ambiguous": is_ambiguous,
-            "is_dispatching_illegal": is_illegal_redisp,
+            "failed_redispatching": failed_redisp,
             "is_illegal_reco": is_illegal_reco,
             "reason_alarm_illegal": reason_alarm_illegal,
             "reason_alert_illegal": reason_alert_illegal,
@@ -3788,7 +3799,7 @@ def step(self, action: BaseAction) -> Tuple[BaseObservation,
             action,
             has_error,
             self.done,  # is_done
-            is_illegal or is_illegal_redisp or is_illegal_reco,
+            is_illegal or failed_redisp or is_illegal_reco,
             is_ambiguous,
         )
         self.infos["rewards"] = other_reward

grid2op/Exceptions/__init__.py

@@ -14,6 +14,7 @@
     "UnknownEnv",
     "MultiEnvException",
     "IllegalAction",
+    "IllegalRedispatching",
     "OnProduction",
     "VSetpointModified",
     "ActiveSetPointAbovePmax",
@@ -63,7 +64,8 @@
     "SomeGeneratorAbovePmax",
     "SomeGeneratorBelowPmin",
     "SomeGeneratorAboveRampmax", 
-    "SomeGeneratorBelowRampmin"
+    "SomeGeneratorBelowRampmin",
+    "ImpossibleRedispatching",
 ]
 
 from grid2op.Exceptions.grid2OpException import Grid2OpException
@@ -84,7 +86,8 @@
                                               SomeGeneratorAbovePmax,
                                               SomeGeneratorBelowPmin,
                                               SomeGeneratorAboveRampmax, 
-                                              SomeGeneratorBelowRampmin)
+                                              SomeGeneratorBelowRampmin,
+                                              ImpossibleRedispatching)
 
 from grid2op.Exceptions.illegalActionExceptions import (IllegalAction,
                                                         OnProduction,
@@ -95,6 +98,7 @@
                                                         OnLines,
                                                         InvalidReconnection,
                                                         UnitCommitorRedispachingNotAvailable,
+                                                        IllegalRedispatching,
                                                         )
 
 from grid2op.Exceptions.ambiguousActionExceptions import (NotEnoughGenerators,

grid2op/Exceptions/envExceptions.py

@@ -134,6 +134,7 @@ class SomeGeneratorBelowPmin(EnvError):
     """
     pass
 
+
 class SomeGeneratorAboveRampmax(EnvError):
     """This is a more precise exception saying that, at the end of the simulation, some generator would
     have their production vary too much, which is not possible in practice.
@@ -157,6 +158,16 @@ class SomeGeneratorBelowRampmin(EnvError):
     """
     pass
 
+
+class ImpossibleRedispatching(EnvError):
+    """This is a more precise exception saying that,  the simulation of a step cannot be made because some 
+    generators would break their physical constraints.
+    
+    .. versionadded:: 1.11.1
+    """
+    pass
+    
+    
 # Unknown environment at creation
 class UnknownEnv(Grid2OpException):
     """

grid2op/Exceptions/illegalActionExceptions.py

@@ -89,6 +89,16 @@ class InvalidReconnection(OnLines):
     pass
 
 
+class IllegalRedispatching(IllegalAction):
+    """
+    This is a more precise exception than :class:`IllegalAction` indicating that
+    the :class:`grid2op.BaseAction.BaseAction`
+    try to apply an invalid redispatching strategy.
+    """
+
+    pass
+
+
 # attempt to use redispatching or unit commit method in an environment not set up.
 class UnitCommitorRedispachingNotAvailable(IllegalAction):
     """