Commit 54873161 authored by Dipam Chakraborty's avatar Dipam Chakraborty
Browse files

documentation and other minor changes

parent 9e624a35
# The NeuralMMO Challenge Starter Kit
![AIcrowd-Logo](https://raw.githubusercontent.com/AIcrowd/AIcrowd/master/app/assets/images/misc/aicrowd-horizontal.png)
This is the starter kit for the [The Neural MMO Challenge](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)
# 🕵️ About The NeuralMMO Challenge
# **[The Neural MMO Challenge](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)** - Starter Kit
Neural-MMO is a platform for agent-based intelligence research featuring hundreds of concurrent agents, multi-thousand-step time horizons, and procedurally-generated, million-tile maps. This release ships with pretrained models, scripted baselines, evaluation tools, a customizable dashboard, and an interactive 3D client packed with visualization tools.
This repository is the Nethack Challenge **Starter kit**! It contains:
* **Instructions** for setting up your codebase to make submissions easy.
* **Baselines** for quickly getting started training your agent.
* **Documentation** for how to submit your model to the leaderboard.
Progress in multiagent intelligence research is fundamentally limited by the complexity of environments available for study. Neural MMO is a massively multiagent AI research environment inspired by Massively Multiplayer Online (MMO) role playing games – self-contained worlds featuring thousands of agents per persistent macrocosm, diverse skilling systems, local and global economies, complex emergent social structures, and ad-hoc high-stakes single and team based conflict. Our goal is not to simulate the near-infinite physical processes of life on Earth but instead to construct an efficient facsimile that incentivizes the emergence of high-level social and general artificial intelligence. To this end, we consider MMOs the best proxy for the real world among human games.
Quick Links:
You can read more in the Neural-MMO documentation
* [The Neural MMO Challenge - Competition Page](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)
* [Neural MMO - Github](https://github.com/jsuarez5341/neural-mmo)
* [Neural MMO - Documentation](https://jsuarez5341.github.io/neural-mmo/build/html/rst/userguide.html)
* [Neural MMO - Discord Server](https://discord.gg/JrRNh8rZ7j)
* [The NetHack Challenge - Starter Kit](https://gitlab.aicrowd.com/neural-mmo/neuralmmo-starter-kit)
* [IMPORTANT - Accept the rules before you submit](https://www.aicrowd.com/challenges/the-neural-mmo-challenge/challenge_rules)
# Table of Contents
1. [About The NeuralMMO Challenge](#about-the-neuralmmo-challenge)
2. [Setup and Installation](#🛠-setup-and-installation)
3. [Getting Started](#💪-getting-started)
4. [Helpful Information](#📋-helpful-information)
# 🔧 Installation
# About The NeuralMMO Challenge
## Quick start
**Neural-MMO** is a platform for **agent-based intelligence research** featuring hundreds of concurrent agents, multi-thousand-step time horizons, and procedurally-generated, million-tile maps. It provides pretrained models, scripted baselines, evaluation tools, a customizable dashboard, and an interactive 3D client packed with visualization tools.
Progress in multiagent intelligence research is fundamentally limited by the complexity of environments available for study. Neural MMO is a massively multiagent **AI research environment inspired by Massively Multiplayer Online (MMO) role playing games** – self-contained worlds featuring thousands of agents per persistent macrocosm, diverse skilling systems, local and global economies, complex emergent social structures, and ad-hoc high-stakes single and team based conflict. Our goal is not to simulate the near-infinite physical processes of life on Earth but instead to construct an efficient facsimile that incentivizes the emergence of high-level social and general artificial intelligence. To this end, **we consider MMOs the best proxy for the real world among human games.**
You can read more in the Neural-MMO documentation.
https://jsuarez5341.github.io/neural-mmo/build/html/rst/userguide.html
**A high level description of the Challenge Procedure:**
- Sign up to join the competition on the AIcrowd website.
- Clone this repo and start developing your solution.
- Train your models on NeuralMMO, and ensure rollout.py runs rollouts.
- Submit your trained models to AIcrowd Gitlab
for evaluation (full instructions below). The automated evaluation setup
will evaluate the submissions against the scripted bots and submissions from othe participants, and your scores will evolve on the leaderboard accordingly.
# 🛠 Setup and Installation
## Setup the environment
- Clone this repository
- Clone this repository to a private repository on your own aicrowd gitlab account.
- You'll need this repository to make submissions.
```bash
git clone https://gitlab.aicrowd.com/neural-mmo/neuralmmo-starter-kit
......@@ -39,34 +74,92 @@ conda install python=3.8 -y
- Install dependencies
```bash
pip install -e env/gym_neuralmmo
cd neuralmmo-starter-kit/
pip install -e ./env/gym_neuralmmo
```
- Get the neuralmmo environment - you can clone it anywhere you like, but our instructions assume you get the neural-mmo folder inside the starter kit.
```bash
git clone --single-branch --depth=1 --branch master https://github.com/jsuarez5341/neural-mmo
git clone --single-branch --depth=1 --branch v1.5.1 https://github.com/jsuarez5341/neural-mmo-client neural-mmo/forge/embyr
cd neural-mmo && bash scripts/setup.sh
```
# 💪 Getting Started
## Generate maps
You'll need these to run training and local evaluations
```
python Forge.py generate --config=SmallMaps
```
# 💪 Getting Started
## Train an agent
Training your first agent is super easy with this one line command. It might take a long time though, but you can try it out for a few epochs.
```bash
python Forge.py train --config=SmallMultimodalSkills --LOAD=False
```
- If you want to change the config for the agent, check out `neural-mmo/projekt/config.py`
- We recommend you to subclass the `CompetitionRound1` class and add your config changes.
- Lot more details about training and the environment are available in the [neural-mmo documentation](https://jsuarez5341.github.io/neural-mmo/build/html/rst/userguide.html)
## Add your trained agent for submission
Add your custom config name to the `agents/neural_baseline_agent.py` which is currently using `projekt.config.CompetitionRound1`
## Evaluate an agent
- Add the neural-mmo folder to the starter python path, this is needed for importing the neural-mmo environment and config loaders.
```bash
export PYTHONPATH=$PYTHONPATH:`pwd`/neural-mmo
```
./run.sh
- Run the rollout script, this is the same file that will be used during evaluation on aicrowd.
```bash
python rollout.py
```
## How do I add a custom agent for rollout ?
<!-- ## How do I add a custom agent for rollout ?
To add a custom model, create an agent inside `agents/` directory. The created agents should inherit a base class (`utils/base_agent.py`).
Agents to be used for rollout should be updated in `players.yaml`.
Agents to be used for rollout should be updated in `players.yaml`. -->
# 🚀 Submission
**Before submitting you need to fill in a few other files**
## `requirements.txt`
We will build the environment for your run based on the python3 packages you specify in `requirements.txt`
If you want to specify stuff apart from python packages, check the section on [Submission environment configuration](#submission-environment-configuration)
## `aicrowd.json`
Your repository should have an aicrowd.json file with following fields:
```json
{
"challenge_id": "the-neural-mmo-challenge",
"authors": ["aicrowd-bot"],
"description": "(optional) description about your awesome agent"
}
```
This file is used to identify your submission as a part of the The Neural MMO Challenge. Don't change the `challenge_id`, you can add in the rest.
## Making the submission
Please follow the instructions in [SUBMISSION.md](/docs/SUBMISSION.md) for making submissions.
# 📋 Helpful information
## Repository Structure
```
......@@ -89,21 +182,6 @@ Agents to be used for rollout should be updated in `players.yaml`.
```
## `aicrowd.json`
Your repository should have an aicrowd.json file with following fields:
```json
{
"challenge_id": "the-neural-mmo-challenge",
"authors": ["aicrowd-bot"],
"description": "(optional) description about your awesome agent",
"gpu": false
}
```
This file is used to identify your submission as a part of the The Neural MMO Challenge. You must use the `challenge_id` as specified above.
## Submission environment configuration
You can specify your software environment by using `Dockerfile``requirements.txt`. Available options are
......@@ -113,40 +191,28 @@ You can specify your software environment by using `Dockerfile``requirements.txt
A sample [`Dockerfile`](Dockerfile) and a corresponding [`requirements.txt`](requirements.txt) are provided in this repository for you reference.
For more details check [RUNTIME.md](/docs/RUNTIME.md)
## Code entrypoint
The evaluator will read the value of `agents` from `agents.yaml` in the repository, and will run the script `run.sh`. Corresponding agents must be located in `agents\` directory. The file `rollout.py` will be replaced during evaluation.
The evaluator will read the value of `agents` from `players.yaml` in the repository, and will run `rollout.py`. Corresponding agents must be located in `agents/` directory. The file `rollout.py` **will be replaced during evaluation** with the file in the original starter kit, DON't modify it.
## Submitting
## Evaluating against other agents locally
### Initial setup
You can specify `opponent_agents` in `players.yaml` and make as many duplicates of them as you like. The total number of players should add up to 128.
1) Setup an AIcrowd GitLab account if you don't have one by going to https://gitlab.aicrowd.com/
2) [Add your SSH key](https://discourse.aicrowd.com/t/how-to-add-ssh-key-to-gitlab/2603)
3) If you accept the challenge rules, click the `Participate` button on [the AIcrowd contest page](https://www.aicrowd.com/challenges/the-neural-mmo-challenge)
### Manually submitting the code
Create a submission by pushing a tag to your repository with a prefix `submission-`. An example is shown below (you can keep repository name as you desire or have multiple repositories):
## Contributors
```bash
# Create a tag for your submission and push
git tag -am "submission-v0.1" submission-v0.1
git push aicrowd master
git push aicrowd submission-v0.1
# Note : If the contents of your repository (latest commit hash) does not change,
# then pushing a new tag will not trigger a new evaluation.
```
or, run
```bash
./utils/submit.sh "submissio -v0.21"
```
- [Siddhartha Laghuvarapu](https://www.aicrowd.com/participants/siddhartha)
- [Jyotish Poonganam](https://www.aicrowd.com/participants/jyotish)
- [Joseph Suarez](https://www.aicrowd.com/participants/joseph_suarez)
- [Dipam Chakraborty](https://www.aicrowd.com/participants/dipam)
5) You should now be able to see the details of your submission in the repository's issues page.
`https://gitlab.aicrowd.com/<your-aicrowd-username>/the-neural-mmo-challenge/issues`
# 📡 Important links
Happy Submitting!! :rocket:
- 💪 Challenge Page: https://www.aicrowd.com/challenges/the-neural-mmo-challenge
- 🗣️ Discussion Forum: https://www.aicrowd.com/challenges/the-neural-mmo-challenge/discussion
- 🏆 Leaderboard: https://www.aicrowd.com/challenges/the-neural-mmo-challenge/leaderboards
**Best of Luck** 🎉
\ No newline at end of file
......@@ -4,7 +4,6 @@
"authors": [
"aicrowd-bot"
],
"description": "(optional) description about your awesome agent",
"gpu": false
"description": "(optional) description about your awesome agent"
}
gcc
g++
git
\ No newline at end of file
# Adding your runtime
## **Installation setup steps**
### **How to specify your installation setup for the submission**
The entrypoint to the installation is the Dockerfile
The Dockerfile provided will have commands to install apt packages from apt.txt and pip packages from requirements.txt
You are strongly advised to specify the version of the library that you use to use for your submission
Examples
For requirements.txt
```torch==1.8.1```
You can add git repositories to requirements.txt as well
```git+https://github.com/tqdm/tqdm.git@devel#egg=tqdm```
For apt.txt
```firefox=45.0.2+build1-0ubuntu1```
## (Optional) Check your installation setup on your own machine
### Setup the environment
Install docker on your machine and run
```bash
docker build -t your-custom-tag .
```
If you get installation errors during the above step, your submission is likely to fail, please review the errors and fix the installation
### Run the submission locally
Run the docker container This will create an environment that emulates how your submission environment will be.
```bash
docker run -it your-custom-tag /bin/bash
```
```bash
python rollout.py
```
If you get runtime errors during the above step, your submission is likely to fail. Please review the errors.
A common error is not specifying one or multiple required libraries
## Installation FAQ
- How to install with an `environment.yml`?
- Add `environment.yml` to the base of your repo. You also need to add commands to add `environment.yml` to the `Dockerfile`. Afterwards, You’re encouraged to follow the above steps Check your installation setup on your own machine to check everything is properly installed.
- How do I install with a setup.py
- You need to add the command to run it in the ```Dockerfile``` - ```RUN pip install .```
- What’s the package versions I have installed on my machine?
- You can find the versions of the python package installations you currently have using pip freeze
- What’s aicrowd_gym
- AIcrowd gym is a library AIcrowd uses to limit the functionality on the submission environment to prevent tampering with the RL Library. For all intents and purposes, aicrowd_gym should work the same as gym for you.
- How do I use a custom script to install?
- You’ll need to call the custom script in the ```Dockerfile```, example you can add this line ```RUN ./custom_script.sh```
# Making submission
This file will help you in making your first submission.
## Submission Entrypoint (where you write your code!)
The evaluator will execute `rollout.py` for generating actions in the neural-mmo environment, this file will be replaced during aicrowd evaluations, so don't modify it!
## IMPORTANT: Saving Models before submission!
Before you submit make sure that you have saved your models, which are needed by your inference code.
In case your files are larger in size you can use `git-lfs` to upload them. More details [here](https://discourse.aicrowd.com/t/how-to-upload-large-files-size-to-your-submission/2304).
## How to submit a trained model!
To make a submission, you will have to create a **private** repository on [https://gitlab.aicrowd.com/](https://gitlab.aicrowd.com/).
You will have to add your SSH Keys to your GitLab account by going to your profile settings [here](https://gitlab.aicrowd.com/profile/keys). If you do not have SSH Keys, you will first need to [generate one](https://docs.gitlab.com/ee/ssh/README.html#generating-a-new-ssh-key-pair).
Then you can create a submission by making a _tag push_ to your repository on [https://gitlab.aicrowd.com/](https://gitlab.aicrowd.com/).
**Any tag push (where the tag name begins with "submission-") to your private repository is considered as a submission**
Then you can add the correct git remote, and finally submit by doing :
```
cd neuralmmo-starter-kit
# Add AIcrowd git remote endpoint
git remote add aicrowd git@gitlab.aicrowd.com:<YOUR_AICROWD_USER_NAME>/neuralmmo-starter-kit.git
git push aicrowd master
```
```
# Create a tag for your submission and push
git tag -am "submission-v0.1" submission-v0.1
git push aicrowd master
git push aicrowd submission-v0.1
# Note : If the contents of your repository (latest commit hash) does not change,
# then pushing a new tag will **not** trigger a new evaluation.
```
You now should be able to see the details of your submission at :
[gitlab.aicrowd.com/<YOUR_AICROWD_USER_NAME>/neuralmmo-starter-kit/issues](https://gitlab.aicrowd.com//<YOUR_AICROWD_USER_NAME>/neuralmmo-starter-kit/issues)
**NOTE**: Remember to update your username instead of `<YOUR_AICROWD_USER_NAME>` above :wink:
### Other helpful files
👉 [RUNTIME.md](/docs/RUNTIME.md)
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