Improve documentation

[jhmenke]

It would be very helpful if the physical units were added to the relevant variables (e.g. in the Observation description). I am sometimes unclear about the units (e.g. observation.rho - these are values all around 0.01).

Minor other issues:

• It would be helpful if the current timestep was part of the Observation object too

[BDonnot]

Hello :-)

The timestep is already in the observation. If "obs" is an observation, then you can access:

• obs.year
• obs.month
• obs.day
• obs.hour_of_day
• obs.minute_of_hour

And even which day of the week it is with obs.day_of_week.

I will try to improve the documentation, as clearly it's not perfect, and especially i'll try to be explicit on the unit. Concerning obs.rho here is what is written:

    rho: :class:`numpy.ndarray`, dtype:float
        The capacity of each powerline. It is defined at the observed current flow divided by the thermal limit of each
        powerline.

rho then don't have any unit. Having a rho of around 0.01 means that the flow is approximately 1% of the thermal limit.

[jhmenke]

Thanks for the quick response. I meant numbered timestamps from 0, 1, 2 ...; they would be helpful, but of course the agent can track the timestep itself.

I will try to improve the documentation, as clearly it's not perfect, and especially i'll try to be explicit on the unit.

Thanks! For example, voltage could be given in per unit, Volts or kV. This would be helpful to have in the docs

rho then don't have any unit. Having a rho of around 0.01 means that the flow is approximately 1% of the thermal limit.

Okay, so in the first 10 episodes for the IEEE14 case, all line loadings (bottom plot) are at maximum 1 %? The voltage (top plot) is also stable ergo nothing is happening in this grid.

[BDonnot]

Hello again :-)

Thanks for the quick response. I meant numbered timestamps from 0, 1, 2 ...; they would be helpful, but of course the agent can track the timestep itself.

I might be wrong, but i'm not sure it's a common practice in reinforcement learning setting. I think for now the best way to have this information would be to assume data are provided each 5 mins and start on 1st january 2019 (default parameters of class ChronicsHandler.GridValue. This would be a way to have the number of time steps.
Keeping track of the number of time steps in the agent is also a perfectly valid solution indeed.

Thanks! For example, voltage could be given in per unit, Volts or kV. This would be helpful to have in the docs

The new version 0.5.0 (pushed this morning) include that information in the documentation (see https://grid2op.readthedocs.io/en/v0.5.0/observation.html#grid2op.Observation.Observation). Voltages are given in Volt (V), power is MW and reactive power in MVar usually.

Looking more at this is, Camilo Romero and I also found a bug in converting pair-unit to volt. This bug has also been fixed in this version.

Okay, so in the first 10 episodes for the IEEE14 case, all line loadings (bottom plot) are at maximum 1 %? The voltage (top plot) is also stable ergo nothing is happening in this grid.

You are correct, this case is given as an example, and is merely present for tests and to show how grid2op works. It should not be used "as is" to train an agent.
To develop an Agent, i recommend to use the "l2rpn_2019" environment:

import grid2op
env = grid2op.make("l2rpn_2019", chronics_path=PATH/TO/L2RPN2019/DATA)

I will try to post the training data for L2RPN_2019 somewhere and has the package to automatically download the 1004 chronics that were provided for the competitors. In the mean time, they are available in the codalab challenge (I intend to do it when coding #20 ), any help welcome of course.

[jhmenke]

I'm reasonably sure that the voltage is returned in kV and not V (l2rpn grid):

obs.v_ex
Out[3]:
array([101.2 , 101.71529709, 107.2 , 101.34659884,
101.71529709, 101.34659884, 101.71529709, 103.98526154,
102.72860143, 104. , 101.66475643, 102.08620353,
102.7609168 , 108.4 , 102.72860143, 99.8014417 ,
102.24393243, 102.7609168 , 101.66475643, 99.8014417 ])

[BDonnot]

You are correct, i will fix that in the documentation. Thanks