usearch 1.2.2 → 2.0.0

package/csharp/eng/build_lib.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+
+# Get absolute path to the usearch dir
+# FIX: realpath is not available on OSX, so use pwd
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_DIR="${SCRIPT_DIR}/"
+
+# Define project paths
+REPO_ROOT=`cd -P "${SCRIPT_DIR}../.." && pwd`
+REPO_ROOT="${REPO_ROOT}/"
+C_DIR="${REPO_ROOT}c/"
+CSHARP_DIR="${REPO_ROOT}csharp/"
+BUILD_ARTIFACTS_DIR="${CSHARP_DIR}lib/"
+
+LIB_FILE="libusearch_c"
+
+# Determine the architecture type (only x64 is supported)
+ARCH_TYPE="$(uname -m)"
+case "$ARCH_TYPE" in
+    x86_64)
+        ARCH="x64"
+        ;;
+    # i386|i486|i586|i686)
+    #     ARCH="x86"
+    #     ;;
+    *)
+        echo "Unsupported architecture"
+        exit 1
+        ;;
+esac
+echo "Detected architecture: $ARCH"
+
+# Determine the OS type (linux or macos) and set the shared library extension accordingly
+case "$(uname -s)" in
+    Darwin)
+        BUILD_ARTIFACTS_DIR+="runtimes/osx-${ARCH}/native/"
+        LIB_FILE+=".dylib"
+        ;;
+    Linux)
+        BUILD_ARTIFACTS_DIR+="runtimes/linux-${ARCH}/native/"
+        LIB_FILE+=".so"
+        ;;
+    *)
+        echo "Unsupported operating system"
+        exit 1
+        ;;
+esac
+
+MAKE_TARGET="${LIB_FILE}"
+
+# Build the native dynamic lib
+cd "$C_DIR" || { echo "C directory not found in $C_DIR"; exit 1; }
+if [ ! -f Makefile ]; then
+  echo "Makefile not found in $C_DIR"
+  exit 1
+fi
+make "${MAKE_TARGET}"
+if [ $? -ne 0 ]; then
+  echo "Build failed!"
+  exit 1
+fi
+
+# Create output dir for shared lib and copy it there
+mkdir -p "$BUILD_ARTIFACTS_DIR"
+cp "${C_DIR}/${LIB_FILE}" "$BUILD_ARTIFACTS_DIR"

package/csharp/eng/clean.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# Get absolute path to the usearch csharp dir
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_DIR="${SCRIPT_DIR}/"
+CSHARP_DIR=`cd -P "${SCRIPT_DIR}.." && pwd`
+CSHARP_DIR="${CSHARP_DIR}/"
+
+rm -rf ${CSHARP_DIR}lib # Local temp path for native libs
+rm -rf ${CSHARP_DIR}packages # Local temp path for nuget packages
+find ${CSHARP_DIR} -type d -name 'bin' -exec rm -rf {} +
+find ${CSHARP_DIR} -type d -name 'obj' -exec rm -rf {} +

package/csharp/nuget/NUGET.md

@@ -0,0 +1,11 @@
+**Cloud.Unum.USearch** is a wrapper for the USearch vector search engine, offering fast searches, multiple metrics, and features like SIMD-optimized metrics.
+
+**Supported metrics**: Euclidean, Angular, Jaccard, Hamming, Haversine, User-Defined Metrics
+
+**Platforms**: Linux, MacOS, Windows
+
+# Getting Started ⚡
+
+- [Quickstart](https://github.com/unum-cloud/usearch/blob/main/csharp/README.md)
+- Join the [Discord community](https://discord.gg/A6wxt6dS9j)
+- Check out the [GitHub repository](https://github.com/unum-cloud/usearch)

package/csharp/nuget/nuget-package.props

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project>
+  <PropertyGroup>
+    <Version Condition="'$(Version)' == ''">0.0.2</Version>
+
+    <Authors>Unum</Authors>
+    <Company>Unum</Company>
+    <PackageTags>USearch Vector Search Disk-based Multi-Modal Semantic-Search Molecular-Search</PackageTags>
+    <PackageId>Cloud.Unum.USearch</PackageId>
+
+    <PackageLicenseFile>LICENSE</PackageLicenseFile>
+    <PackageProjectUrl>https://github.com/unum-cloud/usearch</PackageProjectUrl>
+    <RepositoryUrl>https://github.com/unum-cloud/usearch</RepositoryUrl>
+    <PublishRepositoryUrl>true</PublishRepositoryUrl>
+
+    <PackageIcon>unum.png</PackageIcon>
+    <PackageIconUrl>unum.png</PackageIconUrl>
+    <PackageReadmeFile>NUGET.md</PackageReadmeFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Include="$(NativeLibDir)runtimes\**\*.*" Pack="true" PackagePath="runtimes" />
+    <None Include="$(RepoRoot)LICENSE" Pack="true" PackagePath=""/>
+    <None Include="$(RepoRoot)assets\unum.png" Pack="true" PackagePath=""/>
+    <None Include="$(CSharpDir)nuget\NUGET.md" Pack="true" PackagePath=""/>
+  </ItemGroup>
+
+  <!-- Package validation https://learn.microsoft.com/en-us/dotnet/fundamentals/package-validation/overview?WT.mc_id=DT-MVP-5003978 -->
+  <PropertyGroup Condition="'$(IsPackable)' == 'true'">
+    <EnablePackageValidation Condition="'$(EnablePackageValidation)' == ''">true</EnablePackageValidation>
+  </PropertyGroup>
+
+</Project>

package/csharp/pack.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+
+check_task_status() {
+  local task_name=$1
+  local exit_code=$2
+
+  if [ $exit_code -ne 0 ]; then
+    echo "$task_name failed!"
+    exit 1
+  else
+    echo "$task_name finished successfully!"
+  fi
+}
+
+# Check vars for pack and push are set
+required_vars=("PACKAGE_ID" "PACKAGE_VERSION" "NUGET_APIKEY" "NUGET_SERVER")
+unset_vars=""
+
+for var in "${required_vars[@]}"; do
+  if [ -z "${!var}" ]; then
+    unset_vars="$unset_vars $var"
+  fi
+done
+
+if [ -n "$unset_vars" ]; then
+  echo "The following variables are not set:$unset_vars"
+  exit 1
+fi
+
+# Get absolute path to the usearch dir
+# FIX: realpath is not available on OSX, so use pwd
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_DIR="${SCRIPT_DIR}/"
+
+# Define project paths
+REPO_ROOT=`cd -P "$SCRIPT_DIR../" && pwd`
+REPO_ROOT="${REPO_ROOT}/"
+
+# Clear package output folder
+rm -rf ./packages/*
+
+# Clean previous outputs
+dotnet clean -c Release -p:RepoRoot="$REPO_ROOT"
+
+# Build
+dotnet build -c Release -p:Version=${PACKAGE_VERSION} -p:RepoRoot="$REPO_ROOT"
+
+# Pack
+dotnet pack -c Release -p:Version=${PACKAGE_VERSION} -p:RepoRoot="$REPO_ROOT"
+EXIT_CODE=$?
+check_task_status "Pack" $EXIT_CODE
+
+# Push
+dotnet nuget push "./packages/${PACKAGE_ID}.*.nupkg" -k ${NUGET_APIKEY} -s ${NUGET_SERVER}
+EXIT_CODE=$?
+check_task_status "NuGet Push" $EXIT_CODE

package/csharp/src/Cloud.Unum.USearch.Tests/Cloud.Unum.USearch.Tests.csproj

@@ -0,0 +1,39 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net7.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <IsPackable>false</IsPackable>
+    <Nullable>enable</Nullable>
+    <IsTestProject>true</IsTestProject>
+
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.3.2" />
+    <PackageReference Include="xunit" Version="2.4.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="coverlet.collector" Version="3.1.2">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Cloud.Unum.USearch\Cloud.Unum.USearch.csproj" />
+  </ItemGroup>
+
+  <Target Name="PlaceNativeLibrary" AfterTargets="Build">
+    <ItemGroup>
+      <NativeBinaries Include="$(NativeLibDir)runtimes\$(TargetOS)-$(TargetArchitecture)\native\*.*"/>
+    </ItemGroup>
+
+    <Copy SourceFiles="@(NativeBinaries)" DestinationFolder="$(OutputPath)" />
+    <Message Text="NativeLibDir: $(NativeLibDir)" Importance="high"/>
+    <Message Text="Files: @(NativeBinaries)" Importance="high"/>
+    <Message Text="$(OutputPath)" Importance="high" />
+  </Target>
+</Project>

package/csharp/src/Cloud.Unum.USearch.Tests/InitTests.cs

@@ -0,0 +1,306 @@
+using Cloud.Unum.USearch;
+
+namespace Cloud.Unum.USearch.Tests;
+
+public class InitTests
+{
+    // Epsilon for real values comparisons
+    private const float Epsilon = 0.000001f;
+
+    [Fact]
+    public void InitializedAndDisposedSucceeds()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 3))
+        {
+            Assert.NotNull(index);
+            Assert.Equal((uint)3, index.Dimensions());
+        }
+    }
+
+    [Fact]
+    public void AddDoubleVectorSucceeds()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float64, 3))
+        {
+            index.Add(1, new double[] { 1.0, 2.0, 3.0 });
+            Assert.True(index.Contains(1));
+            Assert.False(index.Contains(2));
+            Assert.Equal((uint)1, index.Size());
+        }
+    }
+
+    [Fact]
+    public void AddDoubleVectorsUnderSameKeySucceeds()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float64, 3, multi: true))
+        {
+            index.Add(1, new double[] { 1.0, 2.0, 3.0 });
+            index.Add(2, new double[] { 1.0, 2.0, 3.0 });
+            index.Add(3, new double[] { 1.0, 2.0, 3.0 });
+            index.Add(1, new double[] { 1.0, 2.0, 3.0 });
+            index.Add(2, new double[] { 1.0, 2.0, 3.0 });
+            Assert.True(index.Contains(1));
+            Assert.True(index.Contains(2));
+            Assert.True(index.Contains(3));
+            Assert.Equal((uint)5, index.Size());
+        }
+    }
+
+    [Fact]
+    public void ItCanGetMultipleFloatVectorsForSingleKey()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 3, multi: true))
+        {
+            var inputVectors = new float[][] {
+                    new float[] { 1.0f, 6.0f, 11.0f },
+                    new float[] { 2.0f, 7.0f, 12.0f },
+                    new float[] { 3.0f, 8.0f, 13.0f },
+                    new float[] { 5.0f, 10.0f, 15.0f }
+            };
+            index.Add(
+                new ulong[] { 2, 2, 2, 2 },
+                inputVectors
+            );
+            Assert.True(index.Contains(2));
+            Assert.Equal((uint)4, index.Size());
+            Assert.Equal(4, index.Count(2));
+
+            int foundVectorsCount = index.Get(2, 3, out float[][] retrievedVectors);
+            Assert.Equal(3, foundVectorsCount);
+        }
+    }
+
+    [Fact]
+    public void ItCanGetMultipleDoubleVectorsForSingleKey()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float64, 3, multi: true))
+        {
+            var inputVectors = new double[][] {
+                new double[] { 1.0, 6.0, 11.0 },
+                new double[] { 2.0, 7.0, 12.0 },
+                new double[] { 3.0, 8.0, 13.0 },
+                new double[] { 5.0, 10.0, 15.0 }
+            };
+            index.Add(
+                new ulong[] { 2, 2, 2, 2 },
+                inputVectors
+            );
+            Assert.True(index.Contains(2));
+            Assert.Equal((uint)4, index.Size());
+            Assert.Equal(4, index.Count(2));
+
+            int foundVectorsCount = index.Get(2, 3, out double[][] retrievedVectors);
+            Assert.Equal(3, foundVectorsCount);
+        }
+    }
+
+    [Fact]
+    public void AddFloatVectorSucceeds()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 3))
+        {
+            index.Add(1, new float[] { 1.0f, 2.0f, 3.0f });
+            Assert.Equal((uint)1, index.Size());
+            Assert.True(index.Contains(1));
+            Assert.False(index.Contains(2));
+        }
+    }
+
+    [Fact]
+    public void AddFloatVectorsUnderSameKeySucceeds()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 3, multi: true))
+        {
+            index.Add(1, new float[] { 1.0f, 2.0f, 3.0f });
+            index.Add(2, new float[] { 1.0f, 2.0f, 3.0f });
+            index.Add(3, new float[] { 1.0f, 2.0f, 3.0f });
+            index.Add(1, new float[] { 1.0f, 2.0f, 3.0f });
+            index.Add(2, new float[] { 1.0f, 2.0f, 3.0f });
+            Assert.True(index.Contains(1));
+            Assert.True(index.Contains(2));
+            Assert.True(index.Contains(3));
+            Assert.Equal((uint)5, index.Size());
+        }
+    }
+
+    [Fact]
+    public void AddGetFloatVectorSucceeds()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 3))
+        {
+            var inputVector = new float[] { 1.0f, 2.0f, 3.0f };
+            index.Add(1, inputVector);
+            Assert.Equal((uint)1, index.Size());
+            Assert.True(index.Contains(1));
+            Assert.False(index.Contains(2));
+            Assert.True(index.Get(1, out float[] retrievedVector) == 1);
+            Assert.NotNull(retrievedVector);
+            bool areEqual = inputVector
+                .Zip(retrievedVector, (a, b) => (a, b))
+                .All(pair => Math.Abs(pair.a - pair.b) <= Epsilon);
+
+            Assert.True(areEqual);
+        }
+    }
+
+    [Fact]
+    public void AddGetDoubleVectorSucceeds()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 3))
+        {
+            var inputVector = new double[] { 1.0, 2.0, 3.33 };
+            index.Add(1, inputVector);
+            Assert.Equal((uint)1, index.Size());
+            Assert.True(index.Contains(1));
+            Assert.False(index.Contains(2));
+            Assert.True(index.Get(1, out double[] retrievedVector) == 1);
+            Assert.NotNull(retrievedVector);
+            bool areEqual = inputVector
+                .Zip(retrievedVector, (a, b) => (a, b))
+                .All(pair => Math.Abs(pair.a - pair.b) <= Epsilon);
+
+            Assert.True(areEqual);
+        }
+    }
+
+    [Fact]
+    public void ItThrowsException_AddAddWithSameKeyAndGetVector()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 3))
+        {
+            ulong key = 1;
+            float[] vector1 = { 1.0f, 2.0f, 33.3f };
+            index.Add(key, vector1);
+            float[] vector2 = { 3.0f, 4.0f, 34.2f };
+            Assert.Throws<USearchException>(() => index.Add(key, vector2));
+        }
+    }
+
+    [Fact]
+    public void TestAddRemoveAddAndGet()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 2))
+        {
+            ulong key = 1;
+            float[] vector = { 1.0f, 2.0f };
+
+            index.Add(key, vector);
+            Assert.True(index.Contains(key));
+            index.Remove(key);
+            Assert.False(index.Contains(key));
+            index.Add(key, vector);
+            Assert.True(index.Contains(key));
+            Assert.True(index.Get(key, out float[] retrievedVector) == 1);
+            Assert.Equal(vector, retrievedVector);
+        }
+    }
+
+    [Fact]
+    public void TestAddRemoveAddWithSameKeyVectorAndGet()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 2))
+        {
+            ulong key = 1;
+            float[] vector = { 1.0f, 2.0f };
+
+            index.Add(key, vector);
+            Assert.True(index.Contains(key));
+            index.Remove(key);
+            Assert.False(index.Contains(key));
+            index.Add(key, vector);
+            Assert.True(index.Contains(key));
+            Assert.True(index.Get(key, out float[] retrievedVector) == 1);
+            Assert.Equal(vector, retrievedVector);
+        }
+    }
+
+    [Fact]
+    public void TestGetKeyThatNotExist()
+    {
+        using (var index = new USearchIndex(MetricKind.Cos, ScalarKind.Float32, 2))
+        {
+            Assert.True(index.Get(1, out float[] retrievedVector) == 0);
+            Assert.False(index.Contains(1));
+        }
+    }
+
+    [Fact]
+    public void Search_FindsExpectedResults()
+    {
+        using (var index = new USearchIndex(MetricKind.L2sq, ScalarKind.Float32, 2))
+        {
+            index.Add(
+                Enumerable.Range(1, 5).Select(i => (ulong)i).ToArray(),
+                new float[][]
+                {
+                    new float[] { -0.5f, -0.6f },
+                    new float[] { -0.1f, -0.1f },
+                    new float[] { 0.2f, 0.2f },
+                    new float[] { 0.7f, 0.8f },
+                    new float[] { 0.9f, 1.0f }
+                }
+            );
+            var queryVector = new float[] { 0.0f, 0.0f };
+
+            var matches = index.Search(queryVector, 2, out ulong[] keys, out float[] distances);
+
+            Assert.Equal(2, matches);
+            Assert.Contains(2UL, keys);
+            Assert.Contains(3UL, keys);
+            Assert.Equal(0.02, distances[0], Epsilon);
+            Assert.Equal(0.08, distances[1], Epsilon);
+        }
+    }
+
+    [Fact]
+    public void Search_AfterRemovingKey_FindsExpectedResults()
+    {
+        using (var index = new USearchIndex(MetricKind.L2sq, ScalarKind.Float32, 2))
+        {
+            index.Add(1, new float[] { 0.1f, 0.2f });
+            index.Add(2, new float[] { 0.2f, 0.3f });
+            index.Add(3, new float[] { 0.3f, 0.4f });
+            index.Remove(2);
+            var queryVector = new float[] { 0.2f, 0.3f };
+
+            var matches = index.Search(queryVector, 2, out ulong[] keys, out float[] distances);
+
+            Assert.Equal(2, matches);
+            Assert.Contains(1UL, keys);
+            Assert.Contains(3UL, keys);
+            Assert.DoesNotContain(2UL, keys);
+        }
+    }
+
+    [Fact]
+    public void Search_WithVectorsLessThanResultsLimit()
+    {
+        using (var index = new USearchIndex(MetricKind.L2sq, ScalarKind.Float32, 2))
+        {
+            index.Add(1, new float[] { 0.9f, 0.9f });
+            index.Add(2, new float[] { 0.8f, 0.8f });
+            var queryVector = new float[] { 0.1f, 0.2f };
+
+            var matches = index.Search(queryVector, 10, out ulong[] keys, out float[] distances);
+
+            Assert.Equal(2, matches);
+            Assert.Contains(1UL, keys);
+            Assert.Contains(2UL, keys);
+        }
+    }
+
+    [Fact]
+    public void ItCanRenameKey()
+    {
+        using (var index = new USearchIndex(MetricKind.L2sq, ScalarKind.Float32, 2))
+        {
+            index.Add(1, new float[] { 0.9f, 0.9f });
+            index.Add(2, new float[] { 0.8f, 0.8f });
+            index.Rename(1, 3);
+            Assert.False(index.Contains(1));
+            Assert.True(index.Contains(2));
+            Assert.True(index.Contains(3));
+        }
+    }
+
+}

package/csharp/src/Cloud.Unum.USearch.Tests/Usings.cs

@@ -0,0 +1 @@
+global using Xunit;

package/docs/benchmarks.md

@@ -19,13 +19,13 @@ The default values vary drastically.
 Below are the performance numbers for a benchmark running on the 64 cores of AWS `c7g.metal` "Graviton 3"-based instances.
 The main columns are:
 
-- **Add**: Number of insertion Queries Per Second.
-- **Search**: Number search Queries Per Second.
-- **Recall @1**: How often does approximate search yield the exact best match?
+- __Add__: Number of insertion Queries Per Second.
+- __Search__: Number search Queries Per Second.
+- __Recall @1__: How often does approximate search yield the exact best match?
 
 ### Different "connectivity"
 
-| Vectors    | Connectivity | EF @ A | EF @ S | **Add**, QPS | **Search**, QPS | **Recall @1** |
+| Vectors    | Connectivity | EF @ A | EF @ S | __Add__, QPS | __Search__, QPS | __Recall @1__ |
 | :--------- | :----------: | :----: | :----: | :----------: | :-------------: | ------------: |
 | `f32` x256 |      16      |  128   |   64   |    75'640    |     131'654     |         99.3% |
 | `f32` x256 |      12      |  128   |   64   |    81'747    |     149'728     |         99.0% |
@@ -33,7 +33,7 @@ The main columns are:
 
 ### Different "expansion factors"
 
-| Vectors    | Connectivity | EF @ A | EF @ S | **Add**, QPS | **Search**, QPS | **Recall @1** |
+| Vectors    | Connectivity | EF @ A | EF @ S | __Add__, QPS | __Search__, QPS | __Recall @1__ |
 | :--------- | :----------: | :----: | :----: | :----------: | :-------------: | ------------: |
 | `f32` x256 |      16      |  128   |   64   |    75'640    |     131'654     |         99.3% |
 | `f32` x256 |      16      |   64   |   32   |   128'644    |     228'422     |         97.2% |
@@ -41,7 +41,7 @@ The main columns are:
 
 ### Different vectors "quantization"
 
-| Vectors      | Connectivity | EF @ A | EF @ S | **Add**, QPS | **Search**, QPS | **Recall @1** |
+| Vectors      | Connectivity | EF @ A | EF @ S | __Add__, QPS | __Search__, QPS | __Recall @1__ |
 | :----------- | :----------: | :----: | :----: | :----------: | :-------------: | ------------: |
 | `f32` x256   |      16      |  128   |   64   |    87'995    |     171'856     |         99.1% |
 | `f16` x256   |      16      |  128   |   64   |    87'270    |     153'788     |         98.4% |

package/docs/compilation.md

@@ -155,7 +155,7 @@ There are a few ways to compile the C 99 USearch SDK.
 Using the Makefile:
 
 ```sh
-make -C ./c libusearch_c.so -C ./c libusearch_c.so
+make -C ./c libusearch_c.so
 ```
 
 Using CMake: