diff --git a/MANIFEST.in b/MANIFEST.in
index ca50ea340f7f443d230f1f473a34331525fdbef1..6669a47ef184b5f70befc0a34088ee388435ba82 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,8 +1,9 @@
-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
@@ -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
diff --git a/README.md b/README.md
index 27ab7d1e550fcd269f7dd2fd9a2401ee5f3e988c..2c00d9011af54abbfaeb812dde57cbdf8b5cb9aa 100644
--- a/README.md
+++ b/README.md
@@ -8,39 +8,15 @@ Flatland
## About Flatland
-Flatland is a toolkit for developing and comparing multi agent reinforcement learning algorithms on grids.
-The base environment is a two-dimensional grid in which many agents can be placed. Each agent must solve one or more tasks in the grid world.
-In general, agents can freely navigate from cell to cell. However, cell-to-cell navigation can be restricted by transition maps.
-Each cell can hold an own transition map. By default, each cell has a default transition map defined which allows all transitions to its
-eight neighbor cells (go up and left, go up, go up and right, go right, go down and right, go down, go down and left, go left).
-So, the agents can freely move from cell to cell.
+Flatland is a opensource toolkit for developing and comparing Multi Agent Reinforcement Learning algorithms in little (or ridiculously large !) gridworlds.
-The general purpose of the implementation allows to implement any kind of two-dimensional gird based environments.
-It can be used for many learning task where a two-dimensional grid could be the base of the environment.
+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/).
-Flatland delivers a python implementation which can be easily extended. And it provides different baselines for different environments.
-Each environment enables an interesting task to solve. For example, the mutli-agent navigation task for railway train dispatching is a very exciting topic.
-It can be easily extended or adapted to the airplane landing problem. This can further be the basic implementation for many other tasks in transportation and logistics.
+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.
-Mapping a railway infrastructure into a grid world is an excellent example showing how the movement of an agent must be restricted.
-As trains can normally not run backwards and they have to follow rails the transition for one cell to the other depends also on train's orientation, respectively on train's travel direction.
-Trains can only change the traveling path at switches. There are two variants of switches. The first kind of switch is the splitting "switch", where trains can change rails and in consequence they can change the traveling path.
-The second kind of switch is the fusion switch, where train can change the sequence. That means two rails come together. Thus, the navigation behavior of a train is very restricted.
-The railway planning problem where many agents share same infrastructure is a very complex problem.
+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.
-Furthermore, trains have a departing location where they cannot depart earlier than the committed departure time.
-Then they must arrive at destination not later than the committed arrival time. This makes the whole planning problem
-very complex. In such a complex environment cooperation is essential. Thus, agents must learn to cooperate in a way that all trains (agents) arrive on time.
-
-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/>`_
+**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/)
## Installation
@@ -152,6 +128,12 @@ and **ideally** you should see something along the lines of
Best of Luck !!
+## Communication
+* [Official Documentation](http://flatland-rl-docs.s3-website.eu-central-1.amazonaws.com/)
+* [Discussion Forum](https://discourse.aicrowd.com/c/flatland-challenge)
+* [Issue Tracker](https://gitlab.aicrowd.com/flatland/flatland/issues/)
+
+
## Contributions
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.
diff --git a/docs/04_specifications.rst b/docs/04_specifications.rst
index 28e66a10e29662902c22e872c4121717f1d7c7dd..61e4dc685b69e3f705683444528e022c7949dd9f 100644
--- a/docs/04_specifications.rst
+++ b/docs/04_specifications.rst
@@ -3,3 +3,4 @@
.. include:: specifications/railway.rst
.. include:: specifications/rendering.rst
.. include:: specifications/visualization.rst
+.. include:: specifications/FAQ.rst
diff --git a/docs/specifications/intro.md b/docs/specifications/intro.md
index 000a5347c0a7e37a4ca1ee7a9c2f79b27f2b67c5..c6b8d792edf9759ae129acdf80804f41e7de0650 100644
--- a/docs/specifications/intro.md
+++ b/docs/specifications/intro.md
@@ -5,5 +5,5 @@ In a human-readable language, specifications provide
- key concepts (generators, envs) and how are they linked
- link relevant code base
-.. image:: specifications/img/UML_flatland.png
+
`Diagram Source <https://confluence.sbb.ch/x/pQfsSw>`_
diff --git a/flatland/core/grid/grid_utils.py b/flatland/core/grid/grid_utils.py
index 20c6f8b54e89ab67365921326e45f2a0eeb523dd..6004c53567f46feb30e283f0b9dbd946ee8f1375 100644
--- a/flatland/core/grid/grid_utils.py
+++ b/flatland/core/grid/grid_utils.py
@@ -50,9 +50,7 @@ class Vec2dOperations:
:param node_a: tuple with coordinate (x,y) or 2d vector
:param node_b: tuple with coordinate (x,y) or 2d vector
- :return:
- -------
- tuple with coordinate (x,y) or 2d vector
+ :return: tuple with coordinate (x,y) or 2d vector
"""
return node_a[0] + node_b[0], node_a[1] + node_b[1]
@@ -62,9 +60,8 @@ class Vec2dOperations:
vector operation : rotates the 2D vector +90°
:param node: tuple with coordinate (x,y) or 2d vector
- :return:
- -------
- tuple with coordinate (x,y) or 2d vector
+
+ :return: tuple with coordinate (x,y) or 2d vector
"""
return node[1], -node[0]
@@ -127,7 +124,7 @@ class Vec2dOperations:
calculates the chebyshev norm of the 2d vector
[see: https://lyfat.wordpress.com/2012/05/22/euclidean-vs-chebyshev-vs-manhattan-distance/]
- :Parameters
+ Parameters
----------
node_a
tuple with coordinate (x,y) or 2d vector
@@ -145,7 +142,7 @@ class Vec2dOperations:
@staticmethod
def normalize(node: Vector2D) -> Tuple[float, float]:
"""
- normalize the 2d vector = v/|v|
+ normalize the 2d vector = `v/|v|`
:param node: tuple with coordinate (x,y) or 2d vector
diff --git a/flatland/envs/rail_generators_city_generator.py b/flatland/envs/rail_generators_city_generator.py
index 53cdaef1e0bbe794f38f72cb77089f296e0c9cf5..ecea9f902d509572afd9087a6e9b64bee144b3f2 100644
--- a/flatland/envs/rail_generators_city_generator.py
+++ b/flatland/envs/rail_generators_city_generator.py
@@ -37,10 +37,10 @@ def city_generator(num_cities: int = 5,
:param a_star_distance_function: Heuristic how the distance between two nodes get estimated in the "a-star" path
:param seed: Random Seed
:param print_out_info: print debug info if True
- :return:
- -------
- numpy.ndarray of type numpy.uint16
- The matrix with the correct 16-bit bitmaps for each cell.
+
+ :return: The matrix with the correct 16-bit bitmaps for each cell.
+ :rtype: numpy.ndarray of type numpy.uint16
+
"""
def do_generate_city_locations(width: int,
@@ -269,8 +269,8 @@ def city_generator(num_cities: int = 5,
intern_connect_max_nbr_of_shortes_city: int):
city_edges = []
- s_nodes:IntVector2DArrayArray = copy.deepcopy(org_s_nodes)
- e_nodes:IntVector2DArrayArray = copy.deepcopy(org_e_nodes)
+ s_nodes: IntVector2DArrayArray = copy.deepcopy(org_s_nodes)
+ e_nodes: IntVector2DArrayArray = copy.deepcopy(org_e_nodes)
for nbr_connected in range(intern_connect_max_nbr_of_shortes_city):
for city_loop in range(len(s_nodes)):
diff --git a/flatland/evaluators/service.py b/flatland/evaluators/service.py
index 8967b52d9d6ee70a7eb8af257ef6b4e25b531314..4f273be466a1c2f95b55cafece4783bad91e0d2c 100644
--- a/flatland/evaluators/service.py
+++ b/flatland/evaluators/service.py
@@ -44,10 +44,9 @@ class FlatlandRemoteEvaluationService:
"""
A remote evaluation service which exposes the following interfaces
of a RailEnv :
- - env_create
- - env_step
- and an additional `env_submit` to cater to score computation and
- on-episode-complete post processings.
+ - env_create
+ - env_step
+ and an additional `env_submit` to cater to score computation and on-episode-complete post processings.
This service is designed to be used in conjunction with
`FlatlandRemoteClient` and both the srevice and client maintain a
@@ -148,17 +147,17 @@ class FlatlandRemoteEvaluationService:
for evaluation. The folder structure expected at the `test_env_folder`
is similar to :
- .
- ├── Test_0
- │  ├── Level_1.pkl
- │  ├── .......
- │  ├── .......
- │  └── Level_99.pkl
- └── Test_1
- ├── Level_1.pkl
-   ├── .......
-   ├── .......
- └── Level_99.pkl
+ .
+ ├── Test_0
+ │  ├── Level_1.pkl
+ │  ├── .......
+ │  ├── .......
+ │  └── Level_99.pkl
+ └── Test_1
+ ├── Level_1.pkl
+   ├── .......
+   ├── .......
+ └── Level_99.pkl
"""
env_paths = sorted(glob.glob(
os.path.join(
@@ -291,9 +290,7 @@ class FlatlandRemoteEvaluationService:
def handle_env_create(self, command):
"""
Handles a ENV_CREATE command from the client
- TODO:
- Add a high level summary of everything thats
- hapenning here.
+ TODO: Add a high level summary of everything thats happening here.
"""
self.simulation_count += 1
if self.simulation_count < len(self.env_file_paths):
@@ -374,9 +371,7 @@ class FlatlandRemoteEvaluationService:
def handle_env_step(self, command):
"""
Handles a ENV_STEP command from the client
- TODO:
- Add a high level summary of everything thats
- hapenning here.
+ TODO: Add a high level summary of everything thats happening here.
"""
_payload = command['payload']
@@ -449,9 +444,7 @@ class FlatlandRemoteEvaluationService:
def handle_env_submit(self, command):
"""
Handles a ENV_SUBMIT command from the client
- TODO:
- Add a high level summary of everything thats
- hapenning here.
+ TODO: Add a high level summary of everything thats happening here.
"""
_payload = command['payload']
diff --git a/flatland/utils/editor.py b/flatland/utils/editor.py
index af1aad222919b00b716dd9da0f3be9534d54e411..e5d55bb51241307d0bf9251eb20ea36faac479ba 100644
--- a/flatland/utils/editor.py
+++ b/flatland/utils/editor.py
@@ -696,10 +696,10 @@ class EditorModel(object):
def click_agent(self, cell_row_col):
""" The user has clicked on a cell -
- - If there is an agent, select it
- - If that agent was already selected, then deselect it
- - If there is no agent selected, and no agent in the cell, create one
- - If there is an agent selected, and no agent in the cell, move the selected agent to the cell
+ * If there is an agent, select it
+ * If that agent was already selected, then deselect it
+ * If there is no agent selected, and no agent in the cell, create one
+ * If there is an agent selected, and no agent in the cell, move the selected agent to the cell
"""
# Has the user clicked on an existing agent?