1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
|
%global _empty_manifest_terminate_build 0
Name: python-Grid2Op
Version: 1.8.1
Release: 1
Summary: An gym compatible environment to model sequential decision making for powersystems
License: Mozilla Public License 2.0 (MPL 2.0)
URL: https://github.com/rte-france/Grid2Op
Source0: https://mirrors.nju.edu.cn/pypi/web/packages/ed/a8/64325a0f46c509c28633d6858bc616adf015f2393e1278ba2e4e07d9ddbc/Grid2Op-1.8.1.tar.gz
BuildArch: noarch
%description
# Grid2Op
[](https://pepy.tech/project/grid2op)
[](https://pypi.org/project/Grid2Op/)
[](https://pypi.org/project/Grid2Op/)
[](https://www.mozilla.org/en-US/MPL/2.0/)
[](https://grid2op.readthedocs.io/en/latest/?badge=latest)
[](https://circleci.com/gh/rte-france/Grid2Op)
[]( https://discord.gg/cYsYrPT)
[](https://mybinder.org/v2/gh/rte-france/Grid2Op/master)
Grid2Op is a platform, 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](https://github.com/MarvinLer/pypownet)
as a library used for the Learning To Run Power Network [L2RPN](https://l2rpn.chalearn.org/).
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/](https://grid2op.readthedocs.io/).
* [1 Installation](#installation)
* [1.1 Setup a Virtualenv (optional)](#setup-a-virtualenv-optional)
* [1.2 Install from source](#install-from-source)
* [1.3 Install from PyPI](#install-from-pypi)
* [1.4 Install for contributors](#install-for-contributors)
* [1.5 Docker](#docker)
* [2 Main features of Grid2Op](#main-features-of-grid2op)
* [3 Getting Started](#getting-started)
* [0 Basic features](getting_started/0_basic_functionalities.ipynb)
* [1 BaseObservation Agents](getting_started/1_Observation_Agents.ipynb)
* [2 BaseAction Grid Manipulation](getting_started/2_Action_GridManipulation.ipynb)
* [3 Training An BaseAgent](getting_started/3_TrainingAnAgent.ipynb)
* [4 Study Your BaseAgent](getting_started/4_StudyYourAgent.ipynb)
* [4 Citing](#Citing)
* [5 Documentation](#documentation)
* [6 Contribute](#contributing)
* [7 Test and known issues](#tests-and-known-issues)
* [8 License information](#license-information)
# Installation
## Requirements:
* Python >= 3.6
## Setup a Virtualenv (optional)
### Create a virtual environment
```commandline
cd my-project-folder
pip3 install -U virtualenv
python3 -m virtualenv venv_grid2op
```
### Enter virtual environment
```commandline
source venv_grid2op/bin/activate
```
## Install from source
```commandline
git clone https://github.com/rte-france/Grid2Op.git
cd Grid2Op
pip3 install -U .
cd ..
```
## Install from PyPI
```commandline
pip3 install grid2op
```
## Install for contributors
```commandline
git clone https://github.com/rte-france/Grid2Op.git
cd Grid2Op
pip3 install -e .
pip3 install -e .[optional]
pip3 install -e .[docs]
```
## Docker
Grid2Op docker containers are available on [dockerhub](https://hub.docker.com/r/bdonnot/grid2op/tags).
To install the latest Grid2Op container locally, use the following:
```commandline
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/).
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](https://gym.openai.com/): 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)
## Powerflow solver
Grid2Op relies on an open source powerflow solver ([PandaPower](https://www.pandapower.org/)),
but is also compatible with other *Backend*. If you have at your disposal another powerflow solver,
the documentation of [grid2op/Backend](grid2op/Backend/Backend.py) can help you integrate it into a proper "Backend"
and have Grid2Op using this powerflow instead of PandaPower.
# Getting Started
Some Jupyter notebook are provided as tutorials for the Grid2Op package. They are located in the
[getting_started](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](getting_started/00_Introduction.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/00_Introduction.ipynb)
and [00_SmallExample](getting_started/00_SmallExample.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/00_SmallExample.ipynb)
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](getting_started/01_Grid2opFramework.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/01_Grid2opFramework.ipynb)
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.
* [02_Observation](getting_started/02_Observation.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/02_Observation.ipynb)
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](getting_started/03_Action.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/03_Action.ipynb)
demonstrates
how to use the BaseAction class and how to manipulate the powergrid.
* [04_TrainingAnAgent](getting_started/04_TrainingAnAgent.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/04_TrainingAnAgent.ipynb)
shows how to get started with
reinforcement learning with the grid2op environment. It shows the basic on how to train a "PPO" model operating the grid relying on "stable baselines 3" PPO implementation.
* [05_StudyYourAgent](getting_started/05_StudyYourAgent.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/05_StudyYourAgent.ipynb)
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_Curtailment](getting_started/06_Redispatching_Curtailment.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/06_Redispatching_Curtailment.ipynb)
explains what is the
"redispatching" and curtailment 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 (and curtailment) allows you to perform **continuous**
actions on the powergrid
problem.
* [07_MultiEnv](getting_started/07_MultiEnv.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/07_MultiEnv.ipynb)
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](getting_started/08_PlottingCapabilities.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/08_PlottingCapabilities.ipynb)
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](https://github.com/mjothy/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](getting_started/09_EnvironmentModifications.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/09_EnvironmentModifications.ipynb)
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.
* [10_StorageUnits](getting_started/10_StorageUnits.ipynb)
[](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.
* [11_IntegrationWithExistingRLFrameworks](getting_started/11_IntegrationWithExistingRLFrameworks.ipynb)
[](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.
Try them out in your own browser without installing
anything with the help of mybinder:
[](https://mybinder.org/v2/gh/rte-france/Grid2Op/master)
Or thanks to google colab (all links are provided near the notebook description)
# Citing
If you use this package in one of your work, please cite:
```
@misc{grid2op,
author = {B. Donnot},
title = {{Grid2op- A testbed platform to model sequential decision making in power systems. }},
year = {2020},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://GitHub.com/rte-france/grid2op}},
}
```
# Documentation
The official documentation is available at
[https://grid2op.readthedocs.io/](https://grid2op.readthedocs.io/).
## Build the documentation locally
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](https://sphinx-rtd-theme.readthedocs.io/en/latest/). These
can be installed with:
```commandline
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:
```commandline
make html
```
For windows, or systems where `make` is not available, the command:
```commandline
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](documentation/html/index.html).
It is recommended to build this documentation locally, for convenience.
For example, the "getting started" notebooks referenced some pages of the help.
<!-- sphinx-build -b html docs documentation-->
# Contributing
We welcome contributions 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.
To contribute to this code, you need to:
1. fork the repository located at https://github.com/rte-france/Grid2Op
2. synch your fork with the "latest developement branch of grid2op". For example, if the latest grid2op release
on pypi is `1.6.5` you need to synch your repo with the branch named `dev_1.6.6` or `dev_1.7.0` (if
the branch `dev_1.6.6` does not exist). It will be the highest number in the branches `dev_*` on
grid2op official github repository.
3. implement your functionality / code your modifications or anything else
4. make sure to add tests and documentation if applicable
5. once it is developed, synch your repo with the last development branch again (see point 2 above) and
make sure to solve any possible conflicts
6. write a pull request and make sure to target the right branch (the "last development branch")
Code in the contribution should pass all the tests, have some dedicated tests for the new feature (if applicable)
and documentation (if applicable).
Before implementing any major feature, please write a github issue first.
# Tests and known issues
## Tests performed currently
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
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
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.
## Perform tests locally
Provided that Grid2Op is installed *from source*:
### Install additional dependencies
```commandline
pip3 install -U grid2op[optional]
```
### Launch tests
```commandline
cd grid2op/tests
python3 -m unittest discover
```
# License information
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](https://www.mozilla.org/en-US/MPL/2.0/)
%package -n python3-Grid2Op
Summary: An gym compatible environment to model sequential decision making for powersystems
Provides: python-Grid2Op
BuildRequires: python3-devel
BuildRequires: python3-setuptools
BuildRequires: python3-pip
%description -n python3-Grid2Op
# Grid2Op
[](https://pepy.tech/project/grid2op)
[](https://pypi.org/project/Grid2Op/)
[](https://pypi.org/project/Grid2Op/)
[](https://www.mozilla.org/en-US/MPL/2.0/)
[](https://grid2op.readthedocs.io/en/latest/?badge=latest)
[](https://circleci.com/gh/rte-france/Grid2Op)
[]( https://discord.gg/cYsYrPT)
[](https://mybinder.org/v2/gh/rte-france/Grid2Op/master)
Grid2Op is a platform, 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](https://github.com/MarvinLer/pypownet)
as a library used for the Learning To Run Power Network [L2RPN](https://l2rpn.chalearn.org/).
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/](https://grid2op.readthedocs.io/).
* [1 Installation](#installation)
* [1.1 Setup a Virtualenv (optional)](#setup-a-virtualenv-optional)
* [1.2 Install from source](#install-from-source)
* [1.3 Install from PyPI](#install-from-pypi)
* [1.4 Install for contributors](#install-for-contributors)
* [1.5 Docker](#docker)
* [2 Main features of Grid2Op](#main-features-of-grid2op)
* [3 Getting Started](#getting-started)
* [0 Basic features](getting_started/0_basic_functionalities.ipynb)
* [1 BaseObservation Agents](getting_started/1_Observation_Agents.ipynb)
* [2 BaseAction Grid Manipulation](getting_started/2_Action_GridManipulation.ipynb)
* [3 Training An BaseAgent](getting_started/3_TrainingAnAgent.ipynb)
* [4 Study Your BaseAgent](getting_started/4_StudyYourAgent.ipynb)
* [4 Citing](#Citing)
* [5 Documentation](#documentation)
* [6 Contribute](#contributing)
* [7 Test and known issues](#tests-and-known-issues)
* [8 License information](#license-information)
# Installation
## Requirements:
* Python >= 3.6
## Setup a Virtualenv (optional)
### Create a virtual environment
```commandline
cd my-project-folder
pip3 install -U virtualenv
python3 -m virtualenv venv_grid2op
```
### Enter virtual environment
```commandline
source venv_grid2op/bin/activate
```
## Install from source
```commandline
git clone https://github.com/rte-france/Grid2Op.git
cd Grid2Op
pip3 install -U .
cd ..
```
## Install from PyPI
```commandline
pip3 install grid2op
```
## Install for contributors
```commandline
git clone https://github.com/rte-france/Grid2Op.git
cd Grid2Op
pip3 install -e .
pip3 install -e .[optional]
pip3 install -e .[docs]
```
## Docker
Grid2Op docker containers are available on [dockerhub](https://hub.docker.com/r/bdonnot/grid2op/tags).
To install the latest Grid2Op container locally, use the following:
```commandline
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/).
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](https://gym.openai.com/): 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)
## Powerflow solver
Grid2Op relies on an open source powerflow solver ([PandaPower](https://www.pandapower.org/)),
but is also compatible with other *Backend*. If you have at your disposal another powerflow solver,
the documentation of [grid2op/Backend](grid2op/Backend/Backend.py) can help you integrate it into a proper "Backend"
and have Grid2Op using this powerflow instead of PandaPower.
# Getting Started
Some Jupyter notebook are provided as tutorials for the Grid2Op package. They are located in the
[getting_started](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](getting_started/00_Introduction.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/00_Introduction.ipynb)
and [00_SmallExample](getting_started/00_SmallExample.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/00_SmallExample.ipynb)
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](getting_started/01_Grid2opFramework.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/01_Grid2opFramework.ipynb)
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.
* [02_Observation](getting_started/02_Observation.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/02_Observation.ipynb)
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](getting_started/03_Action.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/03_Action.ipynb)
demonstrates
how to use the BaseAction class and how to manipulate the powergrid.
* [04_TrainingAnAgent](getting_started/04_TrainingAnAgent.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/04_TrainingAnAgent.ipynb)
shows how to get started with
reinforcement learning with the grid2op environment. It shows the basic on how to train a "PPO" model operating the grid relying on "stable baselines 3" PPO implementation.
* [05_StudyYourAgent](getting_started/05_StudyYourAgent.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/05_StudyYourAgent.ipynb)
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_Curtailment](getting_started/06_Redispatching_Curtailment.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/06_Redispatching_Curtailment.ipynb)
explains what is the
"redispatching" and curtailment 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 (and curtailment) allows you to perform **continuous**
actions on the powergrid
problem.
* [07_MultiEnv](getting_started/07_MultiEnv.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/07_MultiEnv.ipynb)
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](getting_started/08_PlottingCapabilities.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/08_PlottingCapabilities.ipynb)
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](https://github.com/mjothy/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](getting_started/09_EnvironmentModifications.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/09_EnvironmentModifications.ipynb)
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.
* [10_StorageUnits](getting_started/10_StorageUnits.ipynb)
[](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.
* [11_IntegrationWithExistingRLFrameworks](getting_started/11_IntegrationWithExistingRLFrameworks.ipynb)
[](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.
Try them out in your own browser without installing
anything with the help of mybinder:
[](https://mybinder.org/v2/gh/rte-france/Grid2Op/master)
Or thanks to google colab (all links are provided near the notebook description)
# Citing
If you use this package in one of your work, please cite:
```
@misc{grid2op,
author = {B. Donnot},
title = {{Grid2op- A testbed platform to model sequential decision making in power systems. }},
year = {2020},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://GitHub.com/rte-france/grid2op}},
}
```
# Documentation
The official documentation is available at
[https://grid2op.readthedocs.io/](https://grid2op.readthedocs.io/).
## Build the documentation locally
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](https://sphinx-rtd-theme.readthedocs.io/en/latest/). These
can be installed with:
```commandline
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:
```commandline
make html
```
For windows, or systems where `make` is not available, the command:
```commandline
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](documentation/html/index.html).
It is recommended to build this documentation locally, for convenience.
For example, the "getting started" notebooks referenced some pages of the help.
<!-- sphinx-build -b html docs documentation-->
# Contributing
We welcome contributions 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.
To contribute to this code, you need to:
1. fork the repository located at https://github.com/rte-france/Grid2Op
2. synch your fork with the "latest developement branch of grid2op". For example, if the latest grid2op release
on pypi is `1.6.5` you need to synch your repo with the branch named `dev_1.6.6` or `dev_1.7.0` (if
the branch `dev_1.6.6` does not exist). It will be the highest number in the branches `dev_*` on
grid2op official github repository.
3. implement your functionality / code your modifications or anything else
4. make sure to add tests and documentation if applicable
5. once it is developed, synch your repo with the last development branch again (see point 2 above) and
make sure to solve any possible conflicts
6. write a pull request and make sure to target the right branch (the "last development branch")
Code in the contribution should pass all the tests, have some dedicated tests for the new feature (if applicable)
and documentation (if applicable).
Before implementing any major feature, please write a github issue first.
# Tests and known issues
## Tests performed currently
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
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
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.
## Perform tests locally
Provided that Grid2Op is installed *from source*:
### Install additional dependencies
```commandline
pip3 install -U grid2op[optional]
```
### Launch tests
```commandline
cd grid2op/tests
python3 -m unittest discover
```
# License information
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](https://www.mozilla.org/en-US/MPL/2.0/)
%package help
Summary: Development documents and examples for Grid2Op
Provides: python3-Grid2Op-doc
%description help
# Grid2Op
[](https://pepy.tech/project/grid2op)
[](https://pypi.org/project/Grid2Op/)
[](https://pypi.org/project/Grid2Op/)
[](https://www.mozilla.org/en-US/MPL/2.0/)
[](https://grid2op.readthedocs.io/en/latest/?badge=latest)
[](https://circleci.com/gh/rte-france/Grid2Op)
[]( https://discord.gg/cYsYrPT)
[](https://mybinder.org/v2/gh/rte-france/Grid2Op/master)
Grid2Op is a platform, 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](https://github.com/MarvinLer/pypownet)
as a library used for the Learning To Run Power Network [L2RPN](https://l2rpn.chalearn.org/).
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/](https://grid2op.readthedocs.io/).
* [1 Installation](#installation)
* [1.1 Setup a Virtualenv (optional)](#setup-a-virtualenv-optional)
* [1.2 Install from source](#install-from-source)
* [1.3 Install from PyPI](#install-from-pypi)
* [1.4 Install for contributors](#install-for-contributors)
* [1.5 Docker](#docker)
* [2 Main features of Grid2Op](#main-features-of-grid2op)
* [3 Getting Started](#getting-started)
* [0 Basic features](getting_started/0_basic_functionalities.ipynb)
* [1 BaseObservation Agents](getting_started/1_Observation_Agents.ipynb)
* [2 BaseAction Grid Manipulation](getting_started/2_Action_GridManipulation.ipynb)
* [3 Training An BaseAgent](getting_started/3_TrainingAnAgent.ipynb)
* [4 Study Your BaseAgent](getting_started/4_StudyYourAgent.ipynb)
* [4 Citing](#Citing)
* [5 Documentation](#documentation)
* [6 Contribute](#contributing)
* [7 Test and known issues](#tests-and-known-issues)
* [8 License information](#license-information)
# Installation
## Requirements:
* Python >= 3.6
## Setup a Virtualenv (optional)
### Create a virtual environment
```commandline
cd my-project-folder
pip3 install -U virtualenv
python3 -m virtualenv venv_grid2op
```
### Enter virtual environment
```commandline
source venv_grid2op/bin/activate
```
## Install from source
```commandline
git clone https://github.com/rte-france/Grid2Op.git
cd Grid2Op
pip3 install -U .
cd ..
```
## Install from PyPI
```commandline
pip3 install grid2op
```
## Install for contributors
```commandline
git clone https://github.com/rte-france/Grid2Op.git
cd Grid2Op
pip3 install -e .
pip3 install -e .[optional]
pip3 install -e .[docs]
```
## Docker
Grid2Op docker containers are available on [dockerhub](https://hub.docker.com/r/bdonnot/grid2op/tags).
To install the latest Grid2Op container locally, use the following:
```commandline
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/).
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](https://gym.openai.com/): 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)
## Powerflow solver
Grid2Op relies on an open source powerflow solver ([PandaPower](https://www.pandapower.org/)),
but is also compatible with other *Backend*. If you have at your disposal another powerflow solver,
the documentation of [grid2op/Backend](grid2op/Backend/Backend.py) can help you integrate it into a proper "Backend"
and have Grid2Op using this powerflow instead of PandaPower.
# Getting Started
Some Jupyter notebook are provided as tutorials for the Grid2Op package. They are located in the
[getting_started](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](getting_started/00_Introduction.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/00_Introduction.ipynb)
and [00_SmallExample](getting_started/00_SmallExample.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/00_SmallExample.ipynb)
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](getting_started/01_Grid2opFramework.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/01_Grid2opFramework.ipynb)
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.
* [02_Observation](getting_started/02_Observation.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/02_Observation.ipynb)
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](getting_started/03_Action.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/03_Action.ipynb)
demonstrates
how to use the BaseAction class and how to manipulate the powergrid.
* [04_TrainingAnAgent](getting_started/04_TrainingAnAgent.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/04_TrainingAnAgent.ipynb)
shows how to get started with
reinforcement learning with the grid2op environment. It shows the basic on how to train a "PPO" model operating the grid relying on "stable baselines 3" PPO implementation.
* [05_StudyYourAgent](getting_started/05_StudyYourAgent.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/05_StudyYourAgent.ipynb)
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_Curtailment](getting_started/06_Redispatching_Curtailment.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/06_Redispatching_Curtailment.ipynb)
explains what is the
"redispatching" and curtailment 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 (and curtailment) allows you to perform **continuous**
actions on the powergrid
problem.
* [07_MultiEnv](getting_started/07_MultiEnv.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/07_MultiEnv.ipynb)
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](getting_started/08_PlottingCapabilities.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/08_PlottingCapabilities.ipynb)
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](https://github.com/mjothy/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](getting_started/09_EnvironmentModifications.ipynb)
[](https://colab.research.google.com/github/rte-france/Grid2Op/blob/master/getting_started/09_EnvironmentModifications.ipynb)
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.
* [10_StorageUnits](getting_started/10_StorageUnits.ipynb)
[](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.
* [11_IntegrationWithExistingRLFrameworks](getting_started/11_IntegrationWithExistingRLFrameworks.ipynb)
[](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.
Try them out in your own browser without installing
anything with the help of mybinder:
[](https://mybinder.org/v2/gh/rte-france/Grid2Op/master)
Or thanks to google colab (all links are provided near the notebook description)
# Citing
If you use this package in one of your work, please cite:
```
@misc{grid2op,
author = {B. Donnot},
title = {{Grid2op- A testbed platform to model sequential decision making in power systems. }},
year = {2020},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://GitHub.com/rte-france/grid2op}},
}
```
# Documentation
The official documentation is available at
[https://grid2op.readthedocs.io/](https://grid2op.readthedocs.io/).
## Build the documentation locally
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](https://sphinx-rtd-theme.readthedocs.io/en/latest/). These
can be installed with:
```commandline
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:
```commandline
make html
```
For windows, or systems where `make` is not available, the command:
```commandline
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](documentation/html/index.html).
It is recommended to build this documentation locally, for convenience.
For example, the "getting started" notebooks referenced some pages of the help.
<!-- sphinx-build -b html docs documentation-->
# Contributing
We welcome contributions 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.
To contribute to this code, you need to:
1. fork the repository located at https://github.com/rte-france/Grid2Op
2. synch your fork with the "latest developement branch of grid2op". For example, if the latest grid2op release
on pypi is `1.6.5` you need to synch your repo with the branch named `dev_1.6.6` or `dev_1.7.0` (if
the branch `dev_1.6.6` does not exist). It will be the highest number in the branches `dev_*` on
grid2op official github repository.
3. implement your functionality / code your modifications or anything else
4. make sure to add tests and documentation if applicable
5. once it is developed, synch your repo with the last development branch again (see point 2 above) and
make sure to solve any possible conflicts
6. write a pull request and make sure to target the right branch (the "last development branch")
Code in the contribution should pass all the tests, have some dedicated tests for the new feature (if applicable)
and documentation (if applicable).
Before implementing any major feature, please write a github issue first.
# Tests and known issues
## Tests performed currently
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
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
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.
## Perform tests locally
Provided that Grid2Op is installed *from source*:
### Install additional dependencies
```commandline
pip3 install -U grid2op[optional]
```
### Launch tests
```commandline
cd grid2op/tests
python3 -m unittest discover
```
# License information
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](https://www.mozilla.org/en-US/MPL/2.0/)
%prep
%autosetup -n Grid2Op-1.8.1
%build
%py3_build
%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .
%files -n python3-Grid2Op -f filelist.lst
%dir %{python3_sitelib}/*
%files help -f doclist.lst
%{_docdir}/*
%changelog
* Wed May 10 2023 Python_Bot <Python_Bot@openeuler.org> - 1.8.1-1
- Package Spec generated
|
