Merge pull request #329 from rte-france/dev_1.7.1

Upgrade to version 1.7.1

.circleci/config.yml

@@ -171,7 +171,8 @@ jobs:
                command: |
                    source venv_test/bin/activate
                    python -m pip install -U pip setuptools wheel
-                   python -m pip uninstall pathlib
+                   python -m pip install chronix2grid>="1.1.0.post1"
+                   python -m pip uninstall -y grid2op
             - run:
                command: |
                    source venv_test/bin/activate

.gitignore

@@ -354,6 +354,7 @@ bug_jan.py
 venv_test/
 getting_started/saved_agent_PPO_*_results/
 grid2op/data/**/_grid2op_classes/
+test_issue_glop.py
 
 # profiling files
 **.prof

CHANGELOG.rst

@@ -23,14 +23,46 @@ Change Log
 - [???] model delay in observations
 - [???] model delay in action
 - [???] Code and test the "load from disk" method
-- [???] Make the redispatching data independent from the time step (eg instead of "in MW / step" have it in "MW / h"
+- [???] Make the redispatching data independent from the time step (eg instead of "in MW / step" have it in "MW / h")
   and have grid2op convert it to MW / step
 - [???] add a "plot action" method
 - [???] in MultiEnv, when some converter of the observations are used, have each child process to compute
   it in parallel and transfer the resulting data.
 - [???] "asynch" multienv
 - [???] properly model interconnecting powerlines
 
+[1.7.1] - 2022-06-yy
+-----------------------
+- [BREAKING] The possibility to propagate keyword arguments between the environment
+  and the runner implied adding some arguments in the constructor of 
+  `PandapowerBackend`. So if you made a class that inherit from it, you should
+  add these arguments in the constructor (otherwise you will not be able to use
+  the runner) [This should not impact lot of codes, if any]
+- [FIXED] a documentation issue https://github.com/rte-france/Grid2Op/issues/281
+- [FIXED] a bug preventing to use the `FromChronix2grid` chronics class when 
+  there is an opponent on the grid.
+- [FIXED] a documentation issue https://github.com/rte-france/Grid2Op/issues/319
+  on notebook 11
+- [FIXED] some issues when the backend does not support shunts data (caused during the
+  computation of the size of the observation) Tests are now performed in
+  `grid2op/tests/test_educpp_backend.py`
+- [FIXED] a bug when downloading an environment when the archive name is not the 
+  same as the environment names (attempt to delete a non existing folder). This 
+  is the case for `l2rpn_wcci_2022` env. For this env, your are forced to use
+  grid2op version >= 1.7.1
+- [FIXED] an issue when converting a "done" action as a graph, see
+  https://github.com/rte-france/Grid2Op/issues/327
+- [ADDED] score function for the L2RPN WCCI 2022 competition
+- [IMPROVED] adding the compatibility with logger in the reward functions.
+- [IMPROVED] when there is a game over caused by redispatching, the observation is
+  not updated, as it is the case for other type of game over (improved consistency)
+- [IMPROVED] it is now possible to make an environment with a backend that
+  cannot be copied.
+- [IMPROVED] the arguments used to create a backend can be (if used properly)
+  re used (without copy !) when making a `Runner` from an environment for example.
+- [IMPROVED] description and definition of `obs.curtailment_limit_effective` are now
+  consistent (issue https://github.com/rte-france/Grid2Op/issues/321)
+
 [1.7.0] - 2022-04-29
 ---------------------
 - [BREAKING] the `L2RPNSandBoxScore`, `RedispReward` and `EconomicReward` now properly computes the cost of the grid 
@@ -259,7 +291,7 @@ Change Log
   signature by adding an object in the return value. All code provided with grid2op are compatible with this
   new change. (for previously coded opponent, the only thing you have to do to make it compliant with
   the new interface is, in the `opponent.attack(...)` function return `whatever_you_returned_before, None` instead
-  of simply `whatever_you_returned_before`
+  of simply `whatever_you_returned_before`)
 - [FIXED]: `Issue#196 <https://github.com/rte-france/Grid2Op/issues/196>`_ an issue related to the
   low / high of the observation if using the gym_compat module. Some more protections
   are enforced now.
@@ -374,7 +406,7 @@ Change Log
 - [ADDED] more consistent behaviour when using the action space across the different type of actions.
   Now it should understand much more way to interact with it.
 - [ADDED] lots of action properties to manipulate action in a more pythonic way, for example using
-  `act.load_set_bus = ...` instead of the previously way more verbose `act.update({"set_bus": {"loads_id": ...}}`
+  `act.load_set_bus = ...` instead of the previously way more verbose `act.update({"set_bus": {"loads_id": ...}})`
   (this applies for `load`, `gen`, `storage`, `line_or` and `line_ex` and to `set_bus` and `change_bus` and
   also to `storage_p` and `redispatch` so making 12 "properties" in total)
 - [ADDED] an option to retrieve in memory the `EpisodeData` of each episode computed when using the runner.
@@ -463,7 +495,7 @@ Change Log
 - [FIXED] `Issue #147 <https://github.com/rte-france/Grid2Op/issues/147>`_: un consistency between step and simulate
   when cooldowns where applied (rule checking was not using the right method).
 - [FIXED] An error preventing the loading of an Ambiguous Action (in case an agent took such action, the `EpisodeData`
-  would not load it properly.
+  would not load it properly).
 - [IMPROVED] overall documentation of `BaseEnv` and `Environment`
 - [IMPROVED] rationalize the public and private part of the API for `Environment` and `BaseEnv`.
   Some members have been moved to private attribute (their modification would largely alterate the
@@ -483,7 +515,7 @@ Change Log
 - [FIXED] out dated documentation in some classes
 - [FIXED] `Issue #140<https://github.com/rte-france/Grid2Op/issues/140>`_: illegal action were
   not properly computed in some cases, especially in case of divergence of the powerflow. Also now
-  the "why" the action is illegal is displayed (instead of a generic "this action is illegal".
+  the "why" the action is illegal is displayed (instead of a generic "this action is illegal").
 - [FIXED] `LightSim Issue #10<https://github.com/BDonnot/lightsim2grid/issues/10>`_:
   copy of whole environments without needing pickle module.
 - [UPDATED] a missing class documentation `Chronics.Multifolder` in that case.
@@ -611,7 +643,8 @@ Change Log
 - [FIXED] a problem on the grid name import on some version of pandas
 - [ADDED] a function that returns the types of the action see `action.get_types()`
 - [ADDED] a class to "cache" the data in memory instead of reading it over an over again from disk (see
-  `grid2op.chronics.MultifolderWithCache` (related to `Issued #98 <https://github.com/rte-france/Grid2Op/issues/98>`_)
+  `grid2op.chronics.MultifolderWithCache` (related to
+  `Issued #98 <https://github.com/rte-france/Grid2Op/issues/98>`_) )
 - [ADDED] improve the documentation of the observation class.
 - [UPDATED] Reward `LinesReconnectedReward` to take into account maintenances downtimes
 - [UPDATED] Adds an option to disable plotting load and generators names when using `PlotMatplot`

docs/available_envs.rst

@@ -3,6 +3,7 @@
 .. |R2_full_grid| image:: ./img/R2_full_grid.png
 .. |l2rpn_neurips_2020_track1_layout| image:: ./img/l2rpn_neurips_2020_track1_layout.png
 .. |l2rpn_neurips_2020_track2_layout| image:: ./img/l2rpn_neurips_2020_track2_layout.png
+.. |l2rpn_wcci_2022_layout| image:: ./img/l2rpn_wcci_2022_layout.png
 
 
 Available environments
@@ -26,19 +27,19 @@ Inside each folder / environment there are a few files (as of writing):
   this environment will not be compatible with the default backend.
 - "**config.py**" (a file): this file is imported when the environment is loaded. It is used to parametrize the way
   the environment is made. It should define a "config" variable. This "config" is dictionary that is used to initialize
-  the environment. They key should be variable names. See example of such "*config.py*" file in provided environment
-- "**chronics**" (a folder): this folder contains the information to generate the production / loads at each steps.
+  the environment. They key should be variable names. See example of such "*config.py*" file in provided environment.
+
+It can of course contain other information, among them:
+
+- "**chronics**" (a folder) [recommended]: this folder contains the information to generate the production / loads at each steps.
   It can
   itself contain multiple folder, depending on the :class:`grid2op.Chronics.GridValue` class used. In most available
   environment, the class :class:`grid2op.Chronics.Multifolder` is used. This folder is optional, though it is present
   in most grid2op environment provided by default.
-- "**grid_layout.json**" (a file): gives, for each substation its coordinate *(x,y)* when plotted. It is optional, but
+- "**grid_layout.json**" (a file) [recommended]: gives, for each substation its coordinate *(x,y)* when plotted. It is optional, but
   we
   strongly encourage to have such. Otherwise, some tools might not work (including all the tool to represent it, such
   as the renderer (`env.render`), the `EpisodeReplay` or even some other dependency package, such as Grid2Viz).
-
-It can of course contain other information, among them:
-
 - "**prods_charac.csv**" (file): [see :func:`grid2op.Backend.Backend.load_redispacthing_data` for a
   description of this file]
   This contains all the information related to "ramps", "pmin / pmax", etc. This file is optional (grid2op can
@@ -51,8 +52,8 @@ It can of course contain other information, among them:
   This is optional if you don't have any storage units on the grid but required if there are (otherwise a
   `BackendError` will be raised).
 - "**difficulty_levels.json**" (file): This file is useful is you want to define different "difficulty" for your
-  environment. It should be a valid json with keys being difficulty levels ("0" for easiest to "1", "2", "3", "4", "5",
-  ..., "10", ..., "100", ... or "competition" for the hardest / closest to reality difficulty).
+  environment. It should be a valid json with keys being difficulty levels ("0" for easiest to "1", "2", "3", "4", "5"
+  , ..., "10", ..., "100", ... or "competition" for the hardest / closest to reality difficulty).
 
 And this is it for default environment.
 
@@ -89,7 +90,7 @@ And the list of environment that can be downloaded is given by:
     import grid2op
     grid2op.list_available_remote_env()
 
-In this case, remember that the data will be downloaded with:
+In this case, remember that the data will be downloaded in:
 
 .. code-block:: python
 
@@ -109,11 +110,10 @@ env name                          grid size     maintenance    opponent    redis
 :ref:`l2rpn_neurips_2020_track1`   36 sub.       ✔️  ️         ✔️ ️       ✔️ ️                 ❌
 :ref:`l2rpn_neurips_2020_track2`   118 sub.      ✔️  ️         ❌   ️         ✔️ ️                 ❌
 :ref:`l2rpn_icaps_2021`            36 sub.       ✔️  ️         ✔️ ️       ✔️ ️                 ❌
+:ref:`l2rpn_wcci_2022`             118 sub.      ✔️  ️         ✔️ ️       ✔️ ️                 ✔️ ️
 \* educ_case14_redisp \*           14 sub.       ❌️             ❌  ️ ️       ✔️ ️                 ❌
 \* educ_case14_storage \*          14 sub.       ❌️             ❌   ️         ✔️ ️                 ✔️
 \* rte_case5_example \*            5 sub.        ❌️             ❌  ️ ️        ❌ ️ ️                  ❌
-\* educ_case14_redisp \*           14 sub.       ❌️             ❌   ️         ✔️ ️                  ❌
-\* educ_case14_storage \*          14 sub.       ❌️             ❌  ️          ✔️      ️             ❌
 \* rte_case14_opponent \*          14 sub.       ❌️             ✔️ ️        ❌ ️ ️                  ❌
 \* rte_case14_realistic \*         14 sub.       ❌️             ❌ ️  ️        ✔️      ️             ❌
 \* rte_case14_redisp \*            14 sub.       ❌️             ❌ ️  ️        ✔️ ️                  ❌
@@ -194,6 +194,46 @@ This grid looks like:
 
 |l2rpn_case14_sandbox_layout|
 
+
+.. _l2rpn_wcci_2022_dev:
+
+l2rpn_wcci_2022
+++++++++++++++++
+
+This environment will come in two "variations":
+
+- `l2rpn_wcci_2022_dev`: development version (might not be totally finished at time of writing), to be used for
+  test only, only a few snapshots are available.
+- `l2rpn_wcci_2022` : (equivalent of 32 years of powergrid data at 5 mins interval) weights ~1.7 GB
+
+You have the possibility, provided that you installed `chronix2grid` (with `pip install grid2op[chronix2grid]`), to generate as
+much data as you want with the :func:`grid2op.Environment.Environment.generate_data` function. See its documentation for more information.
+
+.. code-block:: python
+
+    import grid2op
+    env_name  = "l2rpn_wcci_2022"
+    env = grid2op.make(env_name)
+
+It counts 118 substations, 186 powerlines, 91 loads and 62 loads. It will be used for the L2RPN competitions at WCCI in 2022.
+
+|l2rpn_wcci_2022_layout|
+
+You can add as many chronics as you want to this environment with the code:
+
+.. code-block:: python
+
+    import grid2op
+    env_name  = "l2rpn_wcci_2022"
+    env = grid2op.make(env_name)
+
+    nb_year = 1 # or any postive integer
+    env.generate_data(nb_year=nb_year)
+
+It might take a while (so we advise you to get a nice cup of tea, coffee or anything)
+and will only work if you installed chronix2grid package.
+
+
 .. _l2rpn_icaps_2021:
 
 l2rpn_icaps_2021
@@ -217,7 +257,10 @@ We recommend to create this environment with:
 
 It is based on the same powergrid as the :ref:`l2rpn_neurips_2020_track1` environment
 and was used for the L2RPN ICAPS 2021 competition. It counts 36 substations, 59
-powerlines, 22 generators and 37 loads.
+powerlines, 22 generators and 37 loads (some of which represents interconnection with 
+another grid).
+
+|l2rpn_neurips_2020_track1_layout|
 
 
 .. _l2rpn_neurips_2020_track1:
@@ -245,7 +288,8 @@ It was the environment used as a training set of the neurips 2020 "L2RPN" compet
 see https://competitions.codalab.org/competitions/25426 .
 
 This environment is part of the IEEE 118 grid, where some generators have been added. It counts 36 substations, 59
-powerlines, 22 generators and 37 loads. The grid is represented in the figure below:
+powerlines, 22 generators and 37 loads (some of which represents interconnection with 
+another grid). The grid is represented in the figure below:
 
 |l2rpn_neurips_2020_track1_layout|
 

docs/createbackend.rst

@@ -159,6 +159,16 @@ There are 4 **__main__** types of method you need to implement if you want to us
   to export some internal value of the backend in a "grid2op compliant format".
 
 
+.. warning::
+    With grid2op version before <1.7.1, you were also required to implement the 
+    :func:`grid2op.Backend.Backend.copy` method.
+
+    As of grid2op >= 1.7.1 this is no longer required. Note however that if you 
+    don't implement it, some features might not be available. This will
+    be the case for *eg* :func:`grid2op.Observation.BaseObservation.simulate` or
+    for :class:`grid2op.simulator.Simulator`.
+
+
 .. _grid-description:
 
 Grid description
@@ -235,7 +245,7 @@ Name                       See paragraph   Type         Size       Description
 `line_ex_pos_topo_vect`_    :ref:`subtv`   vect, int    `n_line`_   Automatically set with a call to `self._compute_pos_big_topo`
 =========================  ==============  ===========  =========  =========================================================
 
-TODO storage doc
+**TODO** storage doc and shunts doc !
 
 Example on how to set them
 +++++++++++++++++++++++++++

docs/gym.rst

@@ -68,22 +68,35 @@ Default Observations space
 ******************************
 For example, an observation space will look like:
 
+- "_shunt_p": Box(`env.n_shunt`,) [type: float, low: -inf, high: inf]
+- "_shunt_q": Box(`env.n_shunt`,) [type: float, low: -inf, high: inf]
+- "_shunt_v": Box(`env.n_shunt`,) [type: float, low: -inf, high: inf]
+- "_shunt_bus": Box(`env.n_shunt`,) [type: int, low: -inf, high: inf]
 - "a_ex": Box(`env.n_line`,) [type: float, low: 0, high: inf]
 - "a_or": Box(`env.n_line`,) [type: float, low: 0, high: inf]
 - "actual_dispatch": Box(`env.n_gen`,)
+- "attention_budget": Box(1,) [type: float, low: 0, high: inf]
+- "current_step": Box(1,) [type: int, low: -inf, high: inf]
 - "curtailment": Box(`env.n_gen`,)  [type: float, low: 0., high: 1.0]
 - "curtailment_limit": Box(`env.n_gen`,)  [type: float, low: 0., high: 1.0]
-- "gen_p": Box(`env.n_gen`,)  [type: float, low: `env.gen_pmin`, high: `env.gen_pmax * 1.2`]
-- "gen_q": Box(`env.n_gen`,)  [type: float, low: -inf, high: inf]
-- "gen_v": Box(`env.n_gen`,)  [type: float, low: 0, high: inf]
+- "curtailment_limit_effective": Box(`env.n_gen`,)  [type: float, low: 0., high: 1.0]
 - "day": Discrete(32)
 - "day_of_week": Discrete(8)
+- "delta_time": Box(0.0, inf, (1,), float32)
 - "duration_next_maintenance": Box(`env.n_line`,)  [type: int, low: -1, high: inf]
+- "gen_p": Box(`env.n_gen`,)  [type: float, low: `env.gen_pmin`, high: `env.gen_pmax * 1.2`]
+- "gen_p_before_curtail": Box(`env.n_gen`,)  [type: float, low: `env.gen_pmin`, high: `env.gen_pmax * 1.2`]
+- "gen_q": Box(`env.n_gen`,)  [type: float, low: -inf, high: inf]
+- "gen_v": Box(`env.n_gen`,)  [type: float, low: 0, high: inf]
+- "gen_margin_up": Box(`env.n_gen`,)  [type: float, low: 0, high: `env.gen_max_ramp_up`]
+- "gen_margin_down": Box(`env.n_gen`,)  [type: float, low: 0, high: `env.gen_max_ramp_down`]
 - "hour_of_day": Discrete(24)
+- "is_alarm_illegal": Discrete(2)
 - "line_status": MultiBinary(`env.n_line`)
 - "load_p": Box(`env.n_load`,) [type: float, low: -inf, high: inf]
 - "load_q": Box(`env.n_load`,) [type: float, low: -inf, high: inf]
 - "load_v": Box(`env.n_load`,) [type: float, low: -inf, high: inf]
+- "max_step": Box(1,) [type: int, low: -inf, high: inf]
 - "minute_of_hour": Discrete(60)
 - "month": Discrete(13)
 - "p_ex": Box(`env.n_line`,)  [type: float, low: -inf, high: inf]
@@ -95,15 +108,22 @@ For example, an observation space will look like:
 - "storage_power": Box(`env.n_storage`,)  [type: float, low: `-env.storage_max_p_prod`, high: `env.storage_max_p_absorb`]
 - "storage_power_target": Box(`env.n_storage`,)  [type: float, low: `-env.storage_max_p_prod`, high: `env.storage_max_p_absorb`]
 - "target_dispatch": Box(`env.n_gen`,)
+- "theta_or": Box(`env.n_line`,)  [type: float, low: -180., high: 180.]
+- "theta_ex": Box(`env.n_line`,)  [type: float, low: -180., high: 180.]
+- "load_theta": Box(`env.n_load`,)  [type: float, low: -180., high: 180.]
+- "gen_theta": Box(`env.n_gen`,)  [type: float, low: -180., high: 180.]
+- "storage_theta": : Box(`env.n_storage`,)  [type: float, low: -180., high: 180.]
 - "time_before_cooldown_line": Box(`env.n_line`,) [type: int, low: 0, high: depending on parameters]
 - "time_before_cooldown_sub": Box(`env.n_sub`,)  [type: int, low: 0, high: depending on parameters]
 - "time_next_maintenance": Box(`env.n_line`,)  [type: int, low: 0, high: inf]
+- "time_since_last_alarm": Box(1,)  [type: int, low: -1, high: inf]
 - "timestep_overflow": Box(`env.n_line`,)  [type: int, low: 0, high: inf]
+- "thermal_limit": Box(`env.n_line`,)  [type: int, low: 0, high: inf]
 - "topo_vect": Box(`env.dim_topo`,)  [type: int, low: -1, high: 2]
 - "v_ex": Box(`env.n_line`,)  [type: float, low: 0, high: inf]
 - "v_or": Box(`env.n_line`,)  [type: flaot, low: 0, high: inf]
+- "was_alarm_used_after_game_over": Discrete(2)
 - "year": Discrete(2100)
-- "delta_time": Box(0.0, inf, (1,), float32)
 
 Each keys correspond to an attribute of the observation. In this example `"line_status": MultiBinary(20)`
 represents the attribute `obs.line_status` which is a boolean vector (for each powerline

getting_started/00_Introduction.ipynb

@@ -251,7 +251,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.5"
+   "version": "3.8.10"
   }
  },
  "nbformat": 4,