Merge pull request #471 from Unity-Technologies/docs-improvements

Docs improvements

Author: Marwan Mattar

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 (Experimental)
 
 ## Documentation and References
 

docs/Background-Machine-Learning.md

@@ -194,7 +194,7 @@ natural choice for reinforcement learning tasks when a large amount of data
 can be generated, say through the use of a simulator or engine such as Unity.
 By generating hundreds of thousands of simulations of
 the environment within Unity, we can learn policies for very complex environments
-(a complex environment is one where the number of observations an agent percieves
+(a complex environment is one where the number of observations an agent perceives
 and the number of actions they can take are large).
 Many of the algorithms we provide in ML-Agents use some form of deep learning,
 built on top of the open-source library, [TensorFlow](Background-TensorFlow.md).

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

@@ -313,7 +313,7 @@ during a successful training session.
 
 ![Example TensorBoard Run](images/mlagents-TensorBoard.png)
 
-## Embedding the Trained Brain into the Unity Environment _[Experimental]_
+## Embedding the Trained Brain into the Unity Environment (Experimental)
 
 Once the training process completes, and the training process saves the model 
 (denoted by the `Saved Model` message) you can add it to the Unity project and 

docs/Learning-Environment-Best-Practices.md

@@ -15,12 +15,12 @@ complexity over time. This can either be done manually, or via Curriculum Learni
 
 ## Vector Observations
 * Vector Observations should include all variables relevant to allowing the agent to take the optimally informed decision.
-* Categorical variables such as type of object (Sword, Shield, Bow) should be encoded in one-hot fashion (ie `3` -> `0, 0, 1`).
+* Categorical variables such as type of object (Sword, Shield, Bow) should be encoded in one-hot fashion (i.e. `3` -> `0, 0, 1`).
 * Besides encoding non-numeric values, all inputs should be normalized to be in the range 0 to +1 (or -1 to 1). For example, the `x` position information of an agent where the maximum possible value is `maxValue` should be recorded as `AddVectorObs(transform.position.x / maxValue);` rather than `AddVectorObs(transform.position.x);`. See the equation below for one approach of normalization. 
 * Positional information of relevant GameObjects should be encoded in relative coordinates wherever possible. This is often relative to the agent position.
 
 ![normalization](images/normalization.png)
 
 ## Vector Actions
 * When using continuous control, action values should be clipped to an appropriate range.
-* Be sure to set the Vector Action's Space Size to the number of used Vector Actions, and not greater, as doing the latter can interfere with the efficency of the training process.
+* Be sure to set the Vector Action's Space Size to the number of used Vector Actions, and not greater, as doing the latter can interfere with the efficiency of the training process.

docs/Learning-Environment-Create-New.md

@@ -161,7 +161,6 @@ So far, our RollerAgent script looks like:
 
     public class RollerAgent : Agent 
     {
-        
         Rigidbody rBody;
         void Start () {
             rBody = GetComponent<Rigidbody>();
@@ -195,7 +194,7 @@ The Agent sends the information we collect to the Brain, which uses it to make a
 
 In our case, the information our agent collects includes:
 
-* Position of the target. In general, it is better to use the relative position of other objects rather than the absolute position for more generalizable training. Note that the agent only collects the x and z coordinates since the floor is aligned with the xz plane and the y component of the target's position never changes.
+* Position of the target. In general, it is better to use the relative position of other objects rather than the absolute position for more generalizable training. Note that the agent only collects the x and z coordinates since the floor is aligned with the x-z plane and the y component of the target's position never changes.
 
         // Calculate relative position
         Vector3 relativePosition = Target.position - this.transform.position;

docs/Learning-Environment-Design-Agents.md

@@ -58,8 +58,6 @@ For examples of various state observation functions, you can look at the [Exampl
         AddVectorObs(ball.transform.GetComponent<Rigidbody>().velocity.z);
     }
 
-<!-- Note that the above values aren't normalized, which we recommend! -->
-
 The feature vector must always contain the same number of elements and observations must always be in the same position within the list. If the number of observed entities in an environment can vary you can pad the feature vector with zeros for any missing entities in a specific observation or you can limit an agent's observations to a fixed subset. For example, instead of observing every enemy agent in an environment, you could only observe the closest five. 
 
 When you set up an Agent's brain in the Unity Editor, set the following properties to use a continuous vector observation:
@@ -94,11 +92,6 @@ Type enumerations should be encoded in the _one-hot_ style. That is, add an elem
     }
 
 
-<!-- 
-How to handle things like large numbers of words or symbols? Should you use a very long one-hot vector? Or a single index into a table? 
-Colors? Better to use a single color number or individual components?
--->
-
 #### Normalization
 
 For the best results when training, you should normalize the components of your feature vector to the range [-1, +1] or [0, 1]. When you normalize the values, the PPO neural network can often converge to a solution faster. Note that it isn't always necessary to normalize to these recommended ranges, but it is considered a best practice when using neural networks. The greater the variation in ranges between the components of your observation, the more likely that training will be affected.
@@ -129,7 +122,7 @@ In addition, make sure that the Agent's Brain expects a visual observation. In t
 
 ### Discrete Vector Observation Space: Table Lookup
 
-You can use the discrete vector observation space when an agent only has a limited number of possible states and those states can be enumerated by a single number. For instance, the [Basic example environment](Learning-Environment-Examples.md) in the ML Agent SDK defines an agent with a discrete vector observation space. The states of this agent are the integer steps between two linear goals. In the Basic example, the agent learns to move to the goal that provides the greatest reward.
+You can use the discrete vector observation space when an agent only has a limited number of possible states and those states can be enumerated by a single number. For instance, the [Basic example environment](Learning-Environment-Examples.md) in ML-Agents defines an agent with a discrete vector observation space. The states of this agent are the integer steps between two linear goals. In the Basic example, the agent learns to move to the goal that provides the greatest reward.
 
 More generally, the discrete vector observation identifier could be an index into a table of the possible states. However, tables quickly become unwieldy as the environment becomes more complex. For example, even a simple game like [tic-tac-toe has 765 possible states](https://en.wikipedia.org/wiki/Game_complexity) (far more if you don't reduce the number of observations by combining those that are rotations or reflections of each other).
 
@@ -310,7 +303,7 @@ To add an Agent to an environment at runtime, use the Unity `GameObject.Instanti
 
 ## Destroying an Agent
 
-Before destroying an Agent Gameobject, you must mark it as done (and wait for the next step in the simulation) so that the Brain knows that this agent is no longer active. Thus, the best place to destroy an agent is in the `Agent.AgentOnDone()` function:
+Before destroying an Agent GameObject, you must mark it as done (and wait for the next step in the simulation) so that the Brain knows that this agent is no longer active. Thus, the best place to destroy an agent is in the `Agent.AgentOnDone()` function:
 
 ```csharp
 public override void AgentOnDone()

docs/Learning-Environment-Design-Brains.md

@@ -24,7 +24,7 @@ The Brain Inspector window in the Unity Editor displays the properties assigned
     	* `Space Type` - Corresponds to whether the observation vector contains a single integer (Discrete) or a series of real-valued floats (Continuous).
     	* `Space Size` - Length of vector observation for brain (In _Continuous_ space type). Or number of possible values (in _Discrete_ space type).
 		* `Stacked Vectors` - The number of previous vector observations that will be stacked before being sent to the brain.
-	* `Visual Observations`	- Describes height, width, and whether to greyscale visual observations for the Brain.
+	* `Visual Observations`	- Describes height, width, and whether to grayscale visual observations for the Brain.
 	* `Vector Action`
 		* `Space Type` - Corresponds to whether action vector contains a single integer (Discrete) or a series of real-valued floats (Continuous).
 		* `Space Size` - Length of action vector for brain (In _Continuous_ state space). Or number of possible values (in _Discrete_ action space).

docs/Learning-Environment-Design-External-Internal-Brains.md

@@ -24,7 +24,7 @@ The training algorithms included in the ML-Agents SDK produce TensorFlow graph m
 
 To use a graph model:
 
-1. Select the Brain GameObject in the **Hierarchy** window of the Unity Editor. (The Brain GameObject must be a child of the Academy Gameobject and must have a Brain component.)
+1. Select the Brain GameObject in the **Hierarchy** window of the Unity Editor. (The Brain GameObject must be a child of the Academy GameObject and must have a Brain component.)
 2. Set the **Brain Type** to **Internal**.
 
     **Note:** In order to see the **Internal** Brain Type option, you must [enable TensorFlowSharp](Using-TensorFlow-Sharp-in-Unity.md).  
@@ -44,7 +44,7 @@ The default values of the TensorFlow graph parameters work with the model produc
 ![Internal Brain Inspector](images/internal_brain.png)
 
 
-   *  `Graph Model` : This must be the `bytes` file corresponding to the pretrained Tensorflow graph. (You must first drag this file into your Resources folder and then from the Resources folder into the inspector)
+   *  `Graph Model` : This must be the `bytes` file corresponding to the pre-trained TensorFlow graph. (You must first drag this file into your Resources folder and then from the Resources folder into the inspector)
 
 Only change the following Internal Brain properties if you have created your own TensorFlow model and are not using an ML-Agents model:
 

docs/Learning-Environment-Design.md

@@ -25,7 +25,7 @@ The ML-Agents Academy class orchestrates the agent simulation loop as follows:
 
 To create a training environment, extend the Academy and Agent classes to implement the above methods. The `Agent.CollectObservations()` and `Agent.AgentAction()` functions are required; the other methods are optional — whether you need to implement them or not depends on your specific scenario.
 
-**Note:** The API used by the Python PPO training process to communicate with and control the Academy during training can be used for other purposes as well. For example, you could use the API to use Unity as the simulation engine for your own machine learning algorithms. See [External ML API](Python-API.md) for more information.
+**Note:** The API used by the Python PPO training process to communicate with and control the Academy during training can be used for other purposes as well. For example, you could use the API to use Unity as the simulation engine for your own machine learning algorithms. See [Python API](Python-API.md) for more information.
 
 ## Organizing the Unity Scene
 

docs/Python-API.md

@@ -38,7 +38,7 @@ A BrainInfo object contains the following fields:
 * **`text_observations`** : A list of string corresponding to the agents text observations.
 * **`memories`** : A two dimensional numpy array of dimension `(batch size, memory size)` which corresponds to the memories sent at the previous step.
 * **`rewards`** : A list as long as the number of agents using the brain containing the rewards they each obtained at the previous step. 
-* **`local_done`** : A list as long as the number of agents using the brain containing  `done` flags (wether or not the agent is done). 
+* **`local_done`** : A list as long as the number of agents using the brain containing  `done` flags (whether or not the agent is done). 
 * **`max_reached`** : A list as long as the number of agents using the brain containing true if the agents reached their max steps.
 * **`agents`** : A list of the unique ids of the agents using the brain.
 * **`previous_actions`** : A two dimensional numpy array of dimension `(batch size, vector action size)` if the vector action space is continuous and `(batch size, 1)` if the vector action space is discrete.