Merge pull request #187 from BDonnot/bd_dev

Bd dev

CHANGELOG.rst

@@ -31,6 +31,7 @@ Change Log
 - [???] "asynch" multienv
 - [???] properly model interconnecting powerlines
 
+
 [1.9.9] - 2024-xx-yy
 ----------------------
 - [BREAKING] the order of the actions in `env.action_space.get_all_unitary_line_set` and 
@@ -49,9 +50,13 @@ Change Log
   in some cases (especially at the time where a line was reconnected)
 - [FIXED] `MultiDiscreteActSpace` and `DiscreteActSpace` could be the same classes
   on some cases (typo in the code).
+- [FIXED] a bug in `MultiDiscreteActSpace` : the "do nothing" action could not be done if `one_sub_set` (or `one_sub_change`)
+  was selected in `attr_to_keep`
 - [ADDED] a method `gridobj.topo_vect_element()` that does the opposite of `gridobj.xxx_pos_topo_vect`
 - [ADDED] a mthod `gridobj.get_powerline_id(sub_id)` that gives the
   id of all powerlines connected to a given substation
+- [ADDED] a convenience function `obs.get_back_to_ref_state(...)`
+  for the observation and not only the action_space.
 - [IMPROVED] handling of "compatibility" grid2op version
   (by calling the relevant things done in the base class 
   in `BaseAction` and `BaseObservation`) and by using the `from packaging import version`
@@ -67,6 +72,9 @@ Change Log
 - [IMPROVED] `obs.get_elements_graph()` by giving access to the bus id (local, global and 
   id of the node) where each element is connected.
 - [IMPROVED] description of the different graph of the grid in the documentation.
+- [IMPROVED] type hints for the `gym_compat` module (more work still required in this area)
+- [IMPROVED] the `MultiDiscreteActSpace` to have one "dimension" controling all powerlines
+  (see "one_line_set" and "one_line_change")
 
 [1.9.8] - 2024-01-26
 ----------------------

docs/action.rst

@@ -448,8 +448,31 @@ Easier actions manipulation
 ----------------------------
 The action class presented here can be quite complex to apprehend, especially for a machine learning algorithm.
 
-It is possible to use the :class:`grid2op.Converter` class for such purpose. You can have a look at the dedicated
-documentation.
+Grid2op offers some more "convient" manipulation of the powergrid by transforming this rather "descriptive"
+action formulation to "action_space" that are compatible with Farama Fundation Gymnasium package (
+package that was formerly "openAI gym").
+
+This includes:
+
+- :class:`grid2op.gym_compat.GymActionSpace` which "represents" actions as a gymnasium `Dict`
+- :class:`grid2op.gym_compat.BoxGymActSpace` which represents actions as gymnasium `Box` 
+  (actions are numpy arrays). This is especially suited for continuous attributes
+  such as redispatching, storage or curtailment.
+- :class:`grid2op.gym_compat.DiscreteActSpace` which represents actions as gymnasium `Discrete`
+  (actions are integer). This is especially suited for discrete actions such as 
+  setting line status or topologies at substation.
+- :class:`grid2op.gym_compat.MultiDiscreteActSpace` which represents actions as gymnasium `Discrete`
+  (actions are integer). This is also especially suited for discrete actions such as 
+  setting line status or topologies at substation.
+
+.. note::
+  The main difference between :class:`grid2op.gym_compat.DiscreteActSpace` and 
+  :class:`grid2op.gym_compat.MultiDiscreteActSpace` is that Discrete actions will 
+  allow the agent to perform only one type of action at each step (either it performs
+  redispatching on one generator OR on another generator OR it set the status of a powerline
+  OR it set the substation at one substation etc. but it cannot "peform redispatching on 
+  2 or more generators" nor can it "perform redispatching on one generator AND disconnect a powerline")
+  which can be rather limited for some applications.
 
 
 Detailed Documentation by class

docs/environment.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: grid2op.Environment
+
 .. _environment-module:
 
 Environment
@@ -105,10 +106,10 @@ impact then you might consult the :ref:`environment-module-data-pipeline` page o
 
 .. _environment-module-chronics-info:
 
-Chronics Customization
-+++++++++++++++++++++++
+Time series Customization
+++++++++++++++++++++++++++
 
-Study always the same chronics
+Study always the same time serie
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 If you spotted a particularly interesting chronics, or if you want, for some reason
 your agent to see only one chronics, you can do this rather easily with grid2op.

docs/makeenv.rst

@@ -80,11 +80,13 @@ It has the following behavior:
    it will be used (see section :ref:`usage`)
 2) if you specify the name of an environment that you have already downloaded, it will use this environment (NB
    currently no checks are implemented if the environment has been updated remotely, which can happen if
-   we realize there were some issues with it.)
+   we realize there were some issues with it.). If you want to update the environments you downloaded
+   please use :func:`grid2op.update_env()`
 3) you are expected to provide an environment name (if you don't know what this is just put `"l2rpn_case14_sandbox"`)
 4) if the flag `test` is set to ``False`` (default behaviour) and none of the above conditions are met, the
    :func:`make` will download the data of this environment locally the first time it is called. If you don't want
-   to download anything then you can pass the flag ``test=True``
+   to download anything then you can pass the flag ``test=True`` (in this case only a small sample of 
+   time series will be available. We don't recommend to do that at all !)
 5) if ``test=True`` (NON default behaviour) nothing will be loaded, and the :func:`make` will attempt to use a
    pre defined environment provided with the python package. We want to emphasize that because the environments provided
    with this package contains only little data, they are not suitable for leaning a consistent agent / controler. That
@@ -134,11 +136,16 @@ context of the L2RPN competition, we don't recommend to modify them.
 
 - `dataset_path`: used to specify the name (or the path) of the environment you want to load
 - `backend`: a initialized backend that will carry out the computation related to power system [mainly use if you want
-  to change from PandapowerBackend (default) to a different one *eg* LightSim2Grid)
-- `reward_class`: change the type of reward you want to use for your agent
-- `other_reward`: tell "env.step" to return addition "rewards"
+  to change from PandapowerBackend (default) to a different one *eg* LightSim2Grid]
+- `reward_class`: change the type of reward you want to use for your agent (see section 
+  :ref:`reward-module` for more information).
+- `other_reward`: tell "env.step" to return addition "rewards"(see section 
+  :ref:`reward-module` for more information).
 - `difficulty`, `param`: control the difficulty level of the game (might not always be available)
-- `chronics_class`, `data_feeding_kwargs`: further customization to how the data will be generated
+- `chronics_class`, `data_feeding_kwargs`: further customization to how the data will be generated,
+  see section :ref:`environment-module-data-pipeline` for more information
+- `n_busbar`: (``int``, default 2) [new in version 1.9.9]  see section :ref:`substation-mod-el` 
+  for more information
 - \* `chronics_path`, `data_feeding`, : to overload default path for the data (**not recommended**)
 - \* `action_class`: which action class your agent is allowed to use (**not recommended**).
 - \* `gamerules_class`: the rules that are checked to declare an action legal / illegal (**not recommended**)

docs/modeled_elements.rst

@@ -1034,19 +1034,48 @@ Substations
 
 Description
 ~~~~~~~~~~~~~~~~~~
-A "substation" is a place where "elements" (side of a powerline, a load, a generator or
+A "substation" is a place (that exists, you can touch it) 
+where "elements" (side of a powerline, a load, a generator or
 a storage unit) belonging to the powergrid are connected all together.
 
 Substations are connected to other substation with powerlines (this is why powerline have two "sides": one for
 each substation they are connecting).
 
 In most powergrid around the world, substations are made of multiple "busbars". In grid2op we supposes that
 every "elements" connected to a substation can be connected to every busbars in the substation. This is mainly
-done for simplicity, for real powergrid it might not be the case. We also, for simplicity, assume that
-each substations counts exactly 2 distincts busbars.
+done for simplicity, for real powergrid it might not be the case.
 
-At the initial step, for all environment available at the time of writing (february 2021) every objects
-were connected to the busbar 1 of their substation. This is not a requirement of grid2op, but it was the case
+In earlier grid2op versions, we also assumed that, for simplicity,
+each substations counts exactly 2 distincts busbars. Starting from grid2op 1.9.9, it is possible
+when you create an environment, to specify how many busbars are available in each substation. You can 
+customize it with:
+
+.. code-block:: python
+
+    import grid2op
+    env_name = "l2rpn_case14_sandbox"
+
+    env_2_busbars = grid2op.make(env_name)  # default
+    env_2_busbars_bis = grid2op.make(env_name, n_busbar=2)  # same as above
+
+    # one busbar
+    env_1_busbar = grid2op.make(env_name, n_busbar=1)
+    #NB: topological action on substation (set_bus, change_bus) are not possible in this case !
+
+    # 3 busbars
+    env_3_busbars = grid2op.make(env_name, n_busbar=3)
+    #NB: "change_bus" type of actions are not possible (it would be ambiguous - non unique-
+    #    on which busbar you want to change them)
+
+    # 10 busbars
+    env_10_busbars = grid2op.make(env_name, n_busbar=10)
+    #NB: "change_bus" type of actions are not possible (it would be ambiguous - non unique-
+    #    on which busbar you want to change them)
+
+
+At the initial step (right after `env.reset()`), for all environment available 
+at the time of writing (february 2021) every objects were connected to the busbar 1 
+of their substation. This is not a requirement of grid2op, but it was the case
 for every environments created.
 
 .. _topology-pb-explained: