From 19ae142e9f921488fb274fd301304f0feffa7ca3 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 13:05:04 -0700 Subject: [PATCH 01/20] update title caps --- docs/Custom-Protos.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/Custom-Protos.md b/docs/Custom-Protos.md index 0de2bc7fda..c4f2c800f1 100644 --- a/docs/Custom-Protos.md +++ b/docs/Custom-Protos.md @@ -1,14 +1,14 @@ -# Creating custom protobuf messages +# Creating Custom Protobuf Messages Unity and Python communicate by sending protobuf messages to and from each other. You can create custom protobuf messages if you want to exchange structured data beyond what is included by default. Assume the ml-agents repository is checked out to a folder named $MLAGENTS_ROOT. Whenever you change the fields of a custom message, you must run `$MLAGENTS_ROOT/protobuf-definitions/make.bat` to create C# and Python files corresponding to the new message. Follow the directions in [this file](../protobuf-definitions/README.md) for guidance. After running it, reinstall the Python package by running `pip install $MLAGENTS_ROOT/ml-agents` and make sure your Unity project is using the newly-generated version of `$MLAGENTS_ROOT/UnitySDK`. -## Custom message types +## Custom Message Types There are three custom message types currently supported, described below. In each case, `env` is an instance of a `UnityEnvironment` in Python. `CustomAction` is described most thoroughly; usage of the other custom messages follows a similar template. -### Custom actions +### Custom Actions By default, the Python API sends actions to Unity in the form of a floating-point list per agent and an optional string-valued text action. @@ -74,7 +74,7 @@ class MyAgent : Agent { Note that the protobuffer compiler automatically configures the capitalization scheme of the C# version of the custom field names you defined in the `CustomAction` message to match C# conventions - "NORTH" becomes "North", "walkAmount" becomes "WalkAmount", etc. -### Custom reset parameters +### Custom Reset Parameters By default, you can configure an environment `env ` in the Python API by specifying a `config` parameter that is a dictionary mapping strings to floats. @@ -133,7 +133,7 @@ params = CustomResetParameters(initialPos=pos, color=color) env.reset(custom_reset_parameters=params) ``` -### Custom observations +### Custom Observations By default, Unity returns observations to Python in the form of a floating-point vector. From 7d0a315e5a07d1a70344e9ea6fd03b92992ed7f1 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 13:05:49 -0700 Subject: [PATCH 02/20] Rename Custom-Protos.md to Creating-Custom-Protobuf-Messages.md --- docs/{Custom-Protos.md => Creating-Custom-Protobuf-Messages.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{Custom-Protos.md => Creating-Custom-Protobuf-Messages.md} (100%) diff --git a/docs/Custom-Protos.md b/docs/Creating-Custom-Protobuf-Messages.md similarity index 100% rename from docs/Custom-Protos.md rename to docs/Creating-Custom-Protobuf-Messages.md From b74a48f33820ba0b3489daf6ab51479eadd2f3b6 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 13:07:55 -0700 Subject: [PATCH 03/20] Updated with custom protobuf messages --- docs/Readme.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/Readme.md b/docs/Readme.md index 31fe235ece..8743938438 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -29,6 +29,7 @@ * [Learning Environment Best Practices](Learning-Environment-Best-Practices.md) * [Using the Monitor](Feature-Monitor.md) * [Using an Executable Environment](Learning-Environment-Executable.md) +* [Creating Custom Protobuf Messages](Creating-Custom-Protobuf-Messages.md) ## Training From 2255f9bfc9d7590c367a58e7f460c97e4de2d865 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 13:35:45 -0700 Subject: [PATCH 04/20] Cleanup against to our doc guidelines --- docs/Creating-Custom-Protobuf-Messages.md | 57 ++++++++++++----------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/docs/Creating-Custom-Protobuf-Messages.md b/docs/Creating-Custom-Protobuf-Messages.md index c4f2c800f1..08569ab361 100644 --- a/docs/Creating-Custom-Protobuf-Messages.md +++ b/docs/Creating-Custom-Protobuf-Messages.md @@ -2,27 +2,29 @@ Unity and Python communicate by sending protobuf messages to and from each other. You can create custom protobuf messages if you want to exchange structured data beyond what is included by default. -Assume the ml-agents repository is checked out to a folder named $MLAGENTS_ROOT. Whenever you change the fields of a custom message, you must run `$MLAGENTS_ROOT/protobuf-definitions/make.bat` to create C# and Python files corresponding to the new message. Follow the directions in [this file](../protobuf-definitions/README.md) for guidance. After running it, reinstall the Python package by running `pip install $MLAGENTS_ROOT/ml-agents` and make sure your Unity project is using the newly-generated version of `$MLAGENTS_ROOT/UnitySDK`. +## Implementing a Custom Message + +Assume the ml-agents repository is checked out to a folder named $MLAGENTS_ROOT. Whenever you change the fields of a custom message, you must run `$MLAGENTS_ROOT/protobuf-definitions/make.bat` to create C# and Python files corresponding to the new message. Follow the directions in [this file](../protobuf-definitions/README.md) for guidance. After running `$MLAGENTS_ROOT/protobuf-definitions/make.bat`, reinstall the Python package by running `pip install $MLAGENTS_ROOT/ml-agents` and make sure your Unity project is using the newly-generated version of `$MLAGENTS_ROOT/UnitySDK`. ## Custom Message Types -There are three custom message types currently supported, described below. In each case, `env` is an instance of a `UnityEnvironment` in Python. `CustomAction` is described most thoroughly; usage of the other custom messages follows a similar template. +There are three custom message types currently supported - Custom Actions, Custom Reset Parameters, and Custom Observations. In each case, `env` is an instance of a `UnityEnvironment` in Python. ### Custom Actions -By default, the Python API sends actions to Unity in the form of a floating-point list per agent and an optional string-valued text action. +By default, the Python API sends actions to Unity in the form of a floating point list and an optional string-valued text action for each agent. -You can define a custom action type to replace or augment this by adding fields to the `CustomAction` message, which you can do by editing the file `protobuf-definitions/proto/mlagents/envs/communicator_objects/custom_action.proto`. +You can define a custom action type, to either replace or augment the default, by adding fields to the `CustomAction` message, which you can do by editing the file `protobuf-definitions/proto/mlagents/envs/communicator_objects/custom_action.proto`. -Instances of custom actions are set via the `custom_action` parameter of `env.step`. An agent receives a custom action by defining a method with the signature +Instances of custom actions are set via the `custom_action` parameter of the `env.step`. An agent receives a custom action by defining a method with the signature: ```csharp public virtual void AgentAction(float[] vectorAction, string textAction, CommunicatorObjects.CustomAction customAction) ``` -Here is an example of creating a custom action that instructs an agent to choose a cardinal direction to walk in and how far to walk. +Below is an example of creating a custom action that instructs an agent to choose a cardinal direction to walk in and how far to walk. -`custom_action.proto` will look like +The `custom_action.proto` file looks like: ```protobuf syntax = "proto3"; @@ -42,7 +44,7 @@ message CustomAction { } ``` -In your Python file, create an instance of a custom action: +The Python instance of the custom action looks like: ```python from mlagents.envs.communicator_objects import CustomAction @@ -52,7 +54,7 @@ action = CustomAction(direction=CustomAction.NORTH, walkAmount=2.0) env.step(custom_action=action) ``` -Then in your agent, +And the agent code looks like: ```csharp ... @@ -72,17 +74,17 @@ class MyAgent : Agent { } ``` -Note that the protobuffer compiler automatically configures the capitalization scheme of the C# version of the custom field names you defined in the `CustomAction` message to match C# conventions - "NORTH" becomes "North", "walkAmount" becomes "WalkAmount", etc. +Keep in mind that the protobuffer compiler automatically configures the capitalization scheme of the C# version of the custom field names you defined in the `CustomAction` message to match C# conventions - "NORTH" becomes "North", "walkAmount" becomes "WalkAmount", etc. ### Custom Reset Parameters -By default, you can configure an environment `env ` in the Python API by specifying a `config` parameter that is a dictionary mapping strings to floats. +By default, you can configure an environment `env` in the Python API by specifying a `config` parameter that is a dictionary mapping strings to floats. -You can also configure an environment using a custom protobuf message. To do so, add fields to the `CustomResetParameters` protobuf message in `custom_reset_parameters.proto`, analogously to `CustomAction` above. Then pass an instance of the message to `env.reset` via the `custom_reset_parameters` keyword parameter. +You can also configure the environment reset using a custom protobuf message. To do this, add fields to the `CustomResetParameters` protobuf message in `custom_reset_parameters.proto`, analogously to `CustomAction` above. Then pass an instance of the message to `env.reset` via the `custom_reset_parameters` keyword parameter. In Unity, you can then access the `customResetParameters` field of your academy to accesss the values set in your Python script. -In this example, an academy is setting the initial position of a box based on custom reset parameters that looks like +In this example, the academy is setting the initial position of a box based on custom reset parameters. The `custom_reset_parameters.proto` would look like: ```protobuf message CustomResetParameters { @@ -101,7 +103,18 @@ message CustomResetParameters { } ``` -In your academy, you'd have something like +The Python instance of the custom reset parameter looks like + +```python +from mlagents.envs.communicator_objects import CustomResetParameters +env = ... +pos = CustomResetParameters.Position(x=1, y=1, z=2) +color = CustomResetParameters.Color(r=.5, g=.1, b=1.0) +params = CustomResetParameters(initialPos=pos, color=color) +env.reset(custom_reset_parameters=params) +``` + +The academy looks like ```csharp public class MyAcademy : Academy @@ -122,17 +135,6 @@ public class MyAcademy : Academy } ``` -Then in Python, when setting up your scene, you might write - -```python -from mlagents.envs.communicator_objects import CustomResetParameters -env = ... -pos = CustomResetParameters.Position(x=1, y=1, z=2) -color = CustomResetParameters.Color(r=.5, g=.1, b=1.0) -params = CustomResetParameters(initialPos=pos, color=color) -env.reset(custom_reset_parameters=params) -``` - ### Custom Observations By default, Unity returns observations to Python in the form of a floating-point vector. @@ -143,8 +145,7 @@ Then in your agent, create an instance of a custom observation via `new Communic In Python, the custom observation can be accessed by calling `env.step` or `env.reset` and accessing the `custom_observations` property of the return value. It will contain a list with one `CustomObservation` instance per agent. -For example, if you have added a field called `customField` to the `CustomObservation` message, you would program your agent like - +For example, if you have added a field called `customField` to the `CustomObservation` message, the agent code looks like: ```csharp class MyAgent : Agent { @@ -156,7 +157,7 @@ class MyAgent : Agent { } ``` -Then in Python, the custom field would be accessed like +In Python, the custom field would be accessed like: ```python ... From 6124993be5c7c2f7abcb1b21151c44446c8509f4 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 13:38:58 -0700 Subject: [PATCH 05/20] Minor text revision --- docs/Installation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/Installation.md b/docs/Installation.md index dccbf47f72..fae9ae760b 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -82,8 +82,7 @@ parameters you can use with `mlagents-learn`. If you intend to make modifications to `ml-agents` or `ml-agents-envs`, you should install the packages from the cloned repo rather than from PyPi. To do this, you will need to install - `ml-agents` and `ml-agents-envs` separately. Do this by running (starting from the repo's main - directory): + `ml-agents` and `ml-agents-envs` separately. From the repo's root directory, run: ```sh cd ml-agents-envs @@ -98,7 +97,6 @@ reflected when you run `mlagents-learn`. It is important to install these packag `mlagents` package depends on `mlagents_envs`, and installing it in the other order will download `mlagents_envs` from PyPi. - ## Docker-based Installation If you'd like to use Docker for ML-Agents, please follow From 1246c4108c16c2e4942a617248a676947e220aaf Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 13:45:34 -0700 Subject: [PATCH 06/20] Create Training-Concurrent-Unity-Instances --- docs/Training-Concurrent-Unity-Instances | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/Training-Concurrent-Unity-Instances diff --git a/docs/Training-Concurrent-Unity-Instances b/docs/Training-Concurrent-Unity-Instances new file mode 100644 index 0000000000..8b13789179 --- /dev/null +++ b/docs/Training-Concurrent-Unity-Instances @@ -0,0 +1 @@ + From 0f655b32418685ea8b11c57bc940c4c2182e5c63 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 13:45:55 -0700 Subject: [PATCH 07/20] Rename Training-Concurrent-Unity-Instances to Training-Concurrent-Unity-Instances.md --- ...ent-Unity-Instances => Training-Concurrent-Unity-Instances.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{Training-Concurrent-Unity-Instances => Training-Concurrent-Unity-Instances.md} (100%) diff --git a/docs/Training-Concurrent-Unity-Instances b/docs/Training-Concurrent-Unity-Instances.md similarity index 100% rename from docs/Training-Concurrent-Unity-Instances rename to docs/Training-Concurrent-Unity-Instances.md From d5cba23ca3a2101b2a1f288ef2fc9f5ea0942230 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 14:08:17 -0700 Subject: [PATCH 08/20] update to right format for --num-envs --- docs/Training-ML-Agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Training-ML-Agents.md b/docs/Training-ML-Agents.md index ef011f7832..9390e72fca 100644 --- a/docs/Training-ML-Agents.md +++ b/docs/Training-ML-Agents.md @@ -134,7 +134,7 @@ environment, you can set the following command line options when invoking [Academy Properties](Learning-Environment-Design-Academy.md#academy-properties). * `--train` – Specifies whether to train model or only run in inference mode. When training, **always** use the `--train` option. -* `--num-envs` - Specifies the number of parallel environments to collect +* `--num-envs=` - Specifies the number of parallel environments to collect experiences from when training. Defaults to 1. * `--base-port` - Specifies the starting port for environment workers. Each Unity environment will use the port `(base_port + worker_id)`, where the worker ID From 0b540ca6980b3737474fe0ad1646f7f504760064 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 14:13:50 -0700 Subject: [PATCH 09/20] added link to concurrent unity instances --- docs/Readme.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/Readme.md b/docs/Readme.md index 8743938438..9539e90f82 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -40,6 +40,7 @@ * [Training with LSTM](Feature-Memory.md) * [Training on the Cloud with Amazon Web Services](Training-on-Amazon-Web-Service.md) * [Training on the Cloud with Microsoft Azure](Training-on-Microsoft-Azure.md) +* [Training Using Concurrent Unity Instances](Training-Using-Concurrent-Unity-Instances.md) * [Using TensorBoard to Observe Training](Using-Tensorboard.md) ## Inference From ff9e5ae2a47fb18d1d59933659e6ad42473efa26 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 14:14:05 -0700 Subject: [PATCH 10/20] Update and rename Training-Concurrent-Unity-Instances.md to Training-Using-Concurrent-Unity-Instances.md --- docs/Training-Concurrent-Unity-Instances.md | 1 - docs/Training-Using-Concurrent-Unity-Instances.md | 10 ++++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) delete mode 100644 docs/Training-Concurrent-Unity-Instances.md create mode 100644 docs/Training-Using-Concurrent-Unity-Instances.md diff --git a/docs/Training-Concurrent-Unity-Instances.md b/docs/Training-Concurrent-Unity-Instances.md deleted file mode 100644 index 8b13789179..0000000000 --- a/docs/Training-Concurrent-Unity-Instances.md +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/Training-Using-Concurrent-Unity-Instances.md b/docs/Training-Using-Concurrent-Unity-Instances.md new file mode 100644 index 0000000000..984661a8bc --- /dev/null +++ b/docs/Training-Using-Concurrent-Unity-Instances.md @@ -0,0 +1,10 @@ +# Training Using Concurrent Unity Instances + +As part of release v0.8, we enabled developers to run concurrent, parallel instances of the Unity executable during training. For certain scenarios, this should speed up the training. + +## How to Run Concurrent Unity Instances During Training + +Please refer to the general instructions on (Training ML-Agents)[Training-ML-Agents.md]. In order to run concurrent Unity instances during training, set number of enviornments using the command line option `--num-envs=` when you invoke `mlagents-learn`. + +## Considerations + From 85e915efa855268c16194f756079bb2f2f4bd84f Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 14:41:42 -0700 Subject: [PATCH 11/20] Added considerations section --- ...Training-Using-Concurrent-Unity-Instances.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/Training-Using-Concurrent-Unity-Instances.md b/docs/Training-Using-Concurrent-Unity-Instances.md index 984661a8bc..f24eb97d85 100644 --- a/docs/Training-Using-Concurrent-Unity-Instances.md +++ b/docs/Training-Using-Concurrent-Unity-Instances.md @@ -4,7 +4,22 @@ As part of release v0.8, we enabled developers to run concurrent, parallel insta ## How to Run Concurrent Unity Instances During Training -Please refer to the general instructions on (Training ML-Agents)[Training-ML-Agents.md]. In order to run concurrent Unity instances during training, set number of enviornments using the command line option `--num-envs=` when you invoke `mlagents-learn`. +Please refer to the general instructions on [Training ML-Agents](Training-ML-Agents.md). In order to run concurrent Unity instances during training, set number of enviornments using the command line option `--num-envs=` when you invoke `mlagents-learn`. ## Considerations +### Buffer Size + +If you are having trouble getting an agent to train, even with multiple concurrent Unity instances, you could increase `buffer_size` in the `config/trainer_config.yaml` file. A common practice is to multiply `buffer_size` by `num-envs`. + +### Resource Constraints + +Invoking concurrent Unity instances is constrained by the resources on the machine. Please use discretion when setting `--num-envs=`. + +### Using num-runs and num-envs + +If you set `--num-runs=` to than 1 and are also invoking concurrent Unity instances using `--num-envs=`, then the number of concurrent Unity instances is equal to `num-runs` times `num-envs`. + +### Result Variation Using Concurrent Unity Instances + +If you keep all the hyperparameters the same, but change `--num-envs=`, the results and model would likely change. From fae361e466652178d5763c14774f2f1ad572c2e7 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 14:47:59 -0700 Subject: [PATCH 12/20] Update Training-Using-Concurrent-Unity-Instances.md --- docs/Training-Using-Concurrent-Unity-Instances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Training-Using-Concurrent-Unity-Instances.md b/docs/Training-Using-Concurrent-Unity-Instances.md index f24eb97d85..7e19835e00 100644 --- a/docs/Training-Using-Concurrent-Unity-Instances.md +++ b/docs/Training-Using-Concurrent-Unity-Instances.md @@ -4,7 +4,7 @@ As part of release v0.8, we enabled developers to run concurrent, parallel insta ## How to Run Concurrent Unity Instances During Training -Please refer to the general instructions on [Training ML-Agents](Training-ML-Agents.md). In order to run concurrent Unity instances during training, set number of enviornments using the command line option `--num-envs=` when you invoke `mlagents-learn`. +Please refer to the general instructions on [Training ML-Agents](Training-ML-Agents.md). In order to run concurrent Unity instances during training, set number of enviornments using the command line option `--num-envs=` when you invoke `mlagents-learn`. Optionally, you can also set the `--base-port`, which is the starting port used for the concurrent Unity instances. ## Considerations From 46ad2ff2e7817bbb0f4d529f1f34e5dc20953561 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 14:50:26 -0700 Subject: [PATCH 13/20] cleaned up language to match doc --- docs/Training-ML-Agents.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/Training-ML-Agents.md b/docs/Training-ML-Agents.md index 9390e72fca..11ec1ddf9a 100644 --- a/docs/Training-ML-Agents.md +++ b/docs/Training-ML-Agents.md @@ -134,12 +134,11 @@ environment, you can set the following command line options when invoking [Academy Properties](Learning-Environment-Design-Academy.md#academy-properties). * `--train` – Specifies whether to train model or only run in inference mode. When training, **always** use the `--train` option. -* `--num-envs=` - Specifies the number of parallel environments to collect +* `--num-envs=` - Specifies the number of concurrent, parallel Unity environment instances to collect experiences from when training. Defaults to 1. -* `--base-port` - Specifies the starting port for environment workers. Each Unity - environment will use the port `(base_port + worker_id)`, where the worker ID - are sequential IDs given to each environment from 0 to `num_envs - 1`. - Defaults to 5005. +* `--base-port` - Specifies the starting port for each concurrent, parallel Unity environment instance. Each instance will use the port `(base_port + worker_id)`, where the `worker_id` + are sequential IDs given to each instance from 0 to `num_envs - 1`. + Default is 5005. * `--docker-target-name=
` – The Docker Volume on which to store curriculum, executable and model files. See [Using Docker](Using-Docker.md). * `--no-graphics` - Specify this option to run the Unity executable in From 9e11aba902536a1afee59f292a1bbaf24995d89c Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 14:54:50 -0700 Subject: [PATCH 14/20] minor updates --- docs/Training-Using-Concurrent-Unity-Instances.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Training-Using-Concurrent-Unity-Instances.md b/docs/Training-Using-Concurrent-Unity-Instances.md index 7e19835e00..14f5b18e76 100644 --- a/docs/Training-Using-Concurrent-Unity-Instances.md +++ b/docs/Training-Using-Concurrent-Unity-Instances.md @@ -4,7 +4,7 @@ As part of release v0.8, we enabled developers to run concurrent, parallel insta ## How to Run Concurrent Unity Instances During Training -Please refer to the general instructions on [Training ML-Agents](Training-ML-Agents.md). In order to run concurrent Unity instances during training, set number of enviornments using the command line option `--num-envs=` when you invoke `mlagents-learn`. Optionally, you can also set the `--base-port`, which is the starting port used for the concurrent Unity instances. +Please refer to the general instructions on [Training ML-Agents](Training-ML-Agents.md). In order to run concurrent Unity instances during training, set the number of environment instances using the command line option `--num-envs=` when you invoke `mlagents-learn`. Optionally, you can also set the `--base-port`, which is the starting port used for the concurrent Unity instances. ## Considerations @@ -18,7 +18,7 @@ Invoking concurrent Unity instances is constrained by the resources on the machi ### Using num-runs and num-envs -If you set `--num-runs=` to than 1 and are also invoking concurrent Unity instances using `--num-envs=`, then the number of concurrent Unity instances is equal to `num-runs` times `num-envs`. +If you set `--num-runs=` greater than 1 and are also invoking concurrent Unity instances using `--num-envs=`, then the number of concurrent Unity instances is equal to `num-runs` times `num-envs`. ### Result Variation Using Concurrent Unity Instances From dbab24bcbb06078620851959ec24ed0043148958 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 15:10:12 -0700 Subject: [PATCH 15/20] retroactive migration from 0.6 to 0.7 --- docs/Migrating.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/Migrating.md b/docs/Migrating.md index 4a1fb05eb5..c33f397757 100644 --- a/docs/Migrating.md +++ b/docs/Migrating.md @@ -1,5 +1,13 @@ # Migrating +## Migrating from ML-Agents toolkit v0.6 to v0.7 + +### Important Changes +* We no longer support TFS and are now using the [Unity Inference Engine](Unity-Inference-Engine.md) + +#### Steps to Migrate +* Make sure to remove the `ENABLE_TENSORFLOW` flag in your Unity Project settings + ## Migrating from ML-Agents toolkit v0.5 to v0.6 ### Important Changes From 48775799a25501211540b24beca30f8841139c4b Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 15:17:02 -0700 Subject: [PATCH 16/20] Updated from 0.7 to 0.8 migration --- docs/Migrating.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/Migrating.md b/docs/Migrating.md index c33f397757..10e2a9f6de 100644 --- a/docs/Migrating.md +++ b/docs/Migrating.md @@ -1,5 +1,17 @@ # Migrating +## Migrating from ML-Agents toolkit v0.7 to v0.8 + +### Important Changes +* We have split the Python packges into two seperate packages `ml-agents` and `ml-agents-envs` + +#### Steps to Migrate +* If you are installing via PyPI, there is no change. +* If you intend to make modifications to `ml-agents` or `ml-agents-envs` please check the Installing for Development in the (Installation documentation)[Installation.md]. + +#### Steps to Migrate +* Make sure to remove the `ENABLE_TENSORFLOW` flag in your Unity project settings + ## Migrating from ML-Agents toolkit v0.6 to v0.7 ### Important Changes From 2108eb16050b316e6b21a67ec01a6ee9cb25fb4a Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 15:17:32 -0700 Subject: [PATCH 17/20] Minor typo --- docs/Migrating.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Migrating.md b/docs/Migrating.md index 10e2a9f6de..05ad3c9c95 100644 --- a/docs/Migrating.md +++ b/docs/Migrating.md @@ -7,7 +7,7 @@ #### Steps to Migrate * If you are installing via PyPI, there is no change. -* If you intend to make modifications to `ml-agents` or `ml-agents-envs` please check the Installing for Development in the (Installation documentation)[Installation.md]. +* If you intend to make modifications to `ml-agents` or `ml-agents-envs` please check the Installing for Development in the [Installation documentation](Installation.md). #### Steps to Migrate * Make sure to remove the `ENABLE_TENSORFLOW` flag in your Unity project settings From b608741b05826a08a12cebb25af867f0283ca09f Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 16:16:20 -0700 Subject: [PATCH 18/20] minor fix --- docs/Training-ML-Agents.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/Training-ML-Agents.md b/docs/Training-ML-Agents.md index 11ec1ddf9a..da597e584b 100644 --- a/docs/Training-ML-Agents.md +++ b/docs/Training-ML-Agents.md @@ -134,11 +134,9 @@ environment, you can set the following command line options when invoking [Academy Properties](Learning-Environment-Design-Academy.md#academy-properties). * `--train` – Specifies whether to train model or only run in inference mode. When training, **always** use the `--train` option. -* `--num-envs=` - Specifies the number of concurrent, parallel Unity environment instances to collect +* `--num-envs=` - Specifies the number of concurrent Unity environment instances to collect experiences from when training. Defaults to 1. -* `--base-port` - Specifies the starting port for each concurrent, parallel Unity environment instance. Each instance will use the port `(base_port + worker_id)`, where the `worker_id` - are sequential IDs given to each instance from 0 to `num_envs - 1`. - Default is 5005. +* `--base-port` - Specifies the starting port. Each concurrent Unity environment instance will get assigned a port sequentially, starting from the `base-port`. Each instance will use the port `(base_port + worker_id)`, where the `worker_id` is sequential IDs given to each instance from 0 to `num_envs - 1`. Default is 5005. * `--docker-target-name=
` – The Docker Volume on which to store curriculum, executable and model files. See [Using Docker](Using-Docker.md). * `--no-graphics` - Specify this option to run the Unity executable in From 8653edf34cf387c72002d48f0db07c1e7922d300 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 16:17:59 -0700 Subject: [PATCH 19/20] accidentally duplicated step --- docs/Migrating.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/Migrating.md b/docs/Migrating.md index 05ad3c9c95..5ec341dbee 100644 --- a/docs/Migrating.md +++ b/docs/Migrating.md @@ -9,9 +9,6 @@ * If you are installing via PyPI, there is no change. * If you intend to make modifications to `ml-agents` or `ml-agents-envs` please check the Installing for Development in the [Installation documentation](Installation.md). -#### Steps to Migrate -* Make sure to remove the `ENABLE_TENSORFLOW` flag in your Unity project settings - ## Migrating from ML-Agents toolkit v0.6 to v0.7 ### Important Changes From 974ffab4416537bdeba69677f230c73fe052b442 Mon Sep 17 00:00:00 2001 From: Jeffrey Shih <34355042+unityjeffrey@users.noreply.github.com> Date: Thu, 11 Apr 2019 16:24:46 -0700 Subject: [PATCH 20/20] updated with new features list --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 663ded3216..e6f46ddfee 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,8 @@ developer communities. * Visualizing network outputs within the environment * Simplified set-up with Docker * Wrap learning environments as a gym +* Utilizes the Unity Inference Engine +* Train using concurrent Unity environment instances ## Documentation