@@ -54,26 +54,158 @@ come from the :class:`grid2op.GridValue` and are detailed in the
5454:func: `GridValue.forecasts ` method.
5555
5656
57- More control on the chronics
57+ More control on the time series
5858-------------------------------
5959We explained, in the description of the :class: `grid2op.Environment ` in sections
6060:ref: `environment-module-chronics-info ` and following how to have more control on which chronics is used,
6161with steps are used within a chronics etc. We will not detailed here again, please refer to this page
6262for more information.
6363
64- However, know that you can have a very detailed control on which chronics are used:
64+ However, know that you can have a very detailed control on which time series using the `options `
65+ kwargs of a call to `env.reset() ` (or the `reset_otions ` kwargs when calling the
66+ `runner.run() `) :
6567
66- - use `env.set_id(THE_CHRONIC_ID) ` (see :func: `grid2op.Environment.Environment.set_id `) to set the id of the
67- chronics you want to use
68- - use `env.chronics_handler.set_filter(a_function) ` (see :func: `grid2op.Chronics.GridValue.set_filter `)
68+
69+ Use a specific time serie for an episode
70+ *******************************************
71+
72+ To use a specific time series for a given episode, you can use
73+ `env.reset(options={"time serie id": THE_ID_YOU_WANT) `.
74+
75+ For example:
76+
77+ .. code-block :: python
78+
79+ import grid2op
80+ env_name = " l2rpn_case14_sandbox"
81+ env = grid2op.make(env_name)
82+
83+ # you can use an int:
84+ obs = env.reset(options = {" time serie id" 0 })
85+
86+ # or the name of the folder (for most grid2op environment)
87+ obs = env.reset(options = {" time serie id" " 0000" # for l2rpn_case14_sandbox
88+
89+ # for say l2rpn_neurips_2020_track1
90+ # obs = env.reset(options={"time serie id": "Scenario_august_008"})
91+
92+ # for say l2rpn_idf_2023
93+ # obs = env.reset(options={"time serie id": "2035-04-23_7"})
94+
95+
96+ note ::
97+ For oldest grid2op versions (please upgrade if that's the case) you needed to use:
98+ `env.set_id(THE_CHRONIC_ID) ` (see :func: `grid2op.Environment.Environment.set_id `) to set the id of the
99+ chronics you want to use.
100+
101+
102+ Skipping the initial few steps
103+ *******************************
104+
105+ Often the time series provided for an environment always start at the same date and time on
106+ the same hour of the day and day of the week. It might not be ideal to learn controler
107+ with such data or might "burn up" computation time during evaluation.
108+
109+ To do that, you can use the `"init ts" ` reset options, for example with:
110+
111+ .. code-block :: python
112+
113+ import grid2op
114+ env_name = " l2rpn_case14_sandbox"
115+ env = grid2op.make(env_name)
116+
117+ # you can use an int:
118+ obs = env.reset(options = {" init ts" 12 })
119+
120+ # obs will skip the first hour of the time series
121+ # 12 steps is equivalent to 1h (5 mins per step in general)
122+
123+
124+ note ::
125+
126+ For oldest grid2op versions (please upgrade if that's the case) you needed to use:
127+ `env.fast_forward_chronics(nb_time_steps) `
128+ (see :func: `grid2op.Environment.BaseEnv.fast_forward_chronics `) to skip initial
129+ few steps
130+ of a given chronics.
131+
132+ Please be aware that this "legacy" behaviour has some issues and is "less clear"
133+ than the "init ts" above and it can have some weird combination with
134+ `set_max_iter ` for example.
135+
136+
137+ Limit the maximum length of the current episode
138+ *************************************************
139+
140+ For most enviroment, the maximum duration of an episode is the equivalent of a week
141+ (~2020 steps) or a month (~8100 steps) which might be too long for some usecase.
142+
143+ Anyway, if you want to reduce it, you can now do it with the `"max step" ` reset
144+ option like this:
145+
146+ .. code-block :: python
147+
148+ import grid2op
149+ env_name = " l2rpn_case14_sandbox"
150+ env = grid2op.make(env_name)
151+
152+ # you can use an int:
153+ obs = env.reset(options = {" max step" 2 * 288 })
154+
155+ # the maximum duration of the episode is now 2*288 steps
156+ # the equivalent of two days
157+
158+ note ::
159+
160+ For oldest grid2op versions (please upgrade if that's the case) you needed to use:
161+ `env.chronics_handler.set_max_iter(nb_max_iter) `
162+ (see :func: `grid2op.Chronics.ChronicsHandler.set_max_iter `) to limit the number
163+ of steps within an episode.
164+
165+ Please be aware that this "legacy" behaviour has some issues and is "less clear"
166+ than the "init ts" above and it can have some weird combination with
167+ `fast_forward_chronics ` for example.
168+
169+ Discard some time series from the existing folder
170+ **************************************************
171+
172+ The folder containing the time series for a given grid2op environment often contains
173+ dozens (thousands sometimes) different time series.
174+
175+ You might want to use only part of them at some point (whether it's some for training and some
176+ for validation and test, or some for training an agent on a process and some to train the
177+ same agent on another process etc.)
178+
179+ Anyway, if you want to do this (on the majority of released environments) you can do it
180+ thanks to the `env.chronics_handler.set_filter(a_function) `.
181+
182+ For example:
183+
184+ .. code-block :: python
185+
186+ import re
187+ import grid2op
188+ env_name = " l2rpn_case14_sandbox"
189+ env = grid2op.make(env_name)
190+
191+ def keep_only_some_ep (chron_name ):
192+ return re.match(r " . * 00. * " is not None
193+
194+ env.chronics_handler.set_filter(keep_only_some_ep)
195+ li_episode_kept = env.chronics_handler.reset()
196+
197+
198+ note ::
199+ For oldest grid2op versions (please upgrade if that's the case) you needed to use:
200+ use `env.chronics_handler.set_filter(a_function) ` (see :func: `grid2op.Chronics.GridValue.set_filter `)
69201 to only use certain chronics
202+
203+
70204- use `env.chronics_handler.sample_next_chronics(probas) `
71205 (see :func: `grid2op.Chronics.GridValue.sample_next_chronics `) to draw at random some chronics
72- - use `env.fast_forward_chronics(nb_time_steps) `
73- (see :func: `grid2op.Environment.BaseEnv.fast_forward_chronics `) to skip initial number of steps
74- of a given chronics
75- - use `env.chronics_handler.set_max_iter(nb_max_iter) `
76- (see :func: `grid2op.Chronics.ChronicsHandler.set_max_iter `) to limit the number of steps within an episode
206+
207+ Performance gain (throughput)
208+ ********************************
77209
78210Chosing the right chronics can also lead to some large advantage in terms of computation time. This is
79211particularly true if you want to benefit the most from HPC for example. More detailed is given in the
0 commit comments