Backend

This page is organized as follow:

Objectives

Warning

Backends are internal to grid2op. You should not have to recode any backend if you are “simply” using grid2op, for example to develop new controller.

Backend is an abstraction that represents the physical system (the powergrid). In theory every powerflow can be used as a backend. For now we only provide a Backend that uses Pandapower and a port in c++ to a subset of pandapower called LightSim2Grid .

Both can serve as example if you want to code a new backend.

This Module defines the template of a backend class. Backend instances are responsible to translate action (performed either by an BaseAgent or by the Environment) into comprehensive powergrid modifications. They are responsible to perform the powerflow (AC or DC) computation.

It is also through the backend that some quantities about the powergrid (such as the flows) can be inspected.

A backend is mandatory for a Grid2Op environment to work properly.

To be a valid backend, some properties are mandatory:

  • order of objects matters and should be deterministic (for example Backend.get_line_status() shall return the status of the lines always in the same order)

  • order of objects should be the same if the same underlying object is queried (for example, is Backend.get_line_status()[i] is the status of the powerline “toto”, then Backend.get_thermal_limit()[i] returns the thermal limits of this same powerline “toto”)

  • it allows to compute AC and DC powerflow

  • it allows to:

    • change the value consumed (both active and reactive) by each load of the network

    • change the amount of power produced and the voltage setpoint of each generator unit of the powergrid

    • allow for powerline connection / disconnection

    • allow for the modification of the connectivity of the powergrid (change in topology)

    • allow for deep copy.

The order of the values returned are always the same and determined when the backend is loaded by its attribute ‘*_names’. For example, when the ith element of the results of a call to Backend.get_line_flow() is the flow on the powerline with name lines_names[i].

Creating a new backend

We developed a dedicated page for the development of new “Backend” compatible with grid2op here Creating a new backend.

Detailed Documentation by class

Classes:

Backend([detailed_infos_for_cascading_failures])

INTERNAL

PandaPowerBackend([...])

INTERNAL

class grid2op.Backend.Backend(detailed_infos_for_cascading_failures=False)[source]

INTERNAL

Warning

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

Unless if you want to code yourself a backend this is not recommend to alter it or use it directly in any way.

If you want to code a backend, an example is given in PandaPowerBackend ( or in the repository lightsim2grid on github)

This documentation is present mainly for exhaustivity. It is not recommended to manipulate a Backend directly. Prefer using an grid2op.Environment.Environment

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.

It is NOT recommended to use this class outside the Environment.

An example of a valid backend is provided in the PandapowerBackend.

All the abstract methods (that need to be implemented for a backend to work properly) are (more information given in the Creating a new backend page):

And optionally:

  • Backend.close() (this is mandatory if your backend implementation (self._grid) is relying on some c / c++ code that do not free memory automatically.

  • Backend.copy() (not that this is mandatory if your backend implementation (in self._grid) cannot be deep copied using the python copy.deepcopy function)

  • Backend.get_line_status(): the default implementation uses the “get_topo_vect()” and then check if buses at both ends of powerline are positive. This is rather slow and can most likely be optimized.

  • Backend.get_line_flow(): the default implementation will retrieve all powerline information at the “origin” side and just return the “a_or” vector. You want to do something smarter here.

  • Backend._disconnect_line(): has a default slow implementation using “apply_action” that might can most likely be optimized in your backend.

  • Backend.reset() will reload the powergrid from the hard drive by default. This is rather slow and we recommend to overload it.

And, if the flag :attr:Backend.shunts_data_available` is set to True the method Backend.shunt_info() should also be implemented.

Note

Backend also support “shunts” information if the self.shunts_data_available flag is set to True in that case, you also need to implement all the relevant shunt information (attributes n_shunt, shunt_to_subid, name_shunt and function shunt_info and handle the modification of shunts bus, active value and reactive value in the “apply_action” function).

In order to be valid and carry out some computations, you should call Backend.load_grid() and later grid2op.Spaces.GridObjects.assert_grid_correct(). It is also more than recommended to call Backend.assert_grid_correct_after_powerflow() after the first powerflow. This is all carried ou in the environment properly.

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

comp_time

Time to compute the powerflow (might be unset, ie stay at 0.0)

Type

float

Methods:

__init__

Initialize self.

copy

Generic (shallow and deep) copying operations.

__init__(detailed_infos_for_cascading_failures=False)[source]

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

_aux_check_finite_float(nb_, str_='')[source]

INTERNAL

Warning

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

check and returns if correct that a number is convertible to dt_float and that it’s finite

_disconnect_line(id_)[source]

INTERNAL

Warning

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

Prefer using the action space to disconnect a powerline.

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

_runpf_with_diverging_exception(is_dc)[source]

INTERNAL

Warning

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

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.

Raises

excgrid2op.Exceptions.DivergingPowerFlow: In case of divergence of the powerflow

abstractmethod apply_action(action)[source]

INTERNAL

Warning

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

Don’t attempt to apply an action directly to a backend. This function will modify the powergrid state given the action in input.

This is one of the core function if you want to code a backend.

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._BackendAction._BackendAction) – the action to be implemented on the powergrid.

Returns

None

assert_grid_correct()[source]

INTERNAL

Warning

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

This is done as it should be by the Environment

assert_grid_correct_after_powerflow()[source]

INTERNAL

Warning

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

This is done as it should be by the Environment

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.

Raise

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

check_kirchoff()[source]

INTERNAL

Warning

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

Check that the powergrid respects kirchhoff’s law. This function can be called at any moment (after a powerflow has been run) 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 (MW)

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

  • 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 (MW)

  • 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 (MVAr)

  • diff_v_bus (numpy.ndarray (2d array)) – difference between maximum voltage and minimum voltage (computed for each elements) at each bus. It is an array of two dimension:

    • first dimension represents the the substation (between 1 and self.n_sub)

    • second element represents the busbar in the substation (0 or 1 usually)

close()[source]

INTERNAL

Warning

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

This is called by env.close() do not attempt to use it otherwise.

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

copy()[source]

INTERNAL

Warning

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

Performs a deep copy of the backend.

In the default implementation we explicitly called the deepcopy operator on self._grid to make the error message more explicit in case there is a problem with this part.

The implementation is equivalent to:

return copy.deepcopy(self)
Returns

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

Return type

Backend

abstractmethod generators_info()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.prod_p, grid2op.Observation.BaseObservation.prod_q and grid2op.Observation.BaseObservation.prod_v instead.

This method is used to retrieve information about the generators (active, reactive production and voltage magnitude of the bus to which it is connected).

Returns

  • prod_p numpy.ndarray – The active power production for each generator (in MW)

  • prod_q numpy.ndarray – The reactive power production for each generator (in MVAr)

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

get_action_to_set()[source]

Get the action to set another backend to represent the internal state of this current backend.

It handles also the information about the shunts if available

Returns

res – The complete action to set a backend to the internal state of self

Return type

grid2op.Action.CompleteAction

get_line_flow()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.a_or or grid2op.Observation.BaseObservation.a_ex for example

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()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.rho and check whether or not the flow is higher tha 1. or have a look at grid2op.Observation.BaseObservation.timestep_overflow and check the non zero index.

Prefer using the attribute of the grid2op.Observation.BaseObservation

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

get_line_status()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.line_status instead

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()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.rho

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()[source]

INTERNAL

Warning

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

Retrieve the thermal limit directly from the environment instead (with a call to grid2op.Environment.BaseEnc.get_thermal_limit() for example)

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

get_theta()[source]

Notes

Don’t forget to set the flag Backend.can_output_theta to True in the Bakcend.load_grid() if you support this feature.

Returns

  • line_or_theta (numpy.ndarray) – For each origin side of powerline, gives the voltage angle

  • line_ex_theta (numpy.ndarray) – For each extremity side of powerline, gives the voltage angle

  • load_theta (numpy.ndarray) – Gives the voltage angle to the bus at which each load is connected

  • gen_theta (numpy.ndarray) – Gives the voltage angle to the bus at which each generator is connected

  • storage_theta (numpy.ndarray) – Gives the voltage angle to the bus at which each storage unit is connected

abstractmethod get_topo_vect()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.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.

As any function of the backend, it is not advised to use it directly. You can get this information in the grid2op.Observation.Observation.topo_vect instead.

Returns

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

Return type

numpy.ndarray dtype: int

abstractmethod lines_ex_info()[source]

INTERNAL

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 (in MW)

  • q_ex numpy.ndarray – the extremity reactive power flowing on the lines (in MVAr)

  • v_ex numpy.ndarray – the voltage magnitude at the extremity of each powerlines (in kV)

  • a_ex numpy.ndarray – the current flow at the extremity of each powerlines (in A)

abstractmethod lines_or_info()[source]

INTERNAL

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 (in MW)

  • q_or numpy.ndarray – the origin reactive power flowing on the lines (in MVAr)

  • v_or numpy.ndarray – the voltage magnitude at the origin of each powerlines (in kV)

  • a_or numpy.ndarray – the current flow at the origin of each powerlines (in A)

abstractmethod load_grid(path, filename=None)[source]

INTERNAL

Warning

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

This is called once at the loading of the powergrid.

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_grid_layout(path, name='grid_layout.json')[source]

INTERNAL

Warning

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

We don’t recommend at all to modify this function.

This function loads the layout (eg the coordinates of each substation) for the powergrid.

Parameters
  • path (str) – TODO

  • name (str) – TODO

load_redispacthing_data(path, name='prods_charac.csv')[source]

INTERNAL

Warning

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

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

We don’t recommend at all to modify this function.

Parameters
  • path (str) –

    Location of the dataframe containing the redispatching data. This dataframe (csv, coma separated) should have at least the columns (other columns are ignored, order of the colums do not matter):

    • ”name”: identifying the name of the generator (should match the names in self.name_gen)

    • ”type”: one of “thermal”, “nuclear”, “wind”, “solar” or “hydro” representing the type of the generator

    • ”pmax”: the maximum value the generator can produce (in MW)

    • ”pmin”: the minimum value the generator can produce (in MW)

    • ”max_ramp_up”: maximum value the generator can increase its production between two consecutive steps TODO make it independant from the duration of the step

    • ”max_ramp_down”: maximum value the generator can decrease its production between two consecutive steps (is positive) TODO make it independant from the duration of the step

    • ”start_cost”: starting cost of the generator in $ (or any currency you want)

    • ”shut_down_cost”: cost associated to the shut down of the generator in $ (or any currency you want)

    • ”marginal_cost”: “average” marginal cost of the generator. For now we don’t allow it to vary across different steps or episode in $/(MW.time step duration) and NOT $/MWh (TODO change that)

    • ”min_up_time”: minimum time a generator need to stay “connected” before we can disconnect it ( measured in time step) (TODO change that)

    • ”min_down_time”: minimum time a generator need to stay “disconnected” before we can connect it again.( measured in time step) (TODO change that)

  • name (str) – Name of the dataframe containing the redispatching data. Defaults to ‘prods_charac.csv’, we don’t advise to change it.

load_storage_data(path, name='storage_units_charac.csv')[source]

INTERNAL

Warning

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

This method will load everything needed in presence of storage unit on the grid.

We don’t recommend at all to modify this function.

Parameters
  • path (str) –

    Location of the dataframe containing the storage unit data. This dataframe (csv, coma separated) should have at least the columns. It is mandatory to have it if there are storage units on the grid, but it is ignored if not:

    • ”name”: identifying the name of the unit storage (should match the names in self.name_storage)

    • ”type”: one of “battery”, “pumped_storage” representing the type of the unit storage

    • ”Emax”: the maximum energy capacity the unit can store (in MWh)

    • ”Emin”: the minimum energy capacity the unit can store (in MWh) [it can be >0 if a battery cannot be completely empty for example]

    • ”max_p_prod”: maximum flow the battery can absorb in MW

    • ”max_p_absorb”: maximum flow the battery can produce in MW

    • ”marginal_cost”: cost in $ (or any currency, really) of usage of the battery.

    • ”power_discharge_loss” (optional): power loss in the battery in MW (the capacity will decrease constantly of this amount). Set it to 0.0 to deactivate it. If not present, it is set to 0.

    • ”charging_efficiency” (optional):

      Float between 0. and 1. 1. means that if the grid provides 1MW (for ex. 1MW for 1h) to the storage capacity, then the state of charge of the battery will increase of 1MWh. If this efficiency is 0.5 then if 1MWh if provided by the grid, then only 0.5MWh will be stored.

    • ”discharging_efficiency” (optional): battery efficiency when it is discharged. 1.0 means if you want to get 1MWh on the grid, the battery state of charge will decrease by 1MWh. If this is 33% then it means if you want to get (grid point of view) 1MWh on the grid, you need to decrease the state of charge of 3MWh.

  • name (str) – Name of the dataframe containing the redispatching data. Defaults to ‘prods_charac.csv’, we don’t advise to change it.

Notes

The battery efficiency defined as the “AC-AC” round trip efficiency is, with the convention above, defined as charging_efficiency * discharging_efficency (see https://www.greeningthegrid.org/news/new-resource-grid-scale-battery-storage-frequently-asked-questions-1 for further references)

abstractmethod loads_info()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.load_p, grid2op.Observation.BaseObservation.load_q and grid2op.Observation.BaseObservation.load_v instead.

This method is used to retrieve information about the loads (active, reactive consumption and voltage magnitude of the bus to which it is connected).

Returns

  • load_p numpy.ndarray – The active power consumption for each load (in MW)

  • load_q numpy.ndarray – The reactive power consumption for each load (in MVAr)

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

next_grid_state(env, is_dc=False)[source]

INTERNAL

Warning

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

This is called by env.step

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.

env

the environment in which the powerflow is ran.

Type

grid2op.Environment.Environment

is_dc

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

Type

bool

Returns

  • disconnected_during_cf (numpy.ndarray, dtype=bool) – For each powerlines, it returns True if the powerline has been disconnected due to a cascading failure or False otherwise.

  • infos (list) – If Backend.detailed_infos_for_cascading_failures is True then it returns the different state computed by the powerflow (can drastically slow down this function, as it requires deep copy of backend object). Otherwise the list is always empty.

reset(grid_path, grid_filename=None)[source]

INTERNAL

Warning

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

This is done in the env.reset() method and should be performed otherwise.

Reload the power grid. For backwards compatibility this method calls Backend.load_grid. But it is encouraged to overload it in the subclasses.

abstractmethod runpf(is_dc=False)[source]

INTERNAL

Warning

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

This is called by Backend.next_grid_state() (that computes some kind of cascading failures).

This is one of the core function if you want to code a backend. It will carry out a powerflow.

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

Returns

an exception in case of divergence (or none if no particular info are available)

Return type

Exception

save_file(full_path)[source]

INTERNAL

Warning

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

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)[source]

INTERNAL

Warning

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

You can set the thermal limit directly in the environment.

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).

shunt_info()[source]

INTERNAL

Warning

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

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.

storage_deact_for_backward_comaptibility()[source]

INTERNAL

Warning

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

This function is called under a very specific condition: an old environment has been loaded that do not take into account the storage units, even though they were possibly some modeled by the backend.

This function is supposed to “remove” from the backend any reference to the storage units.

Overloading this function is not necessary (when developing a new backend). If it is not overloaded however, some “backward compatibility” (for grid2op <= 1.4.0) might not be working properly depending on your backend.

storages_info()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.storage_power instead.

This method is used to retrieve information about the storage units (active, reactive consumption and voltage magnitude of the bus to which it is connected).

Returns

  • storage_p numpy.ndarray – The active power consumption for each load (in MW)

  • storage_q numpy.ndarray – The reactive power consumption for each load (in MVAr)

  • storage_v numpy.ndarray – The voltage magnitude of the bus to which each load is connected (in kV)

sub_from_bus_id(bus_id)[source]

INTERNAL

Warning

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

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

Parameters

bus_id (int) – The id of the bus where you want to know to which substation it belongs

Returns

Return type

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

update_from_obs(obs)[source]

Takes an observation as input and update the internal state of self to match the state of the backend that produced this observation.

Only the “line_status”, “topo_vect”, “prod_p”, “prod_v”, “load_p” and “load_q” attributes of the observations are used.

Notes

If the observation is not perfect (for example with noise, or partial) this method will not work. You need to pass it a complete observation.

For example, you might want to consider to have a state estimator if that is the case.

Parameters

obs (grid2op.Observation.CompleteObservation) – A complete observation describing the state of the grid you want this backend to be in.

update_thermal_limit(env)[source]

INTERNAL

Warning

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

This is done in a call to env.step in case of DLR for example.

If you don’t want this feature, do not implement it.

Update 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

class grid2op.Backend.PandaPowerBackend(detailed_infos_for_cascading_failures=False)[source]

INTERNAL

Warning

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

If you want to code a backend to use grid2op with another powerflow, you can get inspired from this class. Note However that implies knowing the behaviour of PandaPower.

This module presents an example of an implementation of a grid2op.Backend when using the powerflow implementation “pandapower” available at PandaPower for more details about this backend. This file is provided as an example of a proper grid2op.Backend.Backend implementation.

This backend currently does not work with 3 winding transformers and other exotic object.

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

Examples

The only recommended way to use this class is by passing an instance of a Backend into the “make” function of grid2op. Do not attempt to use a backend outside of this specific usage.

import grid2op
from grid2op.Backend import PandaPowerBackend
backend = PandaPowerBackend()

env = grid2op.make(backend=backend)
# and use "env" as any open ai gym environment.

Methods:

__init__

Initialize self.

copy

Generic (shallow and deep) copying operations.

__init__(detailed_infos_for_cascading_failures=False)[source]

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

_check_for_non_modeled_elements()[source]

This function check for elements in the pandapower grid that will have no impact on grid2op. See the full list of grid2op modeled elements in Elements modeled in this environment and their main properties

_convert_id_topo(id_big_topo)[source]

INTERNAL

Warning

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

convert an id of the big topo vector into:

  • the id of the object in its “only object” (eg if id_big_topo represents load 2, then it will be 2)

  • the type of object among: “load”, “gen”, “lineor” and “lineex”

_disconnect_line(id_)[source]

INTERNAL

Warning

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

Prefer using the action space to disconnect a powerline.

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

apply_action(backendAction=None)[source]

INTERNAL

Warning

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

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

assert_grid_correct()[source]

INTERNAL

Warning

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

This is done as it should be by the Environment

close()[source]

INTERNAL

Warning

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

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

copy()[source]

INTERNAL

Warning

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

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()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.prod_p, grid2op.Observation.BaseObservation.prod_q and grid2op.Observation.BaseObservation.prod_v instead.

This method is used to retrieve information about the generators (active, reactive production and voltage magnitude of the bus to which it is connected).

Returns

  • prod_p numpy.ndarray – The active power production for each generator (in MW)

  • prod_q numpy.ndarray – The reactive power production for each generator (in MVAr)

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

get_line_flow()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.a_or or grid2op.Observation.BaseObservation.a_ex for example

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_status()[source]

INTERNAL

Warning

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

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()[source]

INTERNAL

Warning

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

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_theta()[source]

TODO doc

Returns

  • theta_or (numpy.ndarray) – For each orgin side of powerline, gives the voltage angle (in degree)

  • theta_ex (numpy.ndarray) – For each extremity side of powerline, gives the voltage angle (in degree)

  • load_theta (numpy.ndarray) – Gives the voltage angle (in degree) to the bus at which each load is connected

  • gen_theta (numpy.ndarray) – Gives the voltage angle (in degree) to the bus at which each generator is connected

  • storage_theta (numpy.ndarray) – Gives the voltage angle (in degree) to the bus at which each storage unit is connected

get_topo_vect()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.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.

As any function of the backend, it is not advised to use it directly. You can get this information in the grid2op.Observation.Observation.topo_vect instead.

Returns

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

Return type

numpy.ndarray dtype: int

lines_ex_info()[source]

INTERNAL

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 (in MW)

  • q_ex numpy.ndarray – the extremity reactive power flowing on the lines (in MVAr)

  • v_ex numpy.ndarray – the voltage magnitude at the extremity of each powerlines (in kV)

  • a_ex numpy.ndarray – the current flow at the extremity of each powerlines (in A)

lines_or_info()[source]

INTERNAL

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 (in MW)

  • q_or numpy.ndarray – the origin reactive power flowing on the lines (in MVAr)

  • v_or numpy.ndarray – the voltage magnitude at the origin of each powerlines (in kV)

  • a_or numpy.ndarray – the current flow at the origin of each powerlines (in A)

load_grid(path=None, filename=None)[source]

INTERNAL

Warning

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

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()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.load_p, grid2op.Observation.BaseObservation.load_q and grid2op.Observation.BaseObservation.load_v instead.

This method is used to retrieve information about the loads (active, reactive consumption and voltage magnitude of the bus to which it is connected).

Returns

  • load_p numpy.ndarray – The active power consumption for each load (in MW)

  • load_q numpy.ndarray – The reactive power consumption for each load (in MVAr)

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

reset(path=None, grid_filename=None)[source]

INTERNAL

Warning

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

Reload the grid. For pandapower, it is a bit faster to store of a copy of itself at the end of load_grid and deep_copy it to itself instead of calling load_grid again

runpf(is_dc=False)[source]

INTERNAL

Warning

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

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)[source]

INTERNAL

Warning

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

You might want to use it for debugging purpose only, and only if you develop yourself a backend.

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

shunt_info()[source]

INTERNAL

Warning

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

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.

storage_deact_for_backward_comaptibility()[source]

INTERNAL

Warning

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

This function is called under a very specific condition: an old environment has been loaded that do not take into account the storage units, even though they were possibly some modeled by the backend.

This function is supposed to “remove” from the backend any reference to the storage units.

Overloading this function is not necessary (when developing a new backend). If it is not overloaded however, some “backward compatibility” (for grid2op <= 1.4.0) might not be working properly depending on your backend.

storages_info()[source]

INTERNAL

Warning

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

Prefer using grid2op.Observation.BaseObservation.storage_power instead.

This method is used to retrieve information about the storage units (active, reactive consumption and voltage magnitude of the bus to which it is connected).

Returns

  • storage_p numpy.ndarray – The active power consumption for each load (in MW)

  • storage_q numpy.ndarray – The reactive power consumption for each load (in MVAr)

  • storage_v numpy.ndarray – The voltage magnitude of the bus to which each load is connected (in kV)

sub_from_bus_id(bus_id)[source]

INTERNAL

Warning

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

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

Parameters

bus_id (int) – The id of the bus where you want to know to which substation it belongs

Returns

Return type

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:

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