usearch 0.22.3 → 1.1.0

package/simsimd/.releaserc

@@ -0,0 +1,77 @@
+{
+    "branches": [
+        "main"
+    ],
+    "debug": true,
+    "ci": true,
+    "dryRun": false,
+    "plugins": [
+        [
+            "@semantic-release/commit-analyzer",
+            {
+                "preset": "eslint",
+                "releaseRules": [
+                    {
+                        "tag": "Add",
+                        "release": "minor"
+                    },
+                    {
+                        "tag": "Improve",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Make",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Refactor",
+                        "release": false
+                    }
+                ]
+            }
+        ],
+        [
+            "@semantic-release/release-notes-generator",
+            {
+                "preset": "eslint",
+                "releaseRules": [
+                    {
+                        "tag": "Add",
+                        "release": "minor"
+                    },
+                    {
+                        "tag": "Improve",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Make",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Refactor",
+                        "release": false
+                    }
+                ]
+            }
+        ],
+        "@semantic-release/github",
+        [
+            "@semantic-release/exec",
+            {
+                "prepareCmd": "bash .github/workflows/update_version.sh '${nextRelease.version}'"
+            }
+        ],
+        [
+            "@semantic-release/git",
+            {
+                "assets": [
+                    "VERSION",
+                    "conanfile.py",
+                    "package.json",
+                    "Cargo.toml",
+                ],
+                "message": "Build: Released ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+            }
+        ]
+    ]
+}

package/simsimd/.vscode/launch.json

@@ -18,7 +18,33 @@
             ],
             "stopAtEntry": false,
             "preLaunchTask": "Build Benchmark: Debug",
-            "MIMode": "gdb"
+            "linux": {
+                "MIMode": "gdb",
+            },
+            "osx": {
+                "MIMode": "lldb"
+            }
+        },
+        {
+            "name": "Debug Test",
+            "type": "cppdbg",
+            "request": "launch",
+            "program": "${workspaceFolder}/build/test",
+            "cwd": "${workspaceFolder}",
+            "environment": [
+                {
+                    "name": "ASAN_OPTIONS",
+                    "value": "detect_leaks=0:atexit=1:strict_init_order=1:strict_string_checks=1"
+                }
+            ],
+            "stopAtEntry": false,
+            "preLaunchTask": "Build Test: Debug",
+            "linux": {
+                "MIMode": "gdb"
+            },
+            "osx": {
+                "MIMode": "lldb"
+            }
         }
     ]
 }

package/simsimd/.vscode/settings.json

@@ -64,7 +64,28 @@
         "thread": "cpp",
         "typeinfo": "cpp",
         "complex": "cpp",
-        "immintrin.h": "c"
+        "immintrin.h": "c",
+        "__bit_reference": "cpp",
+        "__bits": "cpp",
+        "__config": "cpp",
+        "__debug": "cpp",
+        "__errc": "cpp",
+        "__hash_table": "cpp",
+        "__locale": "cpp",
+        "__mutex_base": "cpp",
+        "__node_handle": "cpp",
+        "__split_buffer": "cpp",
+        "__threading_support": "cpp",
+        "__tuple": "cpp",
+        "__verbose_abort": "cpp",
+        "charconv": "cpp",
+        "ios": "cpp",
+        "locale": "cpp",
+        "optional": "cpp",
+        "variant": "cpp",
+        "__nullptr": "cpp",
+        "unordered_set": "cpp",
+        "span": "cpp"
     },
     "cSpell.words": [
         "dtype",

package/simsimd/.vscode/tasks.json

@@ -7,6 +7,12 @@
             "args": [],
             "type": "shell"
         },
+        {
+            "label": "Build Test: Debug",
+            "command": "cmake -DCMAKE_BUILD_TYPE=Debug -B ./build && make test py_simsimd -C ./build",
+            "args": [],
+            "type": "shell"
+        },
         {
             "label": "Build Benchmark: Release",
             "command": "cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -B ./build_release && make -j 2 -C ./build_release",

package/simsimd/CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
-project(simsimd LANGUAGES CXX)
-set(CMAKE_CXX_STANDARD 11)
+project(simsimd LANGUAGES CXX C)
+set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED YES)
 set(CMAKE_CXX_EXTENSIONS NO)
 
@@ -9,6 +9,7 @@ option(SIMSIMD_BUILD_BENCHMARKS "Compile a micro-benchmark for current ISA" OFF)
 
 # Get external content: Google Benchmark, Thrust
 include(FetchContent)
+include_directories(include/)
 
 # Fetch GBenchmark and surpress internal tests.
 # https://github.com/google/benchmark/blob/main/docs/user_guide.md#using-register-benchmark

package/simsimd/README.md

@@ -1,18 +1,20 @@
 # SimSIMD
 
 SIMD-accelerated similarity measures, metrics, distance functions for x86 and Arm.
-Tuned for Machine Learning applications, mid-size vectors with 100-512 dimensions.
-
-| Distance          | Serial |     x86 AVX     | Arm NEON | Arm SVE |
-| :---------------- | :----: | :-------------: | :------: | :-----: |
-| `f32` Dot Product |   ✅    |    AVX2-FMA     |    ✅     |    ✅    |
-| `f32` Cosine      |   ✅    |    AVX2-FMA     |    ✅     |    ✅    |
-| `f32` Euclidean   |   ✅    |        ❌        |    ❌     |    ✅    |
-|                   |        |                 |          |         |
-| `f16` Dot Product |   ✅    |        ❌        |    ❌     |    ✅    |
-| `f16` Euclidean   |   ✅    |        ❌        |    ❌     |    ✅    |
-|                   |        |                 |          |         |
-| `u1` Hamming      |   ✅    | AVX512VPOPCNTDQ |    ✅     |    ✅    |
+Tuned for Machine Learning applications, mid-size vectors with 100-1024 dimensions.
+For Cosine (Angular) distance, the most common metric in AI, one can expect following performance.
+
+| Method | Vectors | Any Length | Speed on 256b | Speed on 1024b |
+| :----- | :------ | :--------- | ------------: | -------------: |
+| Serial | `f32`   | ✅          |        5 GB/s |         5 GB/s |
+| SVE    | `f32`   | ✅          |       34 GB/s |        40 GB/s |
+| SVE    | `f16`   | ✅          |       28 GB/s |        35 GB/s |
+| NEON   | `f16`   | ❌          |       16 GB/s |        18 GB/s |
+
+> The benchmarks were done on Arm-based "Graviton 3" CPUs powering AWS `c7g.metal` instances.
+> We only use Arm NEON implementation with vectors lengths that are multiples of 128 bits, avoiding any additional head or tail `for` loops for misaligned data.
+> By default, we use GCC12, `-O3`, `-march=native` for benchmarks.
+> Serial versions imply auto-vectorization pragmas.
 
 Need something like this in your CMake-based project?
 
@@ -26,49 +28,76 @@ FetchContent_MakeAvailable(simsimd)
 include_directories(${simsimd_SOURCE_DIR}/include)
 ```
 
-## Benchmarks
-
-By default, we use GCC12, `-O3`, `-march=native` for benchmarks.
-Serial versions imply auto-vectorization pragmas.
+Want to use in Python with [USearch](https://github.com/unum-cloud/usearch)?
 
----
+```py
+from usearch import Index, CompiledMetric, MetricKind, MetricSignature
+from simsimd import to_int, cos_f32x4_neon
 
-Cosine distance performance on a single core of a 64-core Arm-based "Graviton 3" CPUs powering AWS `c7g.metal` instances:
-
-| Method | Vectors    | Any Length | Performance |
-| :----- | :--------- | :--------- | ----------: |
-| Serial | `f32` x16  | ✅          |      5 GB/s |
-| Serial | `f32` x256 | ✅          |      5 GB/s |
-|        |            |            |             |
-| NEON   | `f32` x16  | ❌          |     18 GB/s |
-| NEON   | `f32` x256 | ❌          |     29 GB/s |
-|        |            |            |             |
-| SVE    | `f32` x16  | ✅          |     15 GB/s |
-| SVE    | `f32` x256 | ✅          |     39 GB/s |
-
-We only use Arm NEON implementation with vectors lengths that are multiples of 128 bits, avoiding any additional head or tail `for` loops for misaligned data.
-SVE looses to NEON on very short vectors, but outperforms on longer sequences.
-
----
+metric = CompiledMetric(
+    pointer=to_int(cos_f32x4_neon),
+    kind=MetricKind.Cos,
+    signature=MetricSignature.ArrayArraySize,
+)
 
-On the x86 AMD Zen2 cores making up the 64-core Threadripper PRO 3995WX the numbers are:
+index = Index(256, metric=metric)
+```
 
-| Method  | Vectors    | Any Length | Performance |
-| :------ | :--------- | :--------- | ----------: |
-| Serial  | `f32` x16  | ✅          |      9 GB/s |
-| Serial  | `f32` x256 | ✅          |     10 GB/s |
-|         |            |            |             |
-| AVX-FMA | `f32` x16  | ❌          |     20 GB/s |
-| AVX-FMA | `f32` x256 | ❌          |     24 GB/s |
+## Available Metrics
+
+In the C99 interface all function are prepended with `simsimd_` namespace prefix.
+Signature defines the number of arguments:
+
+- two pointers, and length,
+- two pointers.
+
+The latter is obviously intended for cases, where the number of dimensions is hard-coded.
+Constraints define the limitations on the number of dimensions that an argument vector can have.
+
+| Name                    | Signature | ISA Extesion |  Constraints   |
+| :---------------------- | :-------: | :----------: | :------------: |
+| `dot_f32_sve`           |    ✳️✳️📏    |   Arm SVE    |                |
+| `dot_f32x4_neon`        |    ✳️✳️📏    |   Arm NEON   |  `d % 4 == 0`  |
+| `cos_f32_sve`           |    ✳️✳️📏    |   Arm SVE    |                |
+| `cos_f16_sve`           |    ✳️✳️📏    |   Arm SVE    |                |
+| `cos_f16x4_neon`        |    ✳️✳️📏    |   Arm NEON   |  `d % 4 == 0`  |
+| `cos_i8x16_neon`        |    ✳️✳️📏    |   Arm NEON   | `d % 16 == 0`  |
+| `cos_f32x4_neon`        |    ✳️✳️📏    |   Arm NEON   |  `d % 4 == 0`  |
+| `cos_f16x16_avx512`     |    ✳️✳️📏    | x86 AVX-512  | `d % 16 == 0`  |
+| `cos_f32x4_avx2`        |    ✳️✳️📏    |   x86 AVX2   |  `d % 4 == 0`  |
+| `l2sq_f32_sve`          |    ✳️✳️📏    |   Arm SVE    |                |
+| `l2sq_f16_sve`          |    ✳️✳️📏    |   Arm SVE    |                |
+| `hamming_b1x8_sve`      |    ✳️✳️📏    |   Arm SVE    |  `d % 8 == 0`  |
+| `hamming_b1x128_sve`    |    ✳️✳️📏    |   Arm SVE    | `d % 128 == 0` |
+| `hamming_b1x128_avx512` |    ✳️✳️📏    | x86 AVX-512  | `d % 128 == 0` |
+| `tanimoto_b1x8_naive`   |    ✳️✳️📏    |              |  `d % 8 == 0`  |
+| `tanimoto_maccs_naive`  |    ✳️✳️     |              |   `d == 166`   |
+| `tanimoto_maccs_neon`   |    ✳️✳️     |   Arm NEON   |   `d == 166`   |
+| `tanimoto_maccs_sve`    |    ✳️✳️     |   Arm SVE    |   `d == 166`   |
+| `tanimoto_maccs_avx512` |    ✳️✳️     | x86 AVX-512  |   `d == 166`   |
 
-The gap between auto-vectorized code and directly using 128-bit registers is much less pronounced.
-With AVX2 and 256-bit registers the results should be better, but would be less broadly applicable.
+## Benchmarks
 
----
+The benchmarks are repeated for every function with a different number of cores involved.
+Light-weight distance functions would be memory bound, implying that multi-core performance may be lower, if the bus bandwidth is not enough to saturate all the cores.
+Similarly, heavy-weight distance functions running on all cores may result in CPU frequency downclocking.
+This is well illustrated by the single-core performance of `i9-13950HX`, equipped with DDR5 memory.
+
+| Method                 | Threads | Speed on 1024b |
+| :--------------------- | ------: | -------------: |
+| `tanimoto_maccs_naive` |       1 |       2.8 Gb/s |
+| `tanimoto_maccs_naive` |      32 |       1.2 Gb/s |
+| `cos_f32_naive`        |       1 |      15.3 Gb/s |
+| `cos_f32_naive`        |      32 |       4.5 Gb/s |
+| `dot_f32x4_avx2`       |       1 |      96.2 Gb/s |
+| `dot_f32x4_avx2`       |      32 |      23.6 Gb/s |
+| `cos_f32x4_avx2`       |       1 |      56.3 Gb/s |
+| `cos_f32x4_avx2`       |      32 |      13.9 Gb/s |
 
 To replicate on your hardware, please run following on Linux:
 
 ```sh
+git clone https://github.com/ashvardanian/SimSIMD.git && cd SimSIMD
 cmake -DCMAKE_BUILD_TYPE=Release -DSIMSIMD_BUILD_BENCHMARKS=1 -B ./build && make -C ./build && ./build/simsimd_bench
 ```
 
@@ -76,10 +105,17 @@ MacOS:
 
 ```sh
 brew install llvm
+git clone https://github.com/ashvardanian/SimSIMD.git && cd SimSIMD
 cmake -B ./build \
     -DCMAKE_C_COMPILER="/opt/homebrew/opt/llvm/bin/clang" \
     -DCMAKE_CXX_COMPILER="/opt/homebrew/opt/llvm/bin/clang++" \
     -DSIMSIMD_BUILD_BENCHMARKS=1 \
     && \
     make -C ./build -j && ./build/simsimd_bench
-```
+```
+
+Install and test locally:
+
+```sh
+pip install -e . && pytest python/test.py -s -x
+```

package/simsimd/bench.cxx

@@ -3,16 +3,24 @@
 #include <benchmark/benchmark.h>
 
 #include <simsimd/simsimd.h>
+#include <simsimd/simsimd_chem.h>
 
 namespace bm = benchmark;
 
 static const std::size_t threads_k = std::thread::hardware_concurrency();
-static const std::size_t time_k = 10;
+static constexpr std::size_t time_k = 10;
+static constexpr std::size_t bytes_k = 1024;
 
-template <typename scalar_at, typename metric_at, std::size_t bytes_per_vector_ak = 256,
-          std::size_t dimensions_ak = bytes_per_vector_ak / sizeof(scalar_at)> //
+template <typename return_at, typename... args_at>
+constexpr std::size_t number_of_arguments(return_at (*f)(args_at...)) {
+    return sizeof...(args_at);
+}
+
+template <typename scalar_at, std::size_t bytes_per_vector_ak = bytes_k,
+          typename metric_at = void> //
 static void measure(bm::State& state, metric_at metric) {
 
+    constexpr ::size_t dimensions_ak = bytes_per_vector_ak / sizeof(scalar_at);
     alignas(64) scalar_at a[dimensions_ak]{};
     alignas(64) scalar_at b[dimensions_ak]{};
     float c{};
@@ -20,15 +28,37 @@ static void measure(bm::State& state, metric_at metric) {
     std::fill_n(a, dimensions_ak, static_cast<scalar_at>(1));
     std::fill_n(b, dimensions_ak, static_cast<scalar_at>(2));
 
+    std::size_t iterations = 0;
     for (auto _ : state)
-        bm::DoNotOptimize((c = metric(a, b, dimensions_ak)));
+        if constexpr (number_of_arguments(metric_at{}) == 3)
+            bm::DoNotOptimize((c = metric(a, b, dimensions_ak))), iterations++;
+        else
+            bm::DoNotOptimize((c = metric(a, b))), iterations++;
+
+    state.counters["bytes"] = bm::Counter(iterations * bytes_per_vector_ak * 2u, bm::Counter::kIsRate);
+    state.counters["pairs"] = bm::Counter(iterations, bm::Counter::kIsRate);
+}
 
-    state.SetBytesProcessed(state.iterations() * bytes_per_vector_ak * 2u);
-    state.SetItemsProcessed(state.iterations());
+template <typename scalar_at, std::size_t bytes_per_vector_ak = bytes_k, typename metric_at = void>
+void register_(char const* name, metric_at distance_func) {
+    bm::RegisterBenchmark(name, measure<scalar_at, bytes_per_vector_ak, metric_at>, distance_func)
+        ->Threads(1)
+        ->MinTime(time_k);
+    bm::RegisterBenchmark(name, measure<scalar_at, bytes_per_vector_ak, metric_at>, distance_func)
+        ->Threads(threads_k)
+        ->MinTime(time_k);
 }
 
-template <typename scalar_at, typename metric_at> void register_(char const* name, metric_at distance_func) {
-    bm::RegisterBenchmark(name, measure<scalar_at, metric_at>, distance_func)->Threads(threads_k)->MinTime(time_k);
+simsimd_f32_t cos_f32_naive(simsimd_f32_t* v1, simsimd_f32_t* v2, std::size_t n) {
+    simsimd_f32_t inner_product = 0;
+    simsimd_f32_t magnitude1 = 0;
+    simsimd_f32_t magnitude2 = 0;
+    for (std::size_t i = 0; i != n; ++i) {
+        inner_product += v1[i] * v2[i];
+        magnitude1 += v1[i] * v1[i];
+        magnitude2 += v2[i] * v2[i];
+    }
+    return 1 - inner_product / (std::sqrt(magnitude1) * std::sqrt(magnitude2));
 }
 
 int main(int argc, char** argv) {
@@ -45,7 +75,7 @@ int main(int argc, char** argv) {
     compiled_with_neon = true;
 #endif
 #if defined(__AVX2__)
-    compiled_withavx2 = true;
+    compiled_with_avx2 = true;
 #endif
 #if defined(__AVX512VPOPCNTDQ__)
     compiled_with_avx512popcnt = true;
@@ -59,6 +89,7 @@ int main(int argc, char** argv) {
     std::printf("- Arm SVE support enabled: %s\n", flags[compiled_with_sve]);
     std::printf("- x86 AVX2 support enabled: %s\n", flags[compiled_with_avx2]);
     std::printf("- x86 AVX512VPOPCNTDQ support enabled: %s\n", flags[compiled_with_avx512popcnt]);
+    std::printf("Default vector length: %zu bytes\n", bytes_k);
     std::printf("\n");
 
     // Run the benchmarks
@@ -66,33 +97,41 @@ int main(int argc, char** argv) {
     if (bm::ReportUnrecognizedArguments(argc, argv))
         return 1;
 
+    register_<std::uint8_t, 21>("tanimoto_maccs_naive", simsimd_tanimoto_maccs_naive);
+    register_<simsimd_f32_t>("cos_f32_naive", cos_f32_naive);
+
 #if defined(__ARM_FEATURE_SVE)
-    register_<simsimd_f32_t>("dot_f32sve", simsimd_dot_f32sve);
-    register_<simsimd_f32_t>("cos_f32sve", simsimd_cos_f32sve);
-    register_<simsimd_f32_t>("l2sq_f32sve", simsimd_l2sq_f32sve);
-    register_<std::int16_t>("l2sq_f16sve", simsimd_l2sq_f16sve);
-    register_<std::uint8_t>("hamming_b1x8sve", simsimd_hamming_b1x8sve);
-    register_<std::uint8_t>("hamming_b1x128sve", simsimd_hamming_b1x128sve);
+    register_<simsimd_f32_t>("dot_f32_sve", simsimd_dot_f32_sve);
+    register_<simsimd_f32_t>("cos_f32_sve", simsimd_cos_f32_sve);
+    register_<std::int16_t>("cos_f16_sve", simsimd_cos_f16_sve);
+    register_<simsimd_f32_t>("l2sq_f32_sve", simsimd_l2sq_f32_sve);
+    register_<std::int16_t>("l2sq_f16_sve", simsimd_l2sq_f16_sve);
+    register_<std::uint8_t>("hamming_b1x8_sve", simsimd_hamming_b1x8_sve);
+    register_<std::uint8_t>("hamming_b1x128_sve", simsimd_hamming_b1x128_sve);
+    register_<std::uint8_t, 21>("tanimoto_maccs_sve", simsimd_tanimoto_maccs_sve);
 #endif
 
 #if defined(__ARM_NEON)
-    register_<simsimd_f32_t>("dot_f32x4neon", simsimd_dot_f32x4neon);
-    register_<std::int16_t>("cos_f16x4neon", simsimd_cos_f16x4neon);
-    register_<std::int8_t>("cos_i8x16neon", simsimd_cos_i8x16neon);
-    register_<simsimd_f32_t>("cos_f32x4neon", simsimd_cos_f32x4neon);
+    register_<simsimd_f32_t>("dot_f32x4_neon", simsimd_dot_f32x4_neon);
+    register_<std::int16_t>("cos_f16x4_neon", simsimd_cos_f16x4_neon);
+    register_<std::int8_t>("cos_i8x16_neon", simsimd_cos_i8x16_neon);
+    register_<simsimd_f32_t>("cos_f32x4_neon", simsimd_cos_f32x4_neon);
+    register_<std::uint8_t, 21>("tanimoto_maccs_neon", simsimd_tanimoto_maccs_neon);
 #endif
 
 #if defined(__AVX2__)
-    register_<simsimd_f32_t>("dot_f32x4avx2", simsimd_dot_f32x4avx2);
-    register_<std::int8_t>("dot_i8x16avx2", simsimd_dot_i8x16avx2);
-    register_<simsimd_f32_t>("cos_f32x4avx2", simsimd_cos_f32x4avx2);
+    register_<simsimd_f32_t>("dot_f32x4_avx2", simsimd_dot_f32x4_avx2);
+    register_<simsimd_f32_t>("cos_f32x4_avx2", simsimd_cos_f32x4_avx2);
 #endif
 
 #if defined(__AVX512F__)
-    register_<std::int16_t>("cos_f16x16avx512", simsimd_cos_f16x16avx512);
-    register_<std::uint8_t>("hamming_b1x128avx512", simsimd_hamming_b1x128avx512);
+    register_<std::int16_t>("cos_f16x16_avx512", simsimd_cos_f16x16_avx512);
+    register_<std::uint8_t>("hamming_b1x128_avx512", simsimd_hamming_b1x128_avx512);
+    register_<std::uint8_t, 21>("tanimoto_maccs_avx512", simsimd_tanimoto_maccs_avx512);
 #endif
 
+
+
     bm::RunSpecifiedBenchmarks();
     bm::Shutdown();
     return 0;