From d390789f7b450f4d9067748e7fcc26fad72eac36 Mon Sep 17 00:00:00 2001
From: u214892 <u214892@sbb.ch>
Date: Thu, 26 Sep 2019 13:54:34 +0200
Subject: [PATCH] #80 cleanup
---
MANIFEST.in | 9 ++--
README.md | 40 +++++-------------
docs/04_specifications.rst | 1 +
docs/specifications/intro.md | 2 +-
flatland/core/grid/grid_utils.py | 13 +++---
.../envs/rail_generators_city_generator.py | 12 +++---
flatland/evaluators/service.py | 41 ++++++++-----------
flatland/utils/editor.py | 8 ++--
8 files changed, 50 insertions(+), 76 deletions(-)
diff --git a/MANIFEST.in b/MANIFEST.in
index ca50ea34..6669a47e 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 27ab7d1e..2c00d901 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 28e66a10..61e4dc68 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 000a5347..c6b8d792 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 20c6f8b5..6004c535 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 53cdaef1..ecea9f90 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 8967b52d..4f273be4 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 af1aad22..e5d55bb5 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?
--
GitLab