Merge pull request #480 from rte-france/dev_1.9.1

Version 1.9.1

.circleci/config.yml

@@ -43,6 +43,12 @@ jobs:
                   export _GRID2OP_FORCE_TEST=1
                   cd grid2op/tests/
                   python3 helper_list_test.py | circleci tests split > /tmp/tests_run
+            - run: cat /tmp/tests_run
+            - run:
+                command: |
+                  source venv_test/bin/activate
+                  cd grid2op/tests/
+                  export _GRID2OP_FORCE_TEST=1
                   python3 -m unittest $(cat /tmp/tests_run)
                   
     install36:
@@ -90,19 +96,20 @@ jobs:
             - run:
                command: |
                    source venv_test/bin/activate
-                   pip install -U pip setuptools wheel
+                   python -m pip install -U pip setuptools wheel
             - run:
                command: |
                    source venv_test/bin/activate
-                   pip install -U "numpy>=1.20,<1.21"
-                   pip install -U .[test]
+                   python -m pip install -U numba
+                   python -m pip install -U "numpy>=1.20,<1.21"
+                   python -m pip install -U .[test]
                    export _GRID2OP_FORCE_TEST=1
                    grid2op.testinstall
             - run:
                command: |
                    source venv_test/bin/activate
-                   pip install -U "numpy>=1.21,<1.22"
-                   pip install -U .[test]
+                   python -m pip install -U "numpy>=1.21,<1.22"
+                   python -m pip install -U .[test]
                    export _GRID2OP_FORCE_TEST=1
                    grid2op.testinstall
 
@@ -121,6 +128,7 @@ jobs:
                command: |
                    source venv_test/bin/activate
                    python -m pip install -U pip setuptools wheel
+                   python -m pip install -U numba
             - run:
                command: |
                    source venv_test/bin/activate
@@ -149,6 +157,13 @@ jobs:
                    python -m pip install -U .[test]
                    export _GRID2OP_FORCE_TEST=1
                    grid2op.testinstall
+            - run:
+               command: |
+                   source venv_test/bin/activate
+                   python -m pip install -U "numpy>=1.24,<1.25"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
+                   grid2op.testinstall
 
     install39:
         executor: python39
@@ -171,29 +186,49 @@ jobs:
             - run:
                command: |
                    source venv_test/bin/activate
+                   python -m pip install -U numba
                    python -m pip install -U .[test]
             - run:
                command: |
                    source venv_test/bin/activate
-                   export _GRID2OP_FORCE_TEST=1
                    python -m pip install -U "numpy>=1.20,<1.21"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
                    grid2op.testinstall
             - run:
                command: |
                    source venv_test/bin/activate
                    python -m pip install -U "numpy>=1.21,<1.22"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
                    grid2op.testinstall
             - run:
                command: |
                    source venv_test/bin/activate
-                   export _GRID2OP_FORCE_TEST=1
                    python -m pip install -U "numpy>=1.22,<1.23"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
                    grid2op.testinstall
             - run:
                command: |
                    source venv_test/bin/activate
-                   export _GRID2OP_FORCE_TEST=1
                    python -m pip install -U "numpy>=1.23,<1.24"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
+                   grid2op.testinstall
+            - run:
+               command: |
+                   source venv_test/bin/activate
+                   python -m pip install -U "numpy>=1.24,<1.25"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
+                   grid2op.testinstall
+            - run:
+               command: |
+                   source venv_test/bin/activate
+                   python -m pip install -U "numpy>=1.25,<1.26"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
                    grid2op.testinstall
     install310:
         executor: python310
@@ -210,6 +245,7 @@ jobs:
                command: |
                    source venv_test/bin/activate
                    python -m pip install -U pip setuptools wheel
+                   python -m pip install -U numba
             - run:
                command: |
                    source venv_test/bin/activate
@@ -227,8 +263,60 @@ jobs:
             - run:
                command: |
                    source venv_test/bin/activate
+                   python -m pip install -U "numpy>=1.23,<1.24"
+                   python -m pip install -U .[test]
                    export _GRID2OP_FORCE_TEST=1
+                   grid2op.testinstall
+            - run:
+               command: |
+                   source venv_test/bin/activate
+                   python -m pip install -U "numpy>=1.24,<1.25"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
+                   grid2op.testinstall
+            - run:
+               command: |
+                   source venv_test/bin/activate
+                   python -m pip install -U "numpy>=1.25,<1.26"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
+                   grid2op.testinstall
+    install311:
+        executor: python311
+        resource_class: small
+        steps:
+            - checkout
+            - run: 
+                command: |
+                    apt-get update
+                    apt-get install -y coinor-cbc
+            - run: python -m pip install virtualenv
+            - run: python -m virtualenv venv_test
+            - run:
+               command: |
+                   source venv_test/bin/activate
+                   python -m pip install -U pip setuptools wheel
+                   python -m pip install -U numba
+            - run:
+               command: |
+                   source venv_test/bin/activate
                    python -m pip install -U "numpy>=1.23,<1.24"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
+                   grid2op.testinstall
+            - run:
+               command: |
+                   source venv_test/bin/activate
+                   python -m pip install -U "numpy>=1.24,<1.25"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
+                   grid2op.testinstall
+            - run:
+               command: |
+                   source venv_test/bin/activate
+                   python -m pip install -U "numpy>=1.25,<1.26"
+                   python -m pip install -U .[test]
+                   export _GRID2OP_FORCE_TEST=1
                    grid2op.testinstall
 
 workflows:
@@ -238,7 +326,7 @@ workflows:
           - test
     install:
         jobs:
-          - install37
           - install38
           - install39
           - install310
+          - install311

.gitignore

@@ -379,6 +379,13 @@ test_pp_networks.py
 test_timeout_env.py
 test_pp_dc.py
 et_trace()
+bug_malte.py
+grid2op/tests/tmp_test_1
+test_malte.7z
+test_malte.py
+example_gym_act.py
+test_to_fix.txt
+doc_raise_alert.py
 
 # profiling files
 **.prof

AUTHORS.txt

@@ -16,4 +16,5 @@ Further Contributions by:
     - Jan-Hendrik Menke
     - Vincent Renault
     - Florian Schäfer
-    - Clément Goubet
+    - Clément Goubet
+    - Laure Crochepierre

CHANGELOG.rst

@@ -31,6 +31,61 @@ Change Log
 - [???] "asynch" multienv
 - [???] properly model interconnecting powerlines
 
+[1.9.1] - 2023-07-06
+--------------------
+- [BREAKING] (slightly): default `gym_compat` module now inherit from `gymnasium` (if 
+  gymnasium is installed) instead of `gym`. If you want legacy behaviour, 
+  do not install `gymnasium`. If you want compatibility with sota softwares using `gymnasium`,
+  install it and continue using grid2op transparently. See doc of `gym_compat` module for more
+  information.
+- [BREAKING] remove the support of the "raise_alarm" kwargs in the DiscreteActSpace
+- [BREAKING] remove support for python 3.7 that has reached end of life on 2023-06-27 on
+  pypi and on CI
+- [BREAKING] to avoid misleading behaviour, by default the `BoxGymActSpace` no longer uses
+  the "discrete" attributes ("set_line_status", "change_line_status", "set_bus", "change_bus"). You can
+  still use them in the "attr_to_keep" kwargs if you want.
+- [BREAKING] rename with filename starting with lowercase all the files in the "Reward" module. This is 
+  both consistent with python practice but allows also to make the difference between the file in the 
+  module and the class imported. This should have little to no impact on all codes but to "upgrade"
+  instead of `from grid2op.Reward.BaseReward import BaseReward` just do 
+  `from grid2op.Reward import BaseReward`.
+- [FIXED] an error when an environment with alarm was created before an environment 
+  without alert. This lead to a crash when creating the second environment. This is now fixed.
+- [FIXED] an issue with non renewable generators in `GymActionSpace` (some curtailment was made
+  at 100% of their capacity instead of "no curtailment")
+- [FIXED] a bug in computing the datatype of `BoxGymActSpace` and `BoxGymObsSpace` leading to
+  using "bool" as dtype when it should be int.
+- [FIXED] the behaviour of `BoxGymActSpace` when `subtract` / `divide` were provided (the dtype was 
+  not propagated correctly)
+- [ADDED] support for the "alert" feature (see main doc page) with new observation attributes
+  (`obs.active_alert`, `obs.time_since_last_alert`, `obs.alert_duration`, `obs.total_number_of_alert,` 
+  `obs.time_since_last_attack`, `obs.was_alert_used_after_attack` and `obs.attack_under_alert`) 
+  a new type of action: `act.raise_alert` and a new reward class `AlertReward` (among others)
+- [ADDED] the environment "l2rpn_idf_2023" (accessible via `grid2op.make("l2rpn_idf_2023", test=True)`)
+- [ADDED] the `RecoPowerlinePerArea` that is able to reconnect multiple lines in different area in
+  the same action
+- [ADDED] the kwargs "with_numba" in `PandaPowerBackend` to offer more control on whether or not you want
+  to use numba (default behaviour did not change: "if numba is availble, use it" but now you can disable it 
+  if numba is available but you don't want it)
+- [ADDED] the method `act.decompose_as_unary_actions(...)` to automatically
+  decompose a "complex" action on its unary counterpart. 
+- [ADDED] the env attribute `env._reward_to_obs` that allows to pass information to the observation directly
+  from the reward (this can only be used by regular environment and not by `obs.simulate` nor by `ForecastEnv`)
+- [ADDED] the whole "alert" concept in grid2op with a grid2op environment supporting it (`l2rpn_idf_2023`)
+- [ADDED] the `gym_env.action_space.get_index(attr_nm)` for `BoxGymActSpace` that allows to retrieve which index
+  of the action represents which attribute.
+- [ADDED] the argument `quiet_warnings` in the handlers to prevent the issue of too many warnings when using 
+  `ForecastHandler`
+- [IMPROVED] the method `act.as_serializable_dict()` to work better when exporting / importing actions on different 
+  grids (the output dictionary for `set_bus` and `change_bus` now split the keys between all elements types 
+  instead of relying on the "topo_vect" order (which might vary))
+- [IMPROVED] consistency between how to perform action on storage units between "raw" grid2op, 
+  `GymActionSpace`, `BoxGymActSpace`, `DiscreteActSpace` and `MultiDiscreteActSpace` (
+    used to be a mix of `set_storage` and `storage_power` now it's consistent and is `set_storage` everywhere)
+- [IMPROVED] error message when the "stat.clear_all()" function has been called on a statistic and this same
+  statistic is reused.
+- [IMPROVED] possibility to set "other_rewards" in the config file of the env
+
 [1.9.0] - 2023-06-06
 --------------------
 - [BREAKING] (because prone to bug): force the environment name in the `grid2op.make` function.
@@ -94,6 +149,7 @@ Change Log
   directly from the grid2op action, see `obs.change_forecast_parameters()`
 - [ADDED] possibility to retrieve a "forecast environment" with custom forecasts, see 
   `obs.get_env_from_external_forecasts(...)`
+- [ADDED] now requires "importlib-metadata" package at install
 - [ADDED] adding the `TimedOutEnvironment` that takes "do nothing" actions when the agent
   takes too much time to compute. This involves quite some changes in the runner too.
 - [ADDED] Runner is now able to store if an action is legal or ambiguous
@@ -1166,7 +1222,7 @@ Change Log
   `5bus_example` and the `CASE_14_L2RPN2019`.
 - [FIXED] Runner skipped half the episode in some cases (sequential, even number of scenarios). Now fixed.
 - [FIXED] Some typos on the notebook "getting_started\4-StudyYourAgent.ipynb".
-- [FIXED] Error in the conversion of observation to dictionnary. Twice the same keys were used
+- [FIXED] Error in the conversion of observation to dictionary. Twice the same keys were used
   ('time_next_maintenance') for both `time_next_maintenance` and `duration_next_maintenance`.
 - [UPDATED] The first chronics that is processed by a runner is not the "first" one on the hardrive
   (if sorted in alphabetical order)
@@ -1209,7 +1265,7 @@ Change Log
 
 [0.4.2] - 2020-01-08
 --------------------
-- [BREAKING] previous saved BaseAction Spaces and BaseObservation Spaces (as dictionnary) are no more compatible
+- [BREAKING] previous saved BaseAction Spaces and BaseObservation Spaces (as dictionary) are no more compatible
 - [BREAKING] renaming of attributes describing the powergrid across classes for better consistency:
 
 =============================    =======================  =======================

README.md

@@ -55,6 +55,11 @@ python3 -m virtualenv venv_grid2op
 source venv_grid2op/bin/activate
 ```
 
+## Install from PyPI
+```commandline
+pip3 install grid2op
+```
+
 ## Install from source
 ```commandline
 git clone https://github.com/rte-france/Grid2Op.git
@@ -63,11 +68,6 @@ pip3 install -U .
 cd ..
 ```
 
-## Install from PyPI
-```commandline
-pip3 install grid2op
-```
-
 ## Install for contributors
 ```commandline
 git clone https://github.com/rte-france/Grid2Op.git
@@ -87,12 +87,13 @@ docker pull bdonnot/grid2op:latest
 
 # Main features of Grid2Op
 ## Core functionalities
-Built with modulartiy in mind, Grid2Op acts as a replacement of [pypownet](https://github.com/MarvinLer/pypownet) 
-as a library used for the Learning To Run Power Network [L2RPN](https://l2rpn.chalearn.org/). 
+Built with modulartiy in mind, Grid2Op as a library used for the "Learning To Run Power Network" [L2RPN](https://l2rpn.chalearn.org/)
+competitions serie. It can also
 
 Its main features are:
 * emulates the behavior of a powergrid of any size at any format (provided that a *backend* is properly implemented)
-* allows for grid modifications (active and reactive load values, generator voltages setpoints and active production)
+* allows for grid modifications (active and reactive load values, generator voltages setpoints, active production but most 
+  importantly grid topology beyond powerline connection / disconnection)
 * allows for maintenance operations and powergrid topological changes
 * can adopt any powergrid modeling, especially Alternating Current (AC) and Direct Current (DC) approximation to 
   when performing the compitations
@@ -112,6 +113,8 @@ and have Grid2Op using this powerflow instead of PandaPower.
 Some Jupyter notebook are provided as tutorials for the Grid2Op package. They are located in the 
 [getting_started](getting_started) directories. 
 
+TODO: this needs to be redone, refactorize and better explained for some of them.
+
 These notebooks will help you in understanding how this framework is used and cover the most
 interesting part of this framework:
 
@@ -176,10 +179,10 @@ interesting part of this framework:
 * [10_StorageUnits](getting_started/10_StorageUnits.ipynb)
   [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/10_StorageUnits.ipynb)
   details the usage and behaviour of the storage units
-  in grid2op.
+  in grid2op. 
 * [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/rte-france/Grid2Op/blob/master/getting_started/11_IntegrationWithExistingRLFrameworks.ipynb)
-  explains how to use grid2op with other reinforcement learning framework.
+  explains how to use grid2op with other reinforcement learning framework. TODO: this needs to be redone
 
 Try them out in your own browser without installing 
 anything with the help of mybinder: 
@@ -268,25 +271,25 @@ Grid2op is currently tested on windows, linux and macos.
 
 The unit tests includes testing, on linux machines the correct integration of grid2op with:
 
-- python 3.7
 - python 3.8
 - python 3.9
 - python 3.10
+- python 3.11
 
 On all of these cases, we tested grid2op on all available numpy version >= 1.20 (**nb** available numpy versions depend
 on python version).
 
 The complete test suit is run on linux with the latest numpy version on python 3.8.
 
-**NB** grid2op should work on python 3.11 but as numba is not (yet) compatible with this python version, 
-and because numba is used for some tests, we do not test grid2op with python 3.11 yet.
-
-## Known issue
+## Known issues
 
 Due to the underlying behaviour of the "multiprocessing" package on windows based python versions,
 the "multiprocessing" of the grid2op "Runner" is not supported on windows. This might change in the future, 
 but it is currently not on our priorities.
 
+A quick fix that is known to work include to set the `experimental_read_from_local_dir` when creating the
+environment with `grid2op.make(..., experimental_read_from_local_dir=True)` (see doc for more information)
+
 ## Perform tests locally
 Provided that Grid2Op is installed *from source*: