Observation

This page is organized as follow:

Objectives

In a “reinforcement learning” framework, an grid2op.Agent receive two information before taking any action on the grid2op.Environment.Environment. One of them is the grid2op.Reward.BaseReward that tells it how well the past action performed. The second main input received from the environment is the BaseObservation. This is gives the BaseAgent partial, noisy, or complete information about the current state of the environment. This module implement a generic BaseObservation class and an example of a complete observation in the case of the Learning To Run a Power Network (l2RPN ) competition.

Compared to other Reinforcement Learning problems the L2PRN competition allows another flexibility. Today, when operating a powergrid, operators have “forecasts” at their disposal. We wanted to make them available in the L2PRN competition too. In the first edition of the L2PRN competition, was offered the functionality to simulate the effect of an action on a forecasted powergrid. This forecasted powergrid used:

  • the topology of the powergrid of the last know time step

  • all the injections of given in files.

This functionality was originally attached to the Environment and could only be used to simulate the effect of an action on this unique time step. We wanted in this recoding to change that:

  • in an RL setting, an grid2op.Agent.BaseAgent should not be able to look directly at the grid2op.Environment.Environment. The only information about the Environment the BaseAgent should have is through the grid2op.Observation.BaseObservation and the grid2op.Reward.BaseReward. Having this principle implemented will help enforcing this principle.

  • In some wider context, it is relevant to have these forecasts available in multiple way, or modified by the grid2op.Agent.BaseAgent itself (for example having forecast available for the next 2 or 3 hours, with the Agent able not only to change the topology of the powergrid with actions, but also the injections if he’s able to provide more accurate predictions for example.

The BaseObservation class implement the two above principles and is more flexible to other kind of forecasts, or other methods to build a power grid based on the forecasts of injections.

Main observation attributes

In general, observations have the following attributes (if an attributes has name XXX [eg rho] it can be accessed with obs.XXX [eg obs.rho])

Name(s)

Type

Size (each)

year, month, day, hour_of_day, minute_of_hour, day_of_week

int

1

gen_p, gen_q, gen_v

float

n_gen

load_p, load_q, load_v

float

n_load

p_or, q_or, v_or, a_or

float

n_line

p_ex, q_ex, v_ex, a_ex

float

n_line

rho

float

n_line

topo_vect

int

dim_topo

line_status

bool

n_line

timestep_overflow

int

n_line

time_before_cooldown_line

int

n_line

time_before_cooldown_sub

int

n_sub

time_next_maintenance

int

n_line

duration_next_maintenance

int

n_line

target_dispatch

float

n_gen

actual_dispatch

float

n_gen

storage_charge

float

n_storage

storage_power_target

float

n_storage

storage_power

float

n_storage

gen_p_before_curtail

float

n_gen

curtailment, curtailment_limit

float

n_gen

is_alarm_illegal

bool

1

time_since_last_alarm

int

1

last_alarm

int

dim_alarms

attention_budget

int

1

max_step , current_step

int

1

(NB for concision, if a coma (“,”) is present in the “Name(s)” part of the column, it means multiple attributes are present. If we take the example of the first row, it means that obs.year, obs.month, etc. are all valid attributes of the observation, they are all integers and each is of size 1.)

But where is the graph ?

A powergrid can be represented as (at least) a graph (here: a mathematical object with nodes / vertices are connected by edges).

Grid2op is made in a way that the observation and action do not explicitly represents such graph. This is motivated first by performance reasons, but also because multiple “graphs” can represent equally well a powergrid.

The first one that come to mind is the graph where the nodes / vertices are the buses and the edges are the powerline. We will call this graph the “bus graph”. It can be accessed in grid2op using the grid2op.Observation.BaseObservation.bus_connectivity_matrix() for example. This will return a matrix with 1 when 2 buses are connected and 0 otherwise, with the convention that a bus is always connected to itself. You can think of the environments in grid2op as an environment that allows you to manipulate this graph: split some bus in sub buses by changing at which busbar some elements are connected, or removing some edges from this graph when powerlines are connected / disconnected. An important feature of this graph is that its size changes: it can have a different number of nodes at different steps!

Some methods allow to retrieve these graphs, for example:

For more information, you can consult the A grid, a graph: grid2op representation of the powergrid page.

Detailed Documentation by class

Classes:

BaseObservation([obs_env, action_helper, seed])

Basic class representing an observation.

CompleteObservation([obs_env, …])

This class represent a complete observation, where everything on the powergrid can be observed without any noise.

ObservationSpace(gridobj, env[, …])

Helper that provides useful functions to manipulate BaseObservation.

class grid2op.Observation.BaseObservation(obs_env=None, action_helper=None, seed=None)[source]

Basic class representing an observation.

All observation must derive from this class and implement all its abstract methods.

action_helper

A representation of the possible action space.

Type

grid2op.Action.ActionSpace

year

The current year

Type

int

month

The current month (1 = january, 12 = december)

Type

int

day

The current day of the month (1 = first day of the month)

Type

int

hour_of_day

The current hour of the day (from O to 23)

Type

int

minute_of_hour

The current minute of the current hour (from 0 to 59)

Type

int

day_of_week

The current day of the week (monday = 0 and sunday = 6)

Type

int

gen_p

The active production value of each generator (expressed in MW). (the old name “prod_p” is still usable)

Type

numpy.ndarray, dtype:float

gen_q

The reactive production value of each generator (expressed in MVar). (the old name “prod_q” is still usable)

Type

numpy.ndarray, dtype:float

gen_v

The voltage magnitude of the bus to which each generator is connected (expressed in kV). (the old name “prod_v” is still usable)

Type

numpy.ndarray, dtype:float

load_p

The active load value of each consumption (expressed in MW).

Type

numpy.ndarray, dtype:float

load_q

The reactive load value of each consumption (expressed in MVar).

Type

numpy.ndarray, dtype:float

load_v

The voltage magnitude of the bus to which each consumption is connected (expressed in kV).

Type

numpy.ndarray, dtype:float

p_or

The active power flow at the origin end of each powerline (expressed in MW).

Type

numpy.ndarray, dtype:float

q_or

The reactive power flow at the origin end of each powerline (expressed in MVar).

Type

numpy.ndarray, dtype:float

v_or

The voltage magnitude at the bus to which the origin end of each powerline is connected (expressed in kV).

Type

numpy.ndarray, dtype:float

a_or

The current flow at the origin end of each powerline (expressed in A).

Type

numpy.ndarray, dtype:float

p_ex

The active power flow at the extremity end of each powerline (expressed in MW).

Type

numpy.ndarray, dtype:float

q_ex

The reactive power flow at the extremity end of each powerline (expressed in MVar).

Type

numpy.ndarray, dtype:float

v_ex

The voltage magnitude at the bus to which the extremity end of each powerline is connected (expressed in kV).

Type

numpy.ndarray, dtype:float

a_ex

The current flow at the extremity end of each powerline (expressed in A).

Type

numpy.ndarray, dtype:float

rho

The capacity of each powerline. It is defined at the observed current flow divided by the thermal limit of each powerline (no unit)

Type

numpy.ndarray, dtype:float

topo_vect

For each object (load, generator, ends of a powerline) it gives on which bus this object is connected in its substation. See grid2op.Backend.Backend.get_topo_vect() for more information.

Type

numpy.ndarray, dtype:int

line_status

Gives the status (connected / disconnected) for every powerline (True at position i means the powerline i is connected)

Type

numpy.ndarray, dtype:bool

timestep_overflow

Gives the number of time steps since a powerline is in overflow.

Type

numpy.ndarray, dtype:int

time_before_cooldown_line

For each powerline, it gives the number of time step the powerline is unavailable due to “cooldown” (see grid2op.Parameters.NB_TIMESTEP_COOLDOWN_LINE for more information). 0 means the an action will be able to act on this same powerline, a number > 0 (eg 1) means that an action at this time step cannot act on this powerline (in the example the agent have to wait 1 time step)

Type

numpy.ndarray, dtype:int

time_before_cooldown_sub

Same as BaseObservation.time_before_cooldown_line but for substations. For each substation, it gives the number of timesteps to wait before acting on this substation (see see grid2op.Parameters.NB_TIMESTEP_COOLDOWN_SUB for more information).

Type

numpy.ndarray, dtype:int

time_next_maintenance

For each powerline, it gives the time of the next planned maintenance. For example if there is:

  • 1 at position i it means that the powerline i will be disconnected for maintenance operation at the next time step.

  • 0 at position i means that powerline i is disconnected from the powergrid for maintenance operation at the current time step.

  • -1 at position i means that powerline i will not be disconnected for maintenance reason for this episode.

  • k > 1 at position i it means that the powerline i will be disconnected for maintenance operation at in k time steps

When a powerline is “in maintenance”, it cannot be reconnected by the Agent before the end of this maintenance.

Type

numpy.ndarray, dtype:int

duration_next_maintenance

For each powerline, it gives the number of time step that the maintenance will last (if any). This means that, if at position i of this vector:

  • there is a 0: the powerline is not disconnected from the grid for maintenance

  • there is a 1, 2, … the powerline will be disconnected for at least 1, 2, … timestep (NB in all case, the powerline will stay disconnected until a grid2op.BaseAgent.BaseAgent performs the proper grid2op.BaseAction.BaseAction to reconnect it).

When a powerline is “in maintenance”, it cannot be reconnected by the Agent before the end of this maintenance.

Type

numpy.ndarray, dtype:int

target_dispatch

For each generators, it gives the target redispatching, asked by the agent. This is the sum of all redispatching asked by the agent for during all the episode. It for each generator it is a number between: - pmax and pmax. Note that there is information about all generators there, even the one that are not dispatchable.

Type

numpy.ndarray, dtype:float

actual_dispatch

For each generators, it gives the redispatching currently implemented by the environment. Indeed, the environment tries to implement at best the BaseObservation.target_dispatch, but sometimes, due to physical limitation (pmin, pmax, ramp min and ramp max) it cannot. In this case, only the best possible redispatching is implemented at the current time step, and this is what this vector stores. Note that there is information about all generators there, even the one that are not dispatchable.

Type

numpy.ndarray, dtype:float

storage_charge

The actual ‘state of charge’ of each storage unit, expressed in MWh.

Type

numpy.ndarray, dtype:float

storage_power_target

For each storage units, give the setpoint of production / consumption as given by the agent

Type

numpy.ndarray, dtype:float

storage_power

Give the actual storage production / loads at the given state.

Type

numpy.ndarray, dtype:float

gen_p_before_curtail

Give the production of renewable generator there would have been if no curtailment were applied (NB it returns 0.0 for non renewable generators that cannot be curtailed)

Type

numpy.ndarray, dtype:float

curtailment

Give the actual curtailment setpoint for generator using renewable energy sources (1.0 means no curtailment). This is the results of all curtailment actions applied up to the

Type

numpy.ndarray, dtype:float

curtailment_limit

Limit (in ratio of gen_pmax) imposed on each renewable generator.

Type

numpy.ndarray, dtype:float

current_step

Current number of step performed up until this observation (NB this is not given in the observation if it is transformed into a vector)

Type

int

max_step

Maximum number of steps possible for this episode

Type

int

is_alarm_illegal

whether the last alarm has been illegal (due to budget constraint). It can only be True if an alarm was raised by the agent on the previous step. Otherwise it is always False

Type

bool

time_since_last_alarm

Number of steps since the last successful alarm has been raised. It is -1 if no alarm has been raised yet.

Type

int

last_alarm

For each zones, gives how many steps since the last alarm was raised successfully for this zone

Type

numpy.ndarray, dtype:int

attention_budget

The current attention budget

Type

int

was_alarm_used_after_game_over

Was the last alarm used to compute anything related to the attention budget when there was a game over (can only be set to True if the observation corresponds to a game over, but not necessarily)

Type

bool

_shunt_p

Shunt active value (only available if shunts are available) (in MW)

Type

numpy.ndarray, dtype:float

_shunt_q

Shunt reactive value (only available if shunts are available) (in MVAr)

Type

numpy.ndarray, dtype:float

_shunt_v

Shunt voltage (only available if shunts are available) (in kV)

Type

numpy.ndarray, dtype:float

_shunt_bus

Bus (-1 disconnected, 1 for bus 1, 2 for bus 2) at which each shunt is connected (only available if shunts are available)

Type

numpy.ndarray, dtype:float

Methods:

__eq__

Return self==value.

__init__

Initialize self.

copy

Generic (shallow and deep) copying operations.

Attributes:

__eq__(other)[source]

INTERNAL

Warning

/!\ Internal, do not use unless you know what you are doing /!\

Test the equality of two observations.

2 actions are said to be identical if the have the same impact on the powergrid. This is unlrelated to their respective class. For example, if an BaseAction is of class BaseAction and doesn’t act on the _injection, it can be equal to a an BaseAction of derived class TopologyAction (if the topological modification are the same of course).

This implies that the attributes BaseAction.authorized_keys is not checked in this method.

Note that if 2 actions doesn’t act on the same powergrid, or on the same backend (eg number of loads, or generators is not the same in self and other, or they are not in the same order) then action will be declared as different.

Known issue if two backend are different, but the description of the _grid are identical (ie all n_gen, n_load, n_line, sub_info, dim_topo, all vectors *_to_subid, and *_pos_topo_vect are identical) then this method will not detect the backend are different, and the action could be declared as identical. For now, this is only a theoretical behaviour: if everything is the same, then probably, up to the naming convention, then the powergrid are identical too.

Parameters

other (BaseObservation) – An instance of class BaseAction to which “self” will be compared.

Returns

Return type

True if the action are equal, False otherwise.

__init__(obs_env=None, action_helper=None, seed=None)[source]
__sub__(other)[source]

computes the difference between two observation, and return an observation corresponding to this difference.

This can be used to easily plot the difference between two observations at different step for example.

add_act(act, issue_warn=True)[source]

Easier access to the impact on the observation if an action were applied.

This is for now only useful to get a topology in which the grid would be without doing an expensive obs.simuulate

Notes

This will not give the real topology of the grid in all cases for many reasons amongst:

  1. past topologies are not known by the observation. If you reconnect a powerline in the action without having specified on which bus, it has no way to know (but the environment does!) on which bus it should be reconnected (which is the last known bus)

  2. some “protections” are emulated in the environment. This means that the environment can disconnect some powerline under certain conditions. This is absolutely not taken into account here.

  3. the environment is stochastic, for example there can be maintenance or attacks (hazards) and the generators and loads change each step. This is not taken into account in this function.

  4. no checks are performed to see if the action meets the rules of the game (number of elements you can modify in the action, cooldowns etc.) This method supposes that the action is legal and non ambiguous.

  5. It do not check for possible “game over”, for example due to isolated elements or non-connected grid (grid with 2 or more connex components)

If these issues are important for you, you will need to use the grid2op.Observation.BaseObservation.simulate() method. It can be used like obs.simulate(act, time_step=0) but it is much more expensive.

Parameters
  • act (grid2op.Action.BaseAction) – The action you want to add to the observation

  • issue_warn (bool) – Issue a warning when this method might not compute the proper resulting topologies. Default to True: it issues warning when something not supported is done in the action.

Returns

res – The resulting observation. Note that this observation is not initialized with everything. It is only relevant when you want to study the resulting topology after you applied an action. Lots of res attributes are empty.

Return type

grid2op.Observation.Observation

Examples

You can use it this way, for example if you want to retrieve the topology you would get (see the restriction in the above description) after applying an action:

import grid2op

# create the environment
env_name = ...
env = grid2op.make(env_name)

# generate the first observation
obs = env.reset()

# make some action
act = ...  # see the dedicated page

# have a look at the impact on the action on the topology
partial_obs = obs + act
# or `partial_obs = obs.add_act(act, issue_warn=False)` if you want to silence the warnings

# and now you can inspect the topology with any method you want:
partial_obs.topo_vect
partial_obs.load_bus
bus_mat = partial_obs.bus_connectivity_matrix()
# or even
elem_mat = partial_obs.connectivity_matrix()

# but you cannot use
partial_obs.prod_p
# or
partial_obs.load_q
etc.
as_networkx()[source]

Convert this observation as a networkx graph.

Notes

The resulting graph is “frozen” this means that you cannot add / remove attribute on nodes or edges, nor add / remove edges or nodes.

This graphs has the following properties:

  • it counts as many nodes as the number of buses of the grid

  • it counts less edges than the number of lines of the grid (two lines connecting the same buses are “merged” into one single edge - this is the case for parallel line, that are hence “merged” into the same edge)

  • nodes have attributes:

    • p: the active power produced at this node (negative means the sum of power produce minus power absorbed is negative)

    • q: the reactive power produced at this node

    • v: the voltage magnitude at this node

    • cooldown: how much longer you need to wait before being able to merge / split or change this node

  • edges have attributes too:

    • rho: the relative flow on this powerline

    • cooldown: the number of step you need to wait before being able to act on this powerline

    • status: whether this powerline is connected or not

    • thermal_limit: maximum flow allowed on the the powerline (this is the “a_or” flow)

    • timestep_overflow: number of time steps during which the powerline is on overflow

    • p_or: active power injected at this node at the “origin side”.

    • p_ex: active power injected at this node at the “extremity side”.

    • q_or: reactive power injected at this node at the “origin side”.

    • q_ex: reactive power injected at this node at the “extremity side”.

    • a_or: current flow injected at this node at the “origin side”.

    • a_ex: current flow injected at this node at the “extremity side”.

Danger

IMPORTANT NOTE the “origin” and “extremity” of the networkx graph is not necessarily the same as the one in grid2op. The “origin” side will always be the nodes with the lowest id. For example, if an edges connects the bus 6 to the bus 8, then the “origin” of this powerline is bus 6 (eg the active power injected at node 6 from this edge will be p_or) and the “extremity” side is bus 8 (eg the active power injectioned at node 8 from this edge will be p_ex).

Note

The graph returned by this function is “frozen” to prevent its modification. If you really want to modify it you can

Returns

graph – A possible representation of the observation as a networkx graph

Return type

networkx graph

Examples

The following code explains how to check that a grid meet the kirchoffs law (conservation of energy)

# create an environment and get the observation
import grid2op
env_name = ...
env = grid2op.make(env_name)
obs = env.reset()

# retrieve the networkx graph
graph = obs.as_networkx()

# perform the check for every nodes
for node_id in graph.nodes:
    # retrieve power (active and reactive) produced at this node
    p_ = graph.nodes[node_id]["p"]
    q_ = graph.nodes[node_id]["q"]

    # get the edges
    edges = graph.edges(node_id)
    p_lines = 0
    q_lines = 0
    # get the power that is "evacuated" at each nodes on all the edges connecting it to the other nodes
    # of the network
    for (k1, k2) in edges:
        # now retrieve the active / reactive power injected at this node (looking at either *_or or *_ex
        # depending on the direction of the powerline: remember that the "origin" is always the lowest
        # bus id.
        if k1 < k2:
            # the current inspected node is the lowest, so on the "origin" side
            p_lines += graph.edges[(k1, k2)]["p_or"]
            q_lines += graph.edges[(k1, k2)]["q_or"]
        else:
            # the current node is the largest, so on the "extremity" side
            p_lines += graph.edges[(k1, k2)]["p_ex"]
            q_lines += graph.edges[(k1, k2)]["q_ex"]
    assert abs(p_line - p_) <= 1e-5, "error for kirchoff's law for graph for P"
    assert abs(q_line - q_) <= 1e-5, "error for kirchoff's law for graph for Q"
bus_connectivity_matrix(as_csr_matrix=False, return_lines_index=False)[source]

If we denote by nb_bus the total number bus of the powergrid (you can think of a “bus” being a “node” if you represent a powergrid as a graph [mathematical object, not a plot] with the lines being the “edges”].

The bus_connectivity_matrix will have a size nb_bus, nb_bus and will be made of 0 and 1.

If bus_connectivity_matrix[i,j] = 1 then at least a power line connects bus i and bus j. Otherwise, nothing connects it.

Parameters
  • as_csr_matrix (bool) – Whether to return the bus connectivity matrix as a sparse matrix (csr format) or as a dense matrix. By default it’s False meaning a dense matrix is returned.

  • return_lines_index (bool) – Whether to also return the bus index associated to both side of each powerline.

Returns

res – The bus connectivity matrix defined above.

Return type

numpy.ndarray, shape: (nb_bus, nb_bus) dtype:float

Notes

By convention we say that a bus is connected to itself. So the diagonal of this matrix is 1.

Examples

Here is how you can use this function:

bus_bus_graph, (line_or_bus, line_ex_bus) = obs.bus_connectivity_matrix(return_lines_index=True)

# bus_bus_graph is the matrix described above.
# line_or_bus[0] give the id of the bus to which the origin side of powerline 0 is connected
# line_ex_bus[0] give the id of the bus to which the extremity side of powerline 0 is connected
# (NB: if the powerline is disconnected, both are -1)
# this means that if line 0 is connected: bus_bus_graph[line_or_bus[0], line_ex_bus[0]] = 1
# and bus_bus_graph[line_ex_bus[0], line_or_bus[0]] = 1
# (of course you can replace 0 with any integer `0 <= l_id < obs.n_line`
connectivity_matrix(as_csr_matrix=False)[source]

Computes and return the “connectivity matrix” con_mat. Let “dim_topo := 2 * n_line + n_prod + n_conso + n_storage” (the total number of elements on the grid)

It is a matrix of size dim_topo, dim_topo, with values 0 or 1. For two objects (lines extremity, generator unit, load) i,j :

  • if i and j are connected on the same substation:
    • if conn_mat[i,j] = 0 it means the objects id’ed i and j are not connected to the same bus.

    • if conn_mat[i,j] = 1 it means the objects id’ed i and j are connected to the same bus

  • if i and j are not connected on the same substation then`conn_mat[i,j] = 0` except if i and j are the two extremities of the same power line, in this case conn_mat[i,j] = 1 (if the powerline is in service or 0 otherwise).

By definition, the diagonal is made of 0.

Returns

res – The connectivity matrix, as defined above

Return type

numpy.ndarray, shape:dim_topo,dim_topo, dtype:float

Notes

Matrix can be either a sparse matrix or a dense matrix depending on the argument as_csr_matrix

An object, is not disconnected, is always connected to itself.

Examples

If you want to know if powerline 0 is connected at its “extremity” side with the load of id 0 you can do

import grid2op
env = grid2op.make()
obs = env.reset()

# retrieve the id of extremity of powerline 1:
id_lineex_0 = obs.line_ex_pos_topo_vect[0]
id_load_1 = obs.load_pos_topo_vect[0]

# get the connectivity matrix
connectivity_matrix = obs.connectivity_matrix()

# know if the objects are connected or not
are_connected = connectivity_matrix[id_lineex_0, id_load_1]
# as `are_connected` is 1.0 then these objects are indeed connected

And now, supposes we do an action that changes the topology of the substation to which these two objects are connected, then we get (same example continues)

topo_action = env.action_space({"set_bus": {"substations_id": [(1, [1,1,1,2,2,2])]}})
print(topo_action)
# 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 1 to line (extremity) 0 [on substation 1]
#     - assign bus 1 to line (origin) 2 [on substation 1]
#     - assign bus 1 to line (origin) 3 [on substation 1]
#     - assign bus 2 to line (origin) 4 [on substation 1]
#     - assign bus 2 to generator 0 [on substation 1]
#     - assign bus 2 to load 0 [on substation 1]

obs, reward, done, info = env.step(topo_action)
# and now retrieve the matrix
connectivity_matrix = obs.connectivity_matrix()

# know if the objects are connected or not
are_connected = connectivity_matrix[id_lineex_0, id_load_1]
# as `are_connected` is 0.0 then these objects are not connected anymore
# this is visible when you "print" the action (see above) in the two following lines:
#     - assign bus 1 to line (extremity) 0 [on substation 1]
#     - assign bus 2 to load 0 [on substation 1]
# -> one of them is on bus 1 [line (extremity) 0] and the other on bus 2 [load 0]
copy()[source]

INTERNAL

Warning

/!\ Internal, do not use unless you know what you are doing /!\

Make a copy of the observation.

Returns

res – The deep copy of the observation

Return type

BaseObservation

Notes

The “obs_env” attributes

property curtailment_limit_mw

return the limit of production of a generator in MW rather in ratio

Examples

import grid2op
env_name = ...
env = grid2op.make(env_name)

obs = env.reset()
curtailment_limit_mw = obs.curtailment_limit_mw
property curtailment_mw

return the curtailment, expressed in MW rather than in ratio of pmax.

Examples

import grid2op
env_name = ...
env = grid2op.make(env_name)

obs = env.reset()
curtailment_mw = obs.curtailment_mw
flow_bus_matrix(active_flow=True, as_csr_matrix=False)[source]

A matrix of size “nb bus” “nb bus”. Each row and columns represent a “bus” of the grid (“bus” is a power system word that for computer scientist means “nodes” if the powergrid is represented as a graph)

The diagonal will sum the power produced and consumed at each bus.

The other element of each row of this matrix will be the flow of power from the bus represented by the line i to the bus represented by column j.

Parameters
  • active_flow (bool) – Whether to get the active flow (in MW) or the reactive flow (in MVAr). Defaults to active flow.

  • as_csr_matrix (bool) – Whether to retrieve the results as a scipy csr sparse matrix or as a dense matrix (default)

Returns

  • res (matrix) – Which can either be a sparse matrix or a dense matrix depending on the value of the argument “as_csr_matrix”.

  • mappings (tuple) – The mapping that makes the correspondence between each object and the bus to which it is connected. It is made of 4 elements: (load_bus, prod_bus, lor_bus, lex_bus).

    For example if load_bus[i] = 14 it means that the load with id i is connected to the bus 14. If load_bus[i] = -1 then the object is disconnected.

Examples

Here is how you can use this function:

flow_mat, (load, prod, stor, ind_lor, ind_lex) = obs.flow_bus_matrix()

# flow_mat is the matrix described above.

Lots of information can be deduce from this matrix. For example if you want to know how much power goes from one bus say bus i to another bus (say bus j ) you can look at the associated coefficient flow_mat[i,j] which will also be related to the flow on the origin (or extremity) side of the powerline connecting bus i to bus j

You can also know how much power (total generation + total storage discharging - total load - total storage charging - ) is injected at each bus i by looking at the i th diagonal coefficient.

Another use would be to check if the current powergrid state (as seen by grid2op) meet the Kirchhoff circuit laws (conservation of energy), by doing the sum (row by row) of this matrix. flow_mat.sum(axis=1)

from_vect(vect, check_legit=True)[source]

INTERNAL

Warning

/!\ Internal, do not use unless you know what you are doing /!\

To reload an observation from a vector, use the “env.observation_space.from_vect()”.

Convert back an observation represented as a vector into a proper observation.

Some conversion are done silently from float to the type of the corresponding observation attribute.

Parameters

vect (numpy.ndarray) – A representation of an BaseObservation in the form of a vector that is used to convert back the current observation to be equal to the vect.

property gen_bus

Retrieve the busbar at which each generator is connected.

The result follow grid2op convention:

  • -1 means the generator is disconnected

  • 1 means it is generator to busbar 1

  • 2 means it is connected to busbar 2

  • etc.

Notes

In a same substation, two objects are connected together if (and only if) they are connected to the same busbar.

get_forecasted_inj(time_step=1)[source]

This function allows you to retrieve directly the “forecast” injections for the step time_step.

We remind that the environment, under some conditions, can produce these forecasts automatically. This function allows to retrieve what has been forecast.

Parameters

time_step (int) – The horizon of the forecast (given in number of time steps)

Returns

  • gen_p_f (numpy.ndarray) – The forecast generators active values

  • gen_v_f (numpy.ndarray) – The forecast generators voltage setpoins

  • load_p_f (numpy.ndarray) – The forecast load active consumption

  • load_q_f (numpy.ndarray) – The forecast load reactive consumption

get_time_stamp()[source]

Get the time stamp of the current observation as a datetime.datetime object

property line_ex_bus

Retrieve the busbar at which each extremity end of powerline is connected.

The result follow grid2op convention:

  • -1 means the powerline is disconnected

  • 1 means it is connected to busbar 1

  • 2 means it is connected to busbar 2

  • etc.

Notes

In a same substation, two objects are connected together if (and only if) they are connected to the same busbar.

property line_or_bus

Retrieve the busbar at which each origin end of powerline is connected.

The result follow grid2op convention:

  • -1 means the powerline is disconnected

  • 1 means it is connected to busbar 1

  • 2 means it is connected to busbar 2

  • etc.

Notes

In a same substation, two objects are connected together if (and only if) they are connected to the same busbar.

property load_bus

Retrieve the busbar at which each load is connected.

The result follow grid2op convention:

  • -1 means the load is disconnected

  • 1 means it is load to busbar 1

  • 2 means it is load to busbar 2

  • etc.

Notes

In a same substation, two objects are connected together if (and only if) they are connected to the same busbar.

classmethod process_grid2op_compat()[source]

This function can be overloaded.

This is called when the class is initialized, with init_grid to broadcast grid2op compatibility feature.

property prod_p

As of grid2op version 1.5.0, for better consistency, the “prod_p” attribute has been renamed “gen_p”.

This property is present to maintain the backward compatibility.

Returns

Return type

BaseObservation.gen_p

property prod_q

As of grid2op version 1.5.0, for better consistency, the “prod_q” attribute has been renamed “gen_q”.

This property is present to maintain the backward compatibility.

Returns

Return type

BaseObservation.gen_q

property prod_v

As of grid2op version 1.5.0, for better consistency, the “prod_v” attribute has been renamed “gen_v”.

This property is present to maintain the backward compatibility.

Returns

Return type

BaseObservation.gen_v

reset()[source]

INTERNAL

Warning

/!\ Internal, do not use unless you know what you are doing /!\

Resetting a single observation is unlikely to do what you want to do.

Reset the BaseObservation to a blank state, where everything is set to either None or to its default value.

set_game_over(env=None)[source]

Set the observation to the “game over” state:

  • all powerlines are disconnected

  • all loads are 0.

  • all prods are 0.

  • etc.

Notes

As some attributes are initialized with np.empty it is recommended to reset here all attributes to avoid non deterministic behaviour.

simulate(action, time_step=1)[source]

This method is used to simulate the effect of an action on a forecast powergrid state. This forecast state is built upon the current observation.

The forecast are pre computed by the environment.

More concretely, if not deactivated by the environment (see grid2op.Environment.BaseEnv.deactivate_forecast()) and the environment has the capacity to generate these forecasts (which is the case in most grid2op environments) this function will simulate the effect of doing an action now and return the “next state” (often the state you would get at time t + 5 mins) if you were to do the action at this step.

It has the same return value as the grid2op.Environment.Environment.step() function.

Parameters
  • action (grid2op.Action.Action) – The action to simulate

  • time_step (int) – The time step of the forecasted grid to perform the action on. If no forecast are available for this time step, a grid2op.Exceptions.NoForecastAvailable is thrown.

Raises

grid2op.Exceptions.NoForecastAvailable – if no forecast are available for the time_step querried.

Returns

  • simulated_observation (grid2op.Observation.Observation) – agent’s observation of the current environment after the application of the action “act” on the the current state.

  • reward (float) – amount of reward returned after previous action

  • done (bool) – whether the episode has ended, in which case further step() calls will return undefined results

  • info (dict) – contains auxiliary diagnostic information (helpful for debugging, and sometimes learning)

Notes

This is a simulation in the sense that the “next grid state” is not the real grid state you will get. As you don’t know the future, the “injections you forecast for the next step” will not be the real injection you will get in the next step.

Also, in some circumstances, the “Backend” (ie the powerflow) used to do the simulation may not be the same one as the one used by the environment. This is to model a real fact: as accurate your powerflow is, it does not model all the reality (“all models are wrong”). Having a different solver for the environment ( “the reality”) than the one used to anticipate the impact of the action (this “simulate” function) is a way to represent this fact.

Examples

To simulate what would be the effect of the action “act” if you were to take this action at this step you can do the following:

import grid2op
# retrieve an environment
env = grid2op.make()

# retrieve an observation, this is the same for all observations
obs = env.reset()

# and now you can simulate the effect of doing nothing in the next time step
act = env.action_space()  # this can be any action that grid2op understands
simulated_obs, simulated_reward, simulated_done, simulated_info = obs.simulate(act)

# `simulated_obs` will be the "observation" after the application of action `act` on the
#                 " forecast of the grid state (it will be the "forecast state at time t+5mins usually)
# `simulated_reward` will be the reward for the same action on the same forecast state
# `simulated_done` will indicate whether or not the simulation ended up in a "game over"
# `simulated_info` gives extra information on this forecast state
state_of(_sentinel=None, load_id=None, gen_id=None, line_id=None, storage_id=None, substation_id=None)[source]

Return the state of this action on a give unique load, generator unit, powerline of substation. Only one of load, gen, line or substation should be filled.

The querry of these objects can only be done by id here (ie by giving the integer of the object in the backed). The ActionSpace has some utilities to access them by name too.

Parameters
  • _sentinel (None) – Used to prevent positional parameters. Internal, do not use.

  • load_id (int) – ID of the load we want to inspect

  • gen_id (int) – ID of the generator we want to inspect

  • line_id (int) – ID of the powerline we want to inspect

  • line_id – ID of the powerline we want to inspect

  • storage_id (int) – ID of the storage unit we want to inspect

  • substation_id (int) – ID of the substation unit we want to inspect

Returns

res – A dictionary with keys and value depending on which object needs to be inspected:

  • if a load is inspected, then the keys are:

    • ”p” the active value consumed by the load

    • ”q” the reactive value consumed by the load

    • ”v” the voltage magnitude of the bus to which the load is connected

    • ”theta” (optional) the voltage angle (in degree) of the bus to which the load is connected

    • ”bus” on which bus the load is connected in the substation

    • ”sub_id” the id of the substation to which the load is connected

  • if a generator is inspected, then the keys are:

    • ”p” the active value produced by the generator

    • ”q” the reactive value consumed by the generator

    • ”v” the voltage magnitude of the bus to which the generator is connected

    • ”theta” (optional) the voltage angle (in degree) of the bus to which the gen. is connected

    • ”bus” on which bus the generator is connected in the substation

    • ”sub_id” the id of the substation to which the generator is connected

    • ”actual_dispatch” the actual dispatch implemented for this generator

    • ”target_dispatch” the target dispatch (cumulation of all previously asked dispatch by the agent) for this generator

  • if a powerline is inspected then the keys are “origin” and “extremity” each being dictionary with keys:

    • ”p” the active flow on line side (extremity or origin)

    • ”q” the reactive flow on line side (extremity or origin)

    • ”v” the voltage magnitude of the bus to which the line side (extremity or origin) is connected

    • ”theta” (optional) the voltage angle (in degree) of the bus to which line side (extremity or origin)

      is connected

    • ”bus” on which bus the line side (extremity or origin) is connected in the substation

    • ”sub_id” the id of the substation to which the line side is connected

    • ”a” the current flow on the line side (extremity or origin)

    In the case of a powerline, additional information are:

    • ”maintenance”: information about the maintenance operation (time of the next maintenance and duration of this next maintenance.

    • ”cooldown_time”: for how many timestep i am not supposed to act on the powerline due to cooldown (see grid2op.Parameters.Parameters.NB_TIMESTEP_COOLDOWN_LINE for more information)

  • if a storage unit is inspected, information are:

    • ”storage_power”: the power the unit actually produced / absorbed

    • ”storage_charge”: the state of the charge of the storage unit

    • ”storage_power_target”: the power production / absorbtion targer

    • ”storage_theta”: (optional) the voltage angle of the bus at which the storage unit is connected

    • ”bus”: the bus (1 or 2) to which the storage unit is connected

    • ”sub_id” : the id of the substation to which the sotrage unit is connected

  • if a substation is inspected, it returns the topology to this substation in a dictionary with keys:

    • ”topo_vect”: the representation of which object is connected where

    • ”nb_bus”: number of active buses in this substations

    • ”cooldown_time”: for how many timestep i am not supposed to act on the substation due to cooldown (see grid2op.Parameters.Parameters.NB_TIMESTEP_COOLDOWN_SUB for more information)

Return type

dict

Notes

This function can only be used to retrieve the state of the element of the grid, and not the alarm sent or not, to the operator.

Raises

Grid2OpException – If _sentinel is modified, or if None of the arguments are set or alternatively if 2 or more of the parameters are being set.

property storage_bus

Retrieve the busbar at which each storage unit is connected.

The result follow grid2op convention:

  • -1 means the storage unit is disconnected

  • 1 means it is storage unit to busbar 1

  • 2 means it is connected to busbar 2

  • etc.

Notes

In a same substation, two objects are connected together if (and only if) they are connected to the same busbar.

sub_topology(sub_id)[source]

Returns the topology of the given substation

property thermal_limit

Return the thermal limit of the powergrid, given in Amps (A)

Examples

import grid2op
env_name = ...
env = grid2op.make(env_name)

obs = env.reset()
thermal_limit = obs.thermal_limit
to_dict()[source]

Transform this observation as a dictionary. This dictionary allows you to inspect the state of this observation and is simply a shortcut of the class instance.

Returns

Return type

A dictionary representing the observation.

Notes

The returned dictionary is not necessarily json serializable. To have a grid2op observation that you can serialize in a json fashion, please use the grid2op.Space.GridObjects.to_json() function.

abstractmethod update(env, with_forecast=True)[source]

INTERNAL

Warning

/!\ Internal, do not use unless you know what you are doing /!\ This is carried out automatically by the environment in env.step

Update the actual instance of BaseObservation with the new received value from the environment.

An observation is a description of the powergrid perceived by an agent. The agent takes his decision based on the current observation and the past rewards.

This method update receive complete detailed information about the powergrid, but that does not mean an agent sees everything. For example, it is possible to derive this class to implement some noise in the generator or load, or flows to mimic sensor inaccuracy.

It is also possible to give fake information about the topology, the line status etc.

In the Grid2Op framework it’s also through the observation that the agent has access to some forecast (the way forecast are handled depends are implemented in this class). For example, forecast data (retrieved thanks to chronics_handler) are processed, but can be processed differently. One can apply load / production forecast to each _grid state, or to make forecast for one “reference” _grid state valid a whole day and update this one only etc. All these different mechanisms can be implemented in Grid2Op framework by overloading the update observation method.

This class is really what a dispatcher observes from it environment. It can also include some temperatures, nebulosity, wind etc. can also be included in this class.

Notes

We strongly recommend to call BaseObservation.reset when implementing this function.

where_different(other)[source]

Returns the difference between two observation.

Parameters

other – Other action to compare

Returns

  • diff_ (grid2op.Observation.BaseObservation) – The observation showing the difference between self and other

  • attr_nm (list) – List of string representing the names of the different attributes. It’s [] if the two observations are identical.

class grid2op.Observation.CompleteObservation(obs_env=None, action_helper=None, seed=None)[source]

This class represent a complete observation, where everything on the powergrid can be observed without any noise.

This is the only BaseObservation implemented (and used) in Grid2Op. Other type of observation, for other usage can of course be implemented following this example.

It has the same attributes as the BaseObservation class. Only one is added here.

For a CompleteObservation the unique representation as a vector is:

  1. BaseObservation.year the year [1 element]

  2. BaseObservation.month the month [1 element]

  3. BaseObservation.day the day [1 element]

  4. BaseObservation.hour_of_day the hour of the day [1 element]

  5. BaseObservation.minute_of_hour minute of the hour [1 element]

  6. BaseObservation.day_of_week the day of the week. Monday = 0, Sunday = 6 [1 element]

  7. BaseObservation.gen_p the active value of the productions [grid2op.Space.GridObjects.n_gen elements]

  8. BaseObservation.gen_q the reactive value of the productions [grid2op.Space.GridObjects.n_gen elements]

  9. BaseObservation.gen_v the voltage setpoint of the productions [grid2op.Space.GridObjects.n_gen elements]

  10. BaseObservation.load_p the active value of the loads [grid2op.Space.GridObjects.n_load elements]

  11. BaseObservation.load_q the reactive value of the loads [grid2op.Space.GridObjects.n_load elements]

  12. BaseObservation.load_v the voltage setpoint of the loads [grid2op.Space.GridObjects.n_load elements]

  13. BaseObservation.p_or active flow at origin of powerlines [grid2op.Space.GridObjects.n_line elements]

  14. BaseObservation.q_or reactive flow at origin of powerlines [grid2op.Space.GridObjects.n_line elements]

  15. BaseObservation.v_or voltage at origin of powerlines [grid2op.Space.GridObjects.n_line elements]

  16. BaseObservation.a_or current flow at origin of powerlines [grid2op.Space.GridObjects.n_line elements]

  17. BaseObservation.p_ex active flow at extremity of powerlines [grid2op.Space.GridObjects.n_line elements]

  18. BaseObservation.q_ex reactive flow at extremity of powerlines [grid2op.Space.GridObjects.n_line elements]

  19. BaseObservation.v_ex voltage at extremity of powerlines [grid2op.Space.GridObjects.n_line elements]

  20. BaseObservation.a_ex current flow at extremity of powerlines [grid2op.Space.GridObjects.n_line elements]

  21. BaseObservation.rho line capacity used (current flow / thermal limit) [grid2op.Space.GridObjects.n_line elements]

  22. BaseObservation.line_status line status [grid2op.Space.GridObjects.n_line elements]

  23. BaseObservation.timestep_overflow number of timestep since the powerline was on overflow (0 if the line is not on overflow)[grid2op.Space.GridObjects.n_line elements]

  24. BaseObservation.topo_vect representation as a vector of the topology [for each element it gives its bus]. See grid2op.Backend.Backend.get_topo_vect() for more information.

  25. BaseObservation.time_before_cooldown_line representation of the cooldown time on the powerlines [grid2op.Space.GridObjects.n_line elements]

  26. BaseObservation.time_before_cooldown_sub representation of the cooldown time on the substations [grid2op.Space.GridObjects.n_sub elements]

  27. BaseObservation.time_next_maintenance number of timestep before the next maintenance (-1 means no maintenance are planned, 0 a maintenance is in operation) [BaseObservation.n_line elements]

  28. BaseObservation.duration_next_maintenance duration of the next maintenance. If a maintenance is taking place, this is the number of timestep before it ends. [BaseObservation.n_line elements]

  29. BaseObservation.target_dispatch the target dispatch for each generator [grid2op.Space.GridObjects.n_gen elements]

  30. BaseObservation.actual_dispatch the actual dispatch for each generator [grid2op.Space.GridObjects.n_gen elements]

  31. BaseObservation.storage_charge the actual state of charge of each storage unit [grid2op.Space.GridObjects.n_storage elements]

  32. BaseObservation.storage_power_target the production / consumption of setpoint of each storage unit [grid2op.Space.GridObjects.n_storage elements]

  33. BaseObservation.storage_power the realized production / consumption of each storage unit [grid2op.Space.GridObjects.n_storage elements]

  34. BaseObservation.gen_p_before_curtail : the theoretical generation that would have happened if no generator from renewable energy sources have been performed (in MW) [grid2op.Space.GridObjects.n_gen elements]

  35. BaseObservation.curtailment : the current curtailment applied [grid2op.Space.GridObjects.n_gen elements]

  36. BaseObservation.is_alarm_illegal whether the last alarm has been illegal (due to budget constraint) [bool]

  37. BaseObservation.curtailment_limit : the current curtailment limit (if any) [grid2op.Space.GridObjects.n_gen elements]

  38. BaseObservation.time_since_last_alarm number of step since the last alarm has been raised successfully [int]

  39. BaseObservation.last_alarm : for each alarm zone, gives the last step at which an alarm has been successfully raised at this zone [grid2op.Space.GridObjects.dim_alarms elements]

  40. BaseObservation.attention_budget : the current attention budget [int]

  41. BaseObservation.was_alarm_used_after_game_over : was the last alarm used to compute anything related to the attention budget when there was a game over (can only be set to True if the observation corresponds to a game over) [bool]

Methods:

__init__

Initialize self.

__init__(obs_env=None, action_helper=None, seed=None)[source]
update(env, with_forecast=True)[source]

INTERNAL

Warning

/!\ Internal, do not use unless you know what you are doing /!\ This is carried out automatically by the environment in env.step

Update the actual instance of BaseObservation with the new received value from the environment.

An observation is a description of the powergrid perceived by an agent. The agent takes his decision based on the current observation and the past rewards.

This method update receive complete detailed information about the powergrid, but that does not mean an agent sees everything. For example, it is possible to derive this class to implement some noise in the generator or load, or flows to mimic sensor inaccuracy.

It is also possible to give fake information about the topology, the line status etc.

In the Grid2Op framework it’s also through the observation that the agent has access to some forecast (the way forecast are handled depends are implemented in this class). For example, forecast data (retrieved thanks to chronics_handler) are processed, but can be processed differently. One can apply load / production forecast to each _grid state, or to make forecast for one “reference” _grid state valid a whole day and update this one only etc. All these different mechanisms can be implemented in Grid2Op framework by overloading the update observation method.

This class is really what a dispatcher observes from it environment. It can also include some temperatures, nebulosity, wind etc. can also be included in this class.

Notes

We strongly recommend to call BaseObservation.reset when implementing this function.

class grid2op.Observation.ObservationSpace(gridobj, env, rewardClass=None, observationClass=<class 'grid2op.Observation.CompleteObservation.CompleteObservation'>, actionClass=None, with_forecast=True)[source]

Helper that provides useful functions to manipulate BaseObservation.

BaseObservation should only be built using this Helper. It is absolutely not recommended to make an observation directly form its constructor.

This class represents the same concept as the “BaseObservation Space” in the OpenAI gym framework.

with_forecast

If True the BaseObservation.simulate() will be available. If False it will deactivate this possibility. If simulate function is not used, setting it to False can lead to non neglectible speed-ups.

Type

bool

observationClass

Class used to build the observations. It defaults to CompleteObservation

Type

type

_simulate_parameters

Type of Parameters used to compute powerflow for the forecast.

Type

grid2op.Parameters.Parameters

rewardClass

Class used by the grid2op.Environment.Environment to send information about its state to the grid2op.BaseAgent.BaseAgent. You can change this class to differentiate between the reward of output of BaseObservation.simulate() and the reward used to train the BaseAgent.

Type

type

action_helper_env

BaseAction space used to create action during the BaseObservation.simulate()

Type

grid2op.Action.ActionSpace

reward_helper

BaseReward function used by the the BaseObservation.simulate() function.

Type

grid2op.Reward.HelperReward

obs_env

Instance of the environment used by the BaseObservation Helper to provide forcecast of the grid state.

Type

_ObsEnv

_empty_obs

An instance of the observation with appropriate dimensions. It is updated and will be sent to he BaseAgent.

Type

BaseObservation

Methods:

__init__

Initialize self.

copy

Generic (shallow and deep) copying operations.

__call__(env, _update_state=True)[source]

Call self as a function.

__init__(gridobj, env, rewardClass=None, observationClass=<class 'grid2op.Observation.CompleteObservation.CompleteObservation'>, actionClass=None, with_forecast=True)[source]

INTERNAL

Warning

/!\ Internal, do not use unless you know what you are doing /!\

Env: requires grid2op.Environment.parameters and grid2op.Environment.backend to be valid

change_other_rewards(dict_reward)[source]

this function is used to change the “other rewards” used when you perform simulate.

This can be used, for example, when you want to do faster call to “simulate”. In this case you can remove all the “other_rewards” that will be used by the simulate function.

Parameters

dict_reward (dict) – see description of grid2op.Environment.BaseEnv.other_rewards

Examples

If you want to deactivate the reward in the simulate function, you can do as following:

import grid2op
from grid2op.Reward import CloseToOverflowReward, L2RPNReward, RedispReward
env_name = "l2rpn_case14_sandbox"
other_rewards = {"close_overflow": CloseToOverflowReward,
                 "l2rpn": L2RPNReward,
                 "redisp": RedispReward}
env = grid2op.make(env_name, other_rewards=other_rewards)

env.observation_space.change_other_rewards({})
copy()[source]

INTERNAL

Warning

/!\ Internal, do not use unless you know what you are doing /!\

Perform a deep copy of the Observation space.

get_empty_observation()[source]

INTERNAL

Warning

/!\ Internal, do not use unless you know what you are doing /!\

return an empty observation, for internal use only.

reset(real_env)[source]

reset the observation space with the new values of the environment

size_obs()[source]

Size if the observation vector would be flatten :return:

If you still can’t find what you’re looking for, try in one of the following pages:

Still trouble finding the information ? Do not hesitate to send a github issue about the documentation at this link: Documentation issue template