Add TensorPrimitives.HammingDistance and friends

dotnet · stephentoub · Jun 12, 2024 · Jun 11, 2024 · Jun 12, 2024 · Jun 12, 2024
commit 021de58f7431a671f64e3bd6d2253c7a16fd9a6f
diff --git a/src/libraries/System.Numerics.Tensors/ref/System.Numerics.Tensors.netcore.cs b/src/libraries/System.Numerics.Tensors/ref/System.Numerics.Tensors.netcore.cs
@@ -407,6 +407,8 @@ public static void Floor<T>(System.ReadOnlySpan<T> x, System.Span<T> destination
         public static void FusedMultiplyAdd<T>(System.ReadOnlySpan<T> x, System.ReadOnlySpan<T> y, System.ReadOnlySpan<T> addend, System.Span<T> destination) where T : System.Numerics.IFloatingPointIeee754<T> { }
         public static void FusedMultiplyAdd<T>(System.ReadOnlySpan<T> x, System.ReadOnlySpan<T> y, T addend, System.Span<T> destination) where T : System.Numerics.IFloatingPointIeee754<T> { }
         public static void FusedMultiplyAdd<T>(System.ReadOnlySpan<T> x, T y, System.ReadOnlySpan<T> addend, System.Span<T> destination) where T : System.Numerics.IFloatingPointIeee754<T> { }
+        public static int HammingDistance<T>(System.ReadOnlySpan<T> x, System.ReadOnlySpan<T> y) { throw null; }
+        public static long HammingBitDistance<T>(System.ReadOnlySpan<T> x, System.ReadOnlySpan<T> y) where T : IBinaryInteger<T> { throw null; }
         public static void Hypot<T>(System.ReadOnlySpan<T> x, System.ReadOnlySpan<T> y, System.Span<T> destination) where T : System.Numerics.IRootFunctions<T> { }
         public static void Ieee754Remainder<T>(System.ReadOnlySpan<T> x, System.ReadOnlySpan<T> y, System.Span<T> destination) where T : System.Numerics.IFloatingPointIeee754<T> { }
         public static void Ieee754Remainder<T>(System.ReadOnlySpan<T> x, T y, System.Span<T> destination) where T : System.Numerics.IFloatingPointIeee754<T> { }
@@ -457,6 +459,7 @@ public static void Multiply<T>(System.ReadOnlySpan<T> x, T y, System.Span<T> des
         public static void Negate<T>(System.ReadOnlySpan<T> x, System.Span<T> destination) where T : System.Numerics.IUnaryNegationOperators<T, T> { }
         public static T Norm<T>(System.ReadOnlySpan<T> x) where T : System.Numerics.IRootFunctions<T> { throw null; }
         public static void OnesComplement<T>(System.ReadOnlySpan<T> x, System.Span<T> destination) where T : System.Numerics.IBitwiseOperators<T, T, T> { }
+        public static long PopCount<T>(System.ReadOnlySpan<T> x) where T : System.Numerics.IBinaryInteger<T> { throw null; }
         public static void PopCount<T>(System.ReadOnlySpan<T> x, System.Span<T> destination) where T : System.Numerics.IBinaryInteger<T> { }
         public static void Pow<T>(System.ReadOnlySpan<T> x, System.ReadOnlySpan<T> y, System.Span<T> destination) where T : System.Numerics.IPowerFunctions<T> { }
         public static void Pow<T>(System.ReadOnlySpan<T> x, T y, System.Span<T> destination) where T : System.Numerics.IPowerFunctions<T> { }

diff --git a/src/libraries/System.Numerics.Tensors/src/System.Numerics.Tensors.csproj b/src/libraries/System.Numerics.Tensors/src/System.Numerics.Tensors.csproj
@@ -80,6 +80,7 @@
     <Compile Include="System\Numerics\Tensors\netcore\TensorPrimitives.Floor.cs" />
     <Compile Include="System\Numerics\Tensors\netcore\TensorPrimitives.FusedMultiplyAdd.cs" />
     <Compile Include="System\Numerics\Tensors\netcore\TensorPrimitives.Half.cs" />
+    <Compile Include="System\Numerics\Tensors\netcore\TensorPrimitives.HammingDistance.cs" />
     <Compile Include="System\Numerics\Tensors\netcore\TensorPrimitives.Hypot.cs" />
     <Compile Include="System\Numerics\Tensors\netcore\TensorPrimitives.Ieee754Remainder.cs" />
     <Compile Include="System\Numerics\Tensors\netcore\TensorPrimitives.ILogB.cs" />

diff --git a/....Numerics.Tensors/src/System/Numerics/Tensors/netcore/TensorPrimitives.HammingDistance.cs b/....Numerics.Tensors/src/System/Numerics/Tensors/netcore/TensorPrimitives.HammingDistance.cs
@@ -0,0 +1,191 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+using System.Runtime.Intrinsics;
+
+namespace System.Numerics.Tensors
+{
+    public static partial class TensorPrimitives
+    {
+        /// <summary>Computes the bitwise Hamming distance between two equal-length tensors of values.</summary>
+        /// <param name="x">The first tensor, represented as a span.</param>
+        /// <param name="y">The second tensor, represented as a span.</param>
+        /// <returns>The number of bits that differ between the two spans.</returns>
+        /// <exception cref="ArgumentException">Length of <paramref name="x" /> must be same as length of <paramref name="y" />.</exception>
+        /// <exception cref="ArgumentException"><paramref name="x" /> and <paramref name="y" /> must not be empty.</exception>
+        public static long HammingBitDistance<T>(ReadOnlySpan<T> x, ReadOnlySpan<T> y) where T : IBinaryInteger<T>
+        {
+            if (x.Length != y.Length)
+            {
+                ThrowHelper.ThrowArgument_SpansMustHaveSameLength();
+            }
+
+            long count = 0;
+            for (int i = 0; i < x.Length; i++)
+            {
+                count += long.CreateTruncating(T.PopCount(x[i] ^ y[i]));
+            }
+
+            return count;
+        }
+
+        /// <summary>Computes the Hamming distance between two equal-length tensors of values.</summary>
+        /// <param name="x">The first tensor, represented as a span.</param>
+        /// <param name="y">The second tensor, represented as a span.</param>
+        /// <returns>The number of elements that differ between the two spans.</returns>
+        /// <exception cref="ArgumentException">Length of <paramref name="x" /> must be same as length of <paramref name="y" />.</exception>
+        /// <exception cref="ArgumentException"><paramref name="x" /> and <paramref name="y" /> must not be empty.</exception>
+        /// <remarks>
+        /// <para>
+        /// This method computes the number of locations <c>i</c> where <c>!EqualityComparer&gt;T&lt;.Default.Equal(x[i], y[i])</c>.
+        /// </para>
+        /// </remarks>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static int HammingDistance<T>(ReadOnlySpan<T> x, ReadOnlySpan<T> y)
+        {
+            if (typeof(T) == typeof(char))
+            {
+                // Special-case char, as it's reasonable for someone to want to use HammingDistance on strings,
+                // and we want that accelerated. This can be removed if/when VectorXx<T> supports char.
+                return CountUnequalElements<ushort>(
+                    MemoryMarshal.CreateReadOnlySpan(ref Unsafe.As<T, ushort>(ref MemoryMarshal.GetReference(x)), x.Length),
+                    MemoryMarshal.CreateReadOnlySpan(ref Unsafe.As<T, ushort>(ref MemoryMarshal.GetReference(y)), y.Length));
+            }
+
+            return CountUnequalElements(x, y);
+        }
+
+        /// <summary>Counts the number of elements that are pair-wise different between the two spans.</summary>
+        private static int CountUnequalElements<T>(ReadOnlySpan<T> x, ReadOnlySpan<T> y)
+        {
+            if (x.Length != y.Length)
+            {
+                ThrowHelper.ThrowArgument_SpansMustHaveSameLength();
+            }
+
+            // TODO: This has a very similar structure to CosineSimilarity, which is also open-coded rather than
+            // using a shared routine plus operator, as we don't have one implemented that exactly fits. We should
+            // look at refactoring these to share the core logic.
+
+            int count = 0;
+            if (Vector128.IsHardwareAccelerated && Vector128<T>.IsSupported && x.Length >= Vector128<T>.Count)
+            {
+                if (Vector256.IsHardwareAccelerated && Vector256<T>.IsSupported && x.Length >= Vector256<T>.Count)
+                {
+                    if (Vector512.IsHardwareAccelerated && Vector512<T>.IsSupported && x.Length >= Vector512<T>.Count)
+                    {
+                        ref T xRef = ref MemoryMarshal.GetReference(x);
+                        ref T yRef = ref MemoryMarshal.GetReference(y);
+
+                        int oneVectorFromEnd = x.Length - Vector512<T>.Count;
+                        int i = 0;
+                        do
+                        {
+                            Vector512<T> xVec = Vector512.LoadUnsafe(ref xRef, (uint)i);
+                            Vector512<T> yVec = Vector512.LoadUnsafe(ref yRef, (uint)i);
+
+                            count += BitOperations.PopCount((~Vector512.Equals(xVec, yVec)).ExtractMostSignificantBits());
+
+                            i += Vector512<T>.Count;
+                        }
+                        while (i <= oneVectorFromEnd);
+
+                        // Process the last vector in the span, masking off elements already processed.
+                        if (i != x.Length)
+                        {
+                            Vector512<T> xVec = Vector512.LoadUnsafe(ref xRef, (uint)(x.Length - Vector512<T>.Count));
+                            Vector512<T> yVec = Vector512.LoadUnsafe(ref yRef, (uint)(x.Length - Vector512<T>.Count));
+
+                            Vector512<T> remainderMask = CreateRemainderMaskVector512<T>(x.Length - i);
+                            xVec &= remainderMask;
+                            yVec &= remainderMask;
+
+                            count += BitOperations.PopCount((~Vector512.Equals(xVec, yVec)).ExtractMostSignificantBits());
+                        }
+                    }
+                    else
+                    {
+                        ref T xRef = ref MemoryMarshal.GetReference(x);
+                        ref T yRef = ref MemoryMarshal.GetReference(y);
+
+                        // Process vectors, summing their dot products and squares, as long as there's a vector's worth remaining.
+                        int oneVectorFromEnd = x.Length - Vector256<T>.Count;
+                        int i = 0;
+                        do
+                        {
+                            Vector256<T> xVec = Vector256.LoadUnsafe(ref xRef, (uint)i);
+                            Vector256<T> yVec = Vector256.LoadUnsafe(ref yRef, (uint)i);
+
+                            count += BitOperations.PopCount((~Vector256.Equals(xVec, yVec)).ExtractMostSignificantBits());
+
+                            i += Vector256<T>.Count;
+                        }
+                        while (i <= oneVectorFromEnd);
+
+                        // Process the last vector in the span, masking off elements already processed.
+                        if (i != x.Length)
+                        {
+                            Vector256<T> xVec = Vector256.LoadUnsafe(ref xRef, (uint)(x.Length - Vector256<T>.Count));
+                            Vector256<T> yVec = Vector256.LoadUnsafe(ref yRef, (uint)(x.Length - Vector256<T>.Count));
+
+                            Vector256<T> remainderMask = CreateRemainderMaskVector256<T>(x.Length - i);
+                            xVec &= remainderMask;
+                            yVec &= remainderMask;
+
+                            count += BitOperations.PopCount((~Vector256.Equals(xVec, yVec)).ExtractMostSignificantBits());
+                        }
+                    }
+                }
+                else
+                {
+                    ref T xRef = ref MemoryMarshal.GetReference(x);
+                    ref T yRef = ref MemoryMarshal.GetReference(y);
+
+                    // Process vectors, summing their dot products and squares, as long as there's a vector's worth remaining.
+                    int oneVectorFromEnd = x.Length - Vector128<T>.Count;
+                    int i = 0;
+                    do
+                    {
+                        Vector128<T> xVec = Vector128.LoadUnsafe(ref xRef, (uint)i);
+                        Vector128<T> yVec = Vector128.LoadUnsafe(ref yRef, (uint)i);
+
+                        count += BitOperations.PopCount((~Vector128.Equals(xVec, yVec)).ExtractMostSignificantBits());
+
+                        i += Vector128<T>.Count;
+                    }
+                    while (i <= oneVectorFromEnd);
+
+                    // Process the last vector in the span, masking off elements already processed.
+                    if (i != x.Length)
+                    {
+                        Vector128<T> xVec = Vector128.LoadUnsafe(ref xRef, (uint)(x.Length - Vector128<T>.Count));
+                        Vector128<T> yVec = Vector128.LoadUnsafe(ref yRef, (uint)(x.Length - Vector128<T>.Count));
+
+                        Vector128<T> remainderMask = CreateRemainderMaskVector128<T>(x.Length - i);
+                        xVec &= remainderMask;
+                        yVec &= remainderMask;
+
+                        count += BitOperations.PopCount((~Vector128.Equals(xVec, yVec)).ExtractMostSignificantBits());
+                    }
+                }
+            }
+            else
+            {
+                for (int i = 0; i < x.Length; i++)
+                {
+                    if (!EqualityComparer<T>.Default.Equals(x[i], y[i]))
+                    {
+                        count++;
+                    }
+                }
+            }
+
+            Debug.Assert(count >= 0 && count <= x.Length, $"Expected count to be in the range [0, {x.Length}], got {count}.");
+            return count;
+        }
+    }
+}
diff --git a/.../System.Numerics.Tensors/src/System/Numerics/Tensors/netcore/TensorPrimitives.PopCount.cs b/.../System.Numerics.Tensors/src/System/Numerics/Tensors/netcore/TensorPrimitives.PopCount.cs
@@ -13,6 +13,20 @@ namespace System.Numerics.Tensors
 {
     public static partial class TensorPrimitives
     {
+        /// <summary>Computes the population count of all elements in the specified tensor.</summary>
+        /// <param name="x">The tensor, represented as a span.</param>
+        /// <returns>The sum of the number of bits set in each element in <paramref name="x"/>.</returns>
+        public static long PopCount<T>(ReadOnlySpan<T> x) where T : IBinaryInteger<T>
+        {
+            long count = 0;
+            for (int i = 0; i < x.Length; i++)
+            {
+                count += long.CreateTruncating(T.PopCount(x[i]));
+            }
+
+            return count;
+        }
+
         /// <summary>Computes the element-wise population count of numbers in the specified tensor.</summary>
         /// <param name="x">The tensor, represented as a span.</param>
         /// <param name="destination">The destination tensor, represented as a span.</param>

diff --git a/src/libraries/System.Numerics.Tensors/tests/TensorPrimitives.Generic.cs b/src/libraries/System.Numerics.Tensors/tests/TensorPrimitives.Generic.cs
@@ -2087,6 +2087,81 @@ public void CopySign_ThrowsForOverlapppingInputsWithOutputs()
             AssertExtensions.Throws<ArgumentException>("destination", () => TensorPrimitives.CopySign(array.AsSpan(1, 2), default(T), array.AsSpan(2, 2)));
         }
         #endregion
+
+        #region HammingBitDistance
+        [Fact]
+        public void HammingBitDistance_ThrowsForMismatchedLengths()
+        {
+            Assert.Throws<ArgumentException>(() => TensorPrimitives.HammingBitDistance<int>(new int[1], new int[2]));
+            Assert.Throws<ArgumentException>(() => TensorPrimitives.HammingBitDistance<int>(new int[2], new int[1]));
+        }
+
+        [Fact]
+        public void HammingBitDistance_AllLengths()
+        {
+            Assert.All(Helpers.TensorLengthsIncluding0, tensorLength =>
+            {
+                using BoundedMemory<T> x = CreateAndFillTensor(tensorLength);
+                using BoundedMemory<T> y = CreateAndFillTensor(tensorLength);
+
+                long expected = 0;
+                for (int i = 0; i < tensorLength; i++)
+                {
+                    expected += long.CreateTruncating(T.PopCount(x[i] ^ y[i]));
+                }
+
+                Assert.Equal(expected, TensorPrimitives.HammingBitDistance<T>(x.Span, y.Span));
+            });
+        }
+
+        [Fact]
+        public void HammingBitDistance_KnownValues()
+        {
+            T value42 = T.CreateTruncating(42);
+            T value84 = T.CreateTruncating(84);
+
+            T[] values1 = new T[100];
+            T[] values2 = new T[100];
+
+            Array.Fill(values1, value42);
+            Array.Fill(values2, value84);
+
+            Assert.Equal(0, TensorPrimitives.HammingBitDistance<T>(values1, values1));
+            Assert.Equal(600, TensorPrimitives.HammingBitDistance<T>(values1, values2));
+            Assert.Equal(0, TensorPrimitives.HammingBitDistance<T>(values2, values2));
+        }
+        #endregion
+
+        #region PopCount
+        [Fact]
+        public void PopCount_AllLengths()
+        {
+            Assert.All(Helpers.TensorLengthsIncluding0, tensorLength =>
+            {
+                using BoundedMemory<T> x = CreateAndFillTensor(tensorLength);
+
+                long expected = 0;
+                for (int i = 0; i < tensorLength; i++)
+                {
+                    expected += long.CreateTruncating(T.PopCount(x[i]));
+                }
+
+                Assert.Equal(expected, TensorPrimitives.PopCount<T>(x.Span));
+            });
+        }
+
+        [Fact]
+        public void PopCount_KnownValues()
+        {
+            T[] values = new T[255];
+            for (int i = 0; i < values.Length; i++)
+            {
+                values[i] = T.CreateTruncating(i);
+            }
+
+            Assert.Equal(1016, TensorPrimitives.PopCount<T>(values));
+        }
+        #endregion
     }
 
     public unsafe abstract class GenericNumberTensorPrimitivesTests<T> : TensorPrimitivesTests<T>
@@ -2269,5 +2344,36 @@ public void ScalarSpanDestination_ThrowsForOverlapppingInputsWithOutputs(ScalarS
             AssertExtensions.Throws<ArgumentException>("destination", () => tensorPrimitivesMethod(default, array.AsSpan(4, 2), array.AsSpan(5, 2)));
         }
         #endregion
+
+        #region HammingDistance
+        [Fact]
+        public void HammingDistance_ThrowsForMismatchedLengths()
+        {
+            Assert.Throws<ArgumentException>(() => TensorPrimitives.HammingDistance<int>(new int[1], new int[2]));
+            Assert.Throws<ArgumentException>(() => TensorPrimitives.HammingDistance<int>(new int[2], new int[1]));
+        }
+
+        [Fact]
+        public void HammingDistance_AllLengths()
+        {
+            Assert.All(Helpers.TensorLengthsIncluding0, tensorLength =>
+            {
+                using BoundedMemory<T> x = CreateAndFillTensor(tensorLength);
+                using BoundedMemory<T> y = CreateAndFillTensor(tensorLength);
+
+                int expected = 0;
+                ReadOnlySpan<T> xSpan = x, ySpan = y;
+                for (int i = 0; i < xSpan.Length; i++)
+                {
+                    if (xSpan[i] != ySpan[i])
+                    {
+                        expected++;
+                    }
+                }
+
+                Assert.Equal(expected, TensorPrimitives.HammingDistance<T>(x, y));
+            });
+        }
+        #endregion
     }
 }