{"id":16685323,"url":"https://github.com/wadaboa/flatland-challenge","last_synced_at":"2025-08-01T18:06:58.508Z","repository":{"id":87170665,"uuid":"254311540","full_name":"Wadaboa/flatland-challenge","owner":"Wadaboa","description":"Multi-agent reinforcement learning on trains, for Deep Learning class at UNIBO","archived":false,"fork":false,"pushed_at":"2021-01-14T17:33:48.000Z","size":46793,"stargazers_count":20,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-20T10:23:11.265Z","etag":null,"topics":["flatland-challenge","gnn","graph-neural-networks","mapf","marl","multi-agent","path-finding","reinforcement-learning"],"latest_commit_sha":null,"homepage":"https://www.aicrowd.com/challenges/neurips-2020-flatland-challenge/","language":"TeX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wadaboa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-09T08:15:31.000Z","updated_at":"2024-07-05T15:30:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"09a884b4-98f0-44b7-bff1-2eb4676ee847","html_url":"https://github.com/Wadaboa/flatland-challenge","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wadaboa%2Fflatland-challenge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wadaboa%2Fflatland-challenge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wadaboa%2Fflatland-challenge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wadaboa%2Fflatland-challenge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wadaboa","download_url":"https://codeload.github.com/Wadaboa/flatland-challenge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243428422,"owners_count":20289315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flatland-challenge","gnn","graph-neural-networks","mapf","marl","multi-agent","path-finding","reinforcement-learning"],"created_at":"2024-10-12T14:46:58.664Z","updated_at":"2025-03-13T14:41:23.923Z","avatar_url":"https://github.com/Wadaboa.png","language":"TeX","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flatland challenge\n\n![Example](assets/img/env.gif)\n\nThe Flatland challenge is a competition hosted by [AIcrowd](https://www.aicrowd.com/challenges/neurips-2020-flatland-challenge/), where participants should tackle a multi agent reinforcement learning problem on trains. This repository contains solutions and approaches to the challenge hosted in 2020 and sponsored by NeurIPS.\n\nNeural models have been implemented using the PyTorch framework and training results have been logged to [Weights \u0026 Biases](https://wandb.ai/) (also called `wandb`). Hyperparameters are handled via the use of a custom [parameters.yml](parameters.yml) file, that is accessed in almost every Python module of the project.\n\nOur solutions mostly focus on implementing custom predictors and observators. Moreover, we tried to exploit both common models, like DQN, but also custom-made ones, like those based on GNNs. If you want to know more about our work, you can read the full [report](report/report.pdf).\n\n## Installation\n\nBefore installing the actual Python libraries, make sure that you have installed the system packages listed below.\n\n**Ubuntu/Debian**\n```bash\nsudo apt install libcairo2-dev pkg-config python3-dev libbz2-dev liblzma-dev\n```\n------\n\nNext, to install all the libraries required by the Python package, run the following command:\n```bash\nchmod +x init/init.sh \n./init/init.sh \u003cenv\u003e \u003cdevice\u003e\n```\n\nHere, `\u003cenv\u003e` could be `pip` or `conda`, to choose what type of environment manager you want to use, while `\u003cdevice\u003e` could be `cpu` or `gpu`, to select the right dependencies based on the resources available.\n\nIf you select `conda` as the environment manager, you should have it installed on your system (see [here](https://docs.conda.io/en/latest/miniconda.html) for installation instructions).\n\nBeware that the `pip` environment was only tested with `Python 3.6.3` (you can use [pyenv](https://github.com/pyenv/pyenv) to handle multiple Python versions), while the `conda` environment automatically installs `Python 3.6.8`. \n\n## Training\n\n### New training\n\nIf you want to train one of the implemented models, make sure to select the required parameters in the `parameters.yml` file and then run `python3 src/train.py`. If everything goes as expected, you will find a text like the following on your standard output:\n\n```\n💾 Replay buffer status: 0/100000 experiences\n\n🚉 Starting training     Training 7 trains on 48x27 grid for 5000 episodes      Evaluating on 20 episodes every 200 episodes\n\n🧠 Model with training id 20201218-185537\n\n🚂 Episode    0  🏆 Score: -0.1945 Avg: -0.1945  🏅 Custom score: -0.8782 Avg: -0.8782   💯 Done: 14.29%  Avg:  14.29%   💀 Deadlocks: 85.71%  Avg:  85.71%      🦶 Steps:  130/ 611     🎲 Exploration prob: 1.000    🤔 Choices:  156        🤠 Exploration:  42     🔀 Choices probs: ← 23.70% → 8.30% ◼ 17.90% \n\n...\n```\n\nOne thing to note is that `wandb` logging should be disabled, since it requires a private access token linked to my personal account. Anyways, you can check the learning progress offline using Tensorboard, with the following command:\n\n```bash\ntensorboard --logdir=\"./runs\" --port 6006\n```\n\nTo view the Tensorboard interface, just open the link http://localhost:6006 on your browser.\n\n### Previous training results\n\nIf you want to check results obtained by training models with specific set of parameters, you can visit the [flatland-challenge](https://wandb.ai/wadaboa/flatland-challenge?workspace=user-wadaboa) project in my wandb account. Each run has a \"self-explanatory\" name and contains all the parameters used to train the model, charts depicting the learning progress, `PyTorch`'s `.pt` model files and actual logs extracted from the standard output.\n\n## Testing\n\nIf you want to test one pre-trained model, make sure to insert the model's file path (without the final extension) in `parameters.yml/testing/model` and adjust the other parameters in `parameters.yml` so that they are compatible with the ones used for training the loaded model. Then, simply run `python3 scr/test.py`. If everything goes as expected, you will find a text like the following on your standard output:\n\n```\n🚉 Starting testing      Testing 7 trains on 48x27 grid for 1 episodes\n\n🚂 Test    0     🏆 Score: -1.0000 Avg: -1.0000  🏅 Custom score: -2.1365 Avg: -2.1365   💯 Done: 0.00%   Avg:   0.00%   💀 Deadlocks: 57.14%  Avg:  57.14%      🦶 Steps:  610/ 611     🤔 Choices:  306\n\n...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwadaboa%2Fflatland-challenge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwadaboa%2Fflatland-challenge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwadaboa%2Fflatland-challenge/lists"}