Backend

class grid2op.Backend.Backend(detailed_infos_for_cascading_failures=False)

This is a base class for each Backend object. It allows to run power flow smoothly, and abstract the method of computing cascading failures. This class allow the user or the agent to interact with an power flow calculator, while relying on dedicated methods to change the power _grid behaviour.

detailed_infos_for_cascading_failures

Whether to be verbose when computing a cascading failure.

Type

bool

thermal_limit_a

Thermal limit of the powerline in amps for each powerline. Thie thermal limit is relevant on only one side of the powerline: the same side returned by Backend.get_line_overflow()

Type

numpy.array, dtype:float

__init__(detailed_infos_for_cascading_failures=False)

Initialize an instance of Backend. This does nothing per se. Only the call to Backend.load_grid() should guarantee the backend is properly configured.

Parameters

detailed_infos_for_cascading_failures (bool) – Whether to be detailed (but slow) when computing cascading failures

abstractmethod _disconnect_line(id)

Disconnect the line of id “id” in the backend. In this scenario, the id of a powerline is its position (counted starting from O) in the vector returned by Backend.get_line_status() or Backend.get_line_flow() for example. For example, if the current flow on powerline “l1” is the 42nd element of the vector returned by Backend.get_line_flow() then Backend._disconnect_line(42)() will disconnect this same powerline “l1”.

For assumption about the order of the powerline flows return in this vector, see the help of the Backend.get_line_status() method.

Parameters

id (int) – id of the powerline to be disconnected

Returns

None

_runpf_with_diverging_exception(is_dc)

Computes a power flow on the _grid and raises an exception in case of diverging power flow, or any other exception that can be thrown by the backend.

Parameters

is_dc (bool) – mode of the power flow. If is_dc is True, then the powerlow is run using the DC approximation otherwise it uses the AC powerflow.

Returns

None

abstractmethod apply_action(action)

Modify the powergrid with the action given by an agent or by the envir. For the L2RPN project, this action is mainly for topology if it has been sent by the agent. Or it can also affect production and loads, if the action is made by the environment.

The help of grid2op.BaseAction.BaseAction.__call__() or the code in BaseActiontion.py file give more information about the implementation of this method.

Parameters

action (grid2op.Action.Action) – the action to be implemented on the powergrid.

Returns

None

assert_grid_correct_after_powerflow()

This method is called by the environment. It ensure that the backend remains consistent even after a powerflow has be run with Backend.runpf() method.

Returns

None

Raise

grid2op.Exceptions.EnvError and possibly all of its derived class.

check_kirchoff()

Check that the powergrid respects kirchhoff’s law. This function can be called at any moment to make sure a powergrid is in a consistent state, or to perform some tests for example.

In order to function properly, this method requires that Backend.shunt_info() and Backend.sub_from_bus_id() are properly defined. Otherwise the results might be wrong, especially for reactive values (q_subs and q_bus bellow)

Returns

• p_subs numpy.ndarray – sum of injected active power at each substations

• q_subs numpy.ndarray – sum of injected reactive power at each substations

• p_bus numpy.ndarray – sum of injected active power at each buses. It is given in form of a matrix, with number of substations as row, and number of columns equal to the maximum number of buses for a substation

• q_bus numpy.ndarray – sum of injected reactive power at each buses. It is given in form of a matrix, with number of substations as row, and number of columns equal to the maximum number of buses for a substation

abstractmethod close()

This function is called when the environment is over. After calling this function, the backend might not behave properly, and in any case should not be used before another call to Backend.load_grid() is performed

Returns

Return type

None

abstractmethod copy()

Performs a deep copy of the backend.

Returns

An instance of Backend equal to self, but deep copied.

Return type

Backend

abstractmethod generators_info()

This method is used to retrieve informations about the generators.

Returns

• prod_p numpy.ndarray – The active power production for each generator

• prod_q numpy.ndarray – The reactive power production for each generator

• prod_v numpy.ndarray – The voltage magnitude of the bus to which each generators is connected

abstractmethod get_line_flow()

Return the current flow in each lines of the powergrid. Only one value per powerline is returned.

If the AC mod is used, this shall return the current flow on the end of the powerline where there is a protection. For example, if there is a protection on “origin end” of powerline “l2” then this method shall return the current flow of at the “origin end” of powerline l2.

Note that in general, there is no loss of generality in supposing all protections are set on the “origin end” of the powerline. So this method will return all origin line flows. It is also possible, for a specific application, to return the maximum current flow between both ends of a power _grid for more complex scenario.

For assumption about the order of the powerline flows return in this vector, see the help of the Backend.get_line_status() method.

Returns

an array with the line flows of each powerline

Return type

np.array, dtype:float

get_line_overflow()

faster accessor to the line that are on overflow.

For assumption about the order of the powerline flows return in this vector, see the help of the Backend.get_line_status() method.

Returns

An array saying if a powerline is overflow or not

Return type

np.array, dtype:bool

abstractmethod get_line_status()

Return the status of each lines (connected : True / disconnected: False )

It is assume that the order of the powerline is fixed: if the status of powerline “l1” is put at the 42nd element of the return vector, then it should always be set at the 42nd element.

It is also assumed that all the other methods of the backend that allows to retrieve informations on the powerlines also respect the same convention, and consistent with one another. For example, if powerline “l1” is the 42nd second of the vector returned by Backend.get_line_status() then information about it’s flow will be at position 42 of the vector returned by Backend.get_line_flow() for example.

Returns

an array with the line status of each powerline

Return type

np.array, dtype:bool

get_relative_flow()

This method return the relative flows, eg. the current flow divided by the thermal limits. It has a pretty straightforward default implementation, but it can be overriden for example for transformer if the limits are on the lower voltage side or on the upper voltage level.

Returns

res – The relative flow in each powerlines of the grid.

Return type

numpy.ndarray, dtype: float

get_thermal_limit()

Gives the thermal limit (in amps) for each powerline of the _grid. Only one value per powerline is returned.

It is assumed that both Backend.get_line_flow() and _get_thermal_limit gives the value of the same end of the powerline. See the help of _get_line_flow for a more detailed description of this problem.

For assumption about the order of the powerline flows return in this vector, see the help of the Backend.get_line_status() method.

Returns

An array giving the thermal limit of the powerlines.

Return type

np.array, dtype:float

abstractmethod get_topo_vect()

Get the topology vector from the Backend._grid. The topology vector defines, for each object, on which bus it is connected. It returns -1 if the object is not connected.

It is a vector with as much elements (productions, loads and lines extremity) as there are in the powergrid.

For each elements, it gives on which bus it is connected in its substation.

For example, if the first element of this vector is the load of id 1, then if res[0] = 2 it means that the load of id 1 is connected to the second bus of its substation.

You can check which object of the powerlines is represented by each component of this vector by looking at the *_pos_topo_vect (eg. grid2op.Space.GridObjects.load_pos_topo_vect) vectors. For each elements it gives its position in this vector.

TODO make an example here on how to use this!

Returns

res – An array saying to which bus the object is connected.

Return type

numpy.ndarray, dtype: int

abstractmethod lines_ex_info()

It returns the information extracted from the _grid at the extremity end of each powerline.

For assumption about the order of the powerline flows return in this vector, see the help of the Backend.get_line_status() method.

Returns

• p_ex numpy.ndarray – the extremity active power flowing on the lines

• q_ex numpy.ndarray – the extremity reactive power flowing on the lines

• v_ex numpy.ndarray – the voltage magnitude at the extremity of each powerlines

• a_ex numpy.ndarray – the current flow at the extremity of each powerlines

abstractmethod lines_or_info()

It returns the information extracted from the _grid at the origin end of each powerline.

For assumption about the order of the powerline flows return in this vector, see the help of the Backend.get_line_status() method.

Returns

• p_or numpy.ndarray – the origin active power flowing on the lines

• q_or numpy.ndarray – the origin reactive power flowing on the lines

• v_or numpy.ndarray – the voltage magnitude at the origin of each powerlines

• a_or numpy.ndarray – the current flow at the origin of each powerlines

abstractmethod load_grid(path, filename=None)

Load the powergrid. It should first define self._grid.

And then fill all the helpers used by the backend eg. all the attributes of Space.GridObjects.

After a the call to Backend.load_grid() has been performed, the backend should be in such a state where the grid2op.Space.GridObjects is properly set up. See the description of grid2op.Space.GridObjects to know which attributes should be set here and which should not.

Parameters

• path (string) – the path to find the powergrid

• filename (string, optional) – the filename of the powergrid

Returns

None

load_redispacthing_data(path, name='prods_charac.csv')

This method will load everything needed for the redispatching and unit commitment problem.

Parameters

• path –

• name –

abstractmethod loads_info()

This method is used to retrieve informations about the loads.

Returns

• load_p numpy.ndarray – The active power consumption for each load

• load_q numpy.ndarray – The reactive power consumption for each load

• load_v numpy.ndarray – The voltage magnitude of the bus to which each load is connected

next_grid_state(env, is_dc=False)

This method is called by the environment to compute the next _grid states. It allows to compute the powerline and approximate the “cascading failures” if there are some overflows.

Note that it DOESNT update the environment with the disconnected lines.

Parameters

• env (grid2op.Environment.Environment) – the environment in which the powerflow is ran.

• is_dc (bool) – mode of power flow (AC : False, DC: is_dc is True)

Returns

disconnected lines and list of Backend instances that allows to reconstruct the cascading failures (in which order the powerlines have been disconnected). Note that if Backend.detailed_infos_for_cascading_failures is set to False, the empty list will always be returned.

Return type

tuple: np.array, dtype:bool, list

abstractmethod runpf(is_dc=False)

Run a power flow on the underlying _grid. Powerflow can be AC (is_dc = False) or DC (is_dc = True)

Parameters

is_dc (bool) – is the powerflow run in DC or in AC

Returns

True if it has converged, or false otherwise. In case of non convergence, no flows can be inspected on the _grid.

Return type

bool

save_file(full_path)

Save the current power _grid in a human readable format supported by the backend. The format is not modified by this wrapper.

This function is not mandatory, and if implemented, it is used only as a debugging purpose.

Parameters

full_path (string) – the full path (path + file name + extension) where self._grid is stored.

Returns

None

set_thermal_limit(limits)

This function is used as a convenience function to set the thermal limits Backend.thermal_limit_a in amperes.

It can be used at the beginning of an episode if the thermal limit are not present in the original data files or alternatively if the thermal limits depends on the period of the year (one in winter and one in summer for example).

Parameters

limits (object) –

It can be understood differently according to its type:

• If it’s a numpy.ndarray, then it is assumed the thermal limits are given in amperes in the same order as the powerlines computed in the backend. In that case it modifies all the thermal limits of all the powerlines at once.

• If it’s a dict it must have:

  • as key the powerline names (not all names are mandatory, in that case only the powerlines with the name in this dictionnary will be modified)

  • as value the new thermal limit (should be a strictly positive float).

Returns

Return type

None

shunt_info()

This method is optional. If implemented, it should return the proper information about the shunt in the powergrid.

If not implemented it returns empty list.

Note that if there are shunt on the powergrid, it is recommended that this method should be implemented before calling Backend.check_kirchoff().

If this method is implemented AND Backend.check_kirchoff() is called, the method Backend.sub_from_bus_id() should also be implemented preferably.

Returns

• shunt_p numpy.ndarray – For each shunt, the active power it withdraw at the bus to which it is connected.

• shunt_q numpy.ndarray – For each shunt, the reactive power it withdraw at the bus to which it is connected.

• shunt_v numpy.ndarray – For each shunt, the voltage magnitude of the bus to which it is connected.

• shunt_bus numpy.ndarray – For each shunt, the bus id to which it is connected.

sub_from_bus_id(bus_id)

Optionnal method that allows to get the substation if the bus id is provided.

Parameters

bus_id –

Returns

the substation to which an object connected to bus with id bus_id is connected to.

update_thermal_limit(env)

Upade the new thermal limit in case of DLR for example.

By default it does nothing.

Depending on the operational strategy, it is also possible to implement some Dynamic Line Rating (DLR) strategies. In this case, this function will give the thermal limit for a given time step provided the flows and the weather condition are accessible by the backend. Our methodology doesn’t make any assumption on the method used to get these thermal limits.

Parameters

env (grid2op.Environment.Environment) – The environment used to compute the thermal limit

Returns

Return type

None

class grid2op.Backend.PandaPowerBackend(detailed_infos_for_cascading_failures=False)

As explained in the grid2op.Backend module, every module must inherit the grid2op.Backend class.

This class have more attributes that are used internally for faster information retrieval.

prod_pu_to_kv

The ratio that allow the conversion from pair-unit to kv for the generators

Type

numpy.array, dtype:float

load_pu_to_kv

The ratio that allow the conversion from pair-unit to kv for the loads

Type

numpy.array, dtype:float

lines_or_pu_to_kv

The ratio that allow the conversion from pair-unit to kv for the origin end of the powerlines

Type

numpy.array, dtype:float

lines_ex_pu_to_kv

The ratio that allow the conversion from pair-unit to kv for the extremity end of the powerlines

Type

numpy.array, dtype:float

p_or

The active power flowing at the origin end of each powerline

Type

numpy.array, dtype:float

q_or

The reactive power flowing at the origin end of each powerline

Type

numpy.array, dtype:float

v_or

The voltage magnitude at the origin bus of the powerline

Type

numpy.array, dtype:float

a_or

The current flowing at the origin end of each powerline

Type

numpy.array, dtype:float

p_ex

The active power flowing at the extremity end of each powerline

Type

numpy.array, dtype:float

q_ex

The reactive power flowing at the extremity end of each powerline

Type

numpy.array, dtype:float

a_ex

The current flowing at the extremity end of each powerline

Type

numpy.array, dtype:float

v_ex

The voltage magnitude at the extremity bus of the powerline

Type

numpy.array, dtype:float

__init__(detailed_infos_for_cascading_failures=False)

Initialize an instance of Backend. This does nothing per se. Only the call to Backend.load_grid() should guarantee the backend is properly configured.

Parameters

detailed_infos_for_cascading_failures (bool) – Whether to be detailed (but slow) when computing cascading failures

_disconnect_line(id)

Disconnect the line of id “id” in the backend. In this scenario, the id of a powerline is its position (counted starting from O) in the vector returned by Backend.get_line_status() or Backend.get_line_flow() for example. For example, if the current flow on powerline “l1” is the 42nd element of the vector returned by Backend.get_line_flow() then Backend._disconnect_line(42)() will disconnect this same powerline “l1”.

For assumption about the order of the powerline flows return in this vector, see the help of the Backend.get_line_status() method.

Parameters

id (int) – id of the powerline to be disconnected

Returns

None

apply_action(action: grid2op.Action.BaseAction.BaseAction)

Specific implementation of the method to apply an action modifying a powergrid in the pandapower format.

close()

Called when the grid2op;Environment has terminated, this function only reset the grid to a state where it has not been loaded.

copy()

Performs a deep copy of the power _grid. As pandapower is pure python, the deep copy operator is perfectly suited for the task.

generators_info()

This method is used to retrieve informations about the generators.

Returns

• prod_p numpy.ndarray – The active power production for each generator

• prod_q numpy.ndarray – The reactive power production for each generator

• prod_v numpy.ndarray – The voltage magnitude of the bus to which each generators is connected

get_line_flow()

return the powerflow in amps in all powerlines. :return:

get_line_status()

As all the functions related to powerline, pandapower split them into multiple dataframe (some for transformers, some for 3 winding transformers etc.). We make sure to get them all here.

get_nb_active_bus()

Compute the amount of buses “in service” eg with at least a powerline connected to it.

Returns

res – The total number of active buses.

Return type

int

get_topo_vect()

Get the topology vector from the Backend._grid. The topology vector defines, for each object, on which bus it is connected. It returns -1 if the object is not connected.

It is a vector with as much elements (productions, loads and lines extremity) as there are in the powergrid.

For each elements, it gives on which bus it is connected in its substation.

For example, if the first element of this vector is the load of id 1, then if res[0] = 2 it means that the load of id 1 is connected to the second bus of its substation.

You can check which object of the powerlines is represented by each component of this vector by looking at the *_pos_topo_vect (eg. grid2op.Space.GridObjects.load_pos_topo_vect) vectors. For each elements it gives its position in this vector.

TODO make an example here on how to use this!

Returns

res – An array saying to which bus the object is connected.

Return type

numpy.ndarray, dtype: int

lines_ex_info()

It returns the information extracted from the _grid at the extremity end of each powerline.

For assumption about the order of the powerline flows return in this vector, see the help of the Backend.get_line_status() method.

Returns

• p_ex numpy.ndarray – the extremity active power flowing on the lines

• q_ex numpy.ndarray – the extremity reactive power flowing on the lines

• v_ex numpy.ndarray – the voltage magnitude at the extremity of each powerlines

• a_ex numpy.ndarray – the current flow at the extremity of each powerlines

lines_or_info()

It returns the information extracted from the _grid at the origin end of each powerline.

For assumption about the order of the powerline flows return in this vector, see the help of the Backend.get_line_status() method.

Returns

• p_or numpy.ndarray – the origin active power flowing on the lines

• q_or numpy.ndarray – the origin reactive power flowing on the lines

• v_or numpy.ndarray – the voltage magnitude at the origin of each powerlines

• a_or numpy.ndarray – the current flow at the origin of each powerlines

load_grid(path=None, filename=None)

Load the _grid, and initialize all the member of the class. Note that in order to perform topological modification of the substation of the underlying powergrid, some buses are added to the test case loaded. They are set as “out of service” unless a topological action acts on these specific substations.

loads_info()

This method is used to retrieve informations about the loads.

Returns

• load_p numpy.ndarray – The active power consumption for each load

• load_q numpy.ndarray – The reactive power consumption for each load

• load_v numpy.ndarray – The voltage magnitude of the bus to which each load is connected

runpf(is_dc=False)

Run a power flow on the underlying _grid. This implements an optimization of the powerflow computation: if the number of buses has not changed between two calls, the previous results are re used. This speeds up the computation in case of “do nothing” action applied.

save_file(full_path)

Save the file to json. :param full_path: :return:

shunt_info()

This method is optional. If implemented, it should return the proper information about the shunt in the powergrid.

If not implemented it returns empty list.

Note that if there are shunt on the powergrid, it is recommended that this method should be implemented before calling Backend.check_kirchoff().

If this method is implemented AND Backend.check_kirchoff() is called, the method Backend.sub_from_bus_id() should also be implemented preferably.

Returns

• shunt_p numpy.ndarray – For each shunt, the active power it withdraw at the bus to which it is connected.

• shunt_q numpy.ndarray – For each shunt, the reactive power it withdraw at the bus to which it is connected.

• shunt_v numpy.ndarray – For each shunt, the voltage magnitude of the bus to which it is connected.

• shunt_bus numpy.ndarray – For each shunt, the bus id to which it is connected.

sub_from_bus_id(bus_id)

Optionnal method that allows to get the substation if the bus id is provided.

Parameters

bus_id –

Returns

the substation to which an object connected to bus with id bus_id is connected to.

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

• Index

• Search Page