Merge branch '293_faq_update' into 'master'

Updating FAQ

Closes #293

See merge request flatland/flatland!268

FAQ_Challenge.md

@@ -53,3 +53,79 @@ The environments vary in size and number of agents as well as malfunction parame
 - `(x_dim, y_dim) <= (150, 150)`
 - `n_agents <= 250` (this might be updated)
 - `malfunction rates` this is currently being refactored
+
+### How can I experiment locally before submitting?
+You can follow the instruction in the [starter kit](https://github.com/AIcrowd/flatland-challenge-starter-kit) and use the [provided example files](https://www.aicrowd.com/challenges/flatland-challenge/dataset_files) to run your tests locally.
+
+If you want to generate your own test instances to test your solution you can either head over to the [torch baselines](https://gitlab.aicrowd.com/flatland/baselines/tree/master/torch_training) and get inspired by the setup there.
+Or you can generate your own test cases by using the same generators as used by the submission test set.
+
+In order to generate the appropriate levels you need to import the `malfunction_generator`, `rail_generator` and `schedule_generator` as follows:
+
+```
+from flatland.envs.malfunction_generators import malfunction_from_params
+from flatland.envs.rail_env import RailEnv
+from flatland.envs.rail_generators import sparse_rail_generator
+from flatland.envs.schedule_generators import sparse_schedule_generator
+```
+
+Then you can simply generate levels by instantiating:
+
+```python
+stochastic_data = {'malfunction_rate': 8000,  # Rate of malfunction occurence of single agent
+                   'min_duration': 15,  # Minimal duration of malfunction
+                   'max_duration': 50  # Max duration of malfunction
+                   }
+
+# Custom observation builder without predictor
+observation_builder = YourObservationBuilder()
+
+width = 16 * 7  # With of map
+height = 9 * 7  # Height of map
+nr_trains = 50  # Number of trains that have an assigned task in the env
+cities_in_map = 20  # Number of cities where agents can start or end
+seed = 14  # Random seed
+grid_distribution_of_cities = False  # Type of city distribution, if False cities are randomly placed
+max_rails_between_cities = 2  # Max number of tracks allowed between cities. This is number of entry point to a city
+max_rail_in_cities = 6  # Max number of parallel tracks within a city, representing a realistic trainstation
+
+rail_generator = sparse_rail_generator(max_num_cities=cities_in_map,
+                                       seed=seed,
+                                       grid_mode=grid_distribution_of_cities,
+                                       max_rails_between_cities=max_rails_between_cities,
+                                       max_rails_in_city=max_rail_in_cities,
+                                       )
+# Different agent types (trains) with different speeds.
+speed_ration_map = {1.: 0.25,  # Fast passenger train
+                    1. / 2.: 0.25,  # Fast freight train
+                    1. / 3.: 0.25,  # Slow commuter train
+                    1. / 4.: 0.25}  # Slow freight train
+
+# We can now initiate the schedule generator with the given speed profiles
+
+schedule_generator = sparse_schedule_generator(speed_ration_map)
+
+# Construct the enviornment with the given observation, generataors, predictors, and stochastic data
+env = RailEnv(width=width,
+              height=height,
+              rail_generator=rail_generator,
+              schedule_generator=schedule_generator,
+              number_of_agents=nr_trains,
+              obs_builder_object=observation_builder,
+              malfunction_generator_and_process_data=malfunction_from_params(stochastic_data),
+              remove_agents_at_target=True)
+```
+
+For the testing of you submission you should test different levels in these parameter ranges:
+
+- `width` and `height` between `20` and `150`
+- `nr_train` between `50` and `200`
+- `n_cities` between `2` and `35`
+- `max_rails_between_cities` between `2` and `4`
+- `max_rail_in_city` between `3` and `6`
+- `malfunction_rate` between `500` and `4000`
+- `min_duration` and `max_duration` in ranges from `20` to `80`
+- speeds you can keep more or less equally distributed.
+
+
+With these parameters you should get a good feeling of the test cases your algorithm will be tested against.

FAQ_Repository.md

@@ -30,7 +30,7 @@ Each agent is an object and contains the following information:
     - The attribute `'transition_action_on_cellexit'` contains the information about the action that will be performed at the exit of the cell. Due to speeds smaller than 1. agents have to take several steps within a cell. We however only allow an action to be chosen at cell entry.
 - `malfunction_data = attrib(default=Factory(lambda: dict({'malfunction': 0, 'malfunction_rate': 0, 'next_malfunction': 0, 'nr_malfunctions': 0,'moving_before_malfunction': False})))`: Contains all information relevant for agent malfunctions:
     - The attribute `'malfunction` indicates if the agent is currently broken. If the value is larger than `0` the agent is broken. The integer value represents the number of `env.step()` calls the agent will still be broken.
-    - The attribute `'next_malfunction'` will be REMOVED as it serves no purpose anymore, malfunctions are now generated by a poisson process.
+    - The attribute `'next_malfunction'` was REMOVED as it serves no purpose anymore, malfunctions are now generated by a poisson process.
     - The attribute `'nr_malfunctions'` is a counter that keeps track of the number of malfunctions a specific agent has had.
     - The attribute `'moving_before_malfunction'` is an internal parameter used to restart agents that were moving automatically after the malfunction is fixed.
 - `status = attrib(default=RailAgentStatus.READY_TO_DEPART, type=RailAgentStatus)`: The status of the agent explains what the agent is currently doing. It can be in either one of these states:

examples/introduction_flatland_2_1.py

@@ -3,7 +3,7 @@ import numpy as np
 # In Flatland you can use custom observation builders and predicitors
 # Observation builders generate the observation needed by the controller
 # Preditctors can be used to do short time prediction which can help in avoiding conflicts in the network
-from envs.malfunction_generators import malfunction_from_params
+from flatland.envs.malfunction_generators import malfunction_from_params
 from flatland.envs.observations import GlobalObsForRailEnv
 # First of all we import the Flatland rail environment
 from flatland.envs.rail_env import RailEnv
@@ -31,7 +31,7 @@ from flatland.utils.rendertools import RenderTool, AgentRenderVariant
 
 width = 16 * 7  # With of map
 height = 9 * 7  # Height of map
-nr_trains = 20  # Number of trains that have an assigned task in the env
+nr_trains = 50  # Number of trains that have an assigned task in the env
 cities_in_map = 20  # Number of cities where agents can start or end
 seed = 14  # Random seed
 grid_distribution_of_cities = False  # Type of city distribution, if False cities are randomly placed
@@ -62,7 +62,7 @@ schedule_generator = sparse_schedule_generator(speed_ration_map)
 # We can furthermore pass stochastic data to the RailEnv constructor which will allow for stochastic malfunctions
 # during an episode.
 
-stochastic_data = {'malfunction_rate': 10000,  # Rate of malfunction occurence of single agent
+stochastic_data = {'malfunction_rate': 12000,  # Rate of malfunction occurence of single agent
                    'min_duration': 15,  # Minimal duration of malfunction
                    'max_duration': 50  # Max duration of malfunction
                    }
@@ -86,7 +86,7 @@ env.reset()
 
 # Initiate the renderer
 env_renderer = RenderTool(env, gl="PILSVG",
-                          agent_render_variant=AgentRenderVariant.AGENT_SHOWS_OPTIONS_AND_BOX,
+                          agent_render_variant=AgentRenderVariant.ONE_STEP_BEHIND,
                           show_debug=False,
                           screen_height=600,  # Adjust these parameters to fit your resolution
                           screen_width=800)  # Adjust these parameters to fit your resolution