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

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

         /// 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

     public class Match3ExampleActuatorComponent : Match3ActuatorComponent
     {
         /// <inheritdoc/>
-#pragma warning disable 672
-        public override IActuator CreateActuator()
-#pragma warning restore 672
+        public override IActuator[] CreateActuators()
-            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

             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

         public bool ForceHeuristic;
 
         /// <inheritdoc/>
-#pragma warning disable 672
-        public override IActuator CreateActuator()
-#pragma warning restore 672
+        public override IActuator[] CreateActuators()
-            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

 ## [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)
 
 ### Minor Changes

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

     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>
-        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

                 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

         /// 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.
         /// with the current behavior of Agent.
         /// </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;
         /// <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>
             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);
 
         /// [Agents - Actions]: https://github.com/Unity-Technologies/ml-agents/blob/release_15_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
         /// <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

com.unity.ml-agents/Runtime/Policies/BrainParameters.cs

         internal bool hasUpgradedBrainParametersWithActionSpec;
 
         /// <summary>
-        /// (Deprecated) The number of actions specified by this Brain.
-        /// </summary>
-        [Obsolete("NumActions has been deprecated, please use ActionSpec instead.")]
-        public int NumActions
-        {
-            get
-            {
-                return ActionSpec.NumContinuousActions > 0 ? ActionSpec.NumContinuousActions : ActionSpec.NumDiscreteActions;
-            }
-        }
-
-        /// <summary>
         /// Deep clones the BrainParameter object.
         /// </summary>
         /// <returns> A new BrainParameter object with the same values as the original.</returns>

com.unity.ml-agents/Runtime/Sensors/ObservationWriter.cs

         }
 
         /// <summary>
-        /// Write the range of floats
-        /// </summary>
-        /// <param name="data"></param>
-        /// <param name="writeOffset">Optional write offset.</param>
-        [Obsolete("Use AddList() for better performance")]
-        public void AddRange(IEnumerable<float> data, int writeOffset = 0)
-        {
-            if (m_Data != null)
-            {
-                int index = 0;
-                foreach (var val in data)
-                {
-                    m_Data[index + m_Offset + writeOffset] = val;
-                    index++;
-                }
-            }
-            else
-            {
-                int index = 0;
-                foreach (var val in data)
-                {
-                    m_Proxy.data[m_Batch, index + m_Offset + writeOffset] = val;
-                    index++;
-                }
-            }
-        }
-
-        /// <summary>
         /// Write the list of floats.
         /// </summary>
         /// <param name="data">The actual list of floats to write.</param>

com.unity.ml-agents/Runtime/Sensors/SensorComponent.cs

         /// <returns>Shape of the sensor observation.</returns>
         public abstract int[] GetObservationShape();
 
-        /// <summary>
-        /// Whether the observation is visual or not.
-        /// </summary>
-        /// <returns>True if the observation is visual, false otherwise.</returns>
-        [Obsolete("IsVisual is deprecated, please use GetObservationShape() instead.")]
-        public virtual bool IsVisual()
-        {
-            var shape = GetObservationShape();
-            return shape.Length == 3;
-        }
-
-        /// <summary>
-        /// Whether the observation is vector or not.
-        /// </summary>
-        /// <returns>True if the observation is vector, false otherwise.</returns>
-        [Obsolete("IsVisual is deprecated, please use GetObservationShape() instead.")]
-        public virtual bool IsVector()
-        {
-            var shape = GetObservationShape();
-            return shape.Length == 1;
-        }
     }
 }

com.unity.ml-agents/Runtime/Sensors/VectorSensor.cs

         }
 
         /// <summary>
-        /// Adds a collection of float observations to the vector observations of the agent.
-        /// </summary>
-        /// <param name="observation">Observation.</param>
-        [Obsolete("Use AddObservation(IList<float>) for better performance.")]
-        public void AddObservation(IEnumerable<float> observation)
-        {
-            foreach (var f in observation)
-            {
-                AddFloatObs(f);
-            }
-        }
-
-        /// <summary>
         /// Adds a list or array of float observations to the vector observations of the agent.
         /// </summary>
         /// <param name="observation">Observation.</param>

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

             }
         }
     }
-
-    /// <summary>
-    /// Deprecated, use <see cref="SideChannelManager"/> instead.
-    /// </summary>
-    [Obsolete("Use SideChannelManager instead.")]
-    public static class SideChannelsManager
-    {
-        /// <summary>
-        /// Deprecated, use <see cref="SideChannelManager.RegisterSideChannel"/> instead.
-        /// </summary>
-        /// <param name="sideChannel"></param>
-        public static void RegisterSideChannel(SideChannel sideChannel)
-        {
-            SideChannelManager.RegisterSideChannel(sideChannel);
-        }
-
-        /// <summary>
-        /// Deprecated, use <see cref="SideChannelManager.UnregisterSideChannel"/> instead.
-        /// </summary>
-        /// <param name="sideChannel"></param>
-        public static void UnregisterSideChannel(SideChannel sideChannel)
-        {
-            SideChannelManager.UnregisterSideChannel(sideChannel);
-        }
-    }
 }

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

             Assert.AreEqual(numSteps, agent1.sensor1.numWriteCalls);
             Assert.AreEqual(numSteps, agent1.sensor2.numCompressedCalls);
 
-            // Disable deprecation warnings so we can read/write the old fields.
-#pragma warning disable CS0618
-
-            // Make sure the Heuristic method read the observation and set the action
-            Assert.AreEqual(agent1.collectObservationsCallsForEpisode, agent1.GetAction()[0]);
-#pragma warning restore CS0618
         }
     }
 

docs/Learning-Environment-Design-Agents.md

 The Actuator API allows users to abstract behavior out of Agents and in to
 components (similar to the ISensor API).  The `IActuator` interface and `Agent`
 class both implement the `IActionReceiver` interface to allow for backward compatibility
-with the current `Agent.OnActionReceived` and `Agent.CollectDiscreteActionMasks` APIs.
+with the current `Agent.OnActionReceived`.
 This means you will not have to change your code until you decide to use the `IActuator` API.
 
 Like the `ISensor` interface, the `IActuator` interface is intended for advanced users.

docs/Migrating.md

 
 
 # Migrating
+## Migrating the package to version 2.0
+- If you used any of the APIs that were deprecated before version 2.0, you need to use their replacement. These deprecated APIs have been removed. See the migration steps bellow for specific API replacements.
+
 ## Migrating to Release 13
 ### Implementing IHeuristic in your IActuator implementations
  - If you have any custom actuators, you can now implement the `IHeuristicProvider` interface to have your actuator

com.unity.ml-agents/Runtime/DiscreteActionMasker.cs.meta

-fileFormatVersion: 2
-guid: 8a0ec4ccf4ee450da7766f65228d5460
-timeCreated: 1534530911

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

-fileFormatVersion: 2
-guid: 9650a482703b47db8cd7fb2df8caa1bf
-timeCreated: 1595613441

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

-using System;
-using UnityEngine;
-using UnityEngine.Profiling;
-
-namespace Unity.MLAgents
-{
-    public partial class Agent
-    {
-        /// <summary>
-        /// Deprecated, use <see cref="WriteDiscreteActionMask"/> instead.
-        /// </summary>
-        /// <param name="actionMasker"></param>
-        [Obsolete("CollectDiscreteActionMasks has been deprecated, please use WriteDiscreteActionMask.")]
-        public virtual void CollectDiscreteActionMasks(DiscreteActionMasker actionMasker)
-        {
-        }
-
-        /// <summary>
-        /// Deprecated, use <see cref="Heuristic(in Actuators.ActionBuffers)"/> instead.
-        /// </summary>
-        /// <param name="actionsOut"></param>
-        [Obsolete("The float[] version of Heuristic has been deprecated, please use the ActionBuffers version instead.")]
-        public virtual void Heuristic(float[] actionsOut)
-        {
-            Debug.LogWarning("Heuristic method called but not implemented. Returning placeholder actions.");
-            Array.Clear(actionsOut, 0, actionsOut.Length);
-        }
-
-        /// <summary>
-        /// Deprecated, use <see cref="OnActionReceived(Actuators.ActionBuffers)"/> instead.
-        /// </summary>
-        /// <param name="vectorAction"></param>
-        [Obsolete("The float[] version of OnActionReceived has been deprecated, please use the ActionBuffers version instead.")]
-        public virtual void OnActionReceived(float[] vectorAction) { }
-
-        /// <summary>
-        /// Returns the last action that was decided on by the Agent.
-        /// </summary>
-        /// <returns>
-        /// The last action that was decided by the Agent (or null if no decision has been made).
-        /// </returns>
-        /// <seealso cref="OnActionReceived(ActionBuffers)"/>
-        [Obsolete("GetAction has been deprecated, please use GetStoredActionBuffers instead.")]
-        public float[] GetAction()
-        {
-            Profiler.BeginSample("Agent.GetAction.Deprecated");
-            var actionSpec = m_PolicyFactory.BrainParameters.ActionSpec;
-            // For continuous and discrete actions together, this shouldn't be called because we can only return one.
-            if (actionSpec.NumContinuousActions > 0 && actionSpec.NumDiscreteActions > 0)
-            {
-                Debug.LogWarning("Agent.GetAction() when both continuous and discrete actions are in use. Use Agent.GetStoredActionBuffers() instead.");
-            }
-
-            var storedAction = m_Info.storedActions;
-            if (!storedAction.ContinuousActions.IsEmpty())
-            {
-                return storedAction.ContinuousActions.Array;
-            }
-            Profiler.EndSample();
-            return Array.ConvertAll(storedAction.DiscreteActions.Array, x => (float)x);
-        }
-    }
-}

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

-using System.Collections.Generic;
-using Unity.MLAgents.Actuators;
-
-namespace Unity.MLAgents
-{
-    /// <summary>
-    /// The DiscreteActionMasker class represents a set of masked (disallowed) actions and
-    /// provides utilities for setting and retrieving them.
-    /// </summary>
-    /// <remarks>
-    /// Agents that take discrete actions can explicitly indicate that specific actions
-    /// are not allowed at a point in time. This enables the agent to indicate that some actions
-    /// may be illegal. For example, if an agent is adjacent to a wall or other obstacle
-    /// you could mask any actions that direct the agent to move into the blocked space.
-    /// </remarks>
-    public class DiscreteActionMasker : IDiscreteActionMask
-    {
-        IDiscreteActionMask m_Delegate;
-
-        internal DiscreteActionMasker(IDiscreteActionMask actionMask)
-        {
-            m_Delegate = actionMask;
-        }
-
-        /// <summary>
-        /// Modifies an action mask for discrete control agents.
-        /// </summary>
-        /// <remarks>
-        /// When used, the agent will not be able to perform the actions passed as argument
-        /// at the next decision for the specified action branch. The actionIndices correspond
-        /// to the action options the agent will be unable to perform.
-        ///
-        /// See [Agents - Actions] for more information on masking actions.
-        ///
-        /// [Agents - Actions]: https://github.com/Unity-Technologies/ml-agents/blob/release_15_docs/docs/Learning-Environment-Design-Agents.md#actions
-        /// </remarks>
-        /// <param name="branch">The branch for which the actions will be masked.</param>
-        /// <param name="actionIndices">The indices of the masked actions.</param>
-        public void SetMask(int branch, IEnumerable<int> actionIndices)
-        {
-            m_Delegate.WriteMask(branch, actionIndices);
-        }
-
-        /// <inheritdoc />
-        public void WriteMask(int branch, IEnumerable<int> actionIndices)
-        {
-            m_Delegate.WriteMask(branch, actionIndices);
-        }
-
-        /// <inheritdoc />
-        public bool[] GetMask()
-        {
-            return m_Delegate.GetMask();
-        }
-
-        /// <inheritdoc />
-        public void ResetMask()
-        {
-            m_Delegate.ResetMask();
-        }
-    }
-}