Commit bd052de6 authored by Erik Nygren's avatar Erik Nygren 🚅
Browse files

Merge branch 'master' into 188_refining_generator

# Conflicts:
#	examples/simple_example_city_railway_generator.py
parents 03b13140 f3b309d4
Pipeline #2191 failed with stages
in 17 minutes and 41 seconds
......@@ -55,7 +55,7 @@ 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}
......
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?
=======
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?
......@@ -135,3 +135,70 @@ $ 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
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
Flatland
========
![Test Running](https://gitlab.aicrowd.com/flatland/flatland/badges/master/pipeline.svg)![Test Coverage](https://gitlab.aicrowd.com/flatland/flatland/badges/master/coverage.svg "asdff")
![Flatland](https://i.imgur.com/0rnbSLY.gif)
## About Flatland
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/)
## Installation
### Installation Prerequistes
* Install [Anaconda](https://www.anaconda.com/distribution/) by following the instructions [here](https://www.anaconda.com/distribution/).
* Create a new conda environment:
```console
$ conda create python=3.6 --name flatland-rl
$ conda activate flatland-rl
```
* Install the necessary dependencies
```console
$ conda install -c conda-forge cairosvg pycairo
$ conda install -c anaconda tk
```
### Install Flatland
#### Stable Release
To install flatland, run this command in your terminal:
```console
$ pip install flatland-rl
```
This is the preferred method to install flatland, as it will always install the most recent stable release.
If you don't have `pip`_ installed, this `Python installation guide`_ can guide
you through the process.
.. _pip: https://pip.pypa.io
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
#### From sources
The sources for flatland can be downloaded from [gitlab](https://gitlab.aicrowd.com/flatland/flatland)
You can clone the public repository:
```console
$ git clone git@gitlab.aicrowd.com:flatland/flatland.git
```
Once you have a copy of the source, you can install it with:
```console
$ python setup.py install
```
### Test installation
Test that the installation works
```console
$ flatland-demo
```
### Jupyter Canvas Widget
If you work with jupyter notebook you need to install the Jupyer Canvas Widget. To install the Jupyter Canvas Widget read also
https://github.com/Who8MyLunch/Jupyter_Canvas_Widget#installation
## Basic Usage
Basic usage of the RailEnv environment used by the Flatland Challenge
```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
![Flatland](https://i.imgur.com/VrTQVeM.gif)
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.
## Partners
<a href="https://sbb.ch" target="_blank"><img src="https://i.imgur.com/OSCXtde.png" alt="SBB"/></a>
<a href="https://www.aicrowd.com" target="_blank"><img src="https://avatars1.githubusercontent.com/u/44522764?s=200&v=4" alt="AICROWD"/></a>
========
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
......@@ -38,7 +38,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 +63,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
......
.. include:: tutorials/01_gettingstarted.rst
.. include:: tutorials/02_observationbuilder.rst
.. include:: tutorials/03_rail_and_schedule_generator.rst
.. include:: tutorials/04_stochasticity.rst
.. include:: tutorials/05_multispeed.rst
Tutorials
=========
.. toctree::
:maxdepth: 2
03_tutorials
.. include:: specifications/intro.rst
.. include:: specifications/core.rst
.. include:: specifications/railway.rst
.. include:: specifications/intro_observation_actions.rst
.. include:: specifications/rendering.rst
.. include:: specifications/visualization.rst
.. include:: specifications/FAQ.rst
Specifications
==============
.. toctree::
:maxdepth: 2
04_specifications
......@@ -4,5 +4,4 @@ Changes
.. toctree::
:maxdepth: 2
changelog.md
flatland_2.0.md
07_changes_include.rst
.. include:: ../changelog.rst
.. include:: ../flatland_2.0.rst
About Flatland
==============
.. image:: https://i.imgur.com/rKGEmsk.gif
:align: center
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.
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.
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.
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.
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.
.. image:: https://i.imgur.com/pucB84T.gif
:align: center
:width: 600px
.. image:: https://i.imgur.com/xgWGRse.gif
:align: center
:width: 600px
\ No newline at end of file
......@@ -33,7 +33,7 @@ sys.path.insert(0, os.path.abspath('..'))
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['recommonmark', 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', 'numpydoc']
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', 'numpydoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
......
Welcome to flatland's documentation!
======================================
.. include:: ../README.rst
.. toctree::
:maxdepth: 2
:caption: Contents:
readme
installation
about_flatland
gettingstarted
intro_observationbuilder
intro_observation_actions
specifications_index
modules
FAQ
localevaluation
contributing
changelog_index
authors
01_readme
03_tutorials_toc
04_specifications_toc
05_apidoc
06_contributing
07_changes
08_authors
Indices and tables
==================
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment