.gitignore

@@ -11,7 +11,7 @@ __pycache__/
 env/
 build/
 develop-eggs/
-dist/
+# dist/
 downloads/
 eggs/
 .eggs/
@@ -117,3 +117,11 @@ images/test/
 test_save.dat
 
 .visualizations
+
+playground/
+**/tmp
+**/TEMP
+
+*.pkl
+
+images
\ No newline at end of file

.gitlab-ci.yml

@@ -10,41 +10,69 @@ image: themattrix/tox
 ## - AWS_SECRET_ACCESS_KEY
 
 stages:
+    - build_wheel
     - tests
     - integration_testing
-    - benchmarks_and_profiling
+    - profiling
+    - benchmarks
     - deploy_docs
-cache:
-    paths:
-        - .tox
 
 before_script:
     - echo "Setting Up...."
 
-tests:
+.test-setup: &test-setup
     stage: tests
+    services:
+        - redis
     before_script:
         - apt update
-        - apt install -y libgl1-mesa-glx xvfb graphviz xdg-utils libcairo2-dev libjpeg-dev libgif-dev
+        - apt install -y libgl1-mesa-glx xvfb graphviz libgraphviz-dev xdg-utils libcairo2-dev libjpeg-dev libgif-dev python-pyglet
         - wget -nv https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O /tmp/Miniconda3-latest-Linux-x86_64.sh
         - bash /tmp/Miniconda3-latest-Linux-x86_64.sh -b -p /tmp/miniconda3
         - export PATH=/tmp/miniconda3/bin:$PATH
         - pip install tox awscli
         - conda update -n root conda -y
-        - conda install -c conda-forge tox-conda
+        - conda install -c conda-forge tox-conda -y
+
+test-py37:
+    <<: *test-setup
+    script:
+        - xvfb-run tox -v --recreate -e py37
+
+test-py38:
+    <<: *test-setup
+    script:
+        - xvfb-run tox -v --recreate -e py38
+
+test-notebooks:
+    <<: *test-setup
+    script:
+        - xvfb-run tox -v --recreate -e notebooks
+
+test-examples:
+    <<: *test-setup
     script:
-        - xvfb-run tox -v --recreate
+        - xvfb-run tox -v --recreate -e examples
+
+test-docs:
+    <<: *test-setup
+    script:
+        - xvfb-run tox -v --recreate -e docs
+
+test-coverage:
+    <<: *test-setup
+    script:
+        - xvfb-run tox -v --recreate -e coverage
 
 build_and_deploy_docs:
-    image: "python:latest"
     stage: deploy_docs
     only:
         - master
     dependencies:
-        - tests
+        - test-docs
     before_script:
         - apt update
-        - apt install -y libgl1-mesa-glx xvfb xdg-utils libcairo2-dev libjpeg-dev libgif-dev
+        - apt install -y libgl1-mesa-glx xvfb xdg-utils libcairo2-dev libjpeg-dev libgif-dev graphviz libgraphviz-dev python-pyglet
         - wget -nv https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O /tmp/Miniconda3-latest-Linux-x86_64.sh
         - bash /tmp/Miniconda3-latest-Linux-x86_64.sh -b -p /tmp/miniconda3
         - export PATH=/tmp/miniconda3/bin:$PATH
@@ -55,22 +83,49 @@ build_and_deploy_docs:
         - echo "Bucket=${BUCKET_NAME}"
         - echo "AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION}"
         - echo "CI_COMMIT_REF_SLUG=${CI_COMMIT_REF_SLUG}"
-        - xvfb-run tox -v -e docs
+        - xvfb-run tox -v -e docs --recreate
         - aws s3 cp ./docs/_build/html/ s3://${BUCKET_NAME} --recursive
     environment:
         name: ${CI_COMMIT_REF_SLUG}
         url: http://${BUCKET_NAME}.s3-website.${AWS_DEFAULT_REGION}.amazonaws.com/
 
-benchmarks_and_profiling:
+profiling:
+    dependencies:
+        - test-py38
+        - test-py37
+        - test-notebooks
+        - test-examples
+        - test-coverage
+    stage: profiling
+    only:
+        variables:
+            - $BENCHMARKS_AND_PROFILING
+    before_script:
+        - apt update
+        - apt install -y libgl1-mesa-glx xvfb xdg-utils libcairo2-dev libjpeg-dev libgif-dev graphviz libgraphviz-dev python-pyglet
+        - wget -nv https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O /tmp/Miniconda3-latest-Linux-x86_64.sh
+        - bash /tmp/Miniconda3-latest-Linux-x86_64.sh -b -p /tmp/miniconda3
+        - export PATH=/tmp/miniconda3/bin:$PATH
+        - pip install tox awscli
+        - conda update -n root conda -y
+        - conda install -c conda-forge tox-conda
+    script:
+        - xvfb-run tox -e profiling -v --recreate
+
+benchmarks:
     dependencies:
-        - tests
-    stage: benchmarks_and_profiling
+        - test-py38
+        - test-py37
+        - test-notebooks
+        - test-examples
+        - test-coverage
+    stage: benchmarks
     only:
         variables:
             - $BENCHMARKS_AND_PROFILING
     before_script:
         - apt update
-        - apt install -y libgl1-mesa-glx xvfb xdg-utils libcairo2-dev libjpeg-dev libgif-dev
+        - apt install -y libgl1-mesa-glx xvfb xdg-utils libcairo2-dev libjpeg-dev libgif-dev graphviz libgraphviz-dev python-pyglet
         - wget -nv https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O /tmp/Miniconda3-latest-Linux-x86_64.sh
         - bash /tmp/Miniconda3-latest-Linux-x86_64.sh -b -p /tmp/miniconda3
         - export PATH=/tmp/miniconda3/bin:$PATH
@@ -78,13 +133,15 @@ benchmarks_and_profiling:
         - conda update -n root conda -y
         - conda install -c conda-forge tox-conda
     script:
-        - xvfb-run tox -e benchmarks,profiling -v --recreate
+        - xvfb-run tox -e benchmarks -v --recreate
 
 test_conda_setup:
     stage: integration_testing
+    services:
+        - redis
     before_script:
         - apt update
-        - apt install -y libgl1-mesa-glx xvfb xdg-utils libcairo2-dev libjpeg-dev libgif-dev
+        - apt install -y libgl1-mesa-glx xvfb xdg-utils libcairo2-dev libjpeg-dev libgif-dev graphviz libgraphviz-dev python-pyglet
         - wget -nv https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O /tmp/Miniconda3-latest-Linux-x86_64.sh
         - bash /tmp/Miniconda3-latest-Linux-x86_64.sh -b -p /tmp/miniconda3
         - export PATH=/tmp/miniconda3/bin:$PATH
@@ -92,4 +149,18 @@ test_conda_setup:
     script:
         - xvfb-run bash getting_started/getting_started.sh
 
-
+build_wheel:
+    image: "python:3.7-slim"
+    stage: build_wheel
+    before_script:
+        - apt update
+        - apt install -y make
+        - pip install -r requirements_dev.txt
+    script:
+        - make dist
+        - export WHEEL_NAME="$( find dist -name 'flatland_rl*.whl' )"
+        - mv "${WHEEL_NAME}" "${WHEEL_NAME/-py2.py3-/-py3-}"
+    artifacts:
+        paths:
+            - dist/flatland_rl*.whl
+        expire_in: 2 mos

.gitlab/issue_templates/Story.md

+### Story
+As a **ROLE**, I want **WHAT** so that **PURPOSE**.
+
+### Acceptance Criteria
+- Item 1
+- Item 2
+- Documentation Item 1
+- Documentation Item 2

AUTHORS.md

+# Credits
+
+Development
+-----------
+
+* Christian Baumberger <christian.baumberger@sbb.ch>
+* Christian Eichenberger <christian.markus.eichenberger@sbb.ch>
+* Adrian Egli <adrian.egli@sbb.ch>
+* Mattias Ljungström
+* Sharada Mohanty <mohanty@aicrowd.com>
+* Guillaume Mollard <guillaume.mollard2@gmail.com>
+* Erik Nygren <erik.nygren@sbb.ch>
+* Giacomo Spigler <giacomo.spigler@gmail.com>
+* Jeremy Watson
+
+
+Acknowledgements
+----------------
+* Vaibhav Agrawal <theinfamouswayne@gmail.com>
+* Anurag Ghosh
+
+
+Contributors
+------------
+
+None yet. Why not be the first?

AUTHORS.rst

-=======
-Credits
-=======
-
-Development
-----------------
-
-* S.P. Mohanty <mohanty@aicrowd.com>
-
-* G Spigler <giacomo.spigler@gmail.com>
-
-* A Egli <adrian.egli@sbb.ch>
-
-* E Nygren <erik.nygren@sbb.ch>
-
-* Ch. Eichenberger <christian.markus.eichenberger@sbb.ch>
-
-* Mattias Ljungström
-
-Contributors
-------------
-
-None yet. Why not be the first?

CONTRIBUTING.rst

@@ -108,12 +108,24 @@ Merge Request Guidelines
 Before you submit a merge request, check that it meets these guidelines:
 
 1. The merge request should include tests.
-2. If the merge request adds functionality, the docs should be updated. Put
+2. The code must be formatted (PyCharm)
+3. If the merge request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The merge request should work for Python 3.6, 3.7 and for PyPy. Check
+4. The merge request should work for Python 3.6, 3.7 and for PyPy. Check
    https://gitlab.aicrowd.com/flatland/flatland/pipelines
    and make sure that the tests pass for all supported Python versions.
+   We force pipelines to be run successfully for merge requests to be merged.
+5. Although we cannot enforce it technically, we ask for merge requests to be reviewed by at least one core member
+   in order to ensure that the Technical Guidelines below are respected and that the code is well tested:
+
+5.1.  The remarks from the review should be resolved/implemented and communicated using the 'discussions resolved':
+
+.. image:: images/DiscussionsResolved.png
+
+5.2.  When a merge request is merged, source branches should be deleted and commits squashed:
+
+.. image:: images/SourceBranchSquash.png
 
 Tips
 ----
@@ -135,3 +147,277 @@ $ git push
 $ git push --tags
 
 TODO: Travis will then deploy to PyPI if tests pass. (To be configured properly by Mohanty)
+
+
+Local Evaluation
+----------------
+
+This document explains you how to locally evaluate your submissions before making
+an official submission to the competition.
+
+Requirements
+~~~~~~~~~~~~
+
+* **flatland-rl** : We expect that you have `flatland-rl` installed by following the instructions in  [README.md](README.md).
+
+* **redis** : Additionally you will also need to have  `redis installed <https://redis.io/topics/quickstart>`_ and **should have it running in the background.**
+
+Test Data
+~~~~~~~~~
+
+* **test env data** : You can `download and untar the test-env-data <https://www.aicrowd.com/challenges/flatland-challenge/dataset_files>`, at a location of your choice, lets say `/path/to/test-env-data/`. After untarring the folder, the folder structure should look something like:
+
+
+.. code-block:: console
+
+    .
+    └── test-env-data
+        ├── Test_0
+        │   ├── Level_0.pkl
+        │   └── Level_1.pkl
+        ├── Test_1
+        │   ├── Level_0.pkl
+        │   └── Level_1.pkl
+        ├..................
+        ├..................
+        ├── Test_8
+        │   ├── Level_0.pkl
+        │   └── Level_1.pkl
+        └── Test_9
+            ├── Level_0.pkl
+            └── Level_1.pkl
+
+Evaluation Service
+~~~~~~~~~~~~~~~~~~
+
+* **start evaluation service** : Then you can start the evaluator by running :
+
+.. code-block:: console
+
+    flatland-evaluator --tests /path/to/test-env-data/
+
+RemoteClient
+~~~~~~~~~~~~
+
+* **run client** : Some `sample submission code can be found in the starter-kit <https://github.com/AIcrowd/flatland-challenge-starter-kit/>`_, but before you can run your code locally using `FlatlandRemoteClient`, you will have to set the `AICROWD_TESTS_FOLDER` environment variable to the location where you previous untarred the folder with `the test-env-data`:
+
+
+.. code-block:: console
+
+    export AICROWD_TESTS_FOLDER="/path/to/test-env-data/"
+
+    # or on Windows :
+    #
+    # set AICROWD_TESTS_FOLDER "\path\to\test-env-data\"
+
+    # and then finally run your code
+    python run.py
+
+
+Technical Guidelines
+--------------------
+
+Clean Code
+~~~~~~~~~~
+Please adhere to the general `Clean Code <https://www.planetgeek.ch/wp-content/uploads/2014/11/Clean-Code-V2.4.pdf>`_ principles,
+for instance we write short and concise functions and use appropriate naming to ensure readability.
+
+Naming Conventions
+~~~~~~~~~~~~~~~~~~
+
+We use the pylint naming conventions:
+
+`module_name`, `package_name`, `ClassName`, `method_name`, `ExceptionName`, `function_name`, `GLOBAL_CONSTANT_NAME`, `global_var_name`, `instance_var_name`, `function_parameter_name`, `local_var_name`.
+
+
+numpydoc
+~~~~~~~~
+
+Docstrings should be formatted using numpydoc_.
+
+
+.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
+
+
+Acessing resources
+~~~~~~~~~~~~~~~~~~
+
+We use `importlib-resources <https://importlib-resources.readthedocs.io/en/latest/>`_ to read from local files.
+    Sample usages:
+
+    .. code-block:: python
+
+        from importlib_resources import path
+
+        with path(package, resource) as file_in:
+            new_grid = np.load(file_in)
+
+    And:
+
+    .. code-block:: python
+
+        from importlib_resources import read_binary
+
+        load_data = read_binary(package, resource)
+        self.set_full_state_msg(load_data)
+
+
+
+    Renders the scene into a image (screenshot)
+
+    .. code-block:: python
+
+        renderer.gl.save_image("filename.bmp")
+
+Type Hints
+~~~~~~~~~~
+
+We use Type Hints (`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_) for better readability and better IDE support.
+
+    .. code-block:: python
+        # This is how you declare the type of a variable type in Python 3.6
+        age: int = 1
+
+        # In Python 3.5 and earlier you can use a type comment instead
+        # (equivalent to the previous definition)
+        age = 1  # type: int
+
+        # You don't need to initialize a variable to annotate it
+        a: int  # Ok (no value at runtime until assigned)
+
+        # The latter is useful in conditional branches
+        child: bool
+        if age < 18:
+            child = True
+        else:
+            child = False
+
+Have a look at the `Type Hints Cheat Sheet <https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html>`_ to get started with Type Hints.
+
+Caveat: We discourage the usage of Type Aliases for structured data since its members remain unnamed (see `Issue #284 <https://gitlab.aicrowd.com/flatland/flatland/issues/284/>`_).
+
+    .. code-block:: python
+        # Discouraged: Type Alias with unnamed members
+        Tuple[int, int]
+
+        # Better: use NamedTuple
+        from typing import NamedTuple
+
+        Position = NamedTuple('Position',
+            [
+                ('r', int),
+                ('c', int)
+            ]
+
+
+
+NamedTuple
+~~~~~~~~~~
+For structured data containers for which we do not write additional methods, we use
+`NamedTuple` instead of plain `Dict` to ensure better readability by
+
+    .. code-block:: python
+        from typing import NamedTuple
+
+        RailEnvNextAction = NamedTuple('RailEnvNextAction',
+            [
+                ('action', RailEnvActions),
+                ('next_position', RailEnvGridPos),
+                ('next_direction', Grid4TransitionsEnum)
+            ])
+
+Members of NamedTuple can then be accessed through `.<member>` instead of `['<key>']`.
+
+If we have to ensure some (class) invariant over multiple members
+(for instance, `o.A` always changes at the same time as `o.B`),
+then we should uses classes instead, see the next section.
+
+Class Attributes
+~~~~~~~~~~~~~~~~
+
+We use classes for data structures if we need to write methods that ensure (class) invariants over multiple members,
+for instance, `o.A` always changes at the same time as `o.B`.
+We use the attrs_ class decorator and a way to declaratively define the attributes on that class:
+
+    .. code-block:: python
+        @attrs
+        class Replay(object):
+            position = attrib(type=Tuple[int, int])
+
+.. _attrs: https://github.com/python-attrs/attrs
+
+
+Abstract Base Classes
+~~~~~~~~~~~~~~~~~~~~~
+We use the abc_ class decorator and a way to declaratively define the attributes on that class:
+
+    .. code-block:: python
+        # abc_base.py
+
+        import abc
+
+
+        class PluginBase(metaclass=abc.ABCMeta):
+
+            @abc.abstractmethod
+            def load(self, input):
+                """Retrieve data from the input source
+                and return an object.
+                """
+
+            @abc.abstractmethod
+            def save(self, output, data):
+                """Save the data object to the output."""
+
+
+
+
+And then
+
+    .. code-block:: python
+
+        # abc_subclass.py
+
+        import abc
+        from abc_base import PluginBase
+
+
+        class SubclassImplementation(PluginBase):
+
+            def load(self, input):
+                return input.read()
+
+            def save(self, output, data):
+                return output.write(data)
+
+
+        if __name__ == '__main__':
+            print('Subclass:', issubclass(SubclassImplementation,
+                                          PluginBase))
+            print('Instance:', isinstance(SubclassImplementation(),
+                                          PluginBase))
+
+.. _abc: https://pymotw.com/3/abc/
+
+
+
+Currying
+~~~~~~~~
+We discourage currying to encapsulate state since we often want the stateful object to have multiple methods
+(but the curried function has only its signature and abusing params to switch behaviour is not very readable).
+
+Thus, we should refactor our generators and use classes instead (see `Issue #283 <https://gitlab.aicrowd.com/flatland/flatland/issues/283>`_).
+
+    .. code-block:: python
+        # Type Alias
+        RailGeneratorProduct = Tuple[GridTransitionMap, Optional[Dict]]
+        RailGenerator = Callable[[int, int, int, int], RailGeneratorProduct]
+
+        # Currying: a function that returns a confectioned function with internal state
+        def complex_rail_generator(nr_start_goal=1,
+                                   nr_extra=100,
+                                   min_dist=20,
+                                   max_dist=99999,
+                                   seed=1) -> RailGenerator:
+
+

FAQ.md

+# Frequently Asked Questions (FAQs)
+
+## Questions about the Flatland Challenge:
+These are the most common questions regarding the [Flatland Challenge](https://www.aicrowd.com/challenges/flatland-challenge).
+If your questions are not answered please check the [Forum](https://discourse.aicrowd.com/c/flatland-challenge?_ga=2.33753761.1627822449.1571622829-1432296534.1549103074) and post your question there.
+
+### How can I win prizes in this challenge?
+You can win prizes in different categories.
+
+Best Solution Prize: Won by the participants with the best performing submission on our test set. Only your rankings from the Round 1 and Round 2 are taken into account. Check the leader board on this site regularly for the latest information on your ranking.
+
+The top three submissions in this category will be awarded the following cash prizes (in Swiss Francs):
+
+CHF 7’500.- for first prize
+
+CHF 5’000.- for second prize
+
+CHF 2’500.- for third prize
+
+Community Contributions Prize: Awarded to the person/group who makes the biggest contribution to the community - done through generating new observations and sharing them with the community.
+
+The top submission in this category will be awarded the following cash prize (in Swiss Francs): CHF 5’000.-
+
+In addition, we will hand-pick and award up to five (5) travel grants to the Applied Machine Learning Days 2019 in Lausanne, Switzerland. Participants with promising solutions may be invited to present their solutions at SBB in Bern, Switzerland.
+
+To check your eligibility please read the prizes section in the [rules](https://www.aicrowd.com/challenges/flatland-challenge/challenge_rules/68).
+
+### What are the deadlines for the flatland challenge?
+- The beta round starts on the 1st of July 2019 and ends on the 30th of July 2019
+- Round 1 closed on Sunday, 13th of October 2019, 12 PM. UTC +1
+- Round 2 closes on Sunday, 5th of January 2020, 12 PM. UTC +1
+
+### How is the score of a submission computed?
+The scores of your submission are computed as follows:
+
+1. Mean number of agents done, in other words how many agents reached their target in time.
+2. Mean reward is just the mean of the cummulated reward.
+3. If multiple participants have the same number of done agents we compute a "nomralized" reward as follows:
+```
+normalized_reward =cumulative_reward / (self.env._max_episode_steps +self.env.get_num_agents()
+```
+The mean number of agents done is the primary score value, only when it is tied to we use the "normalized" reward to determine the position on the leaderboard.
+
+### How do I submit to the Flatland Challenge?
+Follow the instructions in the [starter kit](https://github.com/AIcrowd/flatland-challenge-starter-kit) to get your first submission.
+
+### Can I use env variables with my controller?
+Yes you can. You can access all environment variables as you please. We recommend you use a custom observation builder to do so as explained [here](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/03_tutorials.html#custom-observations-and-custom-predictors-tutorial).
+
+### What are the time limits for my submission?
+If there is no action on the server for 10 minutes the submission will be cancelled and a time-out error wil be produced.
+
+If the submissions in total takes longer than 8 hours a time-out will occur.
+
+### What are the parameters for the environments for the submission scoring?
+The environments vary in size and number of agents as well as malfunction parameters. The upper limit of these variables for submissions are:
+- `(x_dim, y_dim) <= (150, 150)`
+- `n_agents <= 250` (this might be updated)
+- `malfunction rates` this is currently being refactored
+
+## Questions about the Flatland Repository:
+This section provides you with information about the most common questions around the Flatland repository. If your question is still not answered either reach out to the contacts listed on the repository directly or open an issue by following these [guidlines](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/06_contributing.html).
+### How can I get started with Flatland?
+Install Flatland by running `pip install -U flatland-rl` or directly from source by cloning the flatland repository and running `python setup.py --install` in the repository directory.
+
+These [Tutorials](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/03_tutorials.html) help you get a basic understanding of the flatland environment.
+### How do I train agents on Flatland?
+Once you have installed Flatland, head over to the [baselines repository](https://gitlab.aicrowd.com/flatland/baselines) to see how you can train your own reinforcement learning agent on Flatland.
+
+Check out this [tutorial](https://gitlab.aicrowd.com/flatland/baselines/blob/master/torch_training/Getting_Started_Training.md?_ga=2.193077805.1627822449.1571622829-1432296534.1549103074) to get a sense of how it works.
+
+### What is a observation builder and which should I use?
+Observation builders give you the possibility to generate custom observations for your controller (reinfocement learning agent, optimization algorithm,...). The observation builder has access to all environment data and can perform any operations on them as long as they are not changed.
+This [tutorial](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/03_tutorials.html#custom-observations-and-custom-predictors-tutorial) will give you a sense on how to use them.
+### What is a predictor and which one should I use?
+Because railway traffic is limited to rails, many decisions that you have to take need to consider future situations and detect upcoming conflicts ahead of time. Therefore, flatland provides the possibility of predictors that predict where agents will be in the future. We provide a stock predictor that assumes each agent just travels along its shortest path.
+You can build more elaborate predictors and use them as part of your observation builder. You find more information [here](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/03_tutorials.html#custom-observations-and-custom-predictors-tutorial).
+### What information is available about each agent?
+Each agent is an object and contains the following information:
+
+- `initial_position = attrib(type=Tuple[int, int])`: The initial position of an agent. This is where the agent will enter the environment. It is the start of the agent journey.
+- `position = attrib(default=None, type=Optional[Tuple[int, int]])`: This is the actual position of the agent. It is updated every step of the environment. Before the agent has entered the environment and after it leaves the environment it is set to `None`
+- `direction = attrib(type=Grid4TransitionsEnum)`: This is the direction an agent is facing. The values for directions are `North:0`, `East:1`, `South:2` and `West:3`.
+- `target = attrib(type=Tuple[int, int])`: This is the target position the agent has to find and reach. Once the agent reaches this position its taks is done.
+- `moving = attrib(default=False, type=bool)`: Because agents can have malfunctions or be stopped because their path is blocked we store the current state of an agent. If `agent.moving == True` the agent is currently advancing. If it is `False` the agent is either blocked or broken.
+- `speed_data = attrib(default=Factory(lambda: dict({'position_fraction': 0.0, 'speed': 1.0, 'transition_action_on_cellexit': 0})))`: This contains all the relevant information about the speed of an agent:
+    - The attribute `'position_fraction'` indicates how far the agent has advanced within the cell. As soon as this value becomes larger than `1` the agent advances to the next cell as defined by `'transition_action_on_cellexit'`.
+    - The attribute `'speed''` defines the travel speed of an agent. It can be any fraction smaller than 1.
+    - 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 `'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:
+    - `READY_TO_DEPART` not in grid yet (position is None) 
+    - `ACTIVE` in grid (position is not None), not done
+    - `DONE` in grid (position is not None), but done
+    - `DONE_REMOVED` removed from grid (position is None)
+
+### Can I use my own reward function?
+Yes you can do reward shaping as you please. All information can be accessed directly in the env.
+### What are rail and schedule generators?
+To generate environments for Flatland you need to provide a railway infrastructure (rail) and a set of tasks for each agent to complete (schedule).
+### What is the max number of timesteps per episode?
+The maximum number of timesteps is `max_time_steps = 4 * 2 * (env.width + env.height + 20)`
+### What are malfunctions and what can i do to resolve them?
+Malfunctions occur according to a Poisson process. The hinder an agent from performing its actions and update its position. While an agent is malfunctioning it is blocking the paths for other agents. There is nothing you can do to fix an agent, it will get fixed automatically as soon as `agent.malfunction_data['malfunction'] == 0` .
+You can however adjust the other agent actions to avoid delay propagation within the railway network and keeping traffic as smooth as possible.
+
+### Can agents communication with each other?
+There is no communitcation layer built into Flatland directly. You can however build a communication layer outside of the Flatland environment if necessary.
+
+## Questions about bugs
+### Why are my trains drawn outside of the rails?
+If you render your environment and the agents appear to be off the rail it is usually due to changes in the railway infrastructure. Make sure that you reset your renderer anytime the infrastructure changes by calling `env_renderer.reset().
+`

FAQ_Bugs.md

+# FAQ about bugs
+
+### Why are my trains drawn outside of the rails?
+If you render your environment and the agents appear to be off the rail it is usually due to changes in the railway infrastructure. Make sure that you reset your renderer anytime the infrastructure changes by calling `env_renderer.reset().
+`
+### I keep getting there error when submitting from windows
+When submitting from a Windows system you might run into the following error:
+```
+OSError: dlopen() failed to load a library: cairo / cairo-2 / cairo-gobject-2 / cairo.so.2
+```
+
+Please follow the intstruction in the starter-kit to avoid these problems. Make sure to reset your `environment.yml` correctly.
+
+[Link to Windows submission instructions](https://github.com/AIcrowd/flatland-challenge-starter-kit/blob/master/windows_submission.md)

FAQ_Challenge.md

+# FAQ about the Flatland Challenge
+
+These are the most common questions regarding the [Flatland Challenge](https://www.aicrowd.com/challenges/flatland-challenge).
+If your questions are not answered please check the [Forum](https://discourse.aicrowd.com/c/flatland-challenge?_ga=2.33753761.1627822449.1571622829-1432296534.1549103074) and post your question there.
+
+### How can I win prizes in this challenge?
+You can win prizes in different categories.
+
+Best Solution Prize: Won by the participants with the best performing submission on our test set. Only your rankings from the Round 1 and Round 2 are taken into account. Check the leader board on this site regularly for the latest information on your ranking.
+
+The top three submissions in this category will be awarded the following cash prizes (in Swiss Francs):
+
+- CHF 7'500.- for first prize
+- CHF 5'000.- for second prize
+- CHF 2'500.- for third prize
+
+Community Contributions Prize: Awarded to the person/group who makes the biggest contribution to the community - done through generating new observations and sharing them with the community.
+
+The top submission in this category will be awarded the following cash prize (in Swiss Francs): CHF 5'000.-
+
+In addition, we will hand-pick and award up to five (5) travel grants (up to 1'500 CHF each)to the Applied Machine Learning Days 2019 in Lausanne, Switzerland. Participants with promising solutions may be invited to present their solutions at SBB in Bern, Switzerland.
+
+To check your eligibility please read the prizes section in the [rules](https://www.aicrowd.com/challenges/flatland-challenge/challenge_rules/68).
+### What are the deadlines for the flatland challenge?
+- The beta round starts on the 1st of July 2019 and ends on the 30th of July 2019
+- Round 1 closed on Sunday, 13th of October 2019, 12 PM. UTC +1
+- Round 2 closes on Sunday, 5th of January 2020, 12 PM. UTC +1
+
+### How is the score of a submission computed?
+The scores of your submission are computed as follows:
+
+1. Mean number of agents done, in other words how many agents reached their target in time.
+2. Mean reward is just the mean of the cummulated reward.
+3. If multiple participants have the same number of done agents we compute a "nomralized" reward as follows:
+```
+normalized_reward =cumulative_reward / (self.env._max_episode_steps +self.env.get_num_agents()
+```
+The mean number of agents done is the primary score value, only when it is tied to we use the "normalized" reward to determine the position on the leaderboard.
+
+### How do I submit to the Flatland Challenge?
+Follow the instructions in the [starter kit](https://github.com/AIcrowd/flatland-challenge-starter-kit) to get your first submission.
+
+### Can I use env variables with my controller?
+Yes you can. You can access all environment variables as you please. We recommend you use a custom observation builder to do so as explained [here](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/03_tutorials.html#custom-observations-and-custom-predictors-tutorial).
+
+### What are the time limits for my submission?
+If there is no action on the server for 10 minutes the submission will be cancelled and a time-out error wil be produced.
+
+If the submissions in total takes longer than 8 hours a time-out will occur.
+
+### What are the parameters for the environments for the submission scoring?
+The environments vary in size and number of agents as well as malfunction parameters. The upper limit of these variables for submissions are:
+- `(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

+# FAQ about the Flatland Repository
+
+This section provides you with information about the most common questions around the Flatland repository. If your question is still not answered either reach out to the contacts listed on the repository directly or open an issue by following these [guidlines](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/06_contributing.html).
+### How can I get started with Flatland?
+Install Flatland by running `pip install -U flatland-rl` or directly from source by cloning the flatland repository and running `python setup.py --install` in the repository directory.
+
+These [Tutorials](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/03_tutorials.html) help you get a basic understanding of the flatland environment.
+### How do I train agents on Flatland?
+Once you have installed Flatland, head over to the [baselines repository](https://gitlab.aicrowd.com/flatland/baselines) to see how you can train your own reinforcement learning agent on Flatland.
+
+Check out this [tutorial](https://gitlab.aicrowd.com/flatland/baselines/blob/master/torch_training/Getting_Started_Training.md?_ga=2.193077805.1627822449.1571622829-1432296534.1549103074) to get a sense of how it works.
+
+### What is a observation builder and which should I use?
+Observation builders give you the possibility to generate custom observations for your controller (reinfocement learning agent, optimization algorithm,...). The observation builder has access to all environment data and can perform any operations on them as long as they are not changed.
+This [tutorial](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/03_tutorials.html#custom-observations-and-custom-predictors-tutorial) will give you a sense on how to use them.
+### What is a predictor and which one should I use?
+Because railway traffic is limited to rails, many decisions that you have to take need to consider future situations and detect upcoming conflicts ahead of time. Therefore, flatland provides the possibility of predictors that predict where agents will be in the future. We provide a stock predictor that assumes each agent just travels along its shortest path.
+You can build more elaborate predictors and use them as part of your observation builder. You find more information [here](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/03_tutorials.html#custom-observations-and-custom-predictors-tutorial).
+### What information is available about each agent?
+Each agent is an object and contains the following information:
+
+- `initial_position = attrib(type=Tuple[int, int])`: The initial position of an agent. This is where the agent will enter the environment. It is the start of the agent journey.
+- `position = attrib(default=None, type=Optional[Tuple[int, int]])`: This is the actual position of the agent. It is updated every step of the environment. Before the agent has entered the environment and after it leaves the environment it is set to `None`
+- `direction = attrib(type=Grid4TransitionsEnum)`: This is the direction an agent is facing. The values for directions are `North:0`, `East:1`, `South:2` and `West:3`.
+- `target = attrib(type=Tuple[int, int])`: This is the target position the agent has to find and reach. Once the agent reaches this position its taks is done.
+- `moving = attrib(default=False, type=bool)`: Because agents can have malfunctions or be stopped because their path is blocked we store the current state of an agent. If `agent.moving == True` the agent is currently advancing. If it is `False` the agent is either blocked or broken.
+- `speed_data = attrib(default=Factory(lambda: dict({'position_fraction': 0.0, 'speed': 1.0, 'transition_action_on_cellexit': 0})))`: This contains all the relevant information about the speed of an agent:
+    - The attribute `'position_fraction'` indicates how far the agent has advanced within the cell. As soon as this value becomes larger than `1` the agent advances to the next cell as defined by `'transition_action_on_cellexit'`.
+    - The attribute `'speed''` defines the travel speed of an agent. It can be any fraction smaller than 1.
+    - 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'` 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:
+    - `READY_TO_DEPART` not in grid yet (position is None) 
+    - `ACTIVE` in grid (position is not None), not done
+    - `DONE` in grid (position is not None), but done
+    - `DONE_REMOVED` removed from grid (position is None)
+
+### Can I use my own reward function?
+Yes you can do reward shaping as you please. All information can be accessed directly in the env.
+### What are rail and schedule generators?
+To generate environments for Flatland you need to provide a railway infrastructure (rail) and a set of tasks for each agent to complete (schedule).
+### What is the max number of timesteps per episode?
+The maximum number of timesteps is `max_time_steps = 4 * 2 * (env.width + env.height + 20)`
+### What are malfunctions and what can i do to resolve them?
+Malfunctions occur according to a Poisson process. The hinder an agent from performing its actions and update its position. While an agent is malfunctioning it is blocking the paths for other agents. There is nothing you can do to fix an agent, it will get fixed automatically as soon as `agent.malfunction_data['malfunction'] == 0` .
+You can however adjust the other agent actions to avoid delay propagation within the railway network and keeping traffic as smooth as possible.
+
+### Can agents communication with each other?
+There is no communitcation layer built into Flatland directly. You can however build a communication layer outside of the Flatland environment if necessary.

MANIFEST.in

-include AUTHORS.rst
+include AUTHORS.md
 include CONTRIBUTING.rst
-include HISTORY.rst
+include changelog.md
 include LICENSE
-include README.rst
+include README.md
+
 include requirements_dev.txt
 include requirements_continuous_integration.txt
 
 
 
-graft svg
+graft flatland/png
 graft env_data
 
 
@@ -16,4 +17,4 @@ recursive-include tests *
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
 
-recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif
+recursive-include docs *.rst *.md conf.py *.jpg *.png *.gif

README.md

+🚂 Flatland
+========
+
+![Flatland](https://i.imgur.com/0rnbSLY.gif)
+
+<p style="text-align:center">
+<img alt="repository" src="https://gitlab.aicrowd.com/flatland/flatland/badges/master/pipeline.svg">
+<img alt="coverage" src="https://gitlab.aicrowd.com/flatland/flatland/badges/master/coverage.svg">
+</p>
+
+Flatland is a open-source toolkit for developing and comparing Multi Agent Reinforcement Learning algorithms in little (or ridiculously large!) gridworlds.
+
+[The official documentation](http://flatland.aicrowd.com/) contains full details about the environment and problem statement
+
+Flatland is tested with Python 3.6, 3.7 and 3.8 on modern versions of macOS, Linux and Windows. You may encounter problems with graphical rendering if you use WSL. Your [contribution is welcome](https://flatland.aicrowd.com/misc/contributing.html) if you can help with this!  
+
+🏆 Challenges
+---
+
+This library was developed specifically for the AIcrowd [Flatland challenges](http://flatland.aicrowd.com/research/top-challenge-solutions.html) in which we strongly encourage you to take part in!
+
+- [Flatland 3 Challenge](https://www.aicrowd.com/challenges/flatland-3) - ONGOING!
+- [AMLD 2021 Challenge](https://www.aicrowd.com/challenges/flatland)
+- [NeurIPS 2020 Challenge](https://www.aicrowd.com/challenges/neurips-2020-flatland-challenge/)
+- [2019 Challenge](https://www.aicrowd.com/challenges/flatland-challenge)
+
+📦 Setup
+---
+
+### Prerequisites (optional)
+
+Install [Anaconda](https://www.anaconda.com/distribution/) and create a new conda environment:
+
+```console
+$ conda create python=3.7 --name flatland-rl
+$ conda activate flatland-rl
+```
+
+### Stable release
+
+Install Flatland from pip:
+
+```console
+$ pip install flatland-rl
+```
+
+This is the preferred method to install Flatland, as it will always install the most recent stable release.
+
+### From sources
+
+The Flatland code source is available from [AIcrowd gitlab](https://gitlab.aicrowd.com/flatland/flatland).
+
+Clone the public repository:
+
+```console
+$ git clone git@gitlab.aicrowd.com:flatland/flatland.git
+```
+
+Once you have a copy of the source, install it with:
+
+```console
+$ pip install -e .
+```
+
+### Test installation
+
+Test that the installation works:
+
+```console
+$ flatland-demo
+```
+
+You can also run the full test suite:
+
+```console
+python setup.py test
+```
+
+👥 Credits
+---
+
+This library was developed by [SBB](https://www.sbb.ch/en/), [Deutsche Bahn](https://www.deutschebahn.com/), [SNCF](https://www.sncf.com/en), [AIcrowd](https://www.aicrowd.com/) and [numerous contributors](http://flatland.aicrowd.com/misc/credits.html) and AIcrowd research fellows from the AIcrowd community.
+
+➕ Contributions
+---
+Please follow the [Contribution Guidelines](https://flatland.aicrowd.com/misc/contributing.html) for more details on how you can successfully contribute to the project. We enthusiastically look forward to your contributions!
+
+💬 Communication
+---
+
+* [Discord Channel](https://discord.com/invite/hCR3CZG)
+* [Discussion Forum](https://discourse.aicrowd.com/c/neurips-2020-flatland-challenge)
+* [Issue Tracker](https://gitlab.aicrowd.com/flatland/flatland/issues/)
+
+🔗 Partners
+---
+
+<a href="https://sbb.ch" target="_blank" style="margin-right:30px"><img src="https://annpr2020.ch/wp-content/uploads/2020/06/SBB.png" alt="SBB" width="140"/></a> 
+<a href="https://www.deutschebahn.com/" target="_blank" style="margin-right:30px"><img src="https://i.imgur.com/pjTki15.png" alt="DB"  width="140"/></a>
+<a href="https://www.sncf.com/en" target="_blank" style="margin-right:30px"><img src="https://iconape.com/wp-content/png_logo_vector/logo-sncf.png" alt="SNCF"  width="140"/></a>
+<a href="https://www.aicrowd.com" target="_blank"><img src="https://i.imgur.com/kBZQGI9.png" alt="AIcrowd"  width="140"/></a>

README.rst

-========
-Flatland
-========
-
-
-
-.. image:: https://gitlab.aicrowd.com/flatland/flatland/badges/master/pipeline.svg
-     :target: https://gitlab.aicrowd.com/flatland/flatland/pipelines
-     :alt: Test Running
-
-.. image:: https://gitlab.aicrowd.com/flatland/flatland/badges/master/coverage.svg
-     :target: https://gitlab.aicrowd.com/flatland/flatland/pipelines
-     :alt: Test Coverage
-
-'
-
-.. image:: https://i.imgur.com/0rnbSLY.gif
-  :width: 800
-  :align: center
-
-Flatland is a opensource toolkit for developing and comparing Multi Agent Reinforcement Learning algorithms in little (or ridiculously large !) gridworlds.
-The base environment is a two-dimensional grid in which many agents can be placed, and each agent must solve one or more navigational tasks in the grid world. More details about the environment and the problem statement can be found in the `official docs <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/>`_.
-
-This library was developed by `SBB <https://www.sbb.ch/en/>`_ , `AIcrowd <https://www.aicrowd.com/>`_ and numerous contributors and AIcrowd research fellows from the AIcrowd community.
-
-This library was developed specifically for the `Flatland Challenge <https://www.aicrowd.com/challenges/flatland-challenge>`_ in which we strongly encourage you to take part in.
-
-
-**NOTE This document is best viewed in the official documentation site at** `Flatland-RL Docs <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/readme.html>`_
-
-Contents
-===========
-* `Official Documentation <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/readme.html>`_
-* `About Flatland <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/about_flatland.html>`_
-* `Installation <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/installation.html>`_
-* `Getting Started <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/gettingstarted.html>`_
-* `Frequently Asked Questions <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/FAQ.html>`_
-* `Code Docs <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/modules.html>`_
-* `Contributing Guidelines <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/contributing.html>`_
-* `Discussion Forum <https://discourse.aicrowd.com/c/flatland-challenge>`_
-* `Issue Tracker <https://gitlab.aicrowd.com/flatland/flatland/issues/>`_
-
-Quick Start
-===========
-
-* Install `Anaconda <https://www.anaconda.com/distribution/>`_ by following the instructions `here <https://www.anaconda.com/distribution/>`_
-* Install the dependencies and the library
-
-.. code-block:: console
-
-    $ conda create python=3.6 --name flatland-rl
-    $ conda activate flatland-rl
-    $ conda install -c conda-forge cairosvg pycairo
-    $ conda install -c anaconda tk
-    $ pip install flatland-rl
-
-* Test that the installation works
-
-.. code-block:: console
-
-    $ flatland-demo
-
-
-Basic Usage
-============
-
-Basic usage of the RailEnv environment used by the Flatland Challenge
-
-.. code-block:: python
-
-    import numpy as np
-    import time
-    from flatland.envs.rail_generators import complex_rail_generator
-    from flatland.envs.schedule_generators import complex_schedule_generator
-    from flatland.envs.rail_env import RailEnv
-    from flatland.utils.rendertools import RenderTool
-
-    NUMBER_OF_AGENTS = 10
-    env = RailEnv(
-                width=20,
-                height=20,
-                rail_generator=complex_rail_generator(
-                                        nr_start_goal=10,
-                                        nr_extra=1,
-                                        min_dist=8,
-                                        max_dist=99999,
-                                        seed=0),
-                schedule_generator=complex_schedule_generator(),
-                number_of_agents=NUMBER_OF_AGENTS)
-
-    env_renderer = RenderTool(env)
-
-    def my_controller():
-        """
-        You are supposed to write this controller
-        """
-        _action = {}
-        for _idx in range(NUMBER_OF_AGENTS):
-            _action[_idx] = np.random.randint(0, 5)
-        return _action
-
-    for step in range(100):
-
-        _action = my_controller()
-        obs, all_rewards, done, _ = env.step(_action)
-        print("Rewards: {}, [done={}]".format( all_rewards, done))
-        env_renderer.render_env(show=True, frames=False, show_observations=False)
-        time.sleep(0.3)
-
-and **ideally** you should see something along the lines of
-
-.. image:: https://i.imgur.com/VrTQVeM.gif
-  :align: center
-  :width: 600px
-
-Best of Luck !!
-
-Contributions
-=============
-Flatland is an opensource project, and we very much value all and any contributions you make towards the project.
-Please follow the `Contribution Guidelines <http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/contributing.html>`_ for more details on how you can successfully contribute to the project. We enthusiastically look forward to your contributions.
-
-Partners
-============
-.. image:: https://i.imgur.com/OSCXtde.png
-   :target: https://sbb.ch
-.. image:: https://avatars1.githubusercontent.com/u/44522764?s=200&v=4
-   :target: https://www.aicrowd.com
-
-
-Authors
-============
-
-* Christian Eichenberger <christian.markus.eichenberger@sbb.ch>
-* Adrian Egli <adrian.egli@sbb.ch>
-* Mattias Ljungström
-* Sharada Mohanty <mohanty@aicrowd.com>
-* Guillaume Mollard <guillaume.mollard2@gmail.com>
-* Erik Nygren <erik.nygren@sbb.ch>
-* Giacomo Spigler <giacomo.spigler@gmail.com>
-* Jeremy Watson
-
-
-Acknowledgements
-====================
-* Vaibhav Agrawal <theinfamouswayne@gmail.com>
-* Anurag Ghosh

benchmarks/benchmark_all_examples.py

@@ -34,4 +34,6 @@ for entry in [entry for entry in importlib_resources.contents('examples') if
                 # https://docs.python.org/3/library/test.html
                 # TODO remove input() from examples?
                 with swap_attr(sys, "stdin", StringIO("q")):
-                    runpy.run_path(file_in, run_name="__main__")
+                    runpy.run_path(file_in, run_name="__main__", init_globals={
+                    'argv': ['--sleep-for-animation=False', '--do_rendering=False']
+                })

benchmarks/profile_all_examples.py

@@ -19,7 +19,9 @@ def profile(resource, entry):
         with swap_attr(sys, "stdin", StringIO("q")):
             global my_func
 
-            def my_func(): runpy.run_path(file_in, run_name="__main__")
+            def my_func(): runpy.run_path(file_in, run_name="__main__", init_globals={
+                    'argv': ['--sleep-for-animation=False', '--do_rendering=False']
+                })
 
             cProfile.run('my_func()', sort='time')
 

benchmarks/run_all_examples.py

@@ -8,8 +8,8 @@ from importlib_resources import path
 
 from benchmarks.benchmark_utils import swap_attr
 
-print("GRRRRRRRR run_all_examples.py")
-
+print("run_all_examples.py")
+error_log_examples = {}
 for entry in [entry for entry in importlib_resources.contents('examples') if
               not pkg_resources.resource_isdir('examples', entry)
               and entry.endswith(".py")
@@ -17,6 +17,7 @@ for entry in [entry for entry in importlib_resources.contents('examples') if
               and 'demo.py' not in entry
               and 'DELETE' not in entry
               ]:
+
     with path('examples', entry) as file_in:
         print("")
         print("")
@@ -25,12 +26,25 @@ for entry in [entry for entry in importlib_resources.contents('examples') if
         print("*****************************************************************")
         print("Running {}".format(entry))
         print("*****************************************************************")
+
         with swap_attr(sys, "stdin", StringIO("q")):
             try:
                 runpy.run_path(file_in, run_name="__main__", init_globals={
-                    'argv': ['--sleep-for-animation=False']
+                    'argv': ['--sleep-for-animation=False', '--do_rendering=False']
                 })
             except Exception as e:
                 print(e)
+                error_log_examples.update({file_in: e})
             print("runpy done.")
         print("Done with {}".format(entry))
+
+if len(error_log_examples.keys()) > 0:
+    print("*****************************************************************")
+    print("Error log:")
+    print("*****************************************************************")
+    print(error_log_examples)
+    print("*****************************************************************")
+else:
+    print("*****************************************************************")
+    print("All examples executed - no error.")
+    print("*****************************************************************")

changelog.md

 Changelog
 ==========
+Changes since Flatland 2.1.0
+--------------------------
 
+### Changes in 'schedule_generators'
+- Schedule generators now provide the max number of steps allowed per episode
+- Pickle files generated with older versions of Flatland need to be regenerated in order to include `_max_episode_steps`
 Changes since Flatland 2.0.0
 --------------------------
+### Changes in `EnvAgent`
+- class `EnvAgentStatic` was removed, so there is only class `EnvAgent` left which should simplify the handling of agents. The member `self.agents_static` of `RailEnv` was therefore also removed. Old Scence saved as pickle files cannot be loaded anymore.
+
+### Changes in malfunction behavior
+- agent attribute `next_malfunction`is not used anymore, it will be removed fully in future versions.
+- `break_agent()` function is introduced which induces malfunctions in agent according to poisson process
+- `_fix_agent_after_malfunction()` fixes agents after attribute `malfunction == 0`
+- Introduced the concept of malfunction generators. Here you can add different malfunction models in future updates. Currently it only loads from files and parameters.
 
 ### Changes in `Environment`
 - moving of member variable `distance_map_computed` to new class `DistanceMap`
 
 ### 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 (compliance for OpenAI Gym). Therefore the reset method needs to be called after the creation of a RailEnv object
+- renaming of parameters RailEnv.reset(): from `regen_rail` to `regenerate_rail`, from `replace_agents` to `regenerate_schedule`
+
+### Changes in schedule generation
+- return value of schedule generator has changed to the named tuple `Schedule`. From the point of view of a consumer, nothing has changed, this is just a type hint which is introduced where the attributes of `Schedule` have names.
 
 Changes since Flatland 1.0.0
 --------------------------
@@ -38,7 +56,8 @@ The stock `ShortestPathPredictorForRailEnv` now respects the different agent spe
   - `rail_generator` now only returns the grid and optionally hints (a python dictionary); the hints are currently use for distance_map and communication of start and goal position in complex rail generator.
   - `schedule_generator` takes a `GridTransitionMap` and the number of agents and optionally the `agents_hints` field of the hints dictionary.
   - Inrodcution of types hints:
-```
+
+```python
 RailGeneratorProduct = Tuple[GridTransitionMap, Optional[Any]]
 RailGenerator = Callable[[int, int, int, int], RailGeneratorProduct]
 AgentPosition = Tuple[int, int]
@@ -62,7 +81,7 @@ To set up multiple speeds you have to modify the `agent.speed_data` within your
 Just like in real-worl transportation systems we introduced stochastic events to disturb normal traffic flow. Currently we implemented a malfunction process that stops agents at random time intervalls for a random time of duration.
 Currently the Flatland environment can be initiated with the following poisson process parameters:
 
-```
+```python
 # Use a the malfunction generator to break agents from time to time
 stochastic_data = {'prop_malfunction': 0.1,  # Percentage of defective agents
                    'malfunction_rate': 30,  # Rate of malfunction occurence