Merge pull request #619 from Unity-Technologies/develop

Release v0.3.1

.gitattributes

@@ -2,3 +2,4 @@
 *.unity binary
 *.prefab binary
 *.meta binary
+*.md text

Dockerfile

@@ -1,8 +1,128 @@
-# Use an official Python runtime as a parent image
-FROM python:3.6-slim
+# Based off of python:3.6-slim, except that we are using ubuntu instead of debian.
+FROM ubuntu:16.04
+
+
+# ensure local python is preferred over distribution python
+ENV PATH /usr/local/bin:$PATH
+
+# http://bugs.python.org/issue19846
+# > At the moment, setting "LANG=C" on a Linux system *fundamentally breaks Python 3*, and that's not OK.
+ENV LANG C.UTF-8
+
+# runtime dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+		ca-certificates \
+		libexpat1 \
+		libffi6 \
+		libgdbm3 \
+		libreadline6 \
+		libsqlite3-0 \
+		libssl1.0.0 \
+	&& rm -rf /var/lib/apt/lists/*
+
+ENV GPG_KEY 0D96DF4D4110E5C43FBFB17F2D347EA6AA65421D
+ENV PYTHON_VERSION 3.6.4
+
+RUN set -ex \
+	&& buildDeps=" \
+		dpkg-dev \
+		gcc \
+		libbz2-dev \
+		libc6-dev \
+		libexpat1-dev \
+		libffi-dev \
+		libgdbm-dev \
+		liblzma-dev \
+		libncursesw5-dev \
+		libreadline-dev \
+		libsqlite3-dev \
+		libssl-dev \
+		make \
+		tcl-dev \
+		tk-dev \
+		wget \
+		xz-utils \
+		zlib1g-dev \
+# as of Stretch, "gpg" is no longer included by default
+		$(command -v gpg > /dev/null || echo 'gnupg dirmngr') \
+	" \
+	&& apt-get update && apt-get install -y $buildDeps --no-install-recommends && rm -rf /var/lib/apt/lists/* \
+	\
+	&& wget -O python.tar.xz "https://www.python.org/ftp/python/${PYTHON_VERSION%%[a-z]*}/Python-$PYTHON_VERSION.tar.xz" \
+	&& wget -O python.tar.xz.asc "https://www.python.org/ftp/python/${PYTHON_VERSION%%[a-z]*}/Python-$PYTHON_VERSION.tar.xz.asc" \
+	&& export GNUPGHOME="$(mktemp -d)" \
+	&& gpg --keyserver ha.pool.sks-keyservers.net --recv-keys "$GPG_KEY" \
+	&& gpg --batch --verify python.tar.xz.asc python.tar.xz \
+	&& rm -rf "$GNUPGHOME" python.tar.xz.asc \
+	&& mkdir -p /usr/src/python \
+	&& tar -xJC /usr/src/python --strip-components=1 -f python.tar.xz \
+	&& rm python.tar.xz \
+	\
+	&& cd /usr/src/python \
+	&& gnuArch="$(dpkg-architecture --query DEB_BUILD_GNU_TYPE)" \
+	&& ./configure \
+		--build="$gnuArch" \
+		--enable-loadable-sqlite-extensions \
+		--enable-shared \
+		--with-system-expat \
+		--with-system-ffi \
+		--without-ensurepip \
+	&& make -j "$(nproc)" \
+	&& make install \
+	&& ldconfig \
+	\
+	&& apt-get purge -y --auto-remove $buildDeps \
+	\
+	&& find /usr/local -depth \
+		\( \
+			\( -type d -a \( -name test -o -name tests \) \) \
+			-o \
+			\( -type f -a \( -name '*.pyc' -o -name '*.pyo' \) \) \
+		\) -exec rm -rf '{}' + \
+	&& rm -rf /usr/src/python
+
+# make some useful symlinks that are expected to exist
+RUN cd /usr/local/bin \
+	&& ln -s idle3 idle \
+	&& ln -s pydoc3 pydoc \
+	&& ln -s python3 python \
+	&& ln -s python3-config python-config
+
+# if this is called "PIP_VERSION", pip explodes with "ValueError: invalid truth value '<VERSION>'"
+ENV PYTHON_PIP_VERSION 9.0.3
+
+RUN set -ex; \
+	\
+	apt-get update; \
+	apt-get install -y --no-install-recommends wget; \
+	rm -rf /var/lib/apt/lists/*; \
+	\
+	wget -O get-pip.py 'https://bootstrap.pypa.io/get-pip.py'; \
+	\
+	apt-get purge -y --auto-remove wget; \
+	\
+	python get-pip.py \
+		--disable-pip-version-check \
+		--no-cache-dir \
+		"pip==$PYTHON_PIP_VERSION" \
+	; \
+	pip --version; \
+	\
+	find /usr/local -depth \
+		\( \
+			\( -type d -a \( -name test -o -name tests \) \) \
+			-o \
+			\( -type f -a \( -name '*.pyc' -o -name '*.pyo' \) \) \
+		\) -exec rm -rf '{}' +; \
+	rm -f get-pip.py
+
 
 RUN apt-get update && apt-get -y upgrade
 
+# xvfb is used to do CPU based rendering of Unity
+RUN apt-get install -y xvfb
+
+
 ADD python/requirements.txt .
 RUN pip install --trusted-host pypi.python.org -r requirements.txt
 

README.md

@@ -27,7 +27,7 @@ to the wider research and game developer communities.
 * Built-in support for Imitation Learning
 * Flexible Agent control with On Demand Decision Making
 * Visualizing network outputs within the environment
-* Simplified set-up with Docker (Experimental)
+* Simplified set-up with Docker
 
 ## Documentation and References
 
@@ -72,6 +72,17 @@ make sure to include as much detail as possible.
 For any other questions or feedback, connect directly with the ML-Agents
 team at [email protected].
 
+## Translations
+
+To make Unity ML-Agents accessible to the global research and
+Unity developer communities, we're attempting to create and maintain
+translations of our documentation. We've started with translating a subset
+of the documentation to one language (Chinese), but we hope to continue
+translating more pages and to other languages. Consequently,
+we welcome any enhancements and improvements from the community.
+
+- [Chinese](docs/localized/zh-CN/)
+
 ## License
 
 [Apache License 2.0](LICENSE)

docs/Getting-Started-with-Balance-Ball.md

@@ -210,7 +210,7 @@ object.
 
 ![Set Brain to External](images/mlagents-SetExternalBrain.png)
 
-Next, we want the set up scene to to play correctly when the training process 
+Next, we want the set up scene to play correctly when the training process 
 launches our environment executable. This means:
 * The environment application runs in the background
 * No dialogs require interaction
@@ -269,7 +269,7 @@ on the same graph.
 
 To summarize, go to your command line, enter the `ml-agents` directory and type: 
 
-```python
+```
 python3 python/learn.py <env_file_path> --run-id=<run-identifier> --train 
 ```
 **Note**: If you're using Anaconda, don't forget to activate the ml-agents environment first.

docs/Installation-Windows.md

@@ -6,7 +6,7 @@ To use ML-Agents, you install Python and the required Python packages as outline
 
 ## Step 1: Install Python via Anaconda
 
-[Download](https://www.anaconda.com/download/#windows) and install Anaconda for Windows. By using Anaconda, you can manage separate environments for different distributions of Python. Python 3 is required as we no longer support Python 2. In this guide, we are using Python version 3.6 and Anaconda version 5.1 ([64-bit](https://repo.continuum.io/archive/Anaconda3-5.1.0-Windows-x86_64.exe) or [32-bit](https://repo.continuum.io/archive/Anaconda3-5.1.0-Windows-x86.exe) direct links).
+[Download](https://www.anaconda.com/download/#windows) and install Anaconda for Windows. By using Anaconda, you can manage separate environments for different distributions of Python. Python 3 is required as we no longer support Python 2. In this guide, we are using Python version 3.5 (Anaconda comes with Python 3.6, we will create an environment with python 3.5) and Anaconda version 5.1 ([64-bit](https://repo.continuum.io/archive/Anaconda3-5.1.0-Windows-x86_64.exe) or [32-bit](https://repo.continuum.io/archive/Anaconda3-5.1.0-Windows-x86.exe) direct links).
 
 <p align="center">
     <img src="images/anaconda_install.PNG" 
@@ -23,15 +23,21 @@ We recommend the default _advanced installation options_. However, select the op
 </p>
 
 After installation, you must open __Anaconda Navigator__ to finish the setup. From the Windows search bar, type _anaconda navigator_. You can close Anaconda Navigator after it opens.
-
+If environment variables were not created, or if you see the error "conda is not recognized as internal or external command", in System Variables, "Path" add the following new paths:
+```
+    C:\ProgramData\Anaconda3\Scripts
+    C:\ProgramData\Anaconda3\Scripts\conda.exe
+    C:\ProgramData\Anaconda3
+    C:\ProgramData\Anaconda3\python.exe
+```
 ## Step 2: Setup and Activate a New Conda Environment
 
 You will create a new [Conda environment](https://conda.io/docs/) to be used with ML-Agents. This means that all the packages that you install are localized to just this environment. It will not affect any other installation of Python or other environments. Whenever you want to run ML-Agents, you will need activate this Conda environment.
 
 To create a new Conda environment, open a new Anaconda Prompt (_Anaconda Prompt_ in the search bar) and type in the following command:
 
 ```
-conda create -n ml-agents python=3.6
+conda create -n ml-agents python=3.5
 ```
 
 You may be asked to install new packages. Type `y` and press enter _(make sure you are connected to the internet)_. You must install these required packages. The new Conda environment is called ml-agents and uses Python version 3.6.
@@ -50,10 +56,10 @@ conda activate ml-agents
 
 You should see `(ml-agents)` prepended on the last line.
 
-Next, install `tensorflow`. Install this package using `pip` - which is a package management system used to install Python packages. In the same Anaconda Prompt, type in the following command _(make sure you are connected to the internet)_:
+Next, install `tensorflow`. Install this package using `pip` - which is a package management system used to install Python packages. Latest versions of Tensorflow won't work, so you will need to make sure that you install version 1.4.0. In the same Anaconda Prompt, type in the following command _(make sure you are connected to the internet)_:
 
 ```
-pip install tensorflow
+pip install tensorflow==1.4.0
 ```
 
 ## Step 3: Install Required Python Packages
@@ -78,6 +84,7 @@ Make sure you are connected to the internet and then type in the Anaconda Prompt
 
 ```
 pip install .
+
 ```
 
 This will complete the installation of all the required Python packages to run ML-Agents. 
@@ -90,7 +97,7 @@ As of ML-Agents v0.3, only CUDA 8 and cuDNN 6 is supported.
 
 ### Install Nvidia CUDA toolkit
 
-[Download](https://developer.nvidia.com/cuda-toolkit-archive) and install the CUDA toolkit from Nvidia's archive. The toolkit includes GPU-accelerated libraries, debugging and optimization tools, a C/C++ compiler and a runtime library and is needed to run ML-Agents. In this guide, we are using version 8.0.61 ([direct link](https://developer.nvidia.com/compute/cuda/8.0/Prod2/network_installers/cuda_8.0.61_win10_network-exe)). 
+[Download](https://developer.nvidia.com/cuda-toolkit-archive) and install the CUDA toolkit from Nvidia's archive. The toolkit includes GPU-accelerated libraries, debugging and optimization tools, a C/C++ (Step Visual Studio 2015) compiler and a runtime library and is needed to run ML-Agents. In this guide, we are using version 8.0.61 ([direct link](https://developer.nvidia.com/compute/cuda/8.0/Prod2/network_installers/cuda_8.0.61_win10_network-exe)). 
 
 Before installing, please make sure you __close any running instances of Unity or Visual Studio__.
 
@@ -166,10 +173,10 @@ Make sure to replace the relevant directory location with the one you have insta
 </p>
 
 ### Install TensorFlow GPU
-Next, install `tensorflow-gpu` using `pip`. In an Anaconda Prompt with the Conda environment ml-agents activated, type in the following command _(make sure you are connected to the internet)_:
+Next, install `tensorflow-gpu` using `pip`. You'll need version 1.4.0 as newer versions require CUDA 9 which is not yet supported. In an Anaconda Prompt with the Conda environment ml-agents activated, type in the following command _(make sure you are connected to the internet)_:
 
 ```
-pip install tensorflow-gpu
+pip install tensorflow-gpu==1.4.0
 ```
 
 Lastly, you should test to see if everything installed properly and that TensorFlow can identify your GPU. In the same Anaconda Prompt, type in the following command:
@@ -186,6 +193,11 @@ You should see something similar to:
 Found device 0 with properties ...
 ```
 
+Step Visual Studio 2015: CUDA 8.0 is not compatible with Visual Studio 2017, so you will need an older version. Uninstall Visual Studio 2017 that comes with Unity, download Visual Studio Enterprise 2015 and install it with the Windows SDK. If you don't want/ can't install Visual Studio Enterprise 2015, you will need: 
+    [Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145),
+    [Visual Studio Community 2015](https://www.visualstudio.com/vs/older-downloads/) + [Windows SDK](https://msdn.microsoft.com/en-us/library/mt683786.aspx).
+
+
 ## Acknowledgements
 
 We would like to thank [Jason Weimann](https://unity3d.college/2017/10/25/machine-learning-in-unity3d-setting-up-the-environment-tensorflow-for-agentml-on-windows-10/) and [Nitish S. Mutha](http://blog.nitishmutha.com/tensorflow/2017/01/22/TensorFlow-with-gpu-for-windows.html) for writing the original articles which were used to create this guide.

docs/Installation.md

@@ -2,7 +2,7 @@
 
 To install and use ML-Agents, you need install Unity, clone this repository
 and install Python with additional dependencies. Each of the subsections
-below overviews each step, in addition to an experimental Docker set-up.
+below overviews each step, in addition to a Docker set-up.
 
 ## Install **Unity 2017.1** or Later
 
@@ -40,6 +40,8 @@ If you are a Windows user who is new to Python and TensorFlow, follow [this guid
 
 ### Mac and Unix Users
 
+[Download](https://www.python.org/downloads/) and install Python 3 if you do not already have it.
+
 If your Python environment doesn't include `pip`, see these 
 [instructions](https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers)
 on installing it.
@@ -49,7 +51,7 @@ and run from the command line:
 
     pip3 install .
 
-## Docker-based Installation (Experimental)
+## Docker-based Installation
 
 If you'd like to use Docker for ML-Agents, please follow 
 [this guide](Using-Docker.md). 

docs/Learning-Environment-Create-New.md

@@ -88,7 +88,7 @@ You can adjust the camera angles to give a better view of the scene at runtime.
 
 ## Implement an Academy
 
-The Academy object coordinates the ML-Agents in the scene and drives the decision-making portion of the simulation loop. Every ML-Agent scene needs one Academy instance. Since the base Academy classis abstract, you must make your own subclass even if you don't need to use any of the methods for a particular environment.
+The Academy object coordinates the ML-Agents in the scene and drives the decision-making portion of the simulation loop. Every ML-Agent scene needs one Academy instance. Since the base Academy class is abstract, you must make your own subclass even if you don't need to use any of the methods for a particular environment.
 
 First, add a New Script component to the Academy GameObject created earlier: 
 
@@ -230,7 +230,6 @@ All the values are divided by 5 to normalize the inputs to the neural network to
 In total, the state observation contains 8 values and we need to use the continuous state space when we get around to setting the Brain properties:
 
 ```csharp
-List<float> observation = new List<float>();
 public override void CollectObservations()
 {
     // Calculate relative position

docs/Learning-Environment-Examples.md

@@ -154,15 +154,15 @@ If you would like to contribute environments, please see our
 ![Banana](images/banana.png)
 
 * Set-up: A multi-agent environment where agents compete to collect bananas. 
-* Goal: The agents must learn to move to as many yellow bananas as possible while avoiding red bananas.
-* Agents: The environment contains 10 agents linked to a single brain.
+* Goal: The agents must learn to move to as many yellow bananas as possible while avoiding blue bananas.
+* Agents: The environment contains 5 agents linked to a single brain.
 * Agent Reward Function (independent): 
     * +1 for interaction with yellow banana
-    * -1 for interaction with red banana.
+    * -1 for interaction with blue banana.
 * Brains: One brain with the following observation/action space.
-    * Vector Observation space: (Continuous) 51 corresponding to velocity of agent, plus ray-based perception of objects around agent's forward direction.
+    * Vector Observation space: (Continuous) 53 corresponding to velocity of agent (2), whether agent is frozen and/or shot its laser (2), plus ray-based perception of objects around agent's forward direction (49; 7 raycast angles with 7 measurements for each).
     * Vector Action space: (Continuous) Size of 3, corresponding to forward movement, y-axis rotation, and whether to use laser to disable other agents.
-    * Visual Observations (Optional): First-person view for each agent. 
+    * Visual Observations (Optional; None by default): First-person view for each agent. 
 * Reset Parameters: None
 
 ## Hallway

docs/ML-Agents-Overview.md

@@ -428,8 +428,7 @@ the broadcasting feature
 * **Docker Set-up (Experimental)** - To facilitate setting up ML-Agents
 without installing Python or TensorFlow directly, we provide a 
 [guide](Using-Docker.md) on how
-to create and run a Docker container. Due to limitations on rendering visual
-observations, this feature is marked experimental.
+to create and run a Docker container.
 
 * **Cloud Training on AWS** - To facilitate using ML-Agents on
 Amazon Web Services (AWS) machines, we provide a 

docs/Readme.md

@@ -7,7 +7,7 @@
     * [Background: TensorFlow](Background-TensorFlow.md)
  * [Installation & Set-up](Installation.md)
     * [Background: Jupyter Notebooks](Background-Jupyter.md)
-    * [Docker Set-up (Experimental)](Using-Docker.md)
+    * [Docker Set-up](Using-Docker.md)
  * [Getting Started with the 3D Balance Ball Environment](Getting-Started-with-Balance-Ball.md)
  * [Example Environments](Learning-Environment-Examples.md)
 

docs/Training-on-Amazon-Web-Service.md

@@ -23,7 +23,7 @@ To verify that all steps worked correctly:
 
 1. In the Unity Editor, load a project containing an ML-Agents environment (you can use one of the example environments if you have not created your own).
 2. Open the Build Settings window (menu: File > Build Settings).
-3. Select Linux as the Target Platform, and x64_86 as the target architecture.
+3. Select Linux as the Target Platform, and x86_64 as the target architecture.
 4. Check Headless Mode (unless you have enabled a virtual screen following the instructions below).
 5. Click Build to build the Unity environment executable.
 6. Upload the executable to your EC2 instance.