makeenv.rst

grid2op.MakeEnv

Make: Using pre defined Environments

This page is organized as follow:

Table of Contents

Objectives

The function define in this module is the easiest and most convenient ways to create a valid grid2op.Environment.Environment.

To get started with such an environment, you can simply do:

import grid2op
env = grid2op.make("rte_case14_realistic")

You can consult the different notebooks in the getting_stared directory of this package for more information on how to use it.

Created Environment should behave exactly like a gym environment. If you notice any unwanted behavior, please address an issue in the official grid2op repository: Grid2Op

The environment created with this method should be fully compatible with the gym framework: if you are developing a new algorithm of "Reinforcement Learning" and you used the openai gym framework to do so, you can port your code in a few minutes (basically this consists in adapting the input and output dimension of your BaseAgent) and make it work with a Grid2Op environment. An example of such modifications is exposed in the getting_started/ notebooks.

Usage

There are two main ways to use the make function. The first one is to directly pass the name of the environment you want to use:

import grid2op
env = grid2op.make("rte_case14_realistic")

This will create the environment known "rte_case14_realistic" with all default parameters. If this environment is has not been downloaded, at the first call to this function it will download it and store it in a cache on your system ( see the section cache_manip for more information), afterwards it will use the downloaded environment.

If your computer don't have internet access, or you prefer to download things manually, it is also possible to provide the full absolute path of you dataset. On linux / unix (including macos) machines this will be something like

import grid2op
env = grid2op.make("/full/path/where/the/env/is/located/rte_case14_realistic")

And on windows based machine this will look like:

import grid2op
env = grid2op.make("C:\\where\\the\\env\\is\\located\\rte_case14_realistic")

In bot cases it will load the environment named "rte_case14_realistic" (provided that you found a way to get it on your machine) located at the path "/full/path/where/the/env/is/located/rte_case14_realistic" (or "C:\the\full\path\where\the\env\is\located\rte_case14_realistic").

Important notes

As of version 0.8.0 a "make" has been updated in grid2op. This function, replace the current implementation of renamed make_old, merges the behaviour of "grid2op.download" script and "make_old" function.

It has the following behavior:

1. if you specify a full path to a local environment (containing the chronics and the default parameters), it will be used (see section usage)
2. if you specify the name of an environment that you have already downloaded, it will use this environment (NB currently no checks are implemented if the environment has been updated remotely, which can happen if we realize there were some issues with it.)
3. if you provided no arguments a default environment will be used: rte_case14_realistic
4. if the flag test is set to False (default behaviour) and none of the above conditions are met, the make will download the data of this environment locally the first time it is called. If you don't want to download anything then you can pass the flag test=True
5. if test=True (NON default behaviour) nothing will be loaded, and the make will attempt to use a pre defined environment provided with the python package. We want to emphasize that because the environments provided with this package contains only little data, they are not suitable for leaning a consistent agent / controler. That is why a warning is sent in this case. Also, keep in mind that if you don't pass test=True then you will not have the possibility to search for these environments provided in the package. Setting "test=True" is NOT recommended for most usage. Have a look at the section usage for more details on how to use make, especially if you don't have an internet connection.
6. if no valid environment is found, make throws a EnvError.

Cache manipulation

Editing the file ~/.grid2opconfig.json allows you to change the data cache location. Programatically, it can be done with change_local_dir.

Call get_current_local_dir to get the local cache directory location.

You can list the environments in the local cache directory by calling list_available_local_env and list all environments that can be downloaded with list_available_remote_env (nb list_available_remote_env requires an internet connection)

import grid2op
print("The current local directory where the environment are downloaded is \n{}"
      "".format(grid2op.get_current_local_dir()))
print("The environments available without necessary download are: \n{}"
      "".format(grid2op.list_available_local_env()))
print("I can download these environments from the internet: \n{}"
      "".format(grid2op.list_available_remote_env()))

NB if you change the cache directory, all previously downloaded environments will not be visible by grid2op and they will not be removed from your local hard drive. This is why we don't recommend to change this folder unless you have a valid reason to do so.

Customize your environment

When you create it, you can change different parameters of the environments. We summarize all parameters that can be modified at the creation of your environment. We recommend you to see the section Parameters of the make_from_dataset_path for more information about the effect of this attributes. NB arguments preceding by a * are listed to be exhaustive. They are technical arguments and should not be modified unless you have a reason to. For example, in the context of the L2RPN competition, we don't recommend to modify them.

• `dataset_path`: used to specify the name (or the path) of the environment you want to load
• `backend`: a initialized backend that will carry out the computation related to power system [mainly use if you want to change from PandapowerBackend (default) to a different one eg LightSim2Grid)
• `reward_class`: change the type of reward you want to use for your agent
• `other_reward`: tell "env.step" to return addition "rewards"
• difficulty, `param`: control the difficulty level of the game (might not always be available)
• chronics_class, `data_feeding_kwargs`: further customization to how the data will be generated
• * chronics_path, data_feeding, : to overload default path for the data (not recommended)
• * `action_class`: which action class your agent is allowed to use (not recommended).
• * `gamerules_class`: the rules that are checked to declare an action legal / illegal (not recommended)
• * `volagecontroler_class`: how the voltages are set on the grid (not recommended)
• * `grid_path`: the path where the default powergrid properties are stored (not recommended)
• * observation_class, `kwargs_observation`: which type of observation do you use (not recommended)
• * opponent_action_class, opponent_class, opponent_init_budget, opponent_budget_per_ts, opponent_budget_class, opponent_space_type, `kwargs_opponent`: all configuration for the opponent. (not recommended)

• * has_attention_budget, attention_budget_class, `kwargs_attention_budget`: all configuration

  for the "alarm" / "attention budget" parameters. (not recommended)

More information about the "customization" of the environment, especially to optimize the I/O or to manipulate which data you interact with are available in the environment-module module (environment-module-usage section).

Warning

Don't modify the action class

We do not recommend to modify the keyword arguments starting with *, and especially the action_class.

You can customize an environment with:

import grid2op
env = grid2op.make(dataset_path, 
                   backend=...,  # put a compatible backend here
                   reward_class=...,  # change the reward function, see BaseReward
                   other_reward={key: reward_func}, # with `key` being strings and `reward_func` inheriting from BaseReward
                   difficulty=...,  # str or ints
                   param=...,  # any Parameters (from grid2op.Parameters import Parameters)
                   etc.
                   )

See documentation of grid2op.MakeEnv.make_from_dataset_path for more information about all these parameters.

Detailed Documentation by class

grid2op.MakeEnv