Merge pull request #12 from BDonnot/TestNotebooks

Upgrade to version 0.3.6

CHANGELOG.rst

@@ -1,5 +1,12 @@
 Change Log
 =============
+[0.3.6] - 2019-12-01
+--------------------
+- [UPDATED] Readme with docker
+- [ADDED] functionality to restrict action based on previous actions
+  (impacts `Environment`, `GameRules` and `Parameters`)
+- [ADDED] tests for the notebooks in `getting_started`
+- [UPDATED] readme to properly show the docker capability
 
 [0.3.5] - 2019-11-28
 --------------------

README.md

@@ -55,64 +55,87 @@ This instructions will install grid2op with its default PandaPower Backend imple
 
 #### Step 1: Install Python3
 On Debian-like systems (Ubuntu):
-```bash
+```commandline
 sudo apt-get install python3
 ```
 
 On Fedora-like systems:
-```bash
+```commandline
 sudo dnf install python3
 ```
 
 If you have any trouble with this step, please refer to
 [the official webpage of Python](https://www.python.org/downloads/release/python-366/).
 
 #### (Optional, recommended) Step 1bis: Create a virtual environment
-```bash
+```commandline
 pip3 install -U virtualenv
 cd Grid2Op
 python3 -m virtualenv venv_grid2op
 ```
 
 #### Step 2: Clone Grid2Op
-```bash
+```commandline
 git clone https://github.com/rte-france/Grid2Op.git
 ```
 
 This should create a folder Grid2Op with the current sources.
 
 #### Step 3: Run the installation script of Grid2Op
 Finally, run the following Python command to install the current simulator (including the Python libraries dependencies):
-```
+```commandline
 cd Grid2Op/
 source venv_grid2op/bin/activate
 pip install -U .
 ```
 After this, this simulator is available under the name grid2op (e.g. ```import grid2op```).
 
 ## Install with Docker
-Support of Docker *coming soon*.
+A grid2op docker is available on [dockerhub](https://hub.docker.com/). It can be simply installed with
+```commandline
+docker pull bdonnot/grid2op:latest
+```
+
+This will pull and install the latest version of grid2op as a docker image. If you want a specific
+version of grid2op (*eg* 0.3.3), and this version has been pushed to docker\* you can instead install:
+
+```commandline
+docker pull bdonnot/grid2op:0.3.3
+```
 
 # Basic usage
 ## Without using Docker
 Experiments can be conducted using the CLI (command line interface).
 
 ### Using CLI arguments
 CLI can be used to run simulations:
-```bash
+```commandline
 python -m grid2op.main
 ```
 
 This will evaluate a *DoNothing* policy (eg. simulating and *Agent* that does not perform
 any action on the powergrid, on the IEEE case 14 for 3 epochs each of 287 time steps.)
 
 For more information:
-```bash
+```commandline
 python -m grid2op.main --help
 ```
 
 ## Using Docker
-*coming soon*
+Then it's possible to start a container from the downloaded image (see [install-with-docker](#install-with-docker)):
+```commandline
+docker run -it bdonnot/grid2op:latest
+```
+
+This command will start a container form the image, execute the main script of grid2op 
+(see [using-cli-arguments](#using-cli-arguments)) and exit this container.
+
+If instead you want to start an interactive session, you can do:
+```commandline
+docker run -it bdonnot/grid2op:latest bash
+```
+This will start the "bash" script from the container, and you interact with it.
+
 
 # Main features of Grid2Op
 
@@ -135,8 +158,8 @@ Its main features are:
 ## Generate the documentation
 A copy of the documentation can be built: you will need Sphinx, a Documentation building tool, and a nice-looking custom
  [Sphinx theme similar to the one of readthedocs.io](https://sphinx-rtd-theme.readthedocs.io/en/latest/):
-```bash
-pip3 install sphinx sphinx-rtd-theme
+```commandline
+pip3 install -U grid2op[docs]
 ```
 This installs both the Sphinx package and the custom template. Then, the documentation can be built with the command:
 ```
@@ -185,7 +208,7 @@ anything with the help of mybinder:
 Some tests (unit test, non regression test etc.) are provided with this package. They are located at grid2op/tests.
 
 The tests can be performed with the command:
-```bash
+```commandline
 cd grid2op/tests
 python3 -m unittest discover
 ```

docs/conf.py

@@ -22,7 +22,7 @@
 author = 'Benjamin Donnot'
 
 # The full version, including alpha/beta/rc tags
-release = '0.3.5'
+release = '0.3.6'
 version = '0.3'
 
 

docs/quickstart.rst

@@ -22,15 +22,14 @@ First, it is recommended (but optionnal) to make a virtual environment:
 .. code-block:: bash
 
     pip3 install -U virtualenv
-    cd Grid2Op
-    python3 -m virtualenv venv_grid2op
-
 
 The second step is to clone the Grid2Op package (`git` is required):
 
 .. code-block:: bash
 
     git clone https://github.com/rte-france/Grid2Op.git
+    cd Grid2Op
+    python3 -m virtualenv venv_grid2op
 
 This should create a folder Grid2Op with the current sources.
 
@@ -74,3 +73,10 @@ interesting part of this framework:
   or on `this github repository <https://github.com/abhinavsagar/Reinforcement-Learning-Tutorial>`_ . This code will
   be adapted (only minor changes, most of them to fit the shape of the data)
   and a (D)DQN will be trained on this problem.
+* 4_StudyYourAgent shows how to study an Agent, for example
+  the methods to reload a saved experiment, or to plot the powergrid given an observation for
+  example. This is an introductory notebook. More user friendly graphical interface should
+  come soon.
+
+These notebooks are available without any installation thanks to
+`mybinder <https://mybinder.org/v2/gh/rte-france/Grid2Op/master>`_

getting_started/0_basic_functionalities.ipynb

@@ -279,7 +279,8 @@
    "source": [
     "powergrid_path = grid2op.CASE_14_FILE\n",
     "multi_episode_path = grid2op.CHRONICS_MLUTIEPISODE\n",
-    "names_chronics_to_backend = grid2op.NAMES_CHRONICS_TO_BACKEND"
+    "names_chronics_to_backend = grid2op.NAMES_CHRONICS_TO_BACKEND\n",
+    "max_iter = 10"
    ]
   },
   {
@@ -307,7 +308,8 @@
     "from grid2op.ChronicsHandler import ChronicsHandler, Multifolder, GridStateFromFileWithForecasts\n",
     "data_feeding = ChronicsHandler(chronicsClass=Multifolder,\n",
     "                               path=multi_episode_path,\n",
-    "                               gridvalueClass=GridStateFromFileWithForecasts)"
+    "                               gridvalueClass=GridStateFromFileWithForecasts,\n",
+    "                               max_iter=max_iter)"
    ]
   },
   {
@@ -496,7 +498,9 @@
     "    obs, reward, done, info = env.step(act) # implement this action on the powergrid\n",
     "    act = my_agent.act(obs, reward, done) # chose an action to do, in this case \"do nothing\"\n",
     "    cum_reward += reward\n",
-    "    time_step += 1"
+    "    time_step += 1\n",
+    "    if time_step > max_iter:\n",
+    "        break"
    ]
   },
   {
@@ -515,8 +519,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "This agent managed to survive 287 timesteps\n",
-      "It's final cumulated reward is 287.0\n"
+      "This agent managed to survive 11 timesteps\n",
+      "It's final cumulated reward is 11.0\n"
      ]
     }
    ],
@@ -585,7 +589,7 @@
     "           path_casefile=powergrid_path,\n",
     "           path_chronics=multi_episode_path,\n",
     "           names_chronics_to_backend=names_chronics_to_backend,\n",
-    "           gridStateclass_kwargs={\"gridvalueClass\": GridStateFromFileWithForecasts}\n",
+    "           gridStateclass_kwargs={\"gridvalueClass\": GridStateFromFileWithForecasts, \"max_iter\": max_iter}\n",
     "          )"
    ]
   },
@@ -610,8 +614,8 @@
      "text": [
       "The results are:\n",
       "\tFor chronics located at /home/donnotben/.local/lib/python3.6/site-packages/grid2op/data/test_multi_chronics/1\n",
-      "\t\t - cumulative reward: 287.00\n",
-      "\t\t - number of time steps completed: 287 / 287\n"
+      "\t\t - cumulative reward: 10.00\n",
+      "\t\t - number of time steps completed: 10 / 10\n"
      ]
     }
    ],
@@ -642,8 +646,8 @@
      "text": [
       "The results are:\n",
       "\tFor chronics located at /home/donnotben/.local/lib/python3.6/site-packages/grid2op/data/test_multi_chronics/1\n",
-      "\t\t - cumulative reward: 287.00\n",
-      "\t\t - number of time steps completed: 287 / 287\n"
+      "\t\t - cumulative reward: 10.00\n",
+      "\t\t - number of time steps completed: 10 / 10\n"
      ]
     }
    ],
@@ -654,7 +658,7 @@
     "           path_casefile=powergrid_path,\n",
     "           path_chronics=multi_episode_path,\n",
     "           names_chronics_to_backend=names_chronics_to_backend,\n",
-    "           gridStateclass_kwargs={\"gridvalueClass\": GridStateFromFileWithForecasts}\n",
+    "           gridStateclass_kwargs={\"gridvalueClass\": GridStateFromFileWithForecasts, \"max_iter\": max_iter}\n",
     "          )\n",
     "print(\"The results are:\")\n",
     "for chron_name, cum_reward, nb_time_step, max_ts in res:\n",
@@ -684,8 +688,8 @@
      "text": [
       "The results are:\n",
       "\tFor chronics located at /home/donnotben/.local/lib/python3.6/site-packages/grid2op/data/test_multi_chronics/1\n",
-      "\t\t - cumulative reward: 287.00\n",
-      "\t\t - number of time steps completed: 287 / 287\n"
+      "\t\t - cumulative reward: 10.00\n",
+      "\t\t - number of time steps completed: 10 / 10\n"
      ]
     }
    ],
@@ -695,7 +699,7 @@
     "           path_casefile=powergrid_path,\n",
     "           path_chronics=multi_episode_path,\n",
     "           names_chronics_to_backend=names_chronics_to_backend,\n",
-    "           gridStateclass_kwargs={\"gridvalueClass\": GridStateFromFileWithForecasts},\n",
+    "           gridStateclass_kwargs={\"gridvalueClass\": GridStateFromFileWithForecasts, \"max_iter\": max_iter},\n",
     "           path_save=os.path.abspath(\"saved_experiment_donothing\")\n",
     "          )\n",
     "print(\"The results are:\")\n",
@@ -715,9 +719,9 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "actions.npy\t\t\t  episode_meta.json   _parameters.json\r\n",
-      "agent_exec_times.npy\t\t  episode_times.json  parameters.json\r\n",
-      "disc_lines_cascading_failure.npy  observations.npy    rewards.npy\r\n"
+      "actions.npy\t\t\t  env_modifications.npy  observations.npy\r\n",
+      "agent_exec_times.npy\t\t  episode_meta.json\t _parameters.json\r\n",
+      "disc_lines_cascading_failure.npy  episode_times.json\t rewards.npy\r\n"
      ]
     }
    ],