Add internal API for Actuators along with their tests. (#4297)

Author: surfnerd

Project/ProjectSettings/ProjectVersion.txt

@@ -1 +1 @@
-m_EditorVersion: 2018.4.17f1
+m_EditorVersion: 2018.4.24f1

com.unity.ml-agents/Runtime/Actuators.meta

@@ -0,0 +1,181 @@
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Diagnostics;
+
+namespace Unity.MLAgents.Actuators
+{
+    /// <summary>
+    /// ActionSegment{T} is a data structure that allows access to a segment of an underlying array
+    /// in order to avoid the copying and allocation of sub-arrays.  The segment is defined by
+    /// the offset into the original array, and an length.
+    /// </summary>
+    /// <typeparam name="T">The type of object stored in the underlying <see cref="Array"/></typeparam>
+    internal readonly struct ActionSegment<T> : IEnumerable<T>, IEquatable<ActionSegment<T>>
+        where T : struct
+    {
+        /// <summary>
+        /// The zero-based offset into the original array at which this segment starts.
+        /// </summary>
+        public readonly int Offset;
+
+        /// <summary>
+        /// The number of items this segment can access in the underlying array.
+        /// </summary>
+        public readonly int Length;
+
+        /// <summary>
+        /// An Empty segment which has an offset of 0, a Length of 0, and it's underlying array
+        /// is also empty.
+        /// </summary>
+        public static ActionSegment<T> Empty = new ActionSegment<T>(System.Array.Empty<T>(), 0, 0);
+
+        static void CheckParameters(T[] actionArray, int offset, int length)
+        {
+#if DEBUG
+            if (offset + length > actionArray.Length)
+            {
+                throw new ArgumentOutOfRangeException(nameof(offset),
+                    $"Arguments offset: {offset} and length: {length} " +
+                    $"are out of bounds of actionArray: {actionArray.Length}.");
+            }
+#endif
+        }
+
+        /// <summary>
+        /// Construct an <see cref="ActionSegment{T}"/> with an underlying array
+        /// and offset, and a length.
+        /// </summary>
+        /// <param name="actionArray">The underlying array which this segment has a view into</param>
+        /// <param name="offset">The zero-based offset into the underlying array.</param>
+        /// <param name="length">The length of the segment.</param>
+        public ActionSegment(T[] actionArray, int offset, int length)
+        {
+            CheckParameters(actionArray, offset, length);
+            Array = actionArray;
+            Offset = offset;
+            Length = length;
+        }
+
+        /// <summary>
+        /// Get the underlying <see cref="Array"/> of this segment.
+        /// </summary>
+        public T[] Array { get; }
+
+        /// <summary>
+        /// Allows access to the underlying array using array syntax.
+        /// </summary>
+        /// <param name="index">The zero-based index of the segment.</param>
+        /// <exception cref="IndexOutOfRangeException">Thrown when the index is less than 0 or
+        /// greater than or equal to <see cref="Length"/></exception>
+        public T this[int index]
+        {
+            get
+            {
+                if (index < 0 || index > Length)
+                {
+                    throw new IndexOutOfRangeException($"Index out of bounds, expected a number between 0 and {Length}");
+                }
+                return Array[Offset + index];
+            }
+        }
+
+        /// <inheritdoc cref="IEnumerable{T}.GetEnumerator"/>
+        IEnumerator<T> IEnumerable<T>.GetEnumerator()
+        {
+            return new Enumerator(this);
+        }
+
+        /// <inheritdoc cref="IEnumerable{T}"/>
+        public IEnumerator GetEnumerator()
+        {
+            return new Enumerator(this);
+        }
+
+        /// <inheritdoc cref="ValueType.Equals(object)"/>
+        public override bool Equals(object obj)
+        {
+            if (!(obj is ActionSegment<T>))
+            {
+                return false;
+            }
+            return Equals((ActionSegment<T>)obj);
+        }
+
+        /// <inheritdoc cref="IEquatable{T}.Equals(T)"/>
+        public bool Equals(ActionSegment<T> other)
+        {
+            return Offset == other.Offset && Length == other.Length && Equals(Array, other.Array);
+        }
+
+        /// <inheritdoc cref="ValueType.GetHashCode"/>
+        public override int GetHashCode()
+        {
+            unchecked
+            {
+                var hashCode = Offset;
+                hashCode = (hashCode * 397) ^ Length;
+                hashCode = (hashCode * 397) ^ (Array != null ? Array.GetHashCode() : 0);
+                return hashCode;
+            }
+        }
+
+        /// <summary>
+        /// A private <see cref="IEnumerator{T}"/> for the <see cref="ActionSegment{T}"/> value type which follows its
+        /// rules of being a view into an underlying <see cref="Array"/>.
+        /// </summary>
+        struct Enumerator : IEnumerator<T>
+        {
+            readonly T[] m_Array;
+            readonly int m_Start;
+            readonly int m_End; // cache Offset + Count, since it's a little slow
+            int m_Current;
+
+            internal Enumerator(ActionSegment<T> arraySegment)
+            {
+                Debug.Assert(arraySegment.Array != null);
+                Debug.Assert(arraySegment.Offset >= 0);
+                Debug.Assert(arraySegment.Length >= 0);
+                Debug.Assert(arraySegment.Offset + arraySegment.Length <= arraySegment.Array.Length);
+
+                m_Array = arraySegment.Array;
+                m_Start = arraySegment.Offset;
+                m_End = arraySegment.Offset + arraySegment.Length;
+                m_Current = arraySegment.Offset - 1;
+            }
+
+            public bool MoveNext()
+            {
+                if (m_Current < m_End)
+                {
+                    m_Current++;
+                    return m_Current < m_End;
+                }
+                return false;
+            }
+
+            public T Current
+            {
+                get
+                {
+                    if (m_Current < m_Start)
+                        throw new InvalidOperationException("Enumerator not started.");
+                    if (m_Current >= m_End)
+                        throw new InvalidOperationException("Enumerator has reached the end already.");
+                    return m_Array[m_Current];
+                }
+            }
+
+            object IEnumerator.Current => Current;
+
+            void IEnumerator.Reset()
+            {
+                m_Current = m_Start - 1;
+            }
+
+            public void Dispose()
+            {
+            }
+        }
+    }
+}

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

@@ -0,0 +1,75 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Unity.MLAgents.Policies;
+
+namespace Unity.MLAgents.Actuators
+{
+    /// <summary>
+    /// Defines the structure of an Action Space to be used by the Actuator system.
+    /// </summary>
+    internal readonly struct ActionSpec
+    {
+
+        /// <summary>
+        /// An array of branch sizes for our action space.
+        ///
+        /// For an IActuator that uses a Discrete <see cref="SpaceType"/>, the number of
+        /// branches is the Length of the Array and each index contains the branch size.
+        /// The cumulative sum of the total number of discrete actions can be retrieved
+        /// by the <see cref="SumOfDiscreteBranchSizes"/> property.
+        ///
+        /// For an IActuator with a Continuous it will be null.
+        /// </summary>
+        public readonly int[] BranchSizes;
+
+        /// <summary>
+        /// The number of actions for a Continuous <see cref="SpaceType"/>.
+        /// </summary>
+        public int NumContinuousActions { get; }
+
+        /// <summary>
+        /// The number of branches for a Discrete <see cref="SpaceType"/>.
+        /// </summary>
+        public int NumDiscreteActions { get; }
+
+        /// <summary>
+        /// Get the total number of Discrete Actions that can be taken by calculating the Sum
+        /// of all of the Discrete Action branch sizes.
+        /// </summary>
+        public int SumOfDiscreteBranchSizes { get; }
+
+        /// <summary>
+        /// Creates a Continuous <see cref="ActionSpec"/> with the number of actions available.
+        /// </summary>
+        /// <param name="numActions">The number of actions available.</param>
+        /// <returns>An Continuous ActionSpec initialized with the number of actions available.</returns>
+        public static ActionSpec MakeContinuous(int numActions)
+        {
+            var actuatorSpace = new ActionSpec(numActions, 0);
+            return actuatorSpace;
+        }
+
+        /// <summary>
+        /// Creates a Discrete <see cref="ActionSpec"/> with the array of branch sizes that
+        /// represents the action space.
+        /// </summary>
+        /// <param name="branchSizes">The array of branch sizes for the discrete action space.  Each index
+        /// contains the number of actions available for that branch.</param>
+        /// <returns>An Discrete ActionSpec initialized with the array of branch sizes.</returns>
+        public static ActionSpec MakeDiscrete(int[] branchSizes)
+        {
+            var numActions = branchSizes.Length;
+            var actuatorSpace = new ActionSpec(0, numActions, branchSizes);
+            return actuatorSpace;
+        }
+
+        ActionSpec(int numContinuousActions, int numDiscreteActions, int[] branchSizes = null)
+        {
+            NumContinuousActions = numContinuousActions;
+            NumDiscreteActions = numDiscreteActions;
+            BranchSizes =  branchSizes;
+            SumOfDiscreteBranchSizes = branchSizes?.Sum() ?? 0;
+        }
+    }
+}

com.unity.ml-agents/Runtime/Actuators/ActionSegment.cs.meta

@@ -0,0 +1,17 @@
+using UnityEngine;
+
+namespace Unity.MLAgents.Actuators
+{
+    /// <summary>
+    /// Editor components for creating Actuators. Generally an IActuator component should
+    /// have a corresponding ActuatorComponent.
+    /// </summary>
+    internal abstract class ActuatorComponent : MonoBehaviour
+    {
+        /// <summary>
+        /// Create the IActuator.  This is called by the Agent when it is initialized.
+        /// </summary>
+        /// <returns>Created IActuator object.</returns>
+        public abstract IActuator CreateActuator();
+    }
+}