Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/google-deepmind/alphastar


https://github.com/google-deepmind/alphastar

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

        
# AlphaStar.



[AlphaStar](https://github.com/deepmind/alphastar) is a package from

[DeepMind](http://deepmind.com) that provides the tools to train an agent to

master StarCraft II offered by [Blizzard Entertainment](http://blizzard.com).



As part of our open-sourcing efforts to drive more research interest around

StarCraft II, we provide the following key offerings with this package:



1.  General purpose architectures to train StarCraftII agents in

    `architectures/` that can be used with different learning algorithms in

    online and offline settings.



2.  Data readers, offline training and evaluation scripts for fully offline

    reinforcement learning with Behavior Cloning as a representative example

    under `unplugged/` directory.



## Setup



We have tested AlphaStar only in **Python3.9** and **Linux**. Currently, we do

not support other operating systems and recommend users to stick to Linux.



### Preliminaries



We recommend using a Python virtual environment to manage dependencies. This

should help to avoid version conflicts and just generally make the installation

process easier.



```shell

python3 -m venv alphastar

source alphastar/bin/activate

pip install --upgrade pip setuptools wheel

```



AlphaStar depends on [PySC2](https://github.com/deepmind/pysc2) converters for

data generation and evaluation. Since the code for converters is written in C++,

any changes to the converter code will require recompiling the PySC2 native

extensions. Because of this we offer two different ways to use AlphaStar:



1.  **Installing AlphaStar with `pip`**: this option requires the least setup.

    However if you make changes to PySC2, or if you want to use a version for

    which no pre-built wheel is available, you will need to manually build and

    install a new wheel for PySC2.

2.  **Building AlphaStar using Bazel**: in this case AlphaStar and PySC2 are

    built together from source. By default the PySC2 sources are fetched

    from GitHub. If you wish to use a local repository instead (e.g. because you

    have made local modifications to PySC2) you should modify

    `alphastar/WORKSPACE` as described in the comments.



#### Installing with `pip`



If you're interested in running the bleeding edge versions, you can do so by

cloning our GitHub repository and then executing the following command from the

main directory (where `setup.py` is located):



```

pip install -e .  # For an editable version

pip install .     # For a non-editable version

```



Note that this will also install all the dependencies of AlphaStar.



### Building with Bazel



First, install Bazel by following the instructions

[here](https://docs.bazel.build/versions/main/install-ubuntu.html).



PySC2 requires C++ 17, so Bazel builds of AlphaStar + PySC2 must use

`--cxxopt='-std=c++17'`. For example, to build all AlphaStar targets, run the

following command from the workspace root:



```shell

bazel build --cxxopt='-std=c++17' ...

```



To recursively run all of the tests within the `architectures/` subdirectory:



```shell

bazel test --cxxopt='-std=c++17' architectures/...

```



See the documentation for

[AlphaStar Unplugged](https://github.com/deepmind/alphastar/blob/master/alphastar/unplugged/README.md)

for example `run` commands.



Note: Bazel caches Python package dependencies downloaded from `pip`. To clear

this cache (for example if you have edited `requirements.txt`), run `bazel clean

--expunge`.



You may wish to use a

[.bazelrc file](https://docs.bazel.build/versions/main/guide.html#bazelrc-the-bazel-configuration-file)

to avoid the need to repeatedly specify command-line options, for instance

`--cxxopt='-std=c++17'`.



## Quickstart



For quickstart instructions on how to run training and evaluation scripts in

*fully offline* settings, please refer to

[this README](https://github.com/deepmind/alphastar/blob/master/alphastar/unplugged/README.md). In

this repository, we have not provided any online RL training code. But, the

architectures are fit to be used in both online and offline training.



## About



Disclaimer: This is not an official Google product.



If you use the agents, architectures and offline RL benchmarks published in this

repository, please cite our

[AlphaStar Unplugged](https://openreview.net/pdf?id=Np8Pumfoty) paper.