This Notebook will dive more into the Action class

It is recommended to have a look at the 0_basic_functionalities and 1_Observation_Agents notebooks before getting into this one.

Objectives

This notebook will cover the basic of how use at best the Action class to perform actions (modify) on the powergrid efficiently. Indeed there are multiple concepts behind this class that are not very clear.

This notebook will be focused on the manipulation of Action from an expert system point of view to demonstrate how a desired action is fundamentally taken in the Grid2Op environment. For a more automatic way to handle action (for example using machine learning, the notebook 3_TrainingAnAgent will give a more detailed example.

In [1]:
import os
import sys
import grid2op
In [2]:
res = None
try:
    from jyquickhelper import add_notebook_menu
    res = add_notebook_menu()
except ModuleNotFoundError:
    print("Impossible to automatically add a menu / table of content to this notebook.\nYou can download \"jyquickhelper\" package with: \n\"pip install jyquickhelper\"")
res
Out[2]:
run previous cell, wait for 2 seconds

I) A few comments on actions

It is recommended to have built locally the documentation, and to refer to the action pages of the documentation or to the Action.py file for a more detailed view on these two classes below.

I.A) "change" vs "set"

To manipulate a powergrid, we decided to introduce two distinct (yet close) concepts that will affect the objects differently:

  • change will:
    • connect a powerline if it was disconnected, or reconnect if it was connected. Similar to a "toggle" operation.
    • assign the object to the second bus if it was connected to bus 1 or assign it to bus 1 if it was connected to bus 2
  • set will:
    • connect a powerline (regardless of its previous status) or disconnect it (regardless of its previous status)
    • assign the object (component in the power network) to a specific bus (regardless of its previous bus and status -- for powerline)

This is another change compared to the previous pypownet implementation, were only the change concept was implemented. Having these two things helps understand what is really going on on the powergrid and allows to represent better the intention of the Agent, especially in debugging phase.

Of course, it is perfectly possible to use only the change capability and thus being closer to the original implementation.

Let's give a "concrete" example to highlight the difference between these two methods. Suppose we have a substation with 5 elements:

  • the origin of powerline $l_1$
  • the extremity of powerline $l_2$
  • the extremity of powerline $l_3$
  • a load $c_1$
  • a generator $g_1$

Let's also assume the original configuration (before the action is applied, i.e., the configuration of the observation at time t) is:

Object Name Original Bus Original Status
$l_1$ (origin) 1 connected
$l_2$ (extremity) 2 connected
$l_3$ (extremity) NA disconnected
$c_1$ 1 NA
$g_1 $ 2 NA

Let's say:

  • action $a_1$ consists in "change the status of origin of powerline $l_1$". After applying this action, the status of powerline 1 is: "disconnected".
  • action $a_2$ consists in "change the status of origin of powerline $l_3$". After applying this action, the status of powerline 2 is: "connected" ***.
  • action $a_3$ "set the bus of $c_1$ to bus 1". It is equivalent to doing absolutely nothing.
  • action $a_4$ "set the bus of $g_1$ to bus 1". It will change the bus of $g_1$ and assign it to bus 1.

* NB Another breaking change compared to the pypownet implementation is the introduction of "ambiguous" action. When a powerline is disconneted, it is not connected to any bus (by definition). So if you reconnect it without specifying on which "bus" it's "ambiguous". This action will not be implemented and the episode will terminate. More on this concept later.

The previous actions are equivalent to:

  • $a_1 \to$ set status of $l_1$ to "disconnected"
  • $a_2 \to$ set status of $l_3$ to "connected"
  • $a_3 \to$ do nothing
  • $a_4 \to$ change bus of $g_1$

I.B) "ambiguous" action

Some actions are "ambiguous" it means that they cannot be properly and / or univocally interpretaded. These actions will raise an "AmbiguousAction" exception if attempted to be used on the powergrid. This will immediately terminate the episode.

For a detailed list of ambiguous actions, the documentation is the only official sources. Are presented here only some example. The documentation is available at _check_for_ambiguity.

An action can be ambiguous in the following context:

  • It affects the "injections" in an incorrect way:

    • it tries to modify a load (setting active or reactive values) that doesn't exist on the powergrid
    • it sets the values of a generator that doesn't exist (setting its voltage setpoint or active production)
  • It affects the "powerlines" in an incorrect manner:

    • it tries to change the status or to assign to a specific bus a powerline that doesn't exist
    • somes lines are reconnected bus the action doesn't specify on which bus.
    • the same action tries to changed and set the status of a powerline
  • It has an ambiguous behaviour concerning the topology of some substations

    • the same action tries to affect with changed and set the bus of a given object.
    • the bus is trying to be modified (set or changed) on a object not present on the powergrid

II) Action Helper / action space

IMPORTANT NOTICE Each Agent has its own 'action helper' attribute that can be called by self.action_space. This is the only recommended way to create a valid Action. Using its constructor is strongly NOT recommended, as it requires a deep knowledge of all the elements in the powergrid, as well as their names, their type, the order in which they are used in the backend etc. For performance reasons, no sanity check are performed to make sure the would be created action this way is compatible with the backend.

In the next cell, we retrieve the action space used by the Agent.

2 main classes are usefull when dealing with Action in Grid2Op. The Action class is the most basic one. The ActionHelper is a tool that helps create and manipulate some actions.

As in most of our notebooks, we start by creating an Environment. We will use the case14_fromfile provided as an example. We will then extract the complete action space (action_space) that is possible to perform on the power grid as a dictionary. When a specific action such as change or set is needed to be performed then we can apply this change to the action_space dictionary by accessing the relevant key in it as discussed below.

In [3]:
# import the usefull class
env = grid2op.make(test=True)
action_space = env.action_space
/home/tezirg/Code/Grid2Op.BDonnot/getting_started/grid2op/MakeEnv/Make.py:223: UserWarning: You are using a development environment. This environment is not intended for training agents.
  warnings.warn(_MAKE_DEV_ENV_WARN)

As opposed to the previous plateform, pypownet, Grid2Op doesn't restrict anything on the type of Action. Generally speaking, an Action can modify production, loads, topology etc. By default though, an Action that an Agent can performed is a TopologyAction, a specific type restricting it's usage to:

  • change the status of the powerline (reconnect / disconnect) them
  • change the way the objects (end of a powerline, generator or load) are interconnected at substations.

We will focus on this class in this notebook.

Then best way to get an action is to give a dictionnary to the "action space" of the player. For example, to get the "do nothing" action, you can just pass the empty dictionnary.

In [4]:
do_nothing = action_space({})

II.A) line status modification

a) modify multiple powerlines

If you want to change (or set) the status of most of the powerlines, you can create a vector having the same size as the number of powerlines of the grid, and pass it to the dictionnary with relevant keys "set_line_status", "change_line_status" and its values "set_status", "change_status" respectively.

The following code will:

  • change the status of powerlines with id 0,1,2
  • set the status "connected" for powerline with id 3,4
  • set the status "disconnected" for powerlines with id 5 and 6
In [5]:
change_status = action_space.get_change_line_status_vect()
change_status[0] = True
change_status[1] = True
change_status[2] = True

set_status = action_space.get_set_line_status_vect()
set_status[3] = 1
set_status[4] = 1
set_status[5] = -1
set_status[6] = -1

this_first_act = action_space({"set_line_status": set_status, "change_line_status": change_status})

NB even if it can handles different type, for performance reason it's better to follow the type of data mentionned bellow. Note also that the data will be interpreted as:

  • for change having a boolean vector
    • True meaning "change"
    • False meaning "don't change"
  • for set it's an integer vector with:
    • 0 meaning "do nothing"
    • 1 meaning "connect it"
    • -1 meaning "disconnect it"

For convenience reason, an Action object can be easily inspected by using the "print" method. It will summarize on which object it has an impact:

In [6]:
print(this_first_act)
This action will:
	 - NOT change anything to the injections
	 - NOT perform any redispatching action
	 - force reconnection of 2 powerlines ([3 4])
	 - force disconnection of 2 powerlines ([5 6])
	 - switch status of 3 powerlines ([0 1 2])
	 - NOT switch anything in the topology
	 - NOT force any particular bus configuration
In [7]:
this_first_act.is_ambiguous()
Out[7]:
(True,
 Grid2OpException AmbiguousAction InvalidLineStatus InvalidLineStatus("You ask to reconnect powerline 3 yet didn't tell on which bus.",))

NB this action is ambiguous so it cannot be implemented on the powergrid. Indeed, powerlines 3 and 4 are reconnected, but we don't specify on which bus! Implementing this action on a grid will be equivalent to doing nothing.

b) modify multiple powerlines at the same time

It's not always convenient to manipulate all the status of all the powerlines, or change it. Fore mor convenience, it's possible to modify only a few of them. The syntax is the following.

In [8]:
the_same_act = action_space({"set_line_status": [(3,1), (4,1), (5,-1), (6,-1)],
                             "change_line_status": [0,1,2]
                            })
print(the_same_act)
This action will:
	 - NOT change anything to the injections
	 - NOT perform any redispatching action
	 - force reconnection of 2 powerlines ([3 4])
	 - force disconnection of 2 powerlines ([5 6])
	 - switch status of 3 powerlines ([0 1 2])
	 - NOT switch anything in the topology
	 - NOT force any particular bus configuration

We can check that the two actions are indeed equal:

In [9]:
the_same_act == this_first_act
Out[9]:
True

II.B) substations reconfiguration / topology changes

One of the interesting aspect of Grid2Op is to be able to modify the topology of the powergrid. In other words it allows to reconfigure the way the objects (generator, load, end of powerlines) are interconnected at their substation.

Comparable to the status change, topological change can be interpreted in two disctincts manners, as described above. The most interesting interactions

In this section we study how to modify the topology of the powergrid.

The underlying way to represent the topology is through a integer vector, having the same dimension as the number of objects of the grid, and for each objects it says one which bus it's connected. Manipulating this vector can be done, but is absolutely not handy. We present here the way to use the helper to change this topology more easily.

To set the bus to which a load is connected, it is recommended to do:

In [10]:
set_bus_load_0 = action_space({"set_bus": {"loads_id": [(0,2)]}})
print(set_bus_load_0)
This action will:
	 - NOT change anything to the injections
	 - NOT perform any redispatching action
	 - NOT force any line status
	 - NOT switch any line status
	 - NOT switch anything in the topology
	 - Set the bus of the following element:
	 	 - assign bus 2 to load 0 [on substation 1]

To change the bus to which a generator is connected, it is recommended to do:

To change the bus a similar interface can be used:

In [11]:
change_bus_load_0 = action_space({"change_bus": {"loads_id": [0]}})
print(change_bus_load_0)
This action will:
	 - NOT change anything to the injections
	 - NOT perform any redispatching action
	 - NOT force any line status
	 - NOT switch any line status
	 - Change the bus of the following element:
	 	 - switch bus of load 0 [on substation 1]
	 - NOT force any particular bus configuration

The API is really similar for generator:

In [12]:
change_bus_gen_0_and_1 = action_space({"change_bus": {"generators_id": [0,1]}})
set_bus_gen_3_and_4 = action_space({"set_bus": {"generators_id": [(3,2), (4,2)]}})
print(set_bus_gen_3_and_4)
This action will:
	 - NOT change anything to the injections
	 - NOT perform any redispatching action
	 - NOT force any line status
	 - NOT switch any line status
	 - NOT switch anything in the topology
	 - Set the bus of the following element:
	 	 - assign bus 2 to generator 4 [on substation 0]
	 	 - assign bus 2 to generator 3 [on substation 7]

It follows the same mechanism for each ends of the powerlines:

In [13]:
change_bus_lines_or_0 = action_space({"change_bus": {"lines_or_id": [0]}})
set_bus_lines_or_4 = action_space({"set_bus": {"lines_or_id": [(3,2)]}})
change_bus_lines_ex_15 = action_space({"change_bus": {"lines_ex_id": [15]}})
set_bus_lines_ex_18 = action_space({"set_bus": {"lines_ex_id": [(18,2)]}})
print(set_bus_lines_ex_18)
This action will:
	 - NOT change anything to the injections
	 - NOT perform any redispatching action
	 - NOT force any line status
	 - NOT switch any line status
	 - NOT switch anything in the topology
	 - Set the bus of the following element:
	 	 - assign bus 2 to line (extremity) 18 [on substation 7]

When reconnecting a powerline, if the bus to which this powerline is reconnected are not specified, the action is ambiguous and thus will not be implemented. It is, in that case, recommended to use the reconnect_powerline method as followed:

In [14]:
reconnecting_line_1 = action_space.reconnect_powerline(line_id=1,bus_or=1,bus_ex=1)
print(reconnecting_line_1)
This action will:
	 - NOT change anything to the injections
	 - NOT perform any redispatching action
	 - force reconnection of 1 powerlines ([1])
	 - NOT switch any line status
	 - NOT switch anything in the topology
	 - Set the bus of the following element:
	 	 - assign bus 1 to line (origin) 1 [on substation 0]
	 	 - assign bus 1 to line (extremity) 1 [on substation 4]

II.C) substations reconfiguration / topology changes

For convenience, it might be better sometimes to use the name of some object to change their bus in case the ID's are not known. Grid2Op allows to do that, only for changing or setting a bus. This method takes longer than the methods showed above. If they are used at all, it's recommended NOT to use them for training an Agent. Their main goal aims at debugging and / or understanding the behaviour of an Agent.

These methods are:

Please refer to the official documentation for a complete detail of their behaviour. To sum up, we can use them this way:

In [15]:
my_act = action_space.set_bus("gen_1_0", # mandatory name of the element
                                 new_bus=2, # mandatory the new bus to connect it too
                                 type_element="gen", # optional the type of the element, one of "line", "gen" or "load"
                                previous_action=None  # optional: if you want to combine multiple action, you can do it with this
                                )
print(my_act)
This action will:
	 - NOT change anything to the injections
	 - NOT perform any redispatching action
	 - NOT force any line status
	 - NOT switch any line status
	 - NOT switch anything in the topology
	 - Set the bus of the following element:
	 	 - assign bus 2 to generator 0 [on substation 1]
In [16]:
action_space.set_bus("1_3_3", # mandatory name of the element
                              extremity="or", # mandatory, which extrmity to change
                                 new_bus=2, # mandatory the new bus to connect it too
                                 type_element="line", # optional the type of the element, one of "line", "gen" or "load"
                                previous_action=my_act  # optional: if you want to combine multiple action, you can do it with this
                                )
print(my_act)
This action will:
	 - NOT change anything to the injections
	 - NOT perform any redispatching action
	 - NOT force any line status
	 - NOT switch any line status
	 - NOT switch anything in the topology
	 - Set the bus of the following element:
	 	 - assign bus 2 to line (origin) 3 [on substation 1]
	 	 - assign bus 2 to generator 0 [on substation 1]

III) Manipulating Action

It is absolutely NOT recommended to use Actions outside of the action space.