Runner¶
This module is here to facilitate the evaluation of agent.
It can handles all types of grid2op.BaseAgent
.
-
class
grid2op.Runner.
ConsoleLog
(max_level=2)[source]¶ A class to emulate the behaviour of a logger, but that prints on the console
-
class
grid2op.Runner.
DoNothingLog
(max_level=2)[source]¶ A class to emulate the behaviour of a logger, but that does absolutely nothing.
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
grid2op.Runner.
Runner
(init_grid_path: str, path_chron, parameters_path=None, names_chronics_to_backend=None, actionClass=<class 'grid2op.Action.TopologyAction.TopologyAction'>, observationClass=<class 'grid2op.Observation.CompleteObservation.CompleteObservation'>, rewardClass=<class 'grid2op.Reward.FlatReward.FlatReward'>, legalActClass=<class 'grid2op.Rules.AlwaysLegal.AlwaysLegal'>, envClass=<class 'grid2op.Environment.Environment.Environment'>, gridStateclass=<class 'grid2op.Chronics.GridStateFromFile.GridStateFromFile'>, backendClass=<class 'grid2op.Backend.PandaPowerBackend.PandaPowerBackend'>, agentClass=<class 'grid2op.Agent.DoNothing.DoNothingAgent'>, agentInstance=None, verbose=False, gridStateclass_kwargs={}, voltageControlerClass=<class 'grid2op.VoltageControler.ControlVoltageFromFile.ControlVoltageFromFile'>, thermal_limit_a=None, max_iter=-1, other_rewards={}, opponent_action_class=<class 'grid2op.Action.DontAct.DontAct'>, opponent_class=<class 'grid2op.Opponent.BaseOpponent.BaseOpponent'>, opponent_init_budget=0, grid_layout=None)[source]¶ A runner is a utilitary tool that allows to create environment, and run simulations more easily. This specific class as for main purpose to evaluate the performance of a trained
grid2op.BaseAgent
, rather than to train it. Of course, it is possible to adapt it for a specific training mechanisms. Examples of such will be made available in the future.-
envClass
¶ The type of the environment used for the game. The class should be given, and not an instance (object) of this class. The default is the
grid2op.Environment
. If modified, it should derived from this class.- Type
type
-
actionClass
¶ The type of action that can be performed by the agent / bot / controler. The class should be given, and not an instance of this class. This type should derived from
grid2op.BaseAction
. The default isgrid2op.TopologyAction
.- Type
type
-
observationClass
¶ This type represents the class that will be used to build the
grid2op.BaseObservation
visible by thegrid2op.BaseAgent
. AsRunner.actionClass
, this should be a type, and not and instance (object) of this type. This type should derived fromgrid2op.BaseObservation
. The default isgrid2op.CompleteObservation
.- Type
type
-
rewardClass
¶ Representes the type used to build the rewards that are given to the
BaseAgent
. AsRunner.actionClass
, this should be a type, and not and instance (object) of this type. This type should derived fromgrid2op.BaseReward
. The default isgrid2op.ConstantReward
that should not be used to train or evaluate an agent, but rather as debugging purpose.- Type
type
-
gridStateclass
¶ This types control the mechanisms to read chronics and assign data to the powergrid. Like every “.*Class” attributes the type should be pass and not an intance (object) of this type. Its default is
grid2op.GridStateFromFile
and it must be a subclass ofgrid2op.GridValue
.- Type
type
-
legalActClass
¶ This types control the mechanisms to assess if an
grid2op.BaseAction
is legal. Like every “.*Class” attributes the type should be pass and not an intance (object) of this type. Its default isgrid2op.AlwaysLegal
and it must be a subclass ofgrid2op.BaseRules
.- Type
type
-
backendClass
¶ This types control the backend, eg. the software that computes the powerflows. Like every “.*Class” attributes the type should be pass and not an intance (object) of this type. Its default is
grid2op.PandaPowerBackend
and it must be a subclass ofgrid2op.Backend
.- Type
type
-
agentClass
¶ This types control the type of BaseAgent, eg. the bot / controler that will take
grid2op.BaseAction
and avoid cascading failures. Like every “.*Class” attributes the type should be pass and not an intance (object) of this type. Its default isgrid2op.DoNothingAgent
and it must be a subclass ofgrid2op.BaseAgent
.- Type
type
-
logger
¶ A object than can be used to log information, either in a text file, or by printing them to the command prompt.
-
init_grid_path
¶ This attributes store the path where the powergrid data are located. If a relative path is given, it will be extended as an absolute path.
- Type
str
-
names_chronics_to_backend
¶ See description of
grid2op.ChronicsHelper.initialize()
for more information about this dictionnary- Type
dict
-
parameters_path
¶ Where to look for the
grid2op.Environment
grid2op.Parameters
. It defaults toNone
which corresponds to using default values.- Type
str
, optional
-
parameters
¶ Type of _parameters used. This is an instance (object) of type
grid2op.Parameters
initialized fromRunner.parameters_path
- Type
-
path_chron
¶ Path indicatng where to look for temporal data.
- Type
str
-
chronics_handler
¶ Initialized from
Runner.gridStateclass
andRunner.path_chron
it represents the input data used to generate grid state by theRunner.env
- Type
grid2op.ChronicsHandler
-
backend
¶ Used to compute the powerflow. This object has the type given by
Runner.backendClass
- Type
-
env
¶ Represents the environment which the agent / bot / control must control through action. It is initialized from the
Runner.envClass
- Type
-
agent
¶ Represents the agent / bot / controler that takes action performed on a environment (the powergrid) to maximize a certain reward.
- Type
-
verbose
¶ If
True
then detailed output of each steps are written.- Type
bool
-
gridStateclass_kwargs
¶ Additional keyword arguments used to build the
Runner.chronics_handler
- Type
dict
-
thermal_limit_a
¶ The thermal limit for the environment (if any).
- Type
numpy.ndarray
-
__init__
(init_grid_path: str, path_chron, parameters_path=None, names_chronics_to_backend=None, actionClass=<class 'grid2op.Action.TopologyAction.TopologyAction'>, observationClass=<class 'grid2op.Observation.CompleteObservation.CompleteObservation'>, rewardClass=<class 'grid2op.Reward.FlatReward.FlatReward'>, legalActClass=<class 'grid2op.Rules.AlwaysLegal.AlwaysLegal'>, envClass=<class 'grid2op.Environment.Environment.Environment'>, gridStateclass=<class 'grid2op.Chronics.GridStateFromFile.GridStateFromFile'>, backendClass=<class 'grid2op.Backend.PandaPowerBackend.PandaPowerBackend'>, agentClass=<class 'grid2op.Agent.DoNothing.DoNothingAgent'>, agentInstance=None, verbose=False, gridStateclass_kwargs={}, voltageControlerClass=<class 'grid2op.VoltageControler.ControlVoltageFromFile.ControlVoltageFromFile'>, thermal_limit_a=None, max_iter=-1, other_rewards={}, opponent_action_class=<class 'grid2op.Action.DontAct.DontAct'>, opponent_class=<class 'grid2op.Opponent.BaseOpponent.BaseOpponent'>, opponent_init_budget=0, grid_layout=None)[source]¶ Initialize the Runner.
- Parameters
init_grid_path (
str
) – Madantory, used to initializeRunner.init_grid_path
.path_chron (
str
) – Madantory where to look for chronics data, used to initializeRunner.path_chron
.parameters_path (
str
ordict
, optional) – Used to initializeRunner.parameters_path
. If it’s a string, this will suppose parameters are located at this path, if it’s a dictionary, this will use the parameters converted from this dictionary.names_chronics_to_backend (
dict
, optional) – Used to initializeRunner.names_chronics_to_backend
.actionClass (
type
, optional) – Used to initializeRunner.actionClass
.observationClass (
type
, optional) – Used to initializeRunner.observationClass
.rewardClass (
type
, optional) – Used to initializeRunner.rewardClass
. Default togrid2op.ConstantReward
that should not* be used to train or evaluate an agent, but rather as debugging purpose.legalActClass (
type
, optional) – Used to initializeRunner.legalActClass
.envClass (
type
, optional) – Used to initializeRunner.envClass
.gridStateclass (
type
, optional) – Used to initializeRunner.gridStateclass
.backendClass (
type
, optional) – Used to initializeRunner.backendClass
.agentClass (
type
, optional) – Used to initializeRunner.agentClass
.agentInstance (
grid2op.Agent.Agent
) – Used to initialize the agent. Note that eitheragentClass
oragentInstance
is used at the same time. If both ot them areNone
or both of them are “notNone
” it throw an error.verbose (
bool
, optional) – Used to initializeRunner.verbose
.thermal_limit_a (
numpy.ndarray
) – The thermal limit for the environment (if any).voltagecontrolerClass (
grid2op.VoltageControler.ControlVoltageFromFile
, optional) – The controler that will change the voltage setpoints of the generators.
-
__weakref__
¶ list of weak references to the object (if defined)
-
staticmethod
_make_progress_bar
(pbar, total, next_pbar)[source]¶ - Parameters
pbar (
bool
ortype
orobject
) –How to display the progress bar, understood as follow:
if pbar is
None
nothing is done.if pbar is a boolean, tqdm pbar are used, if tqdm package is available and installed on the system [if
true
]. If it’s false it’s equivalent to pbar beingNone
if pbar is a
type
( a class), it is used to build a progress bar at the highest level (episode) and and the lower levels (step during the episode). If it’s a type it muyst accept the argument “total” and “desc” when being built, and the closing is ensured by this method.if pbar is an object (an instance of a class) it is used to make a progress bar at this highest level (episode) but not at lower levels (setp during the episode)
-
init_env
()[source]¶ Function used to initialized the environment and the agent. It is called by
Runner.reset()
.- Returns
- Return type
None
-
reset
()[source]¶ Used to reset an environment. This method is called at the beginning of each new episode. If the environment is not initialized, then it initializes it with
Runner.make_env()
.- Returns
- Return type
None
-
run
(nb_episode, nb_process=1, path_save=None, max_iter=None, pbar=False)[source]¶ Main method of the
Runner
class. It will either callRunner.run_sequential()
if “nb_process” is 1 orRunner.run_parrallel()
if nb_process >= 2.- Parameters
nb_episode (
int
) – Number of episode to simulatenb_process (
int
, optional) – Number of process used to play the nb_episode. Default to 1.path_save (
str
, optional) – If not None, it specifies where to store the data. See the description of this moduleRunner
for more information
- Returns
res –
List of tuple. Each tuple having 3 elements:
”i” unique identifier of the episode (compared to
Runner.run_sequential()
, the elements of the returned list are not necessarily sorted by this value)”cum_reward” the cumulative reward obtained by the
Runner.BaseAgent
on this episode i”nb_time_step”: the number of time steps played in this episode.
- Return type
list
-
run_one_episode
(indx=0, path_save=None, pbar=False)[source]¶ Function used to run one episode of the
Runner.agent
and see how it performs in theRunner.env
.- Parameters
indx (
int
) – The number of episode previously runpath_save (
str
, optional) – Path where to save the data. See the description ofgrid2op.Runner
for the structure of the saved file.
- Returns
cum_reward (
float
) – The cumulative reward obtained by the agent during this episodetime_step (
int
) – The number of timesteps that have been played before the end of the episode (because of a “game over” or because there were no more data)
-
run_parrallel
(nb_episode, nb_process=1, path_save=None)[source]¶ This method will run in parrallel, independantly the nb_episode over nb_process.
In case the agent cannot be cloned using copy.copy: nb_process is set to 1
Note that it restarts completely the
Runner.backend
andRunner.env
if the computation is actually performed with more than 1 cores (nb_process > 1)It uses the python multiprocess, and especially the
multiprocess.Pool
to perform the computations. This implies that all runs are completely independant (they happen in different process) and that the memory consumption can be big. Tests may be recommended if the amount of RAM is low.It has the same return type as the
Runner.run_sequential()
.- Parameters
nb_episode (
int
) – Number of episode to simulatenb_process (
int
, optional) – Number of process used to play the nb_episode. Default to 1.path_save (
str
, optional) – If not None, it specifies where to store the data. See the description of this moduleRunner
for more information
- Returns
res –
List of tuple. Each tuple having 3 elements:
”i” unique identifier of the episode (compared to
Runner.run_sequential()
, the elements of the returned list are not necessarily sorted by this value)”cum_reward” the cumulative reward obtained by the
Runner.BaseAgent
on this episode i”nb_time_step”: the number of time steps played in this episode.
”max_ts” : the maximum number of time steps of the chronics
- Return type
list
-
run_sequential
(nb_episode, path_save=None, pbar=False)[source]¶ This method is called to see how well an agent performed on a sequence of episode.
- Parameters
nb_episode (
int
) – Number of episode to play.path_save (
str
, optional) – If not None, it specifies where to store the data. See the description of this moduleRunner
for more informationpbar (
bool
ortype
orobject
) –How to display the progress bar, understood as follow:
if pbar is
None
nothing is done.if pbar is a boolean, tqdm pbar are used, if tqdm package is available and installed on the system [if
true
]. If it’s false it’s equivalent to pbar beingNone
if pbar is a
type
( a class), it is used to build a progress bar at the highest level (episode) and and the lower levels (step during the episode). If it’s a type it muyst accept the argument “total” and “desc” when being built, and the closing is ensured by this method.if pbar is an object (an instance of a class) it is used to make a progress bar at this highest level (episode) but not at lower levels (setp during the episode)
- Returns
res –
List of tuple. Each tuple having 5 elements:
”id_chron” unique identifier of the episode
”name_chron” name of chronics
”cum_reward” the cumulative reward obtained by the
Runner.BaseAgent
on this episode i”nb_time_step”: the number of time steps played in this episode.
”max_ts” : the maximum number of time steps of the chronics
- Return type
list
-
If you still can’t find what you’re looking for, try in one of the following pages: