README.rst

ELF

ELF is an Extensive, Lightweight, and Flexible platform for game research. We have used it to build our Go playing bot, ELF OpenGo, which achieved a 14-0 record versus four global top-30 players in April 2018.

This version is a work-in-progress successor to the original ELF platform.

DISCLAIMER: this code is early research code. What this means is:

• It may not work reliably (or at all) on your system.
• The code quality and documentation are quite lacking, and much of the code might still feel "in-progress".
• There are quite a few hacks made specifically for our systems and infrastructure.

Although we intend to release significant improvements over the next month, we're a small team so your patience is greatly appreciated.

License

ELF is released under the BSD-style licence found in the LICENSE file.

Citing ELF

If you use ELF in your research, please consider citing the original NIPS paper as follows:

@inproceedings{tian2017elf,
  author = {Yuandong Tian and Qucheng Gong and Wenling Shang and Yuxin Wu and C. Lawrence Zitnick},
  title = {ELF: An extensive, lightweight and flexible research platform for real-time strategy games},
  booktitle = {Advances in Neural Information Processing Systems},
  pages = {2656--2666},
  year = {2017}
}

If you use ELF OpenGo or OpenGo-like functionality, please consider citing the library as follows:

@misc{ELFOpenGo2018,
  author = {Yuandong Tian and {Jerry Ma*} and {Qucheng Gong*} and Shubho Sengupta and Zhuoyuan Chen and C. Lawrence Zitnick},
  title = {ELF OpenGo},
  year = {2018},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/pytorch/ELF}}
}

* Qucheng Gong and Jerry Ma equally contributed as second authors.

** We also thank Yuxin Wu for his help on this project.

Dependencies

We run ELF using:

• Ubuntu 18.04
• Python 3.6
• GCC 7.3
• CUDA 9.0
• CUDNN 7.0
• NCCL 2.1.2

At the moment, this is the only supported environment. Other environments may also work, but we unfortunately do not have the manpower to investigate compatibility issues.

Here are the dependency installation commands for Ubuntu 18.04 and conda:

sudo apt-get install cmake g++ gcc libboost-all-dev libzmq3-dev
conda install numpy zeromq pyzmq

# From the project root
git submodule sync && git submodule update --init --recursive

You also need to install PyTorch from source (see instructions here).

Building

cd to the project root and run make to build.

Testing

After building, cd to the project root and run make test to test.

Using ELF

Currently, ELF must be run straight from source. You'll need to run source scripts/devmode_set_pythonpath.sh to augment $PYTHONPATH appropriately.

Training a Go bot

To train a model, please follow these steps:

1. Build ELF and run source scripts/devmode_set_pythonpath.sh as described above.
2. Change directory to scripts/elfgames/go/
3. Edit server_addrs.py to specify the server's IP address. This is the machine that will train the neural network.
4. Create the directory where the server will write the model directory. This defaults to myserver
5. Run start_server.sh to start the server. We have tested this on a machine with 8 GPUs.
6. Run start_client.sh to start the clients. The clients should be able to read the model written by the server, so the clients and the server need to mount the same directory via NFS. We have tested this on 2000 clients, each running exclusively on one GPU.

Running a Go bot

Here is a basic set of commands to run and play the bot via the GTP protocol:

1. Build ELF and run source scripts/devmode_set_pythonpath.sh as described above.
2. Train a model, or grab a pretrained model from the repository's Github "Releases" tab.
3. Change directory to scripts/elfgames/go/
4. Run ./gtp.sh path/to/modelfile.bin --verbose --gpu 0 --num_block 20 --dim 224 --mcts_puct 1.50 --batchsize 16 --mcts_rollout_per_batch 16 --mcts_threads 2 --mcts_rollout_per_thread 8192 --resign_thres 0.05 --mcts_virtual_loss 1

We've found that the above settings work well for playing the bot. You may change mcts_rollout_per_thread to tune the thinking time per move.