More APIs refactoring

Author: Sergio0694

NeuralNetwork.NET/APIs/Structs/Tensor.cs

@@ -16,6 +16,8 @@ namespace NeuralNetworkNET.APIs.Structs
     [DebuggerDisplay("Entities: {Entities}, Length: {Length}, Ptr: {Ptr}")]
     public readonly struct Tensor
     {
+        #region Fields and parameters
+
         /// <summary>
         /// The <see cref="IntPtr"/> value to the allocated memory
         /// </summary>
@@ -51,6 +53,8 @@ public bool IsNull
             get => Ptr == IntPtr.Zero;
         }
 
+        #endregion
+
         /// <summary>
         /// Gets a null instance
         /// </summary>
@@ -109,6 +113,20 @@ public static unsafe void Reshape(float* p, int n, int chw, out Tensor tensor)
             tensor = new Tensor(ptr, n, chw);
         }
 
+        /// <summary>
+        /// Creates a new instance with the same shape as the input <see cref="Tensor"/>
+        /// </summary>
+        /// <param name="mask">The <see cref="Tensor"/> to use to copy the shape</param>
+        /// <param name="tensor">The output <see cref="Tensor"/></param>
+        public static void Like(in Tensor mask, out Tensor tensor) => New(mask.Entities, mask.Length, out tensor);
+
+        /// <summary>
+        /// Creates a new instance with the same shape as the input <see cref="Tensor"/> and all the values initializes to 0
+        /// </summary>
+        /// <param name="mask">The <see cref="Tensor"/> to use to copy the shape</param>
+        /// <param name="tensor">The output <see cref="Tensor"/></param>
+        public static void LikeZeroed(in Tensor mask, out Tensor tensor) => NewZeroed(mask.Entities, mask.Length, out tensor);
+
         /// <summary>
         /// Creates a new instance by copying the contents at the given memory location and reshaping it to the desired size
         /// </summary>
@@ -155,6 +173,34 @@ public static unsafe void From([NotNull] float[] v, int n, int chw, out Tensor t
 
         #region Tools
 
+        /// <summary>
+        /// Creates a new instance by wrapping the current memory area
+        /// </summary>
+        /// <param name="n">The height of the final matrix</param>
+        /// <param name="chw">The width of the final matrix</param>
+        /// <param name="tensor">The resulting instance</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void Reshape(int n, int chw, out Tensor tensor)
+        {
+            if (n * chw != Size) throw new ArgumentException("Invalid input resized shape");
+            tensor = new Tensor(Ptr, n, chw);
+        }
+
+        /// <summary>
+        /// Checks whether or not the current instance has the same shape of the input <see cref="Tensor"/>
+        /// </summary>
+        /// <param name="tensor">The instance to compare</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public bool MatchShape(in Tensor tensor) => Entities == tensor.Entities && Length == tensor.Length;
+
+        /// <summary>
+        /// Checks whether or not the current instance has the same shape as the input arguments
+        /// </summary>
+        /// <param name="entities">The expected number of entities</param>
+        /// <param name="length">The expected length of each entity</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public bool MatchShape(int entities, int length) => Entities == entities && Length == length;
+
         /// <summary>
         /// Overwrites the contents of the current matrix with the input matrix
         /// </summary>
@@ -181,58 +227,36 @@ internal void Duplicate(out Tensor tensor)
         /// <summary>
         /// Copies the contents of the unmanaged array to a managed <see cref="Array"/>
         /// </summary>
+        /// <param name="keepAlive">Indicates whether or not to automatically dispose the current instance</param>
         [Pure, NotNull]
-        public float[] ToArray()
+        public float[] ToArray(bool keepAlive = true)
         {
             if (Ptr == IntPtr.Zero) return new float[0];
             float[] result = new float[Size];
             Marshal.Copy(Ptr, result, 0, Size);
+            if (keepAlive) Free();
             return result;
         }
 
         /// <summary>
         /// Copies the contents of the unmanaged array to a managed 2D <see cref="Array"/>
         /// </summary>
+        /// <param name="keepAlive">Indicates whether or not to automatically dispose the current instance</param>
         [Pure, NotNull]
-        public unsafe float[,] ToArray2D()
+        public unsafe float[,] ToArray2D(bool keepAlive = true)
         {
             if (Ptr == IntPtr.Zero) return new float[0, 0];
             float[,] result = new float[Entities, Length];
             int size = sizeof(float) * Size;
             fixed (float* presult = result)
                 Buffer.MemoryCopy(this, presult, size, size);
+            if (keepAlive) Free();
             return result;
         }
 
         #endregion
 
-        /// <summary>
-        /// Creates a new instance by wrapping the current memory area
-        /// </summary>
-        /// <param name="n">The height of the final matrix</param>
-        /// <param name="chw">The width of the final matrix</param>
-        /// <param name="tensor">The resulting instance</param>
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public void Reshape(int n, int chw, out Tensor tensor)
-        {
-            if (n * chw != Size) throw new ArgumentException("Invalid input resized shape");
-            tensor = new Tensor(Ptr, n, chw);
-        }
-
-        /// <summary>
-        /// Checks whether or not the current instance has the same shape of the input <see cref="Tensor"/>
-        /// </summary>
-        /// <param name="tensor">The instance to compare</param>
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public bool MatchShape(in Tensor tensor) => Entities == tensor.Entities && Length == tensor.Length;
-
-        /// <summary>
-        /// Checks whether or not the current instance has the same shape as the input arguments
-        /// </summary>
-        /// <param name="entities">The expected number of entities</param>
-        /// <param name="length">The expected length of each entity</param>
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public bool MatchShape(int entities, int length) => Entities == entities && Length == length;
+        #region Memory management
 
         /// <summary>
         /// Frees the memory associated with the current instance
@@ -252,8 +276,11 @@ public void TryFree()
 
         // Implicit pointer conversion
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        [SuppressMessage("ReSharper", "ImpureMethodCallOnReadonlyValueField")]
         public static unsafe implicit operator float*(in Tensor tensor) => (float*)tensor.Ptr.ToPointer();
 
+        #endregion
+
         #region Debug
 
         /// <summary>

NeuralNetwork.NET/Extensions/MatrixExtensions.cs

@@ -1,6 +1,5 @@
 using System;
 using System.Collections.Generic;
-using System.Linq;
 using System.Runtime.InteropServices;
 using System.Text;
 using System.Threading.Tasks;
@@ -53,33 +52,6 @@ void NormalizationKernel(int i)
 
         #region Misc
 
-        /// <summary>
-        /// Calculates the position and the value of the biggest item in a matrix
-        /// </summary>
-        /// <param name="m">The input matrix</param>
-        internal static (int x, int y, float value) Max([NotNull] this float[,] m)
-        {
-            // Checks and local variables setup
-            if (m.Length == 0) throw new ArgumentOutOfRangeException("The input matrix can't be empty");
-            if (m.Length == 1) return (0, 0, m[0, 0]);
-            int
-                h = m.GetLength(0),
-                w = m.GetLength(1),
-                x = 0, y = 0;
-            float max = float.MinValue;
-
-            // Find the maximum value and its position
-            for (int i = 0; i < h; i++)
-                for (int j = 0; j < w; j++)
-                {
-                    if (!(m[i, j] > max)) continue;
-                    max = m[i, j];
-                    x = i;
-                    y = j;
-                }
-            return (x, y, max);
-        }
-
         /// <summary>
         /// Finds the minimum and maximum value in the input memory area
         /// </summary>
@@ -115,33 +87,6 @@ internal static unsafe (float Min, float Max) MinMax(float* p, int length)
             return m;
         }
 
-        /// <summary>
-        /// Flattens the input volume in a linear array
-        /// </summary>
-        /// <param name="volume">The volume to flatten</param>
-        [PublicAPI]
-        [Pure, NotNull]
-        [CollectionAccess(CollectionAccessType.Read)]
-        public static float[] Flatten([NotNull, ItemNotNull] this IReadOnlyList<float[,]> volume)
-        {
-            // Preliminary checks and declarations
-            if (volume.Count == 0) throw new ArgumentOutOfRangeException("The input volume can't be empty");
-            int
-                depth = volume.Count,
-                length = volume[0].Length,
-                bytes = sizeof(float) * length;
-            float[] result = new float[depth * length];
-
-            // Execute the copy in parallel
-            bool loopResult = Parallel.For(0, depth, i =>
-            {
-                // Copy the volume data
-                Buffer.BlockCopy(volume[i], 0, result, bytes * i, bytes);
-            }).IsCompleted;
-            if (!loopResult) throw new Exception("Error while runnig the parallel loop");
-            return result;
-        }
-
         /// <summary>
         /// Merges the input samples into a matrix dataset
         /// </summary>
@@ -167,42 +112,12 @@ public static (float[,], float[,]) MergeRows([NotNull] this IReadOnlyList<(float
             return (x, y);
         }
 
-        /// <summary>
-        /// Merges the rows of the input matrices into a single matrix
-        /// </summary>
-        /// <param name="blocks">The matrices to merge</param>
-        [PublicAPI]
-        [Pure, NotNull]
-        [CollectionAccess(CollectionAccessType.Read)]
-        public static float[,] MergeRows([NotNull, ItemNotNull] this IReadOnlyList<float[,]> blocks)
-        {
-            // Preliminary checks and declarations
-            if (blocks.Count == 0) throw new ArgumentOutOfRangeException("The blocks list can't be empty");
-            int
-                h = blocks.Sum(b => b.GetLength(0)),
-                w = blocks[0].GetLength(1),
-                rowBytes = sizeof(float) * w;
-            float[,] result = new float[h, w];
-
-            // Execute the copy in parallel
-            int position = 0;
-            for (int i = 0; i < blocks.Count; i++)
-            {
-                float[,] next = blocks[i];
-                if (next.GetLength(1) != w) throw new ArgumentOutOfRangeException("The blocks must all have the same width");
-                int rows = next.GetLength(0);
-                Buffer.BlockCopy(next, 0, result, rowBytes * position, rowBytes * rows);
-                position += rows;
-            }
-            return result;
-        }
-
         #endregion
 
         #region Argmax
 
         /// <summary>
-        /// Returns the index of the maximum value in the input vector
+        /// Returns the index of the maximum value in the input memory area
         /// </summary>
         /// <param name="p">A pointer to the buffer to read</param>
         /// <param name="length">The length of the buffer to consider</param>
@@ -223,10 +138,19 @@ internal static unsafe int Argmax(float* p, int length)
             return index;
         }
 
+        /// <summary>
+        /// Returns the index of the maximum value in the input tensor
+        /// </summary>
+        /// <param name="tensor">The input <see cref="Tensor"/> to read from</param>
+        [PublicAPI]
+        [CollectionAccess(CollectionAccessType.Read)]
+        public static unsafe int Argmax(in this Tensor tensor) => Argmax(tensor, tensor.Size);
+
         /// <summary>
         /// Returns the index of the maximum value in the input vector
         /// </summary>
         /// <param name="v">The input vector to read from</param>
+        [PublicAPI]
         [CollectionAccess(CollectionAccessType.Read)]
         public static unsafe int Argmax([NotNull] this float[] v)
         {
@@ -237,6 +161,7 @@ public static unsafe int Argmax([NotNull] this float[] v)
         /// Returns the index of the maximum value in the input matrix
         /// </summary>
         /// <param name="m">The input matrix to read from</param>
+        [PublicAPI]
         [CollectionAccess(CollectionAccessType.Read)]
         public static unsafe int Argmax([NotNull] this float[,] m)
         {
@@ -295,7 +220,7 @@ internal static unsafe void Fill([NotNull] this Array array, [NotNull] Func<floa
         /// Returns a deep copy of the input vector
         /// </summary>
         /// <param name="v">The vector to clone</param>
-        /// <remarks>This method avoids the boxing of the <see cref="Array.Clone"/> method, and it is faster thanks to <see cref="Buffer.MemoryCopy"/></remarks>
+        /// <remarks>This method avoids the boxing of the <see cref="Array.Clone"/> method, and it is faster thanks to the use of the methods in the <see cref="Buffer"/> class</remarks>
         [Pure, NotNull]
         [CollectionAccess(CollectionAccessType.Read)]
         public static unsafe float[] BlockCopy([NotNull] this float[] v)
@@ -309,7 +234,7 @@ public static unsafe float[] BlockCopy([NotNull] this float[] v)
 
         #endregion
 
-        #region Content check
+        #region Content equals
 
         /// <summary>
         /// Checks if two matrices have the same size and content
@@ -318,7 +243,7 @@ public static unsafe float[] BlockCopy([NotNull] this float[] v)
         /// <param name="o">The second <see cref="Tensor"/> to test</param>
         /// <param name="absolute">The relative comparison threshold</param>
         /// <param name="relative">The relative comparison threshold</param>
-        public static unsafe bool ContentEquals(in this Tensor m, in Tensor o,float absolute = 1e-6f, float relative = 1e-6f)
+        public static unsafe bool ContentEquals(in this Tensor m, in Tensor o, float absolute = 1e-6f, float relative = 1e-6f)
         {
             if (m.Ptr == IntPtr.Zero && o.Ptr == IntPtr.Zero) return true;
             if (m.Ptr == IntPtr.Zero || o.Ptr == IntPtr.Zero) return false;
@@ -374,53 +299,6 @@ public static bool ContentEquals([CanBeNull] this float[] v, [CanBeNull] float[]
             return true;
         }
 
-        // GetUid helper method
-        private static unsafe int GetUid(float* p, int n)
-        {
-            int hash = 17;
-            unchecked
-            {
-                for (int i = 0; i < n; i++)
-                    hash = hash * 23 + p[i].GetHashCode();
-                return hash;
-            }
-        }
-
-        /// <summary>
-        /// Calculates a unique hash code for the target row of the input matrix
-        /// </summary>
-        [Pure]
-        public static unsafe int GetUid([NotNull] this float[,] m, int row)
-        {
-            int
-                w = m.GetLength(1),
-                offset = row * w;
-            fixed (float* pm = m)
-                return GetUid(pm + offset, w);
-        }
-
-        /// <summary>
-        /// Calculates a unique hash code for the input matrix
-        /// </summary>
-        /// <param name="m">The matrix to analyze</param>
-        [Pure]
-        public static unsafe int GetUid([NotNull] this float[,] m)
-        {
-            fixed (float* pm = m)
-                return GetUid(pm, m.Length);
-        }
-
-        /// <summary>
-        /// Calculates a unique hash code for the input vector
-        /// </summary>
-        /// <param name="v">The vector to analyze</param>
-        [Pure]
-        public static unsafe int GetUid([NotNull] this float[] v)
-        {
-            fixed (float* pv = v)
-                return GetUid(pv, v.Length);
-        }
-
         #endregion
 
         #region String display