adjust documentation on how to call the reset method in RailEnv

changelog.md

@@ -9,6 +9,7 @@ Changes since Flatland 2.0.0
 
 ### Changes in rail generator and `RailEnv`
 - renaming of `distance_maps` into `distance_map`
+- by default the reset method of RailEnv is not called in the constructor of RailEnv anymore. Therefore the reset method needs to be called after the creation of a RailEnv object
 
 Changes since Flatland 1.0.0
 --------------------------

docs/tutorials/01_gettingstarted.rst

@@ -21,7 +21,8 @@ The basic usage of RailEnv environments consists in creating a RailEnv object
 endowed with a rail generator, that generates new rail networks on each reset,
 and an observation generator object, that is supplied with environment-specific
 information at each time step and provides a suitable observation vector to the
-agents.
+agents. After the RailEnv environment is created, one need to call reset() on the
+environment in order to fully initialize the environment
 
 The simplest rail generators are envs.rail_generators.rail_from_manual_specifications_generator
 and envs.rail_generators.random_rail_generator.
@@ -43,6 +44,7 @@ For example,
                   rail_generator=rail_from_manual_specifications_generator(specs),
                   number_of_agents=1,
                   obs_builder_object=TreeObsForRailEnv(max_depth=2))
+    env.reset()
 
 Alternatively, a random environment can be generated (optionally specifying
 weights for each cell type to increase or decrease their proportion in the
@@ -71,6 +73,7 @@ generated rail networks).
                             ),
                   number_of_agents=3,
                   obs_builder_object=TreeObsForRailEnv(max_depth=2))
+    env.reset()
 
 Environments can be rendered using the utils.rendertools utilities, for example:
 
@@ -147,6 +150,7 @@ Next we configure the difficulty of our task by modifying the complex_rail_gener
                                         max_dist=99999,
                                         seed=1),
                     number_of_agents=5)
+    env.reset()
 
 The difficulty of a railway network depends on the dimensions (`width` x `height`) and the number of agents in the network.
 By varying the number of start and goal connections (nr_start_goal) and the number of extra railway elements added (nr_extra)

docs/tutorials/02_observationbuilder.rst

@@ -45,6 +45,7 @@ We can pass an instance of our custom observation builder :code:`SimpleObs` to t
                   rail_generator=random_rail_generator(),
                   number_of_agents=3,
                   obs_builder_object=SimpleObs())
+    env.reset()
 
 Anytime :code:`env.reset()` or :code:`env.step()` is called, the observation builder will return the custom observation of all agents initialized in the env.
 In the next example we highlight how to derive from existing observation builders and how to access internal variables of **Flatland**.
@@ -121,6 +122,7 @@ Note that this simple strategy fails when multiple agents are present, as each a
                     min_dist=8, max_dist=99999, seed=1),
                   number_of_agents=2,
                   obs_builder_object=SingleAgentNavigationObs())
+    env.reset()
 
     obs, all_rewards, done, _ = env.step({0: 0, 1: 1})
     for i in range(env.get_num_agents()):
@@ -136,6 +138,7 @@ navigation to target, and shows the path taken as an animation.
                   rail_generator=random_rail_generator(),
                   number_of_agents=1,
                   obs_builder_object=SingleAgentNavigationObs())
+    env.reset()
 
     obs, all_rewards, done, _ = env.step({0: 0})
 
@@ -270,6 +273,7 @@ We can then use this new observation builder and the renderer to visualize the o
                   rail_generator=complex_rail_generator(nr_start_goal=5, nr_extra=1, min_dist=8, max_dist=99999, seed=1),
                   number_of_agents=3,
                   obs_builder_object=CustomObsBuilder)
+    env.reset()
 
     obs, info = env.reset()
     env_renderer = RenderTool(env, gl="PILSVG")

docs/tutorials/03_rail_and_schedule_generator.md

@@ -7,13 +7,13 @@ Let's have a look at the `sparse_rail_generator`.
 ## Sparse Rail Generator
 ![Example_Sparse](https://i.imgur.com/DP8sIyx.png)
 
-The idea behind the sparse rail generator is to mimic classic railway structures where dense nodes (cities) are sparsely connected to each other and where you have to manage traffic flow between the nodes efficiently. 
+The idea behind the sparse rail generator is to mimic classic railway structures where dense nodes (cities) are sparsely connected to each other and where you have to manage traffic flow between the nodes efficiently.
 The cities in this level generator are much simplified in comparison to real city networks but it mimics parts of the problems faced in daily operations of any railway company.
 
-There are a few parameters you can tune to build your own map and test different complexity levels of the levels. 
-**Warning** some combinations of parameters do not go well together and will lead to infeasible level generation. 
-In the worst case, the level generator currently issues a warning when it cannot build the environment according to the parameters provided. 
-This will lead to a crash of the whole env. 
+There are a few parameters you can tune to build your own map and test different complexity levels of the levels.
+**Warning** some combinations of parameters do not go well together and will lead to infeasible level generation.
+In the worst case, the level generator currently issues a warning when it cannot build the environment according to the parameters provided.
+This will lead to a crash of the whole env.
 We are currently working on improvements here and are **happy for any suggestions from your side**.
 
 To build an environment you instantiate a `RailEnv` as follows:
@@ -40,6 +40,8 @@ env = RailEnv(
     number_of_agents=10,
     obs_builder_object=TreeObsForRailEnv(max_depth=3,predictor=shortest_path_predictor)
 )
+ Call reset on the environment
+env.reset()
 ```
 
 You can see that you now need both a `rail_generator` and a `schedule_generator` to generate a level. These need to work nicely together. The `rail_generator` will only generate the railway infrastructure and provide hints to the `schedule_generator` about where to place agents. The `schedule_generator` will then generate a schedule, meaning it places agents at different train stations and gives them tasks by providing individual targets.

docs/tutorials/04_stochasticity.md

 # Stochasticity Tutorial
 
-Another area where we improved **Flat**land 2.0 are stochastic events added during the episodes. 
+Another area where we improved **Flat**land 2.0 are stochastic events added during the episodes.
 This is very common for railway networks where the initial plan usually needs to be rescheduled during operations as minor events such as delayed departure from trainstations, malfunctions on trains or infrastructure or just the weather lead to delayed trains.
 
 We implemted a poisson process to simulate delays by stopping agents at random times for random durations. The parameters necessary for the stochastic events can be provided when creating the environment.
@@ -28,12 +28,12 @@ You can introduce stochasticity by simply creating the env as follows:
 env = RailEnv(
     ...
     stochastic_data=stochastic_data,  # Malfunction data generator
-    ...    
+    ...
 )
 ```
-In your controller, you can check whether an agent is malfunctioning: 
+In your controller, you can check whether an agent is malfunctioning:
 ```python
-obs, rew, done, info = env.step(actions) 
+obs, rew, done, info = env.step(actions)
 ...
 action_dict = dict()
 for a in range(env.get_num_agents()):
@@ -65,6 +65,7 @@ env = RailEnv(width=50,
               number_of_agents=10,
               stochastic_data=stochastic_data,  # Malfunction data generator
               obs_builder_object=tree_observation)
+env.reset()
 ```
 
 You will quickly realize that this will lead to unforeseen difficulties which means that **your controller** needs to observe the environment at all times to be able to react to the stochastic events.