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 into comprehensive powergrid modifications that can be process by your “Simulator”. The simulator is responsible to perform the powerflow (AC or DC or Time Domain / Dynamic / Transient simulation) and to “translate back” the results (of the simulation) to grid2op.
More precisely, a backend should:
inform grid2op of the grid: which objects exist, where are they connected etc.
being able to process an object of type
grid2op.Action._backendAction._BackendAction
into some modification to your solver (NB these “BackendAction” are created by thegrid2op.Environment.BaseEnv
from the agent’s actions, the time series modifications, the maintenances, the opponent, etc. The backend is not responsible for their creation)being able to run a simulation (DC powerflow, AC powerflow or time domain / transient / dynamic)
expose (through some functions like
Backend.generators_info()
orBackend.loads_info()
) the state of some of the elements in the grid.
Note
A backend can model more elements than what can be controlled or modified in grid2op. For example, at time of writing, grid2op does not allow the modification of HVDC powerlines. But this does not mean that grid2op will not work if your grid counts such devices. It just means that grid2op will not be responsible for modifying them.
Note
A backend can expose only part of the grid to the environment / agent. For example, if you
give it as input a pan european grid but only want to study the grid of Netherlands or
France your backend can only “inform” grid2op (in the Backend.load_grid()
function)
that “only the Dutch (or French) grid” exists and leave out all other informations.
In this case grid2op will perfectly work, agents and environment will work as expected and be able to control the Dutch (or French) part of the grid and your backend implementation can control the rest (by directly updating the state of the solver).
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”, thenBackend.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
Then the Backend module:
Classes:
|
INTERNAL |
|
INTERNAL |
- class grid2op.Backend.Backend(detailed_infos_for_cascading_failures: bool = False, can_be_copied: bool = True, **kwargs)[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):
Backend.load_grid()
(called once per episode, or ifBackend.reset()
is implemented, once for the entirelifetime of the environment)
Backend.apply_action()
(called once per episode -initialization- and at least once per step)Backend.runpf()
(called once per episode -initialization- and at least once per step)Backend.get_topo_vect()
(called once per episode -initialization- and at least once per step)Backend.generators_info()
(called once per episode -initialization- and at least once per step)Backend.loads_info()
(called once per episode -initialization- and at least once per step)Backend.lines_or_info()
(called once per episode -initialization- and at least once per step)Backend.lines_ex_info()
(called once per episode -initialization- and at least once per step)
And optionally:
Backend.reset()
will reload the powergrid from the hard drive by default. This is rather slow and we recommend to overload it.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) [as of grid2op >= 1.7.1 it is no more required. If not implemented, you won’t be able to use some of grid2op feature however]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.
And, if the flag :attr:Backend.shunts_data_available` is set to
True
the methodBackend.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).- 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 an instance of Backend.
_aux_check_finite_float
(nb_[, str_])INTERNAL
_disconnect_line
(id_)INTERNAL
fill the name vectors (eg name_line) if not done already in the backend.
INTERNAL
INTERNAL
apply_action
(backendAction)INTERNAL
assert_grid_correct
([_local_dir_cls])INTERNAL
INTERNAL
New in version 1.10.0.
New in version 1.10.0.
INTERNAL
close
()INTERNAL
copy
()INTERNAL
INTERNAL
Get the action to set another backend to represent the internal state of this current backend.
INTERNAL
INTERNAL
INTERNAL
INTERNAL
INTERNAL
INTERNAL
INTERNAL
INTERNAL
load_grid
(path[, filename])INTERNAL
load_grid_layout
(path[, name])INTERNAL
load_redispacthing_data
(path[, name])INTERNAL
load_storage_data
(path[, name])INTERNAL
INTERNAL
make_complete_path
(path[, filename])Auxiliary function to retrieve the full path of the grid.
next_grid_state
(env[, is_dc])INTERNAL
reset
(path[, grid_filename])INTERNAL
runpf
([is_dc])INTERNAL
save_file
(full_path)INTERNAL
set_thermal_limit
(limits)INTERNAL
INTERNAL
INTERNAL
INTERNAL
sub_from_bus_id
(bus_id)INTERNAL
update_from_obs
(obs[, force_update])Takes an observation as input and update the internal state of self to match the state of the backend that produced this observation.
update_thermal_limit
(env)INTERNAL
update_thermal_limit_from_vect
(thermal_limit_a)You can use it if your backend stores the thermal limits of the grid in a vector (see
PandaPowerBackend
for example)Attributes:
New in version 1.10.0.
Return whether or not this backend has been loaded, that is if load_grid has been called or not with this instance.
- __init__(detailed_infos_for_cascading_failures: bool = False, can_be_copied: bool = True, **kwargs)[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_: float, str_: str | None = '') None [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_: int) None [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()
orBackend.get_line_flow()
for example. For example, if the current flow on powerline “l1” is the 42nd element of the vector returned byBackend.get_line_flow()
thenBackend._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
- _fill_names_obj()[source]
fill the name vectors (eg name_line) if not done already in the backend. This function is used to fill the name of an object of a class. It will also check the existence of these vectors in the class.
- _missing_two_busbars_support_info: bool
New in version 1.10.0.
A flag to indicate whether the
Backend.cannot_handle_more_than_2_busbar()
or theBackend.cannot_handle_more_than_2_busbar()
has been called whenBackend.load_grid()
was called. Starting from grid2op 1.10.0 this is a requirement (to ensure backward compatibility)
- _remove_my_attr_cls()[source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
This function is called at the end of
Backend.assert_grid_correct()
and it “cleans” the attribute of the backend object that are stored in the class now, to avoid discrepency between what has been read from the grid and what have been processed by grid2op (for example in “compatibility” mode, storage are deactivated, so self.n_storage would be different that type(self).n_storage)For this to work, the grid must first be initialized correctly, with the proper type (name of the environment in the class name !)
- _runpf_with_diverging_exception(is_dc: bool) Exception | None [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:
exc –
grid2op.Exceptions.DivergingPowerflow
: In case of divergence of the powerflow
- abstractmethod apply_action(backendAction: _BackendAction | None) None [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:
backendAction – the action to be implemented on the powergrid.
- Returns:
None
- assert_grid_correct(_local_dir_cls=None) None [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() None [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.
- can_handle_more_than_2_busbar()[source]
New in version 1.10.0.
This function should be called once in
Backend.load_grid()
if your backend is able to handle more than 2 busbars per substation.If not called, then the environment will not be able to use more than 2 busbars per substations.
Note
From grid2op 1.10.0 it is preferable that your backend calls one of
Backend.can_handle_more_than_2_busbar()
orBackend.cannot_handle_more_than_2_busbar()
.If not, then the environments created with your backend will not be able to “operate” grid with more than 2 busbars per substation.
Danger
We highly recommend you do not try to override this function.
At least, at time of writing I can’t find any good reason to do so.
- cannot_handle_more_than_2_busbar()[source]
New in version 1.10.0.
This function should be called once in
Backend.load_grid()
if your backend is NOT able to handle more than 2 busbars per substation.If not called, then the environment will not be able to use more than 2 busbars per substations.
Note
From grid2op 1.10.0 it is preferable that your backend calls one of
Backend.can_handle_more_than_2_busbar()
orBackend.cannot_handle_more_than_2_busbar()
.If not, then the environments created with your backend will not be able to “operate” grid with more than 2 busbars per substation.
Danger
We highly recommend you do not try to override this function.
Atleast, at time of writing I can’t find any good reason to do so.
- check_kirchoff() Tuple[ndarray, ndarray, ndarray, ndarray, ndarray] [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()
andBackend.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() None [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() Self [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Note
As of grid2op 1.7.1 you it is not mandatory to implement this function when creating a backend.
If it is not available, then grid2op will automatically deactivate the forecast capability and will not use the “backend.copy()” function.
When this function is not implement, you will not be able to use (for example)
grid2op.Observation.BaseObservation.simulate()
nor thegrid2op.simulator.Simulator
for example.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:
def copy(self): return copy.deepcopy(self)
- Returns:
An instance of Backend equal to
self
, but deep copied.- Return type:
- abstractmethod generators_info() Tuple[ndarray, ndarray, ndarray] [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.gen_p
,grid2op.Observation.BaseObservation.gen_q
andgrid2op.Observation.BaseObservation.gen_v
instead.Note
It is called after the solver has been ran, only in case of success (convergence).
This method is used to retrieve information about the generators (active, reactive production and voltage magnitude of the bus to which it is connected).
Note
The values returned here are the values AFTER the powerflow has been computed and not the target values.
- 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() CompleteAction [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:
- get_line_flow() ndarray [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.a_or
orgrid2op.Observation.BaseObservation.a_ex
for exampleReturn the current flow in each lines of the powergrid. Only one value per powerline is returned.
Note
It is called after the solver has been ran, only in case of success (convergence).
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 side” of powerline “l2” then this method shall return the current flow of at the “origin side” of powerline l2.
Note that in general, there is no loss of generality in supposing all protections are set on the “origin side” 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() ndarray [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 atgrid2op.Observation.BaseObservation.timestep_overflow
and check the non zero index.Note
It is called after the solver has been ran, only in case of success (convergence).
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() ndarray [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.line_status
insteadNote
It is called after the solver has been ran, only in case of success (convergence).
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 byBackend.get_line_flow()
for example.- Returns:
an array with the line status of each powerline
- Return type:
np.array, dtype:bool
- get_relative_flow() ndarray [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.rho
Note
It is called after the solver has been ran, only in case of success (convergence).
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() ndarray [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() Tuple[ndarray, ndarray, ndarray, ndarray] [source]
Note
It is called after the solver has been ran, only in case of success (convergence).
Notes
Don’t forget to set the flag
Backend.can_output_theta
toTrue
in theBakcend.load_grid()
if you support this feature.- Returns:
line_or_theta (
numpy.ndarray
) – For each origin side of powerline, gives the voltage angleline_ex_theta (
numpy.ndarray
) – For each extremity side of powerline, gives the voltage angleload_theta (
numpy.ndarray
) – Gives the voltage angle to the bus at which each load is connectedgen_theta (
numpy.ndarray
) – Gives the voltage angle to the bus at which each generator is connectedstorage_theta (
numpy.ndarray
) – Gives the voltage angle to the bus at which each storage unit is connected
- abstractmethod get_topo_vect() ndarray [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
.Note
It is called after the solver has been ran, only in case of success (convergence).
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, storage) as there are in the powergrid.
For each elements, it gives on which bus it is connected in its substation (after the solver has ran)
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
- property is_loaded: bool
Return whether or not this backend has been loaded, that is if load_grid has been called or not with this instance.
- abstractmethod lines_ex_info() Tuple[ndarray, ndarray, ndarray, ndarray] [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.p_ex
,grid2op.Observation.BaseObservation.q_ex
,grid2op.Observation.BaseObservation.a_ex
and,grid2op.Observation.BaseObservation.v_ex
insteadNote
It is called after the solver has been ran, only in case of success (convergence).
It returns the information extracted from the _grid at the extremity side 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() Tuple[ndarray, ndarray, ndarray, ndarray] [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.p_or
,grid2op.Observation.BaseObservation.q_or
,grid2op.Observation.BaseObservation.a_or
and,grid2op.Observation.BaseObservation.v_or
insteadNote
It is called after the solver has been ran, only in case of success (convergence).
It returns the information extracted from the _grid at the origin side 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: PathLike | str, filename: PathLike | str | None = None) 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 thegrid2op.Space.GridObjects
is properly set up. See the description ofgrid2op.Space.GridObjects
to know which attributes should be set here and which should not.- Parameters:
path (
string
) – the path to find the powergridfilename (
string
, optional) – the filename of the powergrid
- Returns:
None
- load_grid_layout(path: PathLike | str, name: str | None = 'grid_layout.json') None [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
) – TODOname (
str
) – TODO
- load_redispacthing_data(path: PathLike | str, name: str | None = 'prods_charac.csv') None [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.
Notes
Before you use this function, make sure the names of the generators are properly set.
For example you can either read them from the grid (setting self.name_gen) or call self._fill_names_obj() beforehand (this later is done in the environment.)
- 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: PathLike | str, name: str | None = 'storage_units_charac.csv') None [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.
Notes
Before you use this function, make sure the names of the generators are properly set.
For example you can either read them from the grid (setting self.name_gen) or call self._fill_names_obj() beforehand (this later is done in the environment.)
- 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() Tuple[ndarray, ndarray, ndarray] [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
andgrid2op.Observation.BaseObservation.load_v
instead.Note
It is called after the solver has been ran, only in case of success (convergence).
This method is used to retrieve information about the loads (active, reactive consumption and voltage magnitude of the bus to which it is connected).
Note
The values returned here are the values AFTER the powerflow has been computed and not the target values.
- 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)
- make_complete_path(path: PathLike | str, filename: PathLike | str | None = None) str [source]
Auxiliary function to retrieve the full path of the grid.
It is best used at the beginning of the load_grid function of a backend.
- Returns:
_description_
- Return type:
_type_
- Raises:
Grid2OpException – _description_
Grid2OpException – _description_
- next_grid_state(env: BaseEnv, is_dc: bool | None = 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.
- 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 returnsTrue
if the powerline has been disconnected due to a cascading failure orFalse
otherwise.infos (
list
) – IfBackend.detailed_infos_for_cascading_failures
isTrue
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(path: PathLike | str, grid_filename: PathLike | str | None = None) 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: bool = False) Tuple[bool, Exception | None] [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: PathLike | str) None [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: ndarray | Dict[str, float]) None [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() Tuple[ndarray, ndarray, ndarray, ndarray] [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Note
It is called after the solver has been ran, only in case of success (convergence).
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 methodBackend.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() None [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() Tuple[ndarray, ndarray, ndarray] [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: int) int [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- Return type:
The substation to which an object connected to bus with id bus_id is connected to.
- update_from_obs(obs: CompleteObservation, force_update: bool | None = False)[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.force_update (bool) – If set to
True
the backend will be updated without checking the type of the observation you used. This is dangerous. Default value isFalse
(safe).
- update_thermal_limit(env: BaseEnv) None [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
- update_thermal_limit_from_vect(thermal_limit_a: ndarray) None [source]
You can use it if your backend stores the thermal limits of the grid in a vector (see
PandaPowerBackend
for example)Warning
This is not called by the environment and cannot be used to model Dynamic Line Rating. For such purpose please use update_thermal_limit
This function is used to create a “Simulator” from a backend for example.
- Parameters:
vect (np.ndarray) – The thermal limits (in A)
- class grid2op.Backend.PandaPowerBackend(detailed_infos_for_cascading_failures: bool = False, lightsim2grid: bool = False, dist_slack: bool = False, max_iter: int = 10, can_be_copied: bool = True, with_numba: bool = 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 side 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 side of the powerlines
- Type:
numpy.array
, dtype:float
- p_or
The active power flowing at the origin side of each powerline
- Type:
numpy.array
, dtype:float
- q_or
The reactive power flowing at the origin side 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 side of each powerline
- Type:
numpy.array
, dtype:float
- p_ex
The active power flowing at the extremity side of each powerline
- Type:
numpy.array
, dtype:float
- q_ex
The reactive power flowing at the extremity side of each powerline
- Type:
numpy.array
, dtype:float
- a_ex
The current flowing at the extremity side 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 an instance of Backend.
run a powerflow when the file is being loaded.
This function check for elements in the pandapower grid that will have no impact on grid2op.
_convert_id_topo
(id_big_topo)INTERNAL
_disconnect_line
(id_)INTERNAL
apply_action
(backendAction)INTERNAL
close
()INTERNAL
copy
()INTERNAL
INTERNAL
INTERNAL
INTERNAL
INTERNAL
TODO doc
INTERNAL
INTERNAL
INTERNAL
load_grid
(path[, filename])INTERNAL
INTERNAL
reset
(path[, grid_filename])INTERNAL
runpf
([is_dc])INTERNAL
save_file
(full_path)INTERNAL
INTERNAL
INTERNAL
INTERNAL
sub_from_bus_id
(bus_id)INTERNAL
- __init__(detailed_infos_for_cascading_failures: bool = False, lightsim2grid: bool = False, dist_slack: bool = False, max_iter: int = 10, can_be_copied: bool = True, with_numba: bool = 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_run_pf_init()[source]
run a powerflow when the file is being loaded. This is called three times for each call to “load_grid”
- _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()
orBackend.get_line_flow()
for example. For example, if the current flow on powerline “l1” is the 42nd element of the vector returned byBackend.get_line_flow()
thenBackend._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: _BackendAction | None) 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.
- close() None [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() PandaPowerBackend [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
This should return a deep copy of the Backend itself and not just the self._grid
- generators_info() Tuple[ndarray, ndarray, ndarray] [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.gen_p
,grid2op.Observation.BaseObservation.gen_q
andgrid2op.Observation.BaseObservation.gen_v
instead.Note
It is called after the solver has been ran, only in case of success (convergence).
This method is used to retrieve information about the generators (active, reactive production and voltage magnitude of the bus to which it is connected).
Note
The values returned here are the values AFTER the powerflow has been computed and not the target values.
- 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() ndarray [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.a_or
orgrid2op.Observation.BaseObservation.a_ex
for exampleReturn the current flow in each lines of the powergrid. Only one value per powerline is returned.
Note
It is called after the solver has been ran, only in case of success (convergence).
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 side” of powerline “l2” then this method shall return the current flow of at the “origin side” of powerline l2.
Note that in general, there is no loss of generality in supposing all protections are set on the “origin side” 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() ndarray [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() int [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() Tuple[ndarray, ndarray, ndarray, ndarray] [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 connectedgen_theta (
numpy.ndarray
) – Gives the voltage angle (in degree) to the bus at which each generator is connectedstorage_theta (
numpy.ndarray
) – Gives the voltage angle (in degree) to the bus at which each storage unit is connected
- get_topo_vect() ndarray [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
.Note
It is called after the solver has been ran, only in case of success (convergence).
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, storage) as there are in the powergrid.
For each elements, it gives on which bus it is connected in its substation (after the solver has ran)
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() Tuple[ndarray, ndarray, ndarray, ndarray] [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.p_ex
,grid2op.Observation.BaseObservation.q_ex
,grid2op.Observation.BaseObservation.a_ex
and,grid2op.Observation.BaseObservation.v_ex
insteadNote
It is called after the solver has been ran, only in case of success (convergence).
It returns the information extracted from the _grid at the extremity side 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() Tuple[ndarray, ndarray, ndarray, ndarray] [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Prefer using
grid2op.Observation.BaseObservation.p_or
,grid2op.Observation.BaseObservation.q_or
,grid2op.Observation.BaseObservation.a_or
and,grid2op.Observation.BaseObservation.v_or
insteadNote
It is called after the solver has been ran, only in case of success (convergence).
It returns the information extracted from the _grid at the origin side 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: PathLike | str, filename: PathLike | str | None = None) 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() Tuple[ndarray, ndarray, ndarray] [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
andgrid2op.Observation.BaseObservation.load_v
instead.Note
It is called after the solver has been ran, only in case of success (convergence).
This method is used to retrieve information about the loads (active, reactive consumption and voltage magnitude of the bus to which it is connected).
Note
The values returned here are the values AFTER the powerflow has been computed and not the target values.
- 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: PathLike | str, grid_filename: PathLike | str | None = None) 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: bool = False) Tuple[bool, Exception | None] [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: PathLike | str) None [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() Tuple[ndarray, ndarray, ndarray, ndarray] [source]
INTERNAL
Warning
/!\ Internal, do not use unless you know what you are doing /!\
Note
It is called after the solver has been ran, only in case of success (convergence).
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 methodBackend.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() None [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() Tuple[ndarray, ndarray, ndarray] [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: int) int [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- 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