Removing Obsolete methods from the package (#5024)

* Removing Obsolete methods from the package

* Missing depecration and modified changelog

* Readding the obsolete BrainParameter methods, will need a larger discussion on these

* Removing Action Masker, readding the warining when using a non-implemented Heuristic, Removing NumAction from Brain Parameters

* removing documentation and some calls to deprecated methods in the extensions package

* Editing the Changelog to put the unreleased on top

Author: vincentpierre

Project/Assets/ML-Agents/Examples/Basic/Scripts/BasicActuatorComponent.cs

@@ -17,11 +17,9 @@ public class BasicActuatorComponent : ActuatorComponent
         /// Creates a BasicActuator.
         /// </summary>
         /// <returns></returns>
-#pragma warning disable 672
-        public override IActuator CreateActuator()
-#pragma warning restore 672
+        public override IActuator[] CreateActuators()
         {
-            return new BasicActuator(basicController);
+            return new IActuator[] { new BasicActuator(basicController) };
         }
 
         public override ActionSpec ActionSpec

Project/Assets/ML-Agents/Examples/Match3/Scripts/Match3ExampleActuatorComponent.cs

@@ -7,14 +7,12 @@ namespace Unity.MLAgentsExamples
     public class Match3ExampleActuatorComponent : Match3ActuatorComponent
     {
         /// <inheritdoc/>
-#pragma warning disable 672
-        public override IActuator CreateActuator()
-#pragma warning restore 672
+        public override IActuator[] CreateActuators()
         {
             var board = GetComponent<Match3Board>();
             var agent = GetComponentInParent<Agent>();
             var seed = RandomSeed == -1 ? gameObject.GetInstanceID() : RandomSeed + 1;
-            return new Match3ExampleActuator(board, ForceHeuristic, agent, ActuatorName, seed);
+            return new IActuator[] { new Match3ExampleActuator(board, ForceHeuristic, agent, ActuatorName, seed) };
         }
     }
 }

com.unity.ml-agents.extensions/Runtime/Input/InputActuatorComponent.cs

@@ -241,11 +241,6 @@ internal static InputControlScheme CreateControlScheme(InputControl device,
             return inputControlScheme;
         }
 
-#pragma warning disable 672
-        /// <inheritdoc cref="ActuatorComponent.CreateActuator"/>
-        public override IActuator CreateActuator() { return null; }
-#pragma warning restore 672
-
         /// <summary>
         ///
         /// </summary>

com.unity.ml-agents.extensions/Runtime/Match3/Match3ActuatorComponent.cs

@@ -29,14 +29,12 @@ public class Match3ActuatorComponent : ActuatorComponent
         public bool ForceHeuristic;
 
         /// <inheritdoc/>
-#pragma warning disable 672
-        public override IActuator CreateActuator()
-#pragma warning restore 672
+        public override IActuator[] CreateActuators()
         {
             var board = GetComponent<AbstractBoard>();
             var agent = GetComponentInParent<Agent>();
             var seed = RandomSeed == -1 ? gameObject.GetInstanceID() : RandomSeed + 1;
-            return new Match3Actuator(board, ForceHeuristic, seed, agent, ActuatorName);
+            return new IActuator[] { new Match3Actuator(board, ForceHeuristic, seed, agent, ActuatorName) };
         }
 
         /// <inheritdoc/>

com.unity.ml-agents/CHANGELOG.md

@@ -9,6 +9,21 @@ and this project adheres to
 ## [Unreleased]
 ### Major Changes
 #### com.unity.ml-agents (C#)
+- Some methods previously marked as `Obsolete` have been removed. If you were using these methods, you need to replace them with their supported counterpart.
+#### ml-agents / ml-agents-envs / gym-unity (Python)
+
+### Minor Changes
+#### com.unity.ml-agents / com.unity.ml-agents.extensions (C#)
+#### ml-agents / ml-agents-envs / gym-unity (Python)
+
+### Bug Fixes
+#### com.unity.ml-agents (C#)
+#### ml-agents / ml-agents-envs / gym-unity (Python)
+
+
+## [1.9.0-preview] - 2021-03-17
+### Major Changes
+#### com.unity.ml-agents (C#)
 - The `BufferSensor` and `BufferSensorComponent` have been added. They allow the Agent to observe variable number of entities. (#4909)
 #### ml-agents / ml-agents-envs / gym-unity (Python)
 

com.unity.ml-agents/Runtime/Actuators/ActuatorComponent.cs

@@ -9,24 +9,12 @@ namespace Unity.MLAgents.Actuators
     /// </summary>
     public abstract class ActuatorComponent : MonoBehaviour
     {
-        /// <summary>
-        /// Create the IActuator.  This is called by the Agent when it is initialized.
-        /// </summary>
-        /// <returns>Created IActuator object.</returns>
-        [Obsolete("Use CreateActuators instead.")]
-        public abstract IActuator CreateActuator();
-
         /// <summary>
         /// Create a collection of <see cref="IActuator"/>s.  This is called by the <see cref="Agent"/> during
         /// initialization.
         /// </summary>
         /// <returns>A collection of <see cref="IActuator"/>s</returns>
-        public virtual IActuator[] CreateActuators()
-        {
-#pragma warning disable 618
-            return new[] { CreateActuator() };
-#pragma warning restore 618
-        }
+        public abstract IActuator[] CreateActuators();
 
         /// <summary>
         /// The specification of the possible actions for this ActuatorComponent.

com.unity.ml-agents/Runtime/Actuators/IActionReceiver.cs

@@ -148,47 +148,6 @@ public override int GetHashCode()
                 return (ContinuousActions.GetHashCode() * 397) ^ DiscreteActions.GetHashCode();
             }
         }
-
-        /// <summary>
-        /// Packs the continuous and discrete actions into one float array.  The array passed into this method
-        /// must have a Length that is greater than or equal to the sum of the Lengths of
-        /// <see cref="ContinuousActions"/> and <see cref="DiscreteActions"/>.
-        /// </summary>
-        /// <param name="destination">A float array to pack actions into whose length is greater than or
-        /// equal to the addition of the Lengths of this objects <see cref="ContinuousActions"/> and
-        /// <see cref="DiscreteActions"/> segments.</param>
-        [Obsolete("PackActions has been deprecated.")]
-        public void PackActions(in float[] destination)
-        {
-            Debug.Assert(destination.Length >= ContinuousActions.Length + DiscreteActions.Length,
-                $"argument '{nameof(destination)}' is not large enough to pack the actions into.\n" +
-                $"{nameof(destination)}.Length: {destination.Length}\n" +
-                $"{nameof(ContinuousActions)}.Length + {nameof(DiscreteActions)}.Length: {ContinuousActions.Length + DiscreteActions.Length}");
-
-            var start = 0;
-            if (ContinuousActions.Length > 0)
-            {
-                Array.Copy(ContinuousActions.Array,
-                    ContinuousActions.Offset,
-                    destination,
-                    start,
-                    ContinuousActions.Length);
-                start = ContinuousActions.Length;
-            }
-            if (start >= destination.Length)
-            {
-                return;
-            }
-
-            if (DiscreteActions.Length > 0)
-            {
-                Array.Copy(DiscreteActions.Array,
-                    DiscreteActions.Offset,
-                    destination,
-                    start,
-                    DiscreteActions.Length);
-            }
-        }
     }
 
     /// <summary>

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

@@ -301,9 +301,6 @@ internal struct AgentParameters
         /// Whether or not the Agent has been initialized already
         bool m_Initialized;
 
-        /// Keeps track of the actions that are masked at each step.
-        DiscreteActionMasker m_ActionMasker;
-
         /// <summary>
         /// Set of DemonstrationWriters that the Agent will write its step information to.
         /// If you use a DemonstrationRecorder component, this will automatically register its DemonstrationWriter.
@@ -338,17 +335,6 @@ internal struct AgentParameters
         /// </summary>
         IActuator m_VectorActuator;
 
-        /// <summary>
-        /// This is used to avoid allocation of a float array every frame if users are still using the old
-        /// OnActionReceived method.
-        /// </summary>
-        float[] m_LegacyActionCache;
-
-        /// <summary>
-        /// This is used to avoid allocation of a float array during legacy calls to Heuristic.
-        /// </summary>
-        float[] m_LegacyHeuristicCache;
-
         /// Currect MultiAgentGroup ID. Default to 0 (meaning no group)
         int m_GroupId;
 
@@ -952,29 +938,7 @@ public virtual void Initialize() { }
         /// <seealso cref="IActionReceiver.OnActionReceived"/>
         public virtual void Heuristic(in ActionBuffers actionsOut)
         {
-            // Disable deprecation warnings so we can call the legacy overload.
-#pragma warning disable CS0618
-
-            // The default implementation of Heuristic calls the
-            // obsolete version for backward compatibility
-            switch (m_PolicyFactory.BrainParameters.VectorActionSpaceType)
-            {
-                case SpaceType.Continuous:
-                    Heuristic(m_LegacyHeuristicCache);
-                    Array.Copy(m_LegacyHeuristicCache, actionsOut.ContinuousActions.Array, m_LegacyActionCache.Length);
-                    actionsOut.DiscreteActions.Clear();
-                    break;
-                case SpaceType.Discrete:
-                    Heuristic(m_LegacyHeuristicCache);
-                    var discreteActionSegment = actionsOut.DiscreteActions;
-                    for (var i = 0; i < actionsOut.DiscreteActions.Length; i++)
-                    {
-                        discreteActionSegment[i] = (int)m_LegacyHeuristicCache[i];
-                    }
-                    actionsOut.ContinuousActions.Clear();
-                    break;
-            }
-#pragma warning restore CS0618
+            Debug.LogWarning("Heuristic method called but not implemented. Returning placeholder actions.");
         }
 
         /// <summary>
@@ -1064,8 +1028,6 @@ void InitializeActuators()
             var param = m_PolicyFactory.BrainParameters;
             m_VectorActuator = new AgentVectorActuator(this, this, param.ActionSpec);
             m_ActuatorManager = new ActuatorManager(attachedActuators.Length + 1);
-            m_LegacyActionCache = new float[m_VectorActuator.TotalNumberOfActions()];
-            m_LegacyHeuristicCache = new float[m_VectorActuator.TotalNumberOfActions()];
 
             m_ActuatorManager.Add(m_VectorActuator);
 
@@ -1223,17 +1185,7 @@ public ReadOnlyCollection<float> GetObservations()
         /// [Agents - Actions]: https://github.com/Unity-Technologies/ml-agents/blob/release_13_docs/docs/Learning-Environment-Design-Agents.md#actions
         /// </remarks>
         /// <seealso cref="IActionReceiver.OnActionReceived"/>
-        public virtual void WriteDiscreteActionMask(IDiscreteActionMask actionMask)
-        {
-            if (m_ActionMasker == null)
-            {
-                m_ActionMasker = new DiscreteActionMasker(actionMask);
-            }
-            // Disable deprecation warnings so we can call the legacy overload.
-#pragma warning disable CS0618
-            CollectDiscreteActionMasks(m_ActionMasker);
-#pragma warning restore CS0618
-        }
+        public virtual void WriteDiscreteActionMask(IDiscreteActionMask actionMask) { }
 
         /// <summary>
         /// Implement `OnActionReceived()` to specify agent behavior at every step, based
@@ -1301,34 +1253,7 @@ public virtual void WriteDiscreteActionMask(IDiscreteActionMask actionMask)
         /// <param name="actions">
         /// Struct containing the buffers of actions to be executed at this step.
         /// </param>
-        public virtual void OnActionReceived(ActionBuffers actions)
-        {
-            var actionSpec = m_PolicyFactory.BrainParameters.ActionSpec;
-            // For continuous and discrete actions together, we don't need to fall back to the legacy method
-            if (actionSpec.NumContinuousActions > 0 && actionSpec.NumDiscreteActions > 0)
-            {
-                // Nothing implemented.
-                return;
-            }
-
-            if (!actions.ContinuousActions.IsEmpty())
-            {
-                Array.Copy(actions.ContinuousActions.Array,
-                    m_LegacyActionCache,
-                    actionSpec.NumContinuousActions);
-            }
-            else
-            {
-                for (var i = 0; i < m_LegacyActionCache.Length; i++)
-                {
-                    m_LegacyActionCache[i] = (float)actions.DiscreteActions[i];
-                }
-            }
-            // Disable deprecation warnings so we can call the legacy overload.
-#pragma warning disable CS0618
-            OnActionReceived(m_LegacyActionCache);
-#pragma warning restore CS0618
-        }
+        public virtual void OnActionReceived(ActionBuffers actions) { }
 
         /// <summary>
         /// Implement `OnEpisodeBegin()` to set up an Agent instance at the beginning