ChronicsHandler¶
-
class
grid2op.Chronics.
ChangeNothing
(time_interval=datetime.timedelta(0, 300), max_iter=- 1, start_datetime=datetime.datetime(2019, 1, 1, 0, 0), chunk_size=None, **kargs)[source]¶ This class is the most basic class to modify a powergrid values. It does nothing exceptie increasing
GridValue.max_iter
and theGridValue.current_datetime
.-
check_validity
(backend)[source]¶ - Parameters
backend (
grid2op.Backend
) – The backend, not used here.- Returns
res – Always
True
. As this doesn’t change the powergird, there is no way to make invalid changed.- Return type
bool
-
initialize
(order_backend_loads, order_backend_prods, order_backend_lines, order_backend_subs, names_chronics_to_backend=None)[source]¶ This function is used to initialize the data generator. It can be use to load scenarios, or to initialize noise if scenarios are generated on the fly. It must also initialize
GridValue.maintenance_time
,GridValue.maintenance_duration
andGridValue.hazard_duration
.This function should also increment
GridValue.curr_iter
of 1 each time it is called.The
GridValue
is what makes the connection between the data (generally in a shape of files on the hard drive) and the power grid. One of the main advantage of the Grid2Op package is its ability to change the tool that computes the load flows. Generally, suchgrid2op.Backend
expects data in a specific format that is given by the way their internal powergrid is represented, and in particular, the “same” objects can have different name and different position. To ensure that the same chronics would produce the same results on every backend (ie regardless of the order of which the Backend is expecting the data, the outcome of the powerflow is the same) we encourage the user to provide a file that maps the name of the object in the chronics to the name of the same object in the backend.This is done with the “names_chronics_to_backend” dictionnary that has the following keys:
“loads”
“prods”
“lines”
The value associated to each of these keys is in turn a mapping dictionnary from the chronics to the backend. This means that each keys of these subdictionnary is a name of one column in the files, and each values is the corresponding name of this same object in the dictionnary. An example is provided bellow.
- Parameters
order_backend_loads (
numpy.ndarray
, dtype:str) – Ordered name, in the Backend, of the loads. It is required that agrid2op.Backend
object always output the informations in the same order. This array gives the name of the loads following this order. See the documentation ofgrid2op.Backend
for more information about this.order_backend_prods (
numpy.ndarray
, dtype:str) – Same as order_backend_loads, but for generators.order_backend_lines (
numpy.ndarray
, dtype:str) – Same as order_backend_loads, but for powerline.order_backend_subs (
numpy.ndarray
, dtype:str) – Same as order_backend_loads, but for powerline.names_chronics_to_backend (
dict
) – See in the description of the method for more information about its format.
- Returns
- Return type
None
Examples
For example, suppose we have a
grid2op.Backend
with:substations ids strart from 0 to N-1 (N being the number of substations in the powergrid)
loads named “load_i” with “i” the subtations to which it is connected
generators units named “gen_i” (i still the substation id to which it is connected)
powerlnes are named “i_j” if it connected substations i to substation j
And on the other side, we have some files with the following conventions:
substations are numbered from 1 to N
loads are named “i_C” with i being the substation to which it is connected
generators are named “i_G” with is being the id of the substations to which it is connected
powerlines are namesd “i_j_k” where i is the origin substation, j the extremity substations and “k” is a unique identifier of this powerline in the powergrid.
In this case, instead of renaming the powergrid (in the backend) of the data files, it is advised to build the following elements and initialize the object gridval of type
GridValue
with:gridval = GridValue() # Note: this code won't execute because "GridValue" is an abstract class order_backend_loads = ['load_1', 'load_2', 'load_13', 'load_3', 'load_4', 'load_5', 'load_8', 'load_9', 'load_10', 'load_11', 'load_12'] order_backend_prods = ['gen_1', 'gen_2', 'gen_5', 'gen_7', 'gen_0'] order_backend_lines = ['0_1', '0_4', '8_9', '8_13', '9_10', '11_12', '12_13', '1_2', '1_3', '1_4', '2_3', '3_4', '5_10', '5_11', '5_12', '3_6', '3_8', '4_5', '6_7', '6_8'] order_backend_subs = ['sub_0', 'sub_1', 'sub_10', 'sub_11', 'sub_12', 'sub_13', 'sub_2', 'sub_3', 'sub_4', 'sub_5', 'sub_6', 'sub_7', 'sub_8', 'sub_9'] names_chronics_to_backend = {"loads": {"2_C": 'load_1', "3_C": 'load_2', "14": 'load_13', "4_C": 'load_3', "5_C": 'load_4', "6_C": 'load_5', "9_C": 'load_8', "10_C": 'load_9', "11_C": 'load_10', "12_C": 'load_11', "13_C": 'load_12'}, "lines": {'1_2_1': '0_1', '1_5_2': '0_4', '9_10_16': '8_9', '9_14_17': '8_13', '10_11_18': '9_10', '12_13_19': '11_12', '13_14_20': '12_13', '2_3_3': '1_2', '2_4_4': '1_3', '2_5_5': '1_4', '3_4_6': '2_3', '4_5_7': '3_4', '6_11_11': '5_10', '6_12_12': '5_11', '6_13_13': '5_12', '4_7_8': '3_6', '4_9_9': '3_8', '5_6_10': '4_5', '7_8_14': '6_7', '7_9_15': '6_8'}, "prods": {"1_G": 'gen_0', "3_G": "gen_2", "6_G": "gen_5", "2_G": "gen_1", "8_G": "gen_7"}, } gridval.initialize(order_backend_loads, order_backend_prods, order_backend_lines, names_chronics_to_backend)
-
load_next
()[source]¶ This function does nothing but the two requirements of load_next ie:
increasing
GridValue.curr_iter
of 1increasing
GridValue.current_datetime
- Returns
timestamp (
datetime.datetime
) – The current timestamp for which the modifications have been generated.dict_ (
dict
) – Always empty, indicating i do nothing.maintenance_time (
numpy.ndarray
, dtype:int
) – Information about the next planned maintenance. SeeGridValue.maintenance_time
for more information.maintenance_duration (
numpy.ndarray
, dtype:int
) – Information about the duration of next planned maintenance. SeeGridValue.maintenance_duration
for more information.hazard_duration (
numpy.ndarray
, dtype:int
) – Information about the current hazard. SeeGridValue.hazard_duration
for more information.
-
next_chronics
()[source]¶ Restarts:
GridValue.current_datetime
to its origin value ( 2019 / 01 / 01)GridValue.curr_iter
to 0
-
-
class
grid2op.Chronics.
ChronicsHandler
(chronicsClass=<class 'grid2op.Chronics.ChangeNothing.ChangeNothing'>, time_interval=datetime.timedelta(0, 300), max_iter=-1, **kwargs)[source]¶ Represents a Chronics handler that returns a grid state.
As stated previously, it is not recommended to make an directly an object from the class
GridValue
. This utility will ensure that the creation of such objects are properly made.The types of chronics used can be specified in the
ChronicsHandler.chronicsClass
attribute.-
chronicsClass
¶ Type of chronics that will be loaded and generated. Default is
ChangeNothing
(NB the class, and not an object / instance of the class should be send here.) This should be a derived class fromGridValue
.- Type
type
, optional
-
kwargs
¶ key word arguments that will be used to build new chronics.
- Type
dict
, optional
-
max_iter
¶ Maximum number of iterations per episode.
- Type
int
, optional
-
real_data
¶ An instance of type given by
ChronicsHandler.chronicsClass
.- Type
-
path
¶ path where the data are located.
- Type
str
(or None)
-
check_validity
(backend)[source]¶ This method ensure the data are valid and compatible with the backend used.
See definition of
GridValue.check_validity()
for more information about this method.- Returns
- Return type
None
-
done
()[source]¶ This method returns whether or not the episode is done.
See definition of
GridValue.done()
for more information about this method.
-
forecasts
()[source]¶ This method returns the forecasts of the data.
See definition of
GridValue.forecasts()
for more information about this method.
-
get_id
()[source]¶ This method gives a unique identifier for the current episode.
See definition of
GridValue.get_id()
for more information about this method.
-
get_name
()[source]¶ This method retrieve a unique name that is used to serialize episode data on disk.
See definition of
EpisodeData
for more information about this method.
-
initialize
(order_backend_loads, order_backend_prods, order_backend_lines, order_backend_subs, names_chronics_to_backend=None)[source]¶ After being loaded, this method will initialize the data.
See definition of
GridValue.initialize()
for more information about this method.- Returns
- Return type
None
-
max_timestep
()[source]¶ This method gives the maximum number of time step an episode can last.
See definition of
GridValue.max_timestep()
for more information about this method.
-
next_chronics
()[source]¶ This method is called when changing the episode after game over or after it has reached the end.
See definition of
GridValue.next_chronics()
for more information about this method.
-
next_time_step
()[source]¶ This method returns the modification of the powergrid at the next time step for the same episode.
See definition of
GridValue.load_next()
for more information about this method.
-
set_chunk_size
(new_chunk_size)[source]¶ This functions allows to adjust dynamically the chunk size when reading the data.
NB this function is not supported by all data generating process.
- Parameters
new_chunk_size (
int
orNone
) – The new chunk size
-
set_max_iter
(max_iter)[source]¶ This function is used to set the maximum number of iterations possible before the chronics ends.
- Parameters
max_iter (
int
) – The maximum number of timestep in the chronics.
-
shuffle
(shuffler)[source]¶ Will attempt to shuffle the underlying data.
Note that a call to this function might not do anything is the
GridValue.shuffle()
is not implemented forChronicsHandler.real_data
.- Parameters
shuffler (
object
) – Anything that is used to shuffle the data.
-
tell_id
(id_num)[source]¶ This method is called when setting a given episode after game over or after it has reached the end.
See definition of
GridValue.tell_id()
for more information about this method.
-
-
class
grid2op.Chronics.
GridStateFromFile
(path, sep=';', time_interval=datetime.timedelta(0, 300), max_iter=- 1, start_datetime=datetime.datetime(2019, 1, 1, 0, 0), chunk_size=None)[source]¶ Read the injections values from a file stored on hard drive. More detailed about the files is provided in the
GridStateFromFile.initialize()
method.This class reads only files stored as csv. The header of the csv is mandatory and should represent the name of the objects. This names should either be matched to the name of the same object in the backend using the names_chronics_to_backend argument pass into the
GridStateFromFile.initialize()
(seeGridValue.initialize()
for more information) or match the names of the object in the backend.When the grid value is initialized, all present csv are read, sorted in order compatible with the backend and extracted as numpy array.
For now, the current date and times are not read from file. It is mandatory that the chronics starts at 00:00 and its first time stamps is corresponds to January, 1st 2019.
Chronics read from this files don’t implement the “forecast” value.
In this values, only 1 episode is stored. If the end of the episode is reached and another one should start, then it will loop from the beginning.
-
path
¶ The path of the folder where the data are stored. It is recommended to set absolute path, and not relative paths.
- Type
str
-
load_p
¶ All the values of the load active values
- Type
numpy.ndarray
, dtype:float
-
load_q
¶ All the values of the load reactive values
- Type
numpy.ndarray
, dtype:float
-
prod_p
¶ All the productions setpoint active values.
- Type
numpy.ndarray
, dtype:float
-
prod_v
¶ All the productions setpoint voltage magnitude values.
- Type
numpy.ndarray
, dtype:float
-
hazards
¶ This vector represents the possible hazards. It is understood as:
True
there is a hazard for the given powerline,False
there is not.- Type
numpy.ndarray
, dtype:bool
-
maintenance
¶ This vector represents the possible maintenance. It is understood as:
True
there is a maintenance for the given powerline,False
there is not.- Type
numpy.ndarray
, dtype:bool
-
current_index
¶ The index of the last observation sent to the
grid2op.Environment
.- Type
int
-
sep
¶ The csv columns separator. By defaults it’s “;”
- Type
str
, optional
-
names_chronics_to_backend
¶ This directory matches the name of the objects (line extremity, generator or load) to the same object in the backed. See the help of
GridValue.initialize()
for more information).- Type
dict
-
check_validity
(backend)[source]¶ A call to this method ensure that the action that will be sent to the current
grid2op.Environment
can be properly implemented by itsgrid2op.Backend
. This specific method check that the dimension of all vectors are consistent- Parameters
backend (
grid2op.Backend.Backend
) – The backend used by thegrid2op.Environment.Environment
- Returns
- Return type
None
-
done
()[source]¶ Compare to
GridValue.done()
an episode can be over for 2 main reasons:GridValue.max_iter
has been reachedThere are no data in the csv.
The episode is done if one of the above condition is met.
- Returns
res – Whether the episode has reached its end or not.
- Return type
bool
-
get_id
() → str[source]¶ Utility to get the current name of the path of the data are looked at, if data are files.
This could also be used to return a unique identifier to the generated chronics even in the case where they are generated on the fly, for example by return a hash of the seed.
- Returns
res – A unique identifier of the chronics generated for this episode. For example, if the chronics comes from a specific folder, this could be the path to this folder.
- Return type
str
-
initialize
(order_backend_loads, order_backend_prods, order_backend_lines, order_backend_subs, names_chronics_to_backend=None)[source]¶ In this function, the numpy arrays are read from the csv using the panda.dataframe engine.
In order to be valid, the folder located at
GridStateFromFile.path
should at least contain:a file named “load_p.csv” used to initialize
GridStateFromFile.load_p
a file named “load_q.csv” used to initialize
GridStateFromFile.load_q
a file named “prod_p.csv” used to initialize
GridStateFromFile.prod_p
a file named “prod_v.csv” used to initialize
GridStateFromFile.prod_v
a file named “hazards.csv” used to initialize
GridStateFromFile.hazards
a file named “maintenance.csv” used to initialize
GridStateFromFile.maintenance
All these csv must have the same separator specified by
GridStateFromFile.sep
.If a file named “start_datetime.info” is present, then it will be used to initialized
GridStateFromFile.start_datetime
. If this file exists, it should count only one row, with the initial datetime in the “%Y-%m-%d %H:%M” format.If a file named “time_interval.info” is present, then it will be used to initialized the
GridStateFromFile.time_interval
attribute. If this file exists, it should count only one row, with the initial datetime in the “%H:%M” format. Only timedelta composed of hours and minutes are supported (time delta cannot go above 23 hours 55 minutes and cannot be smaller than 0 hour 1 minutes)The first row of these csv is understood as the name of the object concerned by the column. Either this name is present in the
grid2op.Backend
, in this case no modification is performed, or in case the name is not found in the backend and in this case it must be specified in the “names_chronics_to_backend” parameters how to understand it. See the help ofGridValue.initialize()
for more information about this dictionnary.All files should have the same number of rows.
:param See help of
GridValue.initialize()
for a detailed help about the parameters.:- Returns
- Return type
None
-
load_next
()[source]¶ Generate the next values, either by reading from a file, or by generating on the fly and return a dictionnary compatible with the
grid2op.BaseAction
class allowed for theEnvironment
.More information about this dictionnary can be found at
grid2op.BaseAction.update()
.As a (quick) reminder: this dictionnary has for keys:
“injection” (optional): a dictionnary with keys (optional) “load_p”, “load_q”, “prod_p”, “prod_v”
“hazards” (optional) : the outage suffered from the _grid
“maintenance” (optional) : the maintenance operations planned on the grid for the current time step.
- Returns
timestamp (
datetime.datetime
) – The current timestamp for which the modifications have been generated.dict_ (
dict
) – A dictionnary understandable by the :grid2op.BaseAction.update()
method. NB this function should return the dictionnary that will be converted, is should not, in any case, return an action.maintenance_time (
numpy.ndarray
, dtype:int
) – Information about the next planned maintenance. SeeGridValue.maintenance_time
for more information.maintenance_duration (
numpy.ndarray
, dtype:int
) – Information about the duration of next planned maintenance. SeeGridValue.maintenance_duration
for more information.hazard_duration (
numpy.ndarray
, dtype:int
) – Information about the current hazard. SeeGridValue.hazard_duration
for more information.
- Raises
StopIteration – if the chronics is over
-
next_chronics
()[source]¶ Load the next batch of chronics. This function is called after an episode has finished by the
grid2op.Environment
or thegrid2op.Runner
.A call to this function should also reset
GridValue.curr_iter
to 0. :returns: :rtype:None
-
-
class
grid2op.Chronics.
GridStateFromFileWithForecasts
(path, sep=';', time_interval=datetime.timedelta(0, 300), max_iter=- 1, chunk_size=None)[source]¶ An extension of
GridStateFromFile
that implements the “forecast” functionality.Forecast are also read from a file. For this class, only 1 forecast per timestep is read. The “forecast” present in the file at row $i$ is the one available at the corresponding time step, so valid for the grid state at the next time step.
To have more advanced forecasts, this class could be overridden.
-
load_p_forecast
¶ Array used to store the forecasts of the load active values.
- Type
numpy.ndarray
, dtype:float
-
load_q_forecast
¶ Array used to store the forecasts of the load reactive values.
- Type
numpy.ndarray
, dtype:float
-
prod_p_forecast
¶ Array used to store the forecasts of the generator active production setpoint.
- Type
numpy.ndarray
, dtype:float
-
prod_v_forecast
¶ Array used to store the forecasts of the generator voltage magnitude setpoint.
- Type
numpy.ndarray
, dtype:float
-
maintenance_forecast
¶ Array used to store the forecasts of the _maintenance operations.
- Type
numpy.ndarray
, dtype:float
-
check_validity
(backend)[source]¶ A call to this method ensure that the action that will be sent to the current
grid2op.Environment
can be properly implemented by itsgrid2op.Backend
. This specific method check that the dimension of all vectors are consistent- Parameters
backend (
grid2op.Backend.Backend
) – The backend used by thegrid2op.Environment.Environment
- Returns
- Return type
None
-
forecasts
()[source]¶ This is the major difference between
GridStateFromFileWithForecasts
andGridStateFromFile
. It returns non empty forecasts.As explained in the
GridValue.forecasts()
, forecasts are made of list of tuple. Each tuple having exactly 2 elements:Is the time stamp of the forecast
An
grid2op.BaseAction
representing the modification of the powergrid after the forecast.
For this class, only the forecast of the next time step is given, and only for the injections and maintenance.
- Returns
- Return type
See
GridValue.forecasts()
for more information.
-
get_id
() → str[source]¶ Utility to get the current name of the path of the data are looked at, if data are files.
This could also be used to return a unique identifier to the generated chronics even in the case where they are generated on the fly, for example by return a hash of the seed.
- Returns
res – A unique identifier of the chronics generated for this episode. For example, if the chronics comes from a specific folder, this could be the path to this folder.
- Return type
str
-
initialize
(order_backend_loads, order_backend_prods, order_backend_lines, order_backend_subs, names_chronics_to_backend=None)[source]¶ The same condition as
GridStateFromFile.initialize
applies also forGridStateFromFileWithForecasts.load_p_forecast
,GridStateFromFileWithForecasts.load_q_forecast
,GridStateFromFileWithForecasts.prod_p_forecast
,GridStateFromFileWithForecasts.prod_v_forecast
andGridStateFromFileWithForecasts.maintenance_forecast
.:param See help of
GridValue.initialize()
for a detailed help about the _parameters.:- Returns
- Return type
None
-
-
class
grid2op.Chronics.
GridValue
(time_interval=datetime.timedelta(0, 300), max_iter=- 1, start_datetime=datetime.datetime(2019, 1, 1, 0, 0), chunk_size=None)[source]¶ This is the base class for every kind of data for the _grid.
It allows the
grid2op.Environment
to perform powergrid modification that make the “game” time dependant.It is not recommended to directly create
GridValue
object, but to use thegrid2op.Environment.chronics_handler" for such a purpose. This is made in an attempt to make sure the :func:`GridValue.initialize
is called. Before this initialization, it is not recommended to use anyGridValue
object.The method
GridValue.next_chronics()
should be used between two epoch of the game. If there are no more data to be generated from this object, thenGridValue.load_next()
should raise aStopIteration
exception and a call toGridValue.done()
should return True.-
time_interval
¶ Time interval between 2 consecutive timestamps. Default 5 minutes.
- Type
datetime.timedelta
-
start_datetime
¶ The datetime of the first timestamp of the scenario.
- Type
datetime.datetime
-
current_datetime
¶ The timestamp of the current scenario.
- Type
datetime.datetime
-
n_gen
¶ Number of generators in the powergrid
- Type
int
-
n_load
¶ Number of loads in the powergrid
- Type
int
-
n_line
¶ Number of powerline in the powergrid
- Type
int
-
max_iter
¶ Number maximum of data to generate for one episode.
- Type
int
-
curr_iter
¶ Duration of the current episode.
- Type
int
-
maintenance_time
¶ Number of time steps the next maintenance will take place with the following convention:
-1 no maintenance are planned for the forseeable future
0 a maintenance is taking place
1, 2, 3 … a maintenance will take place in 1, 2, 3, … time step
Some examples are given in
GridValue.maintenance_time_1d()
.- Type
numpy.ndarray
, dtype:int
-
maintenance_duration
¶ Duration of the next maintenance. 0 means no maintenance is happening. If a maintenance is planned for a given powerline, this number decreases each time step, up until arriving at 0 when the maintenance is over. Note that if a maintenance is planned (see
GridValue.maintenance_time
) this number indicates how long the maintenance will last, and does not suppose anything on the maintenance taking place or not (= there can be positive number here without a powerline being removed from the grid for maintenance reason). Some examples are given inGridValue.maintenance_duration_1d()
.- Type
numpy.ndarray
, dtype:int
-
hazard_duration
¶ Duration of the next hzard. 0 means no maintenance is happening. If a hazard is taking place for a given powerline, this number decreases each time step, up until arriving at 0 when the maintenance is over. On the contrary to
GridValue.maintenance_duration
, if a component of this vector is higher than 1, it means that the powerline is out of service. Some examples are given inGridValue.get_hazard_duration_1d()
.- Type
numpy.ndarray
, dtype:int
-
abstractmethod
check_validity
(backend)[source]¶ To make sure that the data returned by this class are of the proper dimension, a call to this method must be performed before actually using the data generated by this class.
In the grid2op framework, this is ensure because the
grid2op.Environment
calls this method in its initialization.- Parameters
backend (
grid2op.Backend
) – The backend used by the :class;`Environment`.
-
done
()[source]¶ Whether the episode is over or not.
- Returns
done –
True
means the episode has arrived to the end (no more data to generate)False
means that the episode is not over yet.- Return type
bool
-
forecasts
()[source]¶ This method is used to generate the forecasts that are made available to the
grid2op.BaseAgent
. This forecasts are behaving the same way than a list of tuple as the one returned byGridValue.load_next()
method.The way they are generated depends on the GridValue class. If not forecasts are made available, then the empty list should be returned.
- Returns
res – Each element of this list having the same type as what is returned by
GridValue.load_next()
.- Return type
list
-
staticmethod
get_hazard_duration_1d
(hazard)[source]¶ This function allows to transform a 1d numpy aarray maintenance (or hazards), where is specify:
0 there is no maintenance at this time step
1 there is a maintenance at this time step
Into the representation in terms of “hzard duration” as specified in
GridValue.maintenance_duration
which is:0 no forseeable hazard operation will be performed
- 1, 2 etc. is the number of time step the next hzard will last (it is positive only when a hazard
affect a given powerline)
Compared to
GridValue.get_maintenance_duration_1d()
we only know when the hazard occurs how long it will last.- Parameters
maintenance (
numpy.ndarray
) – 1 dimensional array representing the time series of the maintenance (0 there is no maintenance, 1 there is a maintenance at this time step)- Returns
maintenance_duration – Array representing the time series of the duration of the next maintenance forseeable.
- Return type
numpy.ndarray
Examples
If no maintenance are planned:
hazard = np.array([0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]) hazard_duration = GridValue.get_hazard_duration_1d(hazard) assert np.all(hazard_duration == np.array([0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]))
If a maintenance planned of 3 time steps starting at timestep 6 (index 5 - index starts at 0)
hazard = np.array([0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0]) hazard_duration = GridValue.get_hazard_duration_1d(hazard) assert np.all(hazard_duration == np.array([0,0,0,0,0,3,2,1,0,0,0,0,0,0,0,0]))
If a maintenance planned of 3 time steps starting at timestep 6 (index 5 - index starts at 0), and a second one for 2 time steps at time step 13
hazard = np.array([0,0,0,0,0,1,1,1,0,0,0,0,1,1,0,0,0]) hazard_duration = GridValue.get_hazard_duration_1d(hazard) assert np.all(hazard_duration == np.array([0,0,0,0,0,3,2,1,0,0,0,0,2,1,0,0,0]))
-
get_id
() → str[source]¶ Utility to get the current name of the path of the data are looked at, if data are files.
This could also be used to return a unique identifier to the generated chronics even in the case where they are generated on the fly, for example by return a hash of the seed.
- Returns
res – A unique identifier of the chronics generated for this episode. For example, if the chronics comes from a specific folder, this could be the path to this folder.
- Return type
str
-
staticmethod
get_maintenance_duration_1d
(maintenance)[source]¶ This function allows to transform a 1d numpy aarray maintenance (or hazards), where is specify:
0 there is no maintenance at this time step
1 there is a maintenance at this time step
Into the representation in terms of “next maintenance duration” as specified in
GridValue.maintenance_duration
which is:0 no forseeable maintenance operation will be performed
- 1, 2 etc. is the number of time step the next maintenance will last (it can be positive even in the
case that no maintenance is currently being performed.
- Parameters
maintenance (
numpy.ndarray
) – 1 dimensional array representing the time series of the maintenance (0 there is no maintenance, 1 there is a maintenance at this time step)- Returns
maintenance_duration – Array representing the time series of the duration of the next maintenance forseeable.
- Return type
numpy.ndarray
Examples
If no maintenance are planned:
maintenance = np.array([0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]) maintenance_duration = GridValue.get_maintenance_duration_1d(maintenance) assert np.all(maintenance_duration == np.array([0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]))
If a maintenance planned of 3 time steps starting at timestep 6 (index 5 - index starts at 0)
maintenance = np.array([0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0]) maintenance_duration = GridValue.get_maintenance_duration_1d(maintenance) assert np.all(maintenance_duration == np.array([3,3,3,3,3,3,2,1,0,0,0,0,0,0,0,0]))
If a maintenance planned of 3 time steps starting at timestep 6 (index 5 - index starts at 0), and a second one for 2 time steps at time step 13
maintenance = np.array([0,0,0,0,0,1,1,1,0,0,0,0,1,1,0,0,0]) maintenance_duration = GridValue.get_maintenance_duration_1d(maintenance) assert np.all(maintenance_duration == np.array([3,3,3,3,3,3,2,1,2,2,2,2,2,1,0,0,0]))
-
staticmethod
get_maintenance_time_1d
(maintenance)[source]¶ This function allows to transform a 1d numpy aarray maintenance, where is specify:
0 there is no maintenance at this time step
1 there is a maintenance at this time step
Into the representation in terms of “next maintenance time” as specified in
GridValue.maintenance_time
which is:-1 no foreseeable maintenance operation will be performed
0 a maintenance operation is being performed
1, 2 etc. is the number of time step the next maintenance will be performed.
- Parameters
maintenance (
numpy.ndarray
) – 1 dimensional array representing the time series of the maintenance (0 there is no maintenance, 1 there is a maintenance at this time step)- Returns
maintenance_duration – Array representing the time series of the duration of the next maintenance forseeable.
- Return type
numpy.ndarray
Examples
If no maintenance are planned:
maintenance_time = GridValue.get_maintenance_time_1d(np.array([0 for _ in range(10)])) assert np.all(maintenance_time == np.array([-1 for _ in range(10)]))
If a maintenance planned of 3 time steps starting at timestep 6 (index 5 - index starts at 0)
maintenance = np.array([0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0]) maintenance_time = GridValue.get_maintenance_time_1d(maintenance) assert np.all(maintenance_time == np.array([5,4,3,2,1,0,0,0,-1,-1,-1,-1,-1,-1,-1,-1]))
If a maintenance planned of 3 time steps starting at timestep 6 (index 5 - index starts at 0), and a second one for 2 time steps at time step 13
maintenance = np.array([0,0,0,0,0,1,1,1,0,0,0,0,1,1,0,0,0]) maintenance_time = GridValue.get_maintenance_time_1d(maintenance) assert np.all(maintenance_time == np.array([5,4,3,2,1,0,0,0,4,3,2,1,0,0,-1,-1,-1]))
-
abstractmethod
initialize
(order_backend_loads, order_backend_prods, order_backend_lines, order_backend_subs, names_chronics_to_backend)[source]¶ This function is used to initialize the data generator. It can be use to load scenarios, or to initialize noise if scenarios are generated on the fly. It must also initialize
GridValue.maintenance_time
,GridValue.maintenance_duration
andGridValue.hazard_duration
.This function should also increment
GridValue.curr_iter
of 1 each time it is called.The
GridValue
is what makes the connection between the data (generally in a shape of files on the hard drive) and the power grid. One of the main advantage of the Grid2Op package is its ability to change the tool that computes the load flows. Generally, suchgrid2op.Backend
expects data in a specific format that is given by the way their internal powergrid is represented, and in particular, the “same” objects can have different name and different position. To ensure that the same chronics would produce the same results on every backend (ie regardless of the order of which the Backend is expecting the data, the outcome of the powerflow is the same) we encourage the user to provide a file that maps the name of the object in the chronics to the name of the same object in the backend.This is done with the “names_chronics_to_backend” dictionnary that has the following keys:
“loads”
“prods”
“lines”
The value associated to each of these keys is in turn a mapping dictionnary from the chronics to the backend. This means that each keys of these subdictionnary is a name of one column in the files, and each values is the corresponding name of this same object in the dictionnary. An example is provided bellow.
- Parameters
order_backend_loads (
numpy.ndarray
, dtype:str) – Ordered name, in the Backend, of the loads. It is required that agrid2op.Backend
object always output the informations in the same order. This array gives the name of the loads following this order. See the documentation ofgrid2op.Backend
for more information about this.order_backend_prods (
numpy.ndarray
, dtype:str) – Same as order_backend_loads, but for generators.order_backend_lines (
numpy.ndarray
, dtype:str) – Same as order_backend_loads, but for powerline.order_backend_subs (
numpy.ndarray
, dtype:str) – Same as order_backend_loads, but for powerline.names_chronics_to_backend (
dict
) – See in the description of the method for more information about its format.
- Returns
- Return type
None
Examples
For example, suppose we have a
grid2op.Backend
with:substations ids strart from 0 to N-1 (N being the number of substations in the powergrid)
loads named “load_i” with “i” the subtations to which it is connected
generators units named “gen_i” (i still the substation id to which it is connected)
powerlnes are named “i_j” if it connected substations i to substation j
And on the other side, we have some files with the following conventions:
substations are numbered from 1 to N
loads are named “i_C” with i being the substation to which it is connected
generators are named “i_G” with is being the id of the substations to which it is connected
powerlines are namesd “i_j_k” where i is the origin substation, j the extremity substations and “k” is a unique identifier of this powerline in the powergrid.
In this case, instead of renaming the powergrid (in the backend) of the data files, it is advised to build the following elements and initialize the object gridval of type
GridValue
with:gridval = GridValue() # Note: this code won't execute because "GridValue" is an abstract class order_backend_loads = ['load_1', 'load_2', 'load_13', 'load_3', 'load_4', 'load_5', 'load_8', 'load_9', 'load_10', 'load_11', 'load_12'] order_backend_prods = ['gen_1', 'gen_2', 'gen_5', 'gen_7', 'gen_0'] order_backend_lines = ['0_1', '0_4', '8_9', '8_13', '9_10', '11_12', '12_13', '1_2', '1_3', '1_4', '2_3', '3_4', '5_10', '5_11', '5_12', '3_6', '3_8', '4_5', '6_7', '6_8'] order_backend_subs = ['sub_0', 'sub_1', 'sub_10', 'sub_11', 'sub_12', 'sub_13', 'sub_2', 'sub_3', 'sub_4', 'sub_5', 'sub_6', 'sub_7', 'sub_8', 'sub_9'] names_chronics_to_backend = {"loads": {"2_C": 'load_1', "3_C": 'load_2', "14": 'load_13', "4_C": 'load_3', "5_C": 'load_4', "6_C": 'load_5', "9_C": 'load_8', "10_C": 'load_9', "11_C": 'load_10', "12_C": 'load_11', "13_C": 'load_12'}, "lines": {'1_2_1': '0_1', '1_5_2': '0_4', '9_10_16': '8_9', '9_14_17': '8_13', '10_11_18': '9_10', '12_13_19': '11_12', '13_14_20': '12_13', '2_3_3': '1_2', '2_4_4': '1_3', '2_5_5': '1_4', '3_4_6': '2_3', '4_5_7': '3_4', '6_11_11': '5_10', '6_12_12': '5_11', '6_13_13': '5_12', '4_7_8': '3_6', '4_9_9': '3_8', '5_6_10': '4_5', '7_8_14': '6_7', '7_9_15': '6_8'}, "prods": {"1_G": 'gen_0', "3_G": "gen_2", "6_G": "gen_5", "2_G": "gen_1", "8_G": "gen_7"}, } gridval.initialize(order_backend_loads, order_backend_prods, order_backend_lines, names_chronics_to_backend)
-
abstractmethod
load_next
()[source]¶ Generate the next values, either by reading from a file, or by generating on the fly and return a dictionnary compatible with the
grid2op.BaseAction
class allowed for theEnvironment
.More information about this dictionnary can be found at
grid2op.BaseAction.update()
.As a (quick) reminder: this dictionnary has for keys:
“injection” (optional): a dictionnary with keys (optional) “load_p”, “load_q”, “prod_p”, “prod_v”
“hazards” (optional) : the outage suffered from the _grid
“maintenance” (optional) : the maintenance operations planned on the grid for the current time step.
- Returns
timestamp (
datetime.datetime
) – The current timestamp for which the modifications have been generated.dict_ (
dict
) – A dictionnary understandable by the :grid2op.BaseAction.update()
method. NB this function should return the dictionnary that will be converted, is should not, in any case, return an action.maintenance_time (
numpy.ndarray
, dtype:int
) – Information about the next planned maintenance. SeeGridValue.maintenance_time
for more information.maintenance_duration (
numpy.ndarray
, dtype:int
) – Information about the duration of next planned maintenance. SeeGridValue.maintenance_duration
for more information.hazard_duration (
numpy.ndarray
, dtype:int
) – Information about the current hazard. SeeGridValue.hazard_duration
for more information.
- Raises
StopIteration – if the chronics is over
-
max_timestep
()[source]¶ This method returned the maximum timestep that the current episode can last. Note that if the
grid2op.BaseAgent
performs a bad action that leads to a game over, then the episode can lasts less.- Returns
res – -1 if possibly infinite length of a positive integer representing the maximum duration of this episode
- Return type
int
-
abstractmethod
next_chronics
()[source]¶ Load the next batch of chronics. This function is called after an episode has finished by the
grid2op.Environment
or thegrid2op.Runner
.A call to this function should also reset
GridValue.curr_iter
to 0. :returns: :rtype:None
-
shuffle
(shuffler)[source]¶ This method can be overiden if the data that are represented by this object need to be shuffle.
By default it does nothing. :param shuffler: Any function that can be used to shuffle the data. :type shuffler:
object
-
tell_id
(id_num)[source]¶ Tell the backend to use one folder for the chronics in particular. This method is mainly use when the GridValue object can deal with many folder. In this case, this method is used by the
grid2op.Runner
to indicate which chronics to load for the current simulated episode.This is important to ensure reproducibility, especially in parrallel computation settings.
This should also be used in case of generation “on the fly” of the chronics to ensure the same property.
By default it does nothing.
- Returns
- Return type
None
-
-
class
grid2op.Chronics.
ReadPypowNetData
(path, sep=';', time_interval=datetime.timedelta(0, 300), max_iter=- 1, chunk_size=None)[source]¶
If you still can’t find what you’re looking for, try in one of the following pages: