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.
ELF is released under the BSD-style licence found in the LICENSE file.
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.
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).
cd to the project root and run make to build.
After building, cd to the project root and run make test to test.
Currently, ELF must be run straight from source. You'll need to run source scripts/devmode_set_pythonpath.sh to augment $PYTHONPATH appropriately.
To train a model, please follow these steps:
- Build ELF and run
source scripts/devmode_set_pythonpath.shas described above. - Change directory to
scripts/elfgames/go/ - Edit
server_addrs.pyto specify the server's IP address. This is the machine that will train the neural network. - Create the directory where the server will write the model directory. This defaults to
myserver - Run
start_server.shto start the server. We have tested this on a machine with 8 GPUs. - Run
start_client.shto 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.
Here is a basic set of commands to run and play the bot via the GTP protocol:
- Build ELF and run
source scripts/devmode_set_pythonpath.shas described above. - Train a model, or grab a pretrained model from the repository's Github "Releases" tab.
- Change directory to
scripts/elfgames/go/ - 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.
Copyright © 2018-present, Facebook, Inc. — all rights reserved.