[Side Channels] Edited the documenation and renamed a few things

com.unity.ml-agents/CHANGELOG.md

@@ -13,10 +13,6 @@ and this project adheres to
 - The `--load` and `--train` command-line flags have been deprecated. Training
   now happens by default, and use `--resume` to resume training instead. (#3705)
 - The Jupyter notebooks have been removed from the repository.
-- Introduced the `SideChannelUtils` to register, unregister and access side
-  channels.
-- `Academy.FloatProperties` was removed, please use
-  `SideChannelUtils.GetSideChannel<FloatPropertiesChannel>()` instead.
 - Removed the multi-agent gym option from the gym wrapper. For multi-agent
   scenarios, use the [Low Level Python API](../docs/Python-API.md).
 - The low level Python API has changed. You can look at the document
@@ -36,21 +32,29 @@ and this project adheres to
   communication between Unity and the Python process.
 - The obsolete `Agent` methods `GiveModel`, `Done`, `InitializeAgent`,
   `AgentAction` and `AgentReset` have been removed.
-- The GhostTrainer has been extended to support asymmetric games and the asymmetric example environment Strikers Vs. Goalie has been added.
+- The GhostTrainer has been extended to support asymmetric games and the
+  asymmetric example environment Strikers Vs. Goalie has been added.
+- The SideChannel API has changed (#3833, #3660) :
+  - Introduced the `SideChannelManager` to register, unregister and access side
+  channels.
+  - `EnvironmentParameters` replaces the default `FloatProperties`.
+  You can access the `EnvironmentParameters` with
+  `Academy.Instance.EnvironmentParameters` on C# and create an
+  `EnvironmentParametersChannel` on Python
+  - `SideChannel.OnMessageReceived` is now a protected method (was public)
+  - SideChannel IncomingMessages methods now take an optional default argument,
+  which is used when trying to read more data than the message contains.
+  - Added a feature to allow sending stats from C# environments to TensorBoard
+  (and other python StatsWriters). To do this from your code, use
+  `Academy.Instance.StatsRecorder.Add(key, value)`(#3660)
 
 ### Minor Changes
 
 - Format of console output has changed slightly and now matches the name of the
   model/summary directory. (#3630, #3616)
-- Added a feature to allow sending stats from C# environments to TensorBoard
-  (and other python StatsWriters). To do this from your code, use
-  `SideChannelUtils.GetSideChannel<StatsSideChannel>().AddStat(key, value)`
-  (#3660)
 - Renamed 'Generalization' feature to 'Environment Parameter Randomization'.
 - Timer files now contain a dictionary of metadata, including things like the
   package version numbers.
-- SideChannel IncomingMessages methods now take an optional default argument,
-  which is used when trying to read more data than the message contains.
 - The way that UnityEnvironment decides the port was changed. If no port is
   specified, the behavior will depend on the `file_name` parameter. If it is
   `None`, 5004 (the editor port) will be used; otherwise 5005 (the base

com.unity.ml-agents/Runtime/Academy.cs

@@ -58,7 +58,7 @@ public class Academy : IDisposable
         /// on each side, although we may allow some flexibility in the future.
         /// This should be incremented whenever a change is made to the communication protocol.
         /// </summary>
-        const string k_ApiVersion = "0.16.0";
+        const string k_ApiVersion = "0.17.0";
 
         /// <summary>
         /// Unity package version of com.unity.ml-agents.

com.unity.ml-agents/Runtime/EnvironmentParameters.cs

@@ -38,7 +38,7 @@ internal EnvironmentParameters()
         /// <returns></returns>
         public float GetParameterWithDefault(string key, float defaultValue)
         {
-            return m_Channel.GetParameterWithDefault(key, defaultValue);
+            return m_Channel.GetWithDefault(key, defaultValue);
         }
 
         /// <summary>

com.unity.ml-agents/Runtime/SideChannels/EnvironmentParametersChannel.cs

@@ -1,5 +1,6 @@
 using System.Collections.Generic;
 using System;
+using UnityEngine;
 
 namespace MLAgents.SideChannels
 {
@@ -49,7 +50,7 @@ protected override void OnMessageReceived(IncomingMessage msg)
             }
             else
             {
-                throw new UnityAgentsException("EnvironmentParametersChannel only supports floats.");
+                Debug.LogWarning("EnvironmentParametersChannel received an unknown data type.")
             }
         }
 
@@ -60,7 +61,7 @@ protected override void OnMessageReceived(IncomingMessage msg)
         /// <param name="key">Parameter key.</param>
         /// <param name="defaultValue">Default value to return.</param>
         /// <returns></returns>
-        public float GetParameterWithDefault(string key, float defaultValue)
+        public float GetWithDefault(string key, float defaultValue)
         {
             float valueOut;
             bool hasKey = m_Parameters.TryGetValue(key, out valueOut);

com.unity.ml-agents/Runtime/SideChannels/FloatPropertiesChannel.cs

@@ -43,7 +43,7 @@ protected override void OnMessageReceived(IncomingMessage msg)
         }
 
         /// <inheritdoc/>
-        public void SetProperty(string key, float value)
+        public void Set(string key, float value)
         {
             m_FloatProperties[key] = value;
             using (var msgOut = new OutgoingMessage())
@@ -59,7 +59,7 @@ public void SetProperty(string key, float value)
         }
 
         /// <inheritdoc/>
-        public float GetPropertyWithDefault(string key, float defaultValue)
+        public float GetWithDefault(string key, float defaultValue)
         {
             float valueOut;
             bool hasKey = m_FloatProperties.TryGetValue(key, out valueOut);
@@ -73,7 +73,7 @@ public void RegisterCallback(string key, Action<float> action)
         }
 
         /// <inheritdoc/>
-        public IList<string> ListProperties()
+        public IList<string> List()
         {
             return new List<string>(m_FloatProperties.Keys);
         }

com.unity.ml-agents/Tests/Editor/SideChannelTests.cs

@@ -90,31 +90,31 @@ public void TestFloatPropertiesSideChannel()
             var dictSender = new Dictionary<Guid, SideChannel> { { propB.ChannelId, propB } };
 
             propA.RegisterCallback(k1, f => { wasCalled++; });
-            var tmp = propB.GetPropertyWithDefault(k2, 3.0f);
+            var tmp = propB.GetWithDefault(k2, 3.0f);
             Assert.AreEqual(tmp, 3.0f);
-            propB.SetProperty(k2, 1.0f);
-            tmp = propB.GetPropertyWithDefault(k2, 3.0f);
+            propB.Set(k2, 1.0f);
+            tmp = propB.GetWithDefault(k2, 3.0f);
             Assert.AreEqual(tmp, 1.0f);
 
             byte[] fakeData = SideChannelsManager.GetSideChannelMessage(dictSender);
             SideChannelsManager.ProcessSideChannelData(dictReceiver, fakeData);
 
-            tmp = propA.GetPropertyWithDefault(k2, 3.0f);
+            tmp = propA.GetWithDefault(k2, 3.0f);
             Assert.AreEqual(tmp, 1.0f);
 
             Assert.AreEqual(wasCalled, 0);
-            propB.SetProperty(k1, 1.0f);
+            propB.Set(k1, 1.0f);
             Assert.AreEqual(wasCalled, 0);
             fakeData = SideChannelsManager.GetSideChannelMessage(dictSender);
             SideChannelsManager.ProcessSideChannelData(dictReceiver, fakeData);
             Assert.AreEqual(wasCalled, 1);
 
-            var keysA = propA.ListProperties();
+            var keysA = propA.List();
             Assert.AreEqual(2, keysA.Count);
             Assert.IsTrue(keysA.Contains(k1));
             Assert.IsTrue(keysA.Contains(k2));
 
-            var keysB = propA.ListProperties();
+            var keysB = propA.List();
             Assert.AreEqual(2, keysB.Count);
             Assert.IsTrue(keysB.Contains(k1));
             Assert.IsTrue(keysB.Contains(k2));

docs/Custom-SideChannels.md

@@ -3,7 +3,7 @@
 You can create your own side channel in C# and Python and use it to communicate
 custom data structures between the two. This can be useful for situations in
 which the data to be sent is too complex or structured for the built-in
-`FloatPropertiesChannel`, or is not related to any specific agent, and therefore
+`EnvironmentParameters`, or is not related to any specific agent, and therefore
 inappropriate as an agent observation.
 
 ## Overview
@@ -24,7 +24,7 @@ To send data from C# to Python, create an `OutgoingMessage` instance, add data t
 `base.QueueMessageToSend(msg)` method inside the side channel, and call the
 `OutgoingMessage.Dispose()` method.
 
-To register a side channel on the Unity side, call `SideChannelUtils.RegisterSideChannel` with the side channel
+To register a side channel on the Unity side, call `SideChannelManager.RegisterSideChannel` with the side channel
 as only argument.
 
 ### Python side
@@ -122,16 +122,16 @@ public class RegisterStringLogSideChannel : MonoBehaviour
         // When a Debug.Log message is created, we send it to the stringChannel
         Application.logMessageReceived += stringChannel.SendDebugStatementToPython;
 
-        // The channel must be registered with the SideChannelUtils class
-        SideChannelUtils.RegisterSideChannel(stringChannel);
+        // The channel must be registered with the SideChannelManager class
+        SideChannelManager.RegisterSideChannel(stringChannel);
     }
 
     public void OnDestroy()
     {
         // De-register the Debug.Log callback
         Application.logMessageReceived -= stringChannel.SendDebugStatementToPython;
         if (Academy.IsInitialized){
-            SideChannelUtils.UnregisterSideChannel(stringChannel);
+            SideChannelManager.UnregisterSideChannel(stringChannel);
         }
     }
 

docs/Migrating.md

@@ -33,6 +33,19 @@ double-check that the versions are in the same. The versions can be found in
 - The signature of `Agent.Heuristic()` was changed to take a `float[]` as a
   parameter, instead of returning the array. This was done to prevent a common
   source of error where users would return arrays of the wrong size.
+- The SideChannel API has changed (#3833, #3660) :
+  - Introduced the `SideChannelManager` to register, unregister and access side
+  channels.
+  - `EnvironmentParameters` replaces the default `FloatProperties`.
+  You can access the `EnvironmentParameters` with
+  `Academy.Instance.EnvironmentParameters` on C# and create an
+  `EnvironmentParametersChannel` on Python
+  - `SideChannel.OnMessageReceived` is now a protected method (was public)
+  - SideChannel IncomingMessages methods now take an optional default argument,
+  which is used when trying to read more data than the message contains.
+  - Added a feature to allow sending stats from C# environments to TensorBoard
+  (and other python StatsWriters). To do this from your code, use
+  `Academy.Instance.StatsRecorder.Add(key, value)`(#3660)
 
 ### Steps to Migrate
 
@@ -42,18 +55,14 @@ double-check that the versions are in the same. The versions can be found in
 - To force-overwrite files from a pre-existing run, add the `--force`
   command-line flag.
 - The Jupyter notebooks have been removed from the repository.
-- `Academy.FloatProperties` was removed.
-- `Academy.RegisterSideChannel` and `Academy.UnregisterSideChannel` were
-  removed.
-- Replace `Academy.FloatProperties` with
-  `SideChannelUtils.GetSideChannel<FloatPropertiesChannel>()`.
-- Replace `Academy.RegisterSideChannel` with
-  `SideChannelUtils.RegisterSideChannel()`.
-- Replace `Academy.UnregisterSideChannel` with
-  `SideChannelUtils.UnregisterSideChannel`.
 - If your Agent class overrides `Heuristic()`, change the signature to
   `public override void Heuristic(float[] actionsOut)` and assign values to
   `actionsOut` instead of returning an array.
+- If you used `SideChannels` you must:
+  - Replace `Academy.FloatProperties` with `Academy.Instance.EnvironmentParameters`.
+  - `Academy.RegisterSideChannel` and `Academy.UnregisterSideChannel` were
+  removed. Use `SideChannelManager.RegisterSideChannel` and
+  `SideChannelManager.UnregisterSideChannel` instead.
 
 ## Migrating from 0.14 to 0.15
 

docs/Python-API.md

@@ -306,41 +306,34 @@ i = env.reset()
 ...
 ```
 
-#### FloatPropertiesChannel
-The `FloatPropertiesChannel` will allow you to get and set pre-defined numerical values in the environment. This can be useful for adjusting environment-specific settings, or for reading non-agent related information from the environment. You can call `get_property` and `set_property` on the side channel to read and write properties.
+#### EnvironmentParameters
+The `EnvironmentParameters` will allow you to get and set pre-defined numerical values in the environment. This can be useful for adjusting environment-specific settings, or for reading non-agent related information from the environment. You can call `get_property` and `set_property` on the side channel to read and write properties.
 
-`FloatPropertiesChannel` has three methods:
+`EnvironmentParametersChannel` has one methods:
 
- * `set_property` Sets a property in the Unity Environment.
+ * `set_float_parameter` Sets a float parameter in the Unity Environment.
     * key: The string identifier of the property.
     * value: The float value of the property.
 
- * `get_property` Gets a property in the Unity Environment. If the property was not found, will return None.
-    * key: The string identifier of the property.
-
- * `list_properties` Returns a list of all the string identifiers of the properties
-
 ```python
 from mlagents_envs.environment import UnityEnvironment
-from mlagents_envs.side_channel.float_properties_channel import FloatPropertiesChannel
+from mlagents_envs.side_channel.environment_parameters_channel import EnvironmentParametersChannel
 
-channel = FloatPropertiesChannel()
+channel = EnvironmentParametersChannel()
 
 env = UnityEnvironment(side_channels=[channel])
 
-channel.set_property("parameter_1", 2.0)
+channel.set_float_parameter("parameter_1", 2.0)
 
 i = env.reset()
-
-readout_value = channel.get_property("parameter_2")
 ...
 ```
 
 Once a property has been modified in Python, you can access it in C# after the next call to `step` as follows:
 
 ```csharp
-var sharedProperties = SideChannelUtils.GetSideChannel<FloatPropertiesChannel>();
-float property1 = sharedProperties.GetPropertyWithDefault("parameter_1", 0.0f);
+var envParameters = Academy.Instance.EnvironmentParameters;
+float property1 = envParameters.GetWithDefault("parameter_1", 0.0f);
 ```
 
 #### Custom side channels

docs/Training-Curriculum-Learning.md

@@ -40,8 +40,8 @@ the same environment.
 
 In order to define the curricula, the first step is to decide which parameters of
 the environment will vary. In the case of the Wall Jump environment,
-the height of the wall is what varies. We define this as a `Shared Float Property`
-that can be accessed in `SideChannelUtils.GetSideChannel<FloatPropertiesChannel>()`, and by doing
+the height of the wall is what varies. We define this as a `Environment Parameters`
+that can be accessed in `Academy.Instance.EnvironmentParameters`, and by doing
 so it becomes adjustable via the Python API.
 Rather than adjusting it by hand, we will create a YAML file which
 describes the structure of the curricula. Within it, we can specify which

docs/Using-Tensorboard.md

@@ -95,6 +95,6 @@ To get custom metrics from a C# environment into Tensorboard, you can use the
 StatsSideChannel:
 
 ```csharp
-var statsSideChannel = SideChannelUtils.GetSideChannel<StatsSideChannel>();
-statsSideChannel.AddStat("MyMetric", 1.0);
+var statsRecorder = Academy.Instance.StatsRecorder;
+statsSideChannel.Add("MyMetric", 1.0);
 ```

ml-agents-envs/mlagents_envs/environment.py

@@ -58,7 +58,7 @@ class UnityEnvironment(BaseEnv):
     # Currently we require strict equality between the communication protocol
     # on each side, although we may allow some flexibility in the future.
     # This should be incremented whenever a change is made to the communication protocol.
-    API_VERSION = "0.16.0"
+    API_VERSION = "0.17.0"
 
     # Default port that the editor listens on. If an environment executable
     # isn't specified, this port will be used.

ml-agents-envs/mlagents_envs/side_channel/environment_parameters_channel.py

@@ -8,7 +8,7 @@ class EnvironmentParametersChannel(SideChannel):
     """
     This is the SideChannel for sending environment parameters to Unity.
     You can send parameters to an environment with the command
-    set_float_property.
+    set_float_parameter.
     """
 
     class EnvironmentDataTypes(IntEnum):
@@ -24,7 +24,7 @@ def on_message_received(self, msg: IncomingMessage) -> None:
             + "this should not have happend."
         )
 
-    def set_float_property(self, key: str, value: float) -> None:
+    def set_float_parameter(self, key: str, value: float) -> None:
         """
         Sets a float environment parameter in the Unity Environment.
         :param key: The string identifier of the parameter.

ml-agents/mlagents/trainers/simple_env_manager.py

@@ -44,7 +44,7 @@ def _reset_env(
     ) -> List[EnvironmentStep]:  # type: ignore
         if config is not None:
             for k, v in config.items():
-                self.env_params.set_float_property(k, v)
+                self.env_params.set_float_parameter(k, v)
         self.env.reset()
         all_step_result = self._generate_all_results()
         self.previous_step = EnvironmentStep(all_step_result, 0, {}, {})

ml-agents/mlagents/trainers/subprocess_env_manager.py

@@ -170,7 +170,7 @@ def external_brains():
                 _send_response(EnvironmentCommand.EXTERNAL_BRAINS, external_brains())
             elif req.cmd == EnvironmentCommand.RESET:
                 for k, v in req.payload.items():
-                    env_parameters.set_float_property(k, v)
+                    env_parameters.set_float_parameter(k, v)
                 env.reset()
                 all_step_result = _generate_all_results()
                 _send_response(EnvironmentCommand.RESET, all_step_result)