Grid2Op is a plateform, built with modularity in mind, that allows to perform powergrid operation. And that's what it stands for: Grid To Operate. Grid2Op acts as a replacement of pypownet as a library used for the Learning To Run Power Network L2RPN.
This framework allows to perform most kind of powergrid operations, from modifying the setpoint of generators, to load shedding, performing maintenance operations or modifying the topology of a powergrid to solve security issues.
Official documentation: the official documentation is available at https://grid2op.readthedocs.io/.
- 1 Installation
- 2 Main features of Grid2Op
- 3 Getting Started
- 4 Documentation
- 5 Test and known issues
- 6 License information
- Python >= 3.6
cd my-project-folder
pip3 install -U virtualenv
python3 -m virtualenv venv_grid2op
source venv_grid2op/bin/activate
git clone https://github.com/rte-france/Grid2Op.git
cd Grid2Op
pip3 install -U .
cd ..
pip3 install grid2op
git clone https://github.com/rte-france/Grid2Op.git
cd Grid2Op
pip3 install -e .
pip3 install -e .[optional]
pip3 install -e .[docs]
Grid2Op docker containers are available on dockerhub.
To install the latest Grid2Op container locally, use the following:
docker pull bdonnot/grid2op:latest
Built with modulartiy in mind, Grid2Op acts as a replacement of pypownet as a library used for the Learning To Run Power Network L2RPN.
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 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
- supports changes of powerflow solvers, actions, observations to better suit any need in performing power system operations modeling
- has an RL-focused interface, compatible with OpenAI-gym: same interface for the Environment class.
- parameters, game rules or type of actions are perfectly parametrizable
- can adapt to any kind of input data, in various format (might require the rewriting of a class)
Grid2Op relies on an open source powerflow solver (PandaPower), but is also compatible with other Backend. If you have at your disposal another powerflow solver, the documentation of grid2op/Backend can help you integrate it into a proper "Backend" 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 directories.
These notebooks will help you in understanding how this framework is used and cover the most interesting part of this framework:
- 00_Introduction and 00_SmallExample describe what is adressed by the grid2op framework (with a tiny introductions to both power systems and reinforcement learning) and give and introductory example to a small powergrid manipulation.
- 01_Grid2opFramework covers the basics
of the
Grid2Op framework. It also covers how to create a valid environment and how to use the
Runner
class to assess how well an agent is performing rapidly. - O2_Observation details how to create an "expert agent" that will take pre defined actions based on the observation it gets from the environment. This Notebook also covers the functioning of the BaseObservation class.
- 03_Action demonstrates how to use the BaseAction class and how to manipulate the powergrid.
- 04_TrainingAnAgent shows how to get started with reinforcement learning in the Grid2Op framework. It will use the code provided by Abhinav Sagar available on his blog or on his github repository. 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.
- 05_StudyYourAgent shows how to study an BaseAgent, 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.
- 06_Redispatching explains what is the "redispatching" from the point of view of a company who's in charge of keeping the powergrid safe (aka a Transmission System Operator) and how to manipulate this concept in grid2op. Redispatching allows you to perform continuous actions on the powergrid problem.
- 07_MultiEnv details how grid2op natively support a single agent interacting with multiple environments at the same time. This is particularly handy to train "asynchronous" agent in the Reinforcement Learning community for example.
- 08_PlottingCapabilities shows you the different ways with which you can represent (visually) the grid your agent interact with. A renderer is available like in many open AI gym environment. But you also have the possibility to post process an agent and make some movies out of it, and we also developed a Graphical User Interface (GUI) called "grid2viz" that allows to perform in depth study of your agent's behaviour on different scenarios and even to compare it with baselines.
- 09_EnvironmentModifications elaborates on the maintenance, hazards and attacks. All three of these represents external events that can disconnect some powerlines. This notebook covers how to spot when such things happened and what can be done when the maintenance or the attack is over.
Try them out in your own browser without installing
anything with the help of mybinder:
The official documentation is available at https://grid2op.readthedocs.io/.
A copy of the documentation can be built if the project is installed from source: you will need Sphinx, a Documentation building tool, and a nice-looking custom Sphinx theme similar to the one of readthedocs.io. These can be installed with:
pip3 install -U grid2op[docs]
This installs both the Sphinx package and the custom template.
Then, on systems where make
is available (mainly gnu-linux and macos) the documentation can be built with the command:
make html
For windows, or systems where make
is not available, the command:
sphinx-build -b html docs documentation
This will create a "documentation" subdirectory and the main entry point of the document will be located at index.html.
It is recommended to build this documentation locally, for convenience. For example, the "getting started" notebooks referenced some pages of the help.
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.6
- python 3.7
- python 3.8
- python 3.9
Note that, at time of writing, "numba" which accelerates the computation of the powerflow for the default "powerflow solver" is not available for python 3.9 (more information at numba/numba#6345).
On all of these cases, we tested grid2op on all available numpy version >= 1.18.
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.
Provided that Grid2Op is installed from source:
pip3 install -U grid2op[optional]
cd grid2op/tests
python3 -m unittest discover
Copyright 2019-2020 RTE France
RTE: http://www.rte-france.com
This Source Code is subject to the terms of the Mozilla Public License (MPL) v2 also available here
We welcom contribution from everyone. They can take the form of pull requests for smaller changed. In case of a major change (or if you have a doubt on what is "a small change"), please open an issue first to discuss what you would like to change.
Code in the contribution should pass all the tests, have some dedicated tests for the new feature and documentation.