README.md 7.4 KB
Newer Older
Shivam Khandelwal's avatar
Shivam Khandelwal committed
1
2
![Nethack Banner](https://raw.githubusercontent.com/facebookresearch/nle/master/dat/nle/logo.png)

Dipam Chakraborty's avatar
Dipam Chakraborty committed
3
4
5
6
7
# **NeurIPS 2021 - The NetHack Challenge** - Getting started
* **Challenge page** - https://www.aicrowd.com/challenges/neurips-2021-nethack-challenge
* **IMPORTANT - [Accept the rules before you submit](https://www.aicrowd.com/challenges/neurips-2021-nethack-challenge/challenge_rules)**
* **Join the discord server** - https://discord.gg/zkFWQmSWBA
* Clone the starter kit to start competing - TODO Add final starter kit link
Shivam Khandelwal's avatar
Shivam Khandelwal committed
8

Dipam Chakraborty's avatar
Dipam Chakraborty committed
9
This repository is the Nethack Challenge **Submission template and Starter kit**! It contains: 
Shivam Khandelwal's avatar
Shivam Khandelwal committed
10
11
*  **Documentation** on how to submit your models to the leaderboard
*  **The procedure** for best practices and information on how we evaluate your agent, etc.
Dipam Chakraborty's avatar
Dipam Chakraborty committed
12
*  **Baselines** for you to get started with training easily
Shivam Khandelwal's avatar
Shivam Khandelwal committed
13

Dipam Chakraborty's avatar
Dipam Chakraborty committed
14
<p style="text-align:center"><img style="text-align:center" src="https://raw.githubusercontent.com/facebookresearch/nle/master/dat/nle/example_run.gif"></p>
Shivam Khandelwal's avatar
Shivam Khandelwal committed
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# Table of Contents

1. [Competition Procedure](#competition-procedure)


#  Competition Procedure

The NetHack Learning Environment (NLE) is a Reinforcement Learning environment presented at NeurIPS 2020. NLE is based on NetHack 3.6.6 and designed to provide a standard RL interface to the game, and comes with tasks that function as a first step to evaluate agents on this new environment. You can read more about NLE in the NeurIPS 2020 paper.

We are excited that this competition offers machine learning students, researchers and NetHack-bot builders the opportunity to participate in a grand challenge in AI without prohibitive computational costs—and we are eagerly looking forward to the wide variety of submissions.


**The following is a high level description of how this process works**

1. **Sign up** to join the competition [on the AIcrowd website](https://www.aicrowd.com/challenges/neurips-2021-nethack-challenge).
2. **Clone** this repo and start developing your solution.
Dipam Chakraborty's avatar
Dipam Chakraborty committed
32
33
3. **Train** your models on NLE and write rollout code in `rollout.py`.
4. [**Submit**](#how-to-submit-a-model) your trained models to [AIcrowd Gitlab](https://gitlab.aicrowd.com) for evaluation [(full instructions below)](#how-to-submit-a-model). The automated evaluation setup will evaluate the submissions against the NLE environment for a fixed number of rollouts to compute and report the metrics on the leaderboard of the competition.
Shivam Khandelwal's avatar
Shivam Khandelwal committed
34

Dipam Chakraborty's avatar
Dipam Chakraborty committed
35
36
37
![](https://i.imgur.com/xzQkwKV.jpg)

# Installation - Nethack Learning Environment
Shivam Khandelwal's avatar
Shivam Khandelwal committed
38

Dipam Chakraborty's avatar
Dipam Chakraborty committed
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
NLE requires `python>=3.5`, `cmake>=3.14` to be installed and available both when building the
package, and at runtime.

On **MacOS**, one can use `Homebrew` as follows:

``` bash
$ brew install cmake
```

On a plain **Ubuntu 18.04** distribution, `cmake` and other dependencies
can be installed by doing:

```bash
# Python and most build deps
$ sudo apt-get install -y build-essential autoconf libtool pkg-config \
    python3-dev python3-pip python3-numpy git flex bison libbz2-dev

# recent cmake version
$ wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -
$ sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
$ sudo apt-get update && apt-get --allow-unauthenticated install -y \
    cmake \
    kitware-archive-keyring
```

Afterwards it's a matter of setting up your environment. We advise using a conda
environment for this:

```bash
$ conda create -n nle python=3.8
$ conda activate nle
$ pip install git+https://github.com/facebookresearch/nle.git@eric/competition --no-binary:nle
```

Find more details on the [original nethack repository](https://github.com/facebookresearch/nle)
Shivam Khandelwal's avatar
Shivam Khandelwal committed
74
75
76
77
78
79
80
81
82

# How to start participating

## Setup

1. **Add your SSH key** to AIcrowd GitLab

You can 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).

Dipam Chakraborty's avatar
Dipam Chakraborty committed
83
2.  **Clone the repository** - TODO
Shivam Khandelwal's avatar
Shivam Khandelwal committed
84
85
86
87
88
89
90

    ```
    git clone git@github.com:AIcrowd/neurips-2021-nethack-starter-kit.git
    ```

3. **Install** competition specific dependencies!
    ```
Dipam Chakraborty's avatar
Dipam Chakraborty committed
91
92
93
94
    pip install aicrowd-api
    pip install aicrowd-gym

    ## Install NLE according to the instructions above
Shivam Khandelwal's avatar
Shivam Khandelwal committed
95
96
    ```

97
4. Try out a random agent by setting `AGENT = RandomAgent` in `submission_config.py` and then running `rollout.py`.
Shivam Khandelwal's avatar
Shivam Khandelwal committed
98

99
5. See [this](/nethack_baselines/torchbeast/README.md) for an example of how to train and submit an IMPALA agent. Check out `nethack_baselines` for more examples. 
Shivam Khandelwal's avatar
Shivam Khandelwal committed
100

Dipam Chakraborty's avatar
Dipam Chakraborty committed
101
## How do I specify my software runtime / dependencies ? - TODO
Shivam Khandelwal's avatar
Shivam Khandelwal committed
102
103
104

We accept submissions with custom runtime, so you don't need to worry about which libraries or framework to pick from.

Dipam Chakraborty's avatar
Dipam Chakraborty committed
105
The configuration files typically include `requirements.txt` (pypi packages), `apt.txt` (apt packages) or even your own `Dockerfile`.
Shivam Khandelwal's avatar
Shivam Khandelwal committed
106

Dipam Chakraborty's avatar
Dipam Chakraborty committed
107
You can check detailed information about the same in the [RUNTIME.md](/docs/RUNTIME.md) file.
Shivam Khandelwal's avatar
Shivam Khandelwal committed
108
109
110
111
112
113
114
115
116
117
118

## What should my code structure be like ?

Please follow the example structure as it is in the starter kit for the code structure.
The different files and directories have following meaning:

```
.
├── aicrowd.json           # Submission meta information - like your username
├── apt.txt                # Packages to be installed inside docker image
├── requirements.txt       # Python packages to be installed
Dipam Chakraborty's avatar
Dipam Chakraborty committed
119
├── rollout.py             # Your rollout code - can use a batched agent
Dipam Chakraborty's avatar
Dipam Chakraborty committed
120
├── run.sh                 # Submission entrypoint   
Shivam Khandelwal's avatar
Shivam Khandelwal committed
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
└── utility                # The utility scripts to provide smoother experience to you.
    ├── docker_build.sh
    ├── docker_run.sh
    ├── environ.sh
```

Finally, **you must specify an AIcrowd submission JSON in `aicrowd.json` to be scored!** 

The `aicrowd.json` of each submission should contain the following content:

```json
{
  "challenge_id": "evaluations-api-neurips-nethack",
  "authors": ["your-aicrowd-username"],
  "description": "(optional) description about your awesome agent",
  "external_dataset_used": false
}
```

This JSON is used to map your submission to the challenge - so please remember to use the correct `challenge_id` as specified above.

Dipam Chakraborty's avatar
Dipam Chakraborty committed
142
143
144
145
146
147
148
## Can I use some other language instead of python?

The submission entrypoint is a bash script `run.sh`, you can call any arbitrary code you like from here. However, the environment has to be setup using python as in `rollout.py`. Any other code will have to communicte with the envrironment created in python.

**Note**: You need to install your dependencies for running your code by following the `How do I specify my software runtime/dependencies` section above.


Shivam Khandelwal's avatar
Shivam Khandelwal committed
149
150
151
152
## How to make submission

👉 [SUBMISSION.md](/docs/SUBMISSION.md)

Dipam Chakraborty's avatar
Dipam Chakraborty committed
153

Shivam Khandelwal's avatar
Shivam Khandelwal committed
154

Dipam Chakraborty's avatar
Dipam Chakraborty committed
155
# Other Information
Shivam Khandelwal's avatar
Shivam Khandelwal committed
156
157
158
159
160
161
162
163
164

## Hardware and Time constraints

To be added.

## Local Run

To be added.

Dipam Chakraborty's avatar
Dipam Chakraborty committed
165
## Contributing? - TODO
Shivam Khandelwal's avatar
Shivam Khandelwal committed
166

Dipam Chakraborty's avatar
Dipam Chakraborty committed
167
To be added
Shivam Khandelwal's avatar
Shivam Khandelwal committed
168

Dipam Chakraborty's avatar
Dipam Chakraborty committed
169
## Contributors - TODO
Shivam Khandelwal's avatar
Shivam Khandelwal committed
170

171
172
- [Jyotish Poonganam](https://www.aicrowd.com/participants/jyotish)
- [Dipam chakraborty](https://www.aicrowd.com/participants/dipam)
Dipam Chakraborty's avatar
Dipam Chakraborty committed
173
- [Shivam Khandelwal](https://www.aicrowd.com/participants/shivam)
Shivam Khandelwal's avatar
Shivam Khandelwal committed
174
175


Dipam Chakraborty's avatar
Dipam Chakraborty committed
176
# 📎 Important links - TODO
Shivam Khandelwal's avatar
Shivam Khandelwal committed
177
178
179
180
181
182

💪 &nbsp;Challenge Page: https://www.aicrowd.com/challenges/neurips-2021-nethack-challenge

🗣️ &nbsp;Discussion Forum: https://www.aicrowd.com/challenges/neurips-2021-nethack-challenge/discussion

🏆 &nbsp;Leaderboard: https://www.aicrowd.com/challenges/neurips-2021-nethack-challenge/leaderboards
Dipam Chakraborty's avatar
Dipam Chakraborty committed
183
184

**Best of Luck** 🎉 🎉