Merge pull request #704 from BDonnot/bd_dev

Small fixes (mainly doc) from review

Author: BDonnot

CHANGELOG.rst

@@ -100,7 +100,7 @@ Native multi agents support:
 - add detachment
 - add change_bus / set_bus
 
-[1.11.0] - 202x-yy-zz
+[1.11.0] - 2025-04-14
 -----------------------
 - [BREAKING] Change for `FromMultiEpisodeData` that disables the caching by default
   when creating the data.

README.md

@@ -202,6 +202,9 @@ interesting part of this framework:
 * [11_IntegrationWithExistingRLFrameworks](getting_started/11_IntegrationWithExistingRLFrameworks.ipynb)
   [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Grid2Op/grid2op/blob/master/getting_started/11_IntegrationWithExistingRLFrameworks.ipynb)
   explains how to use grid2op with other reinforcement learning framework. TODO: this needs to be redone
+* [12_DetachmentOfLoadsAndGenerators.ipynb](getting_started/12_DetachmentOfLoadsAndGenerators.ipynb.ipynb)
+  [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Grid2Op/grid2op/blob/master/getting_started/12_DetachmentOfLoadsAndGenerators.ipynb.ipynb)
+  explains briefly what is detachment.
 
 Try them out in your own browser without installing
 anything with the help of mybinder:

binder/environment.yml

@@ -8,7 +8,6 @@ dependencies:
   - pip
   - pip:
     - grid2op
-    - jyquickhelper
     - numpy
     - numba
     - seaborn

getting_started/13_DetachmentOfLoadsAndGenerators.ipynb renamed to getting_started/12_DetachmentOfLoadsAndGenerators.ipynb

@@ -23,14 +23,13 @@
     "from pathlib import Path\n",
     "\n",
     "# Setup Environment\n",
-    "data_path = Path.cwd() / \"grid2op\" / \"data\"\n",
-    "p = Parameters()\n",
-    "p.MAX_SUB_CHANGED = 5\n",
-    "env = grid2op.make(data_path / \"rte_case5_example\", param=p, allow_detachment=True)\n",
+    "env_standard = grid2op.make(\"rte_case5_example\", test=True, allow_detachment=False)\n",
+    "env_with_detach = grid2op.make(\"rte_case5_example\", test=True, allow_detachment=True)\n",
     "\n",
     "# Setup Plotter Utility\n",
-    "plotter = PlotMatplot(env.observation_space, load_name=True, gen_name=True, dpi=150)\n",
-    "print(f\"Loads: {env.n_load}, Generators: {env.n_gen}, Storage: {env.n_storage}, Allow Detachment: {env._allow_detachment}\")"
+    "plotter = PlotMatplot(env_standard.observation_space, load_name=True, gen_name=True, dpi=150)\n",
+    "for env, env_name in zip([env_standard, env_with_detach], [\"env_standard\", \"env_with_detach\"]):\n",
+    "    print(f\"For {env_name}: Loads: {env.n_load}, Generators: {env.n_gen}, Storage: {env.n_storage}, Detachment is allowed: {env.detachment_is_allowed}\")"
    ]
   },
   {
@@ -46,22 +45,33 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "load_lookup = {name:i for i,name in enumerate(env.name_load)}\n",
-    "gen_lookup = {name:i for i,name in enumerate(env.name_gen)}\n",
-    "act = env.action_space({\"set_bus\":[(env.load_pos_topo_vect[load_lookup[\"load_3_1\"]], -1),\n",
-    "                                   (env.load_pos_topo_vect[load_lookup[\"load_4_2\"]], -1)]})\n",
+    "act = env_standard.action_space({\"set_bus\":{\"loads_id\": [(\"load_3_1\", -1)]}})\n",
     "print(act)\n",
-    "env.set_id(\"00\")\n",
-    "init_obs = env.reset()\n",
-    "obs, reward, done, info = env.step(act)\n",
+    "init_obs = env_standard.reset(seed=0, options={\"time serie id\": \"00\"})\n",
+    "obs, reward, done, info = env_standard.step(act)\n",
     "plotter.plot_obs(obs, figure=plt.figure(figsize=(8,5)))\n",
+    "plt.title(\"Without providing 'allow_detachment=True' grid2op fails if a load is disconnected\")\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "init_obs = env_with_detach.reset(seed=0, options={\"time serie id\": \"00\"})\n",
+    "obs, reward, done, info = env_with_detach.step(act)\n",
+    "plotter.plot_obs(obs, figure=plt.figure(figsize=(8,5)))\n",
+    "plt.title(\"Providing 'allow_detachment=True' grid2op continues if a load is disconnected\")\n",
+    "plt.tight_layout()\n",
     "plt.show()"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "venv_test",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -75,9 +85,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.7"
+   "version": "3.10.12"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

grid2op/Action/baseAction.py

@@ -339,7 +339,7 @@ class BaseAction(GridObjects):
     Typically `0 <= storage_id < env.n_storage` and `amount` is a floating point between the maximum
     power and minimum power the storage unit can absorb / produce.
 
-    Finally, in order to perform curtailment action on renewable generators, you can:
+    In order to perform curtailment action on renewable generators, you can:
 
     .. code-block:: python
 
@@ -354,7 +354,40 @@ class BaseAction(GridObjects):
     giving the limit of power you allow each renewable generator to produce (expressed in ratio of
     Pmax). For example if `gen_id=1` and `amount=0.7` it means you limit the production of
     generator 1 to 70% of its Pmax.
+    
+    Finally, provided that the environment is loaded with `allow_detachment=True`, you can also
+    perform "detachment" action on the grid with:
+    
+    .. code-block:: python
+    
+        import grid2op
+        from grid2op.Action import BaseAction
+        env_name = "l2rpn_case14_sandbox"  # or any other name
+        env = grid2op.make(env_name, allow_detachment=True)
+
+        # method 1
+        act = env.action_space({"detach_load": [load1_id, load2_id, ...]})
+
+        # method 2
+        act = env.action_space()
+        act.detach_load = [load1_id, load2_id, ...]
 
+    You can do similar action for storage and generator, for example
+    
+    .. code-block:: python
+    
+        import grid2op
+        from grid2op.Action import BaseAction
+        env_name = "educ_case14_storage"  # or any other name
+        env = grid2op.make(env_name, test=True, allow_detachment=True)
+
+        # for generators (method 1 showed here, but method 2 works, of course)
+        act = env.action_space({"detach_gen": [gen1_id, gen2_id, ...]})
+        
+        # for storage units (method 2 showed here, but method 1 works too, of course)
+        act = env.action_space()
+        act.detach_storage = [storage1_id, storage2_id, ...]
+    
     """
 
     authorized_keys = {
@@ -550,19 +583,6 @@ def process_detachment(cls):
                 if el in cls.authorized_keys:
                     cls.authorized_keys.remove(el)
             cls._update_value_set()
-        # else:
-        #     # I support detachment, I need to make sure this is registered
-        #     cls.attr_list_vect = copy.deepcopy(cls.attr_list_vect)
-        #     cls.attr_list_set = copy.deepcopy(cls.attr_list_set)
-        #     # add the detachment from the list to vector
-        #     for el in ["_detach_load", "_detach_gen", "_detach_storage"]:
-        #         if el not in cls.attr_list_vect:
-        #             cls.attr_list_vect.append(el)
-        #     # add the detachment from the allowed action
-        #     for el in ["detach_load", "detach_gen", "detach_storage"]:
-        #         if el not in cls.authorized_keys:
-        #             cls.authorized_keys.add(el)
-        #     cls._update_value_set()
         return super().process_detachment()
 
     def copy(self) -> "BaseAction":
@@ -3569,6 +3589,16 @@ def __str__(self) -> str:
                 res.append(f"\t - Raise alert(s) {line_str}")
             else:
                 res.append("\t - Not raise any alert")
+        
+        if my_cls.detachment_is_allowed:
+            for el in my_cls.OBJ_SUPPORT_DETACH:
+                _modif_detach_xxx = getattr(self, f"_modif_detach_{el}")
+                _detach_xxx = getattr(self, f"_detach_{el}")
+                if _modif_detach_xxx:
+                    res.append(f"\t - Detach {el}: {_detach_xxx.nonzero()[0]}")
+                else:
+                    res.append(f"\t - Not detach any {el}")
+                    
         return "\n".join(res)
 
     def impact_on_objects(self) -> dict:

grid2op/Action/playableAction.py

@@ -28,7 +28,10 @@ class PlayableAction(BaseAction):
         "set_storage",
         "curtail",
         "raise_alarm",
-        "raise_alert"
+        "raise_alert",
+        "detach_load",  # new in 1.11.0
+        "detach_gen",  # new in 1.11.0
+        "detach_storage",  # new in 1.11.0
     }
 
     attr_list_vect = [
@@ -40,7 +43,10 @@ class PlayableAction(BaseAction):
         "_storage_power",
         "_curtail",
         "_raise_alarm",
-        "_raise_alert"
+        "_raise_alert",
+        "_detach_load",  # new in 1.11.0
+        "_detach_gen",  # new in 1.11.0
+        "_detach_storage",  # new in 1.11.0
     ]
     attr_list_set = set(attr_list_vect)
     shunt_added = True  # no shunt here

grid2op/Observation/baseObservation.py

@@ -432,20 +432,65 @@ class BaseObservation(GridObjects):
           `env.parameters.ALERT_TIME_WINDOW` steps)  
 
     gen_p_delta: :class:`numpy.ndarray`, dtype:float
+        .. versionadded:: 1.11.0
+        
+        Difference between the generator setpoint (asked by the environment)
+        and the generator real active value at the given steps.
+        
+        For example, if the "asked generator value" is such that 
+        "sum asked_generator_value = sum load" then the 
+        gen_p_delta attribute will corresponds exactly to how the 
+        power losses are compensated by the backend.
      
     load_detached: :class:`numpy.ndarray`, dtype:bool
+        .. versionadded:: 1.11.0
+        
+        Whether or not each load has been detached (only 
+        available for env supporting detachement feature)
     
     gen_detached: :class:`numpy.ndarray`, dtype:bool
+        .. versionadded:: 1.11.0
+        
+        Whether or not each generator has been detached (only 
+        available for env supporting detachement feature)
     
     storage_detached: :class:`numpy.ndarray`, dtype:bool
+        .. versionadded:: 1.11.0
+        
+        Whether or not each storage unit has been detached (only 
+        available for env supporting detachement feature)
     
     load_p_detached: :class:`numpy.ndarray`, dtype:float
+        .. versionadded:: 1.11.0
+        
+        Amount (in MW) given how many MW have beeen "detached"
+        for each load on the grid. It is 0 for 
+        load still connected to the grid and only available for
+        environment supporting detachment.
     
     load_q_detached: :class:`numpy.ndarray`, dtype:float
+        .. versionadded:: 1.11.0
+        
+        Amount (in MVAr) given how many MVAr have beeen "detached"
+        for each load on the grid. It is 0 for 
+        load still connected to the grid and only available for
+        environment supporting detachment.
     
     gen_p_detached: :class:`numpy.ndarray`, dtype:float
+        .. versionadded:: 1.11.0
+        
+        Amount (in MW) given how many MW have beeen "detached"
+        for each generator on the grid. It is 0 for 
+        generator still connected to the grid and only available for
+        environment supporting detachment.
     
     storage_p_detached: :class:`numpy.ndarray`, dtype:float
+        .. versionadded:: 1.11.0
+        
+        Amount (in MW) given how many MW have beeen "detached"
+        for each storage unit on the grid. It is 0 for 
+        storage unit still connected to the grid and only available for
+        environment supporting detachment.
     
     _shunt_p: :class:`numpy.ndarray`, dtype:float
         Shunt active value (only available if shunts are available) (in MW)
@@ -1294,6 +1339,8 @@ def _aux_process_grid2op_compat_1_11_0(cls):
             "load_q_detached",
             "gen_p_detached",
             "storage_p_detached",
+            # protection (>= 1.11.0)
+            "timestep_protection_engaged"
         ]:
             try:
                 cls.attr_list_vect.remove(el)