Merge pull request #150 from BDonnot/master

update to version 1.2.3

.gitignore

@@ -217,7 +217,15 @@ test_sac
 test_if_bug.py
 getting_started/saved_agent_DDDQN_10000/
 getting_started/saved_agent_DDDQN_10000_results/
-
+test_reboot.py
+test_multimixrunner/
+test_N1reward.py
+i_saved_the_runner_here/
+output_pdf/
+test_make_plot_injj.ipynb
+plot_inj_prez_gdrive.ipynb
+where_i_want_to_save_it/
+test_issue147.py
 
 # profiling files
 **.prof

CHANGELOG.rst

@@ -7,7 +7,6 @@ Change Log
 - [???] Extensive tests for DistanceReward
 - [???] better logging
 - [???] add a "plot action" method
-- [???] rationalize the public and private part of the API. Some members now are public but should be private.
 - [???] 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.
@@ -16,6 +15,29 @@ Change Log
 - [???] 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)
 
+[1.2.3] - 2020-09-25
+----------------------
+- [ADDED] `l2rpn-baselines` package dependency in the "binder" environment.
+- [FIXED] binder integration that was broken momentarily
+- [FIXED] an issue in the sampling of redispatching action (ramp up and ramp down were inverted)
+- [FIXED] an issue causing errors when using `action_space.change_bus` and `action_space.set_bus`
+- [FIXED] an issue in the sampling: redispatching and "change_bus" where always performed at the
+  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
+  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).
+- [FIXED] An error preventing the loading of an Ambiguous Action (in case an agent took such action, the `EpisodeData`
+  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
+  behaviour of grid2op).
+- [IMPROVED] internal functions are tagged as "Internal, do not use" in the documentation.
+- [IMPROVED] Improved documentation for the `Environment` and `MultiMixEnvironment`.
+
 [1.2.2] - 2020-08-19
 ---------------------
 - [FIXED] `LightSim Issue #10<https://github.com/BDonnot/lightsim2grid/issues/10>`_: tests were

binder/environment.yml

@@ -5,8 +5,10 @@ dependencies:
   - python
   - numpy
   - keras
+  - pip
   - pip:
     - grid2op[challenge]
+    - l2rpn-baselines
     - jyquickhelper
     - numpy
     - numba

docs/action.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: grid2op.Action
+.. _action-module:
 
 Action
 ===================================
@@ -39,6 +40,20 @@ instances of BaseAction is assessed both when calling :func:`BaseAction.update`
 :func:`BaseAction._check_for_ambiguity` performed for example by the Backend when it must implement its effect on the
 powergrid through a call to :func:`BaseAction.__call__`
 
+Constructing an action in grid2op is made in the following manner:
+
+.. code-block:: python
+
+    import grid2op
+    env = grid2op.make()
+    dictionary_describing_the_action = {}
+    my_action = env.action_space(dictionary_describing_the_action)
+    print(my_action)
+
+On the above code, `dictionary_describing_the_action` should be a dictionary that describe what action
+you want to perform on the grid. For more information you can consult the help of the :func:`BaseAction.update`.
+
+
 .. _Illegal-vs-Ambiguous:
 
 Illegal vs Ambiguous
@@ -137,6 +152,8 @@ action                                         original status   final status
 
 \* means that this bus is affected: if it was on bus 1 it moves on bus 2 and vice versa.
 
+.. _action-module-converter:
+
 Easier actions manipulation
 ----------------------------
 The action class presented here can be quite complex to apprehend, especially for a machine learning algorithm.

docs/agent.rst

@@ -1,4 +1,5 @@
 .. currentmodule:: grid2op.Agent
+.. _agent-module:
 
 Agent
 ============
@@ -20,6 +21,36 @@ To perform their actions, agent receive two main signals from the :class:`grid2o
 Both these signals can be use to determine what is the best action to perform on the grid. This is actually the main
 objective of an :class:`BaseAgent`, and this is done in the :func:`BaseAgent.act` method.
 
+To get started coding your agent we encourage you to read the description of the :ref:`action-module` to know how
+to implement your action. Don't hesitate to have a look at the :ref:`action-module-converter` for
+an easier / higher level action manipulation.
+
+Once you know how to manipulate a powergrid in case of the grid2op framework, you can easily implement an agent
+following this example
+
+.. code-block:: python
+
+    import grid2op
+    from grid2op.Agent import BaseAgent
+
+    class MyCustomAgent(BaseAgent):
+        def __init__(self, action_space, something_else, and_another_something):
+            # define here the constructor of your agent
+            # here we say our agent needs "something_else" and "and_another_something"
+            # to be built just to demonstrate it does not cause any problem to extend the
+            # construction of the base class BaseAgent that only takes "action_space" as a constructor
+            BaseAgent.__init__(self, action_space)
+            self.something_else = something_else
+            self.and_another_something = and_another_something
+
+        def act(obs, reward, done=False):
+            # this is the only method you need to implement
+            # it takes an observation obs (and a reward and a flag)
+            # and should return a valid action
+            dictionary_describing_the_action = {}  # this can be anything you want that grid2op understands
+            my_action = env.action_space(dictionary_describing_the_action)
+            return my_action
+
 
 Detailed Documentation by class
 -------------------------------

docs/backend.rst

@@ -5,6 +5,16 @@ Backend
 
 Objectives
 -----------
+
+.. warning:: Backends are internal to grid2op. You should not have to recode any backend if you are "simply"
+    using grid2op, for example to develop new controller.
+
+    Backend is an abstraction that represents the physical system (the powergrid). In theory every powerflow can be
+    used as a backend. For now we only provide a Backend that uses  `Pandapower <http://www.pandapower.org/>`_ and
+    a port in c++ to a subset of pandapower called `LightSim2Grid <https://github.com/BDonnot/lightsim2grid>`_ .
+
+    Both can serve as example if you want to code a new backend.
+
 This Module defines the template of a backend class.
 Backend instances are responsible to translate action (performed either by an BaseAgent or by the Environment) into
 comprehensive powergrid modifications.
@@ -34,7 +44,6 @@ The order of the values returned are always the same and determined when the bac
 '\*_names'. For example, when the ith element of the results of a call to :func:`Backend.get_line_flow` is the
 flow on the powerline with name `lines_names[i]`.
 
-
 Detailed Documentation by class
 -------------------------------
 .. automodule:: grid2op.Backend

docs/conf.py

@@ -48,7 +48,10 @@
     # 'sphinx.ext.autosectionlabel',
 
     # 'details',
-    #'exception_hierarchy'
+    #'exception_hierarchy',
+
+    # for pdf
+    # 'rst2pdf.pdfbuilder'
 ]
 # Add any paths that contain templates here, relative to this directory.
 templates_path = [] #'_templates']
@@ -73,6 +76,9 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# for pdf
+pdf_documents = [('index', u'rst2pdf', u'Sample rst2pdf doc', u'Your Name'),]
+
 
 def setup(app):
   app.add_javascript('custom.js')