Current state of implementation:
- Run
python conflict_avoiding_agents.pyto run the hand-crafted approach- Hand-crafted approach lets agents go only if no other agents traverse the same path in opposite direction.
- Run
python train_policy.pyto train or execute models. There are several CLI-arguments:
--train
Runs a training session (default)
--run
Runs a testing session
--epochs
Number of epochs to train the model
--checkpoint
The path to a previously trained model or to a new checkpoint under which
the model will be saved after training.
--data_path
Acquiring a dataset takes simulating a lot of episodes which takes time.
If data_path is given, the script will save a dataset once it is acquired
and if the script is rerun will load it automatically.
--batches_per_epoch
Number of batches of an epoch.
--batch_size
The number of samples in each batch.
--max_agents
The maximal number of agents that spawn in the environment.
- A simple training run could look like this:
python train_policy.py --train --data_path flatland_data.npy --checkpoint ckpts/baseline_model- This run will persist the dataset in the file
flatland_data.npyand create a model checkpoint inckpts/baseline_model
- Following this training, the model can be tested via
python train_policy.py --run --checkpoint ckpts/baseline_model
This is the starter kit for the Flatland 3 Challenge hosted on AIcrowd. Clone the repository to compete now!
This repository contains:
- Documentation on how to submit your models to the leaderboard.
- Information on evaluating your agents locally, baselines and some best practises to have hassle free submissions.
- Starter code for you to get started!
IMPORTANT - Accept the rules before you submit
- ⚔️ Competition procedure
- 🚃 Flatland 3 Environment
- 💪 Getting started
- 🛠 Preparing your submission
- 📚 Submission
- 📝 Submission Checklist
- 📎 Important links
- ✨ Contributors
Flatland tackles a key problem in the transportation world: How to efficiently manage dense traffic on complex railway networks?
Flatland is a simulated game environment aiming to test multi-agent reinforcment learning solutions for scheduling trains. Flatland procedurally generates maps with train tracks and cities for any given grid size. It populates these maps with trains to be taken from a source city to a destination within a time constraint. The challenge is to deal with stochasticity of malfunctions while efficiently scheduling the all trains.
Check the Flatland Documentation to find out more.
Up until this point, the trains in Flatland were allowed to depart and arrive whenever they desired, the only goal was to make every train reach its destination as fast as possible. However, things are quite different in the real world. Timing and punctuality are crucial to railways. Trains have specific schedules. They are expected to depart and arrive at particular times.
This concept has been introduced to the environment in Flatland 3.0. Trains now have a time window within which they are expected to start and reach their destination.
Timetable attributes can now be accessed with agent.earliest_departure and agent.latest_arrival for every agent in a Flatland environment instance.
For people who have worked on Flatland previously, check the migration guide for other code changes in Flatland 3.
In this challenge, you will pit your ideas on reinforcement learning and operations research to get the best solution to Flatland 3. Your contribution may shape the way modern traffic management systems are implemented, not only in railway but also in other areas of transportation and logistics!
The following is a high level description of how this process works.
- Sign up to join the competition on the Flatland 3 challenge page at AIcrowd.
- Clone this repo and start developing your solution.
- Design and build your agents that can solve Flatland 3 maps.
- Submit your agents to AIcrowd Gitlab for evaluation. [Refer this for detailed instructions].
We recommend using
python 3.6. If you are using Miniconda/Anaconda, you can install it usingconda install python=3.6.
Clone the starter kit repository and install the dependencies.
git clone https://gitlab.aicrowd.com/flatland/flatland-starter-kit
cd flatland-starter-kit
pip install git+http://gitlab.aicrowd.com/flatland/flatland.git
conda env create -f environment.ymlImplement an agent that is capable of adding producing actions for every train in the Flatland map. Refer to baselines/run.py for a reference agent.
Note: Please note that the maps are generated on the evaluator and your cannot control the settings for map generation.
| File/Directory | Description |
|---|---|
baselines |
Directory containing an example RL agent as well as training code for the same. Please refer to baselines/README.md for further details. |
utils/submit.sh |
Helper script to submit your repository to AIcrowd GitLab. |
Dockerfile |
(Optional) You can add a Dockerfile for specifying your exact environment. Refer to docs/RUNTIME.md for further details. |
environment.yml |
File containing the list of python packages you want to install for the submission to run. This will instantiate a conda environment. |
apt.txt |
File containing the list of packages you want to install for submission to run. Refer runtime configuration for more information. |
run.sh |
Submission entrypoint - Use this as the entrypoint to run your code you need to run for your submission. |
aicrowd.json |
For specifying your submission track, RL or Overall. |
You can specify the list of python packages needed for your code to run in your environment.yml file. We will install the packages using conda env create -f environment.yml command.
You can also specify the OS packages needed using apt.txt file. We install these packages using apt-get install command.
For more information on how you can configure the evaluation runtime, please refer RUNTIME.md.
You can add your SSH Keys to your GitLab account by going to your profile settings here. If you do not have SSH Keys, you will first need to generate one.
Your repository should have an aicrowd.json file with following fields:
{
"challenge_id" : "flatland-3",
"grader_id" : "flatland-3",
"authors" : ["Your Name"],
"description" : "Brief description for your submission",
"debug": false,
"tags": "RL" OR "Overall"
}This file is used to identify your submission as a part of the Flatland 3 challenge. You must use the challenge_id, and grader_id as specified above.
debug: If you set debug to true, then the evaluation will run for a shorter time, and the logs from your submitted code will be made available to you to help you debug. These test submissions will appear at the bottom of the leaderboard (score of -1.0).
git remote add aicrowd [email protected]:<username>/flatland-starter-kit.gitNote: This needs to be done only once. This configuration will be saved in your repository for future use.
./utils/submit.sh "some description"If you want to submit without the helper script, please refer SUBMISSION.md.
- Accept the challenge rules. You can do this by going to the challenge overview page and clicking the "Participate" button. You only need to do this once.
- Modify run.sh that is runs your agent's code.
- Add your model checkpoints (if any) to the repo. The
utils/submit.shwill automatically detect large files and add them to git LFS. If you are using the script, please refer to this post explaining how to add your models. - Update runtime configuration using
environment.yml,apt.txtand/orDockerfileas necessary. Please make sure that you specified the same package versions that you use locally on your machine.
- 💪 Challenge information
- 🗣 Community
- 🚃 Flatland resources
Best of Luck 🎉