Merge pull request #159 from BDonnot/master

upgrade to version 1.3.0

.circleci/config.yml

@@ -22,4 +22,4 @@ workflows:
   version: 2.1
   test:
     jobs:
-      - test
+      - test

.gitignore

@@ -226,6 +226,24 @@ test_make_plot_injj.ipynb
 plot_inj_prez_gdrive.ipynb
 where_i_want_to_save_it/
 test_issue147.py
+test_rllib.py
+bug_neg_prod.py
+test_ray/
+test.py
+getting_started/chronics_educ/
+grid2op/data/educ_case14_redisp/
+getting_started/prepare_env_aub.ipynb
+test_log_122/
+test_issue156.py
+test_redisp.py
+getting_started/test_env_converter.ipynb
+test_spektral.py
+test_spektral_example.py
+test_training_gnn*.pdf
+getting_started/donothing_case14_realistic.ipynb
+getting_started/first_plot_attempt.ipynb
+getting_started/investigate_redisp_bug.ipynb
+**/split_and_save_meta_params.json
 
 # profiling files
 **.prof

CHANGELOG.rst

@@ -5,15 +5,50 @@ Change Log
 --------------------
 - [???] Extensive tests for BridgeReward
 - [???] Extensive tests for DistanceReward
+- [???] in the observation, make the possibility to retrieve the "active flow graph" (ie graph with edges having active
+  flows, and nodes the active production / consumption) and "reactive flow graph"
 - [???] better logging
 - [???] add a "plot action" method
 - [???] simulate in MultiEnv
 - [???] in MultiEnv, when some converter of the observations are used, have each child process to compute
-  it in parrallel and transfer the resulting data.
+  it in parallel and transfer the resulting data.
+- [???] "asynch" multienv
 - [???] properly model interconnecting powerlines
 - [???] model curtailment
 - [???] model batteries / pumped storage in grid2op (generator but that can be charged / discharged)
-- [???] model dumps (as in dump storage) in grid2op (stuff that have a given energy max, and cannot produce more than the available energy)
+- [???] model dumps (as in dump storage) in grid2op (stuff that have a given energy max, and cannot produce more than
+  the available energy)
+
+[1.3.0] - 2020-10-xx
+---------------------
+- [BREAKING] GymConverter has been moved to `grid2op.gym_compat` module instead of  `grid2op.Converter`
+- [FIXED] wrong computation of voltage magnitude at extremity of powerlines when the powerlines were disconnected.
+- [FIXED] `Issue #151 <https://github.com/rte-france/Grid2Op/issues/151>`_: modification of observation attributes 3
+  could lead to crash
+- [FIXED] `Issue #153 <https://github.com/rte-france/Grid2Op/issues/153>`_: negative generator could happen in some
+  cases
+- [FIXED] an error that lead to wrong normalization of some generator (due to slack bus) when using the
+  gymconverter.
+- [FIXED] a bug that prevented runner to read back previously stored data (and now a test to check
+  backward compatibility down to version 1.0.0)
+- [FIXED] small issue that could lead to non reproducibility when shuffling chronics
+- [FIXED] a bug in `obs.bus_connectivity_matrix()` when powerlines were disconnected
+- [ADDED] a class to deactivate the maintenance and hazards in the chronics from file
+  `GridStateFromFileWithForecastsWithoutMaintenance`
+- [ADDED] a keyword argument in the matplotlib plot information on the grid
+  (`plot_helper.plot_info(..., coloring=...)`)
+- [ADDED] a function to change the color palette of powerlines (`plot_helper.assign_line_palette`)
+- [ADDED] a function to change the color palette of generators (`plot_helper.assign_gen_palette`)
+- [ADDED] Support the attack of the opponent in the `EpisodeData` class
+- [ADDED] Now the observations are set to a "game over" state when a game over occurred
+  see `BaseObservation.set_game_over`
+- [ADDED] a method to plot the redispatching state of the grid `PlotMatplot.plot_current_dispatch`
+- [ADDED] the documentation of `Episode` module that was not displayed.
+- [IMPROVED] silence the warning issue when calling `MultiEnv.get_seeds`
+- [IMPROVED] the tolerance of the redispatching algorithm is now more consistent between the precision of the solver
+  used and the time when it's
+- [IMPROVED] make faster and more robust the optimization routine used during redispatching
+- [IMPROVED] error message when the state fails because of infeasible redispatching
 
 [1.2.3] - 2020-09-25
 ----------------------
@@ -25,7 +60,7 @@ Change Log
   same time
 - [FIXED] `Issue #144 <https://github.com/rte-france/Grid2Op/issues/144>`_: typo that could lead to not
   display some error messages in some cases.
-- [FIXED] `Issue #146 <https://github.com/rte-france/Grid2Op/issues/146>`_: akward behaviour that lead to not calling
+- [FIXED] `Issue #146 <https://github.com/rte-france/Grid2Op/issues/146>`_: awkward behaviour that lead to not calling
   the reward function when the episode was over.
 - [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).

docs/episode.rst

@@ -0,0 +1,60 @@
+Episode
+===================================
+Objectives
+-----------
+Grid2op defines some special function that help with restoring agent that has run during some episode that has been
+saved by the runner.
+
+Here are some basic usage.
+
+First you run an episode:
+
+.. code-block:: python
+
+    import grid2op
+    from grid2op.Runner import Runner
+
+    # I create an environment
+    env = grid2op.make("rte_case5_example", test=True)
+
+    # I create the runner
+    runner = Runner(**env.get_params_for_runner())
+    path_save = "/I/SAVED/RESULTS/THERE"
+
+    # I start the runner and save the results in "/I/SAVED/RESULTS/THERE"
+    # I start the evaluation on 2 different episode
+    res = runner.run(path_save=path_save, nb_episode=2)
+
+Second you can reload the data (here to plot the different productions active values):
+
+.. code-block:: python
+
+    import grid2op
+    from grid2op.Episode import EpisodeData
+
+    # I study only the first episode saved, because... why not
+    path_saved = "/I/SAVED/RESULTS/THERE"  # same path as before
+
+    li_episode = EpisodeData.list_episode(path_saved)
+    full_path, episode_studied = li_episode[0]
+    this_episode = EpisodeData.from_disk(path_agent, episode_studied)
+
+    # now the episode is loaded, and you can easily iterate through the observation, the actions etc.
+    for act in this_episode.actions:
+        print(act)
+
+    for i, obs in enumerate(this_episode.observations):
+        print("At step {} the active productions were {}".format(i, obs.prod_p))
+
+    # etc. etc.
+
+
+
+Detailed Documentation by class
+--------------------------------
+.. automodule:: grid2op.Episode
+    :members:
+    :autosummary:
+
+.. include:: final.rst
+

docs/gym.rst

@@ -1,3 +1,4 @@
+.. currentmodule:: grid2op.gym_compat
 .. _openai-gym:
 
 Compatibility with openAI gym
@@ -17,12 +18,117 @@ Starting from 1.2.0 we implemented some automatic converters that are able to au
 grid2op representation for the action space and the observation space into open AI gym "spaces". More precisely these
 are represented as gym.spaces.Dict.
 
+As of grid2op 1.4.0 we tighten the gap between openAI gym and grid2op by introducing the dedicated module
+`grid2op.gym_compat` . Withing this module there are lots of functionalities to convert a grid2op environment
+into a gym environment (that inherit `gym.Env` instead of "simply" implementing the open ai gym interface).
+
+
+A simple usage is:
+
+.. code-block:: python
+
+    import grid2op
+    from grid2op.gym_compat import GymEnv
+
+    env_name = "l2rpn_case14_sandbox"  # or any other grid2op environment name
+    g2op_env = grid2op.make(env_name)  # create the gri2op environment
+
+    gym_env = GymEnv(g2op_env)  # create the gym environment
+
+    # check that this is a properly defined gym environment:
+    import gym
+    print(f"Is gym_env and open AI gym environment: {isinstance(gym_env, gym.Env)}")
+    # it shows "Is gym_env and open AI gym environment: True"
+
+Observation space and action space customization
+-------------------------------------------------
+By default, the action space and observation space are `gym.spaces.Dict` with the keys being the attribute
+to modify.
+
+For example, an observation space, for the environment "l2rpn_case14_sandbox" will look like:
+
+- "a_ex": Box(20,)
+- "a_or": Box(20,)
+- "actual_dispatch": Box(6,)
+- "day": Discrete(32)
+- "day_of_week": Discrete(8)
+- "duration_next_maintenance": Box(20,)
+- "hour_of_day": Discrete(24)
+- "line_status": MultiBinary(20)
+- "load_p": Box(11,)
+- "load_q": Box(11,)
+- "load_v": Box(11,)
+- "minute_of_hour": Discrete(60)
+- "month": Discrete(13)
+- "p_ex": Box(20,)
+- "p_or": Box(20,)
+- "prod_p": Box(6,)
+- "prod_q": Box(6,)
+- "prod_v": Box(6,)
+- "q_ex": Box(20,)
+- "q_or": Box(20,)
+- "rho": Box(20,)
+- "target_dispatch": Box(6,)
+- "time_before_cooldown_line": Box(20,)
+- "time_before_cooldown_sub": Box(14,)
+- "time_next_maintenance": Box(20,)
+- "timestep_overflow": Box(20,)
+- "topo_vect": Box(57,)
+- "v_ex": Box(20,)
+- "v_or": Box(20,)
+- "year": Discrete(2100)
+
+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
+`True` encodes for "connected" and `False` for "disconnected") See the chapter :ref:`observation_module` for
+more information
+
+We offer some convenience functions to customize these environment. They all more or less the same
+manner. We show here an example of a "converter" that will scale the data:
+
+.. code-block:: python
+
+    import grid2op
+    from grid2op.gym_compat import GymEnv
+    from grid2op.gym_compat import ScalerAttrConverter
+
+    env_name = "l2rpn_case14_sandbox"  # or any other grid2op environment name
+    g2op_env = grid2op.make(env_name)  # create the gri2op environment
+
+    gym_env = GymEnv(g2op_env)  # create the gym environment
+
+    ob_space = gym_env.observation_space
+    ob_space = ob_space.reencode_space("actual_dispatch",
+                                       ScalerAttrConverter(substract=0.,
+                                       divide=env.gen_pmax,
+                                       init_space=ob_space["actual_dispatch"])
+                                       )
+
+    gym_env.observation_space = ob_space
+
+
+A detailled list of such "converter" is documented on the section "Detailed Documentation by class". In
+the table below we describe some of them (**nb** if you notice a converter is not displayed there,
+do not hesitate to write us a "feature request" for the documentation, thanks in advance)
+
+======================================   ============================================================
+Converter name                           Objective
+======================================   ============================================================
+:class:`ContinuousToDiscreteConverter`   TODO
+:class:`MultiToTupleConverter`           TODO
+:class:`ScalerAttrConverter`             TODO
+======================================   ============================================================
+
+
+Legacy version
+---------------
+
 If you are interested by this feature, we recommend you to proceed like this:
 
 .. code-block:: python
 
    import grid2op
-   from grid2op.Converters import GymActionSpace, GymObservationSpace
+   from grid2op.gym_compat import GymActionSpace, GymObservationSpace
    from grid2op.Agent import BaseAgent
 
    class MyAgent(BaseAgent):
@@ -58,4 +164,13 @@ If you are interested by this feature, we recommend you to proceed like this:
 
 We also implemented some "converter" that allow the conversion of some action space into more convenient
 `gym.spaces` (this is only available if gym is installed of course). Please check
-:class:`grid2op.Converter.GymActionSpace` for more information and examples.
+:class:`grid2op.gym_compat.GymActionSpace` for more information and examples.
+
+
+Detailed Documentation by class
+--------------------------------
+.. automodule:: grid2op.gym_compat
+    :members:
+    :autosummary:
+
+.. include:: final.rst

docs/index.rst

@@ -87,6 +87,7 @@ Technical Documentation
    chronics
    converter
    environment
+   episode
    rules
    observation
    opponent

docs/observation.rst

@@ -36,6 +36,8 @@
 .. _target_dispatch: ./observation.html#grid2op.Observation.BaseObservation.target_dispatch
 .. _actual_dispatch: ./observation.html#grid2op.Observation.BaseObservation.actual_dispatch
 
+.. _observation_module:
+
 Observation
 ===================================
 

getting_started/0_Introduction.ipynb

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

getting_started/1_Grid2opFramework.ipynb

@@ -214,7 +214,7 @@
    "outputs": [],
    "source": [
     "from grid2op.Agent import DoNothingAgent\n",
-    "my_agent = DoNothingAgent(env.helper_action_player)"
+    "my_agent = DoNothingAgent(env.env_action)"
    ]
   },
   {
@@ -455,4 +455,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

getting_started/2_Observation_Agents.ipynb

@@ -121,7 +121,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "do_nothing_act = env.helper_action_player({})\n",
+    "do_nothing_act = env.action_space({})\n",
     "obs, reward, done, info = env.step(do_nothing_act)"
    ]
   },
@@ -796,7 +796,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "do_nothing_act = env.helper_action_player({})\n",
+    "do_nothing_act = env.action_space({})\n",
     "obs_sim, reward_sim, is_done_sim, info_sim = obs.simulate(do_nothing_act)"
    ]
   },
@@ -1066,4 +1066,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

getting_started/5_StudyYourAgent.ipynb

@@ -546,7 +546,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.2"
+   "version": "3.7.5"
   }
  },
  "nbformat": 4,