usearch 2.8.1 → 2.8.3

package/.github/workflows/release.yml

@@ -25,7 +25,7 @@ jobs:
         with:
           persist-credentials: false
       - uses: actions/setup-node@v3
-      - run: npm install --save-dev @semantic-release/exec @semantic-release/git conventional-changelog-eslint semantic-release && npx semantic-release
+      - run: npm install --save-dev --prefix ./package-ci @semantic-release/exec @semantic-release/git conventional-changelog-eslint semantic-release && npx --prefix ./package-ci semantic-release
 
   rebase:
     name: Rebase Dev. Branch

package/CITATION.cff

@@ -5,7 +5,7 @@ authors:
   given-names: "Ash"
   orcid: "https://orcid.org/0000-0002-4882-1815"
 title: "USearch by Unum Cloud"
-version: 2.8.1
+version: 2.8.3
 doi: 10.5281/zenodo.7949416
 date-released: 2023-10-22
 url: "https://github.com/unum-cloud/usearch"

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "2.8.1"
+version = "2.8.3"
 authors = ["Ash Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "Smaller & Faster Single-File Vector Search Engine from Unum"
 edition = "2021"

package/README.md

@@ -392,7 +392,7 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.8.1},
+version = {2.8.3},
 year = {2023},
 month = oct,
 }

package/conanfile.py

@@ -7,7 +7,7 @@ required_conan_version = ">=1.53.0"
 class USearchConan(ConanFile):
 
     name = "usearch"
-    version = '2.8.1'
+    version = '2.8.3'
     license = "Apache-2.0"
     description = "Smaller & Faster Single-File Vector Search Engine from Unum"
     homepage = "https://github.com/unum-cloud/usearch"

package/csharp/nuget/nuget-package.props

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project>
   <PropertyGroup>
-    <Version Condition="'$(Version)' == ''">2.8.1</Version>
+    <Version Condition="'$(Version)' == ''">2.8.3</Version>
 
     <Authors>Unum</Authors>
     <Company>Unum</Company>

package/include/usearch/index.hpp

@@ -11,7 +11,7 @@
 
 #define USEARCH_VERSION_MAJOR 2
 #define USEARCH_VERSION_MINOR 8
-#define USEARCH_VERSION_PATCH 1
+#define USEARCH_VERSION_PATCH 3
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074
@@ -547,6 +547,7 @@ class max_heap_gt {
     inline bool empty() const noexcept { return !size_; }
     inline std::size_t size() const noexcept { return size_; }
     inline std::size_t capacity() const noexcept { return capacity_; }
+
     /// @brief  Selects the largest element in the heap.
     /// @return Reference to the stored element.
     inline element_t const& top() const noexcept { return elements_[0]; }
@@ -2205,7 +2206,7 @@ class index_gt {
             node_t node = nodes_[candidate.slot];
             return {member_cref_t{node.ckey(), candidate.slot}, candidate.distance};
         }
-        inline std::size_t merge_into(          //
+        inline std::size_t merge_into(                 //
             vector_key_t* keys, distance_t* distances, //
             std::size_t old_count, std::size_t max_count) const noexcept {
 
@@ -2279,10 +2280,10 @@ class index_gt {
         typename callback_at = dummy_callback_t, //
         typename prefetch_at = dummy_prefetch_t  //
         >
-    add_result_t add(                                    //
+    add_result_t add(                                           //
         vector_key_t key, value_at&& value, metric_at&& metric, //
-        index_update_config_t config = {},               //
-        callback_at&& callback = callback_at{},          //
+        index_update_config_t config = {},                      //
+        callback_at&& callback = callback_at{},                 //
         prefetch_at&& prefetch = prefetch_at{}) usearch_noexcept_m {
 
         add_result_t result;
@@ -2389,7 +2390,7 @@ class index_gt {
         >
     add_result_t update(                        //
         member_iterator_t iterator,             //
-        vector_key_t key,                              //
+        vector_key_t key,                       //
         value_at&& value,                       //
         metric_at&& metric,                     //
         index_update_config_t config = {},      //

package/javascript/usearch.js

@@ -84,7 +84,7 @@ class BatchMatches {
 }
 
 function isOneKey(keys) {
-    return typeof keys === 'number' || typeof keys === 'bigint';
+    return (!Number.isNaN(keys) && typeof keys === 'number') || typeof keys === 'bigint';
 }
 
 function normalizeKeys(keys) {
@@ -92,7 +92,7 @@ function normalizeKeys(keys) {
         keys = BigUint64Array.of(BigInt(keys));
     } else if (Array.isArray(keys)) {
         keys = keys.map(key => {
-            if (typeof key !== 'bigint' && typeof key !== 'number')
+            if ((typeof key !== 'bigint' && typeof key !== 'number') || Number.isNaN(key))
                 throw new Error("All keys must be integers or bigints.");
             return BigInt(key);
         });
@@ -151,7 +151,7 @@ class Index {
         if (typeof dimensionsOrConfigs === 'object' && dimensionsOrConfigs !== null) {
             // Parameters are provided as an object
             ({ dimensions, metric = MetricKind.Cos, quantization = ScalarKind.F32, connectivity = 0, expansion_add = 0, expansion_search = 0, multi = false } = dimensionsOrConfigs);
-        } else if (typeof dimensionsOrConfigs === 'number' || typeof dimensionsOrConfigs === 'bigint') {
+        } else if ((typeof dimensionsOrConfigs === 'number' && !Number.isNaN(dimensionsOrConfigs)) || typeof dimensionsOrConfigs === 'bigint') {
             // Parameters are provided as individual arguments
             dimensions = dimensionsOrConfigs;
         } else {
@@ -238,7 +238,7 @@ class Index {
      * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of arrays) or if its flattened size is not a multiple of dimensions.
      */
     search(vectors, k) {
-        if (typeof k !== 'number' || k <= 0) {
+        if ((!Number.isNaN(k) && typeof k !== 'number') || k <= 0) {
             throw new Error("`k` must be a positive integer representing the number of nearest neighbors to search for.");
         }
 

package/javascript/usearch.test.js

@@ -35,3 +35,25 @@ test('Batch operations', () => {
     assert.deepEqual(results.keys, new BigUint64Array([15n, 16n]), 'keys should be 15 and 16');
     assert.deepEqual(results.distances, new Float32Array([45, 130]), 'distances should be 45 and 130');
 });
+
+
+test('Operations with invalid values', () => {
+    const indexBatch = new usearch.Index(2, 'l2sq');
+
+    const keys = [NaN, 16n];
+    const vectors = [new Float32Array([10, 30]), new Float32Array([1, 5])];
+
+    try {
+        indexBatch.add(keys, vectors);
+        throw new Error('indexBatch.add should have thrown an error.');
+    } catch (err) {
+        assert.equal(err.message, 'All keys must be integers or bigints.');
+    }
+
+    try {
+        indexBatch.search(NaN, 2);
+        throw new Error('indexBatch.search should have thrown an error.');
+    } catch (err) {
+        assert.equal(err.message, 'Vectors must be a TypedArray or an array of arrays.');
+    }
+});

package/package-ci.json

@@ -0,0 +1,10 @@
+{
+    "name": "usearch-ci",
+    "version": "1.0.0",
+    "devDependencies": {
+        "@semantic-release/exec": "^6.0.3",
+        "@semantic-release/git": "^10.0.1",
+        "conventional-changelog-eslint": "^3.0.9",
+        "semantic-release": "^21.1.2"
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.8.1",
+    "version": "2.8.3",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian (https://ashvardanian.com/)",
     "license": "Apache 2.0",
@@ -27,10 +27,6 @@
         "test": "node --test ./javascript/usearch.test.js"
     },
     "devDependencies": {
-        "@semantic-release/exec": "^6.0.3",
-        "@semantic-release/git": "^10.0.1",
-        "conventional-changelog-eslint": "^3.0.9",
-        "semantic-release": "^21.1.2",
         "typescript": "^5.1.6"
     }
 }

package/simsimd/.github/workflows/prerelease.yml

@@ -61,20 +61,29 @@ jobs:
 
   test_javascript:
     name: Test JavaScript
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        os: [ubuntu-22.04, macOS-11, windows-2022]
-        node-version: [18.x]
+    runs-on: ubuntu-22.04
+    env:
+      CC: gcc-12
+      CXX: g++-12
+
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: "main"
+      - run: git submodule update --init --recursive
+
+      - name: Update compilers
+        run: |
+          sudo apt update
+          sudo apt install -y cmake build-essential libjemalloc-dev libomp-dev gcc-12 g++-12
+
       - name: Set up Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: "18.x"
+          node-version: 18
 
-      - name: Build locally
-        run: npm install
-
-      - name: Test
-        run: npm test
+      - name: Build and Test
+        run: |
+          npm install
+          npm ci
+          npm test

package/simsimd/.github/workflows/release.yml

@@ -18,18 +18,18 @@ permissions:
 jobs:
   versioning:
     name: Semantic Release
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v3
         with:
           persist-credentials: false
       - uses: actions/setup-node@v3
-      - run: npm install --save-dev @semantic-release/exec @semantic-release/git conventional-changelog-eslint semantic-release && npx semantic-release
+      - run: npm install --save-dev --prefix ./package-ci @semantic-release/exec @semantic-release/git conventional-changelog-eslint semantic-release && npx --prefix ./package-ci semantic-release
 
   rebase:
     name: Rebase Dev. Branch
     needs: versioning
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout the latest code
         uses: actions/checkout@v3
@@ -109,17 +109,33 @@ jobs:
     name: Publish JavaScript
     needs: versioning
     runs-on: ubuntu-22.04
+    env:
+      CC: gcc-12
+      CXX: g++-12
+
     steps:
       - uses: actions/checkout@v3
         with:
           ref: "main"
       - run: git submodule update --init --recursive
-      - uses: actions/setup-node@v3
+
+      - name: Update compilers
+        run: |
+          sudo apt update
+          sudo apt install -y cmake build-essential libjemalloc-dev libomp-dev gcc-12 g++-12
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
         with:
           node-version: 18
-      - run: npm install
-      - run: npm ci
-      - run: npm test
-      - uses: JS-DevTools/npm-publish@v2
+
+      - name: Build and Test
+        run: |
+          npm install
+          npm ci
+          npm test
+
+      - name: Publish
+        uses: JS-DevTools/npm-publish@v2
         with:
           token: ${{ secrets.NPM_TOKEN }}

package/simsimd/CMakeLists.txt

@@ -46,9 +46,9 @@ if(CMAKE_CXX_COMPILER_ID MATCHES "^(Apple)?Clang$")
   if(NOT APPLE)
     add_compile_options(-march=native)
   endif()
-  add_compile_options(-pedantic -ferror-limit=1 -ffast-math)
+  add_compile_options(-pedantic -ferror-limit=1)
 elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-  add_compile_options(-march=native -pedantic -fmax-errors=1 -ffast-math)
+  add_compile_options(-march=native -pedantic -fmax-errors=1)
 elseif(CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM")
   add_compile_options(-w -ferror-limit=1)
 endif()

package/simsimd/README.md

@@ -34,7 +34,7 @@ Given 1000 embeddings from OpenAI Ada API with 1536 dimensions, running on the A
 
 ### Intel Sapphire Rapids
 
-On the Intel Sapphire Rapids platform, SimSIMD was benchmarked against auto-vectorized code using GCC 12. GCC handles single-precision `float` and `int8_t` well. However, it fails on `_Float16` arrays, which has been part of the C language since 2011.
+On the Intel Sapphire Rapids platform, SimSIMD was benchmarked against auto-vectorized code using GCC 12. GCC handles single-precision `float`, but might not be the best choice for `int8` and `_Float16` arrays, which has been part of the C language since 2011.
 
 |                 | GCC 12 `f32` | GCC 12 `f16` | SimSIMD `f16` | `f16` improvement |
 | :-------------- | -----------: | -----------: | ------------: | ----------------: |

package/simsimd/cpp/bench.cxx

@@ -3,8 +3,8 @@
 
 #include <benchmark/benchmark.h>
 
-#define SIMSIMD_RSQRT sqrtf
-#define SIMSIMD_LOG logf
+#define SIMSIMD_RSQRT(x) (1 / sqrtf(x))
+#define SIMSIMD_LOG(x) (logf(x))
 #include <simsimd/simsimd.h>
 
 namespace bm = benchmark;
@@ -78,7 +78,7 @@ void register_(std::string name, metric_at* distance_func, metric_at* baseline_f
     using pair_bytes_t = vectors_pair_gt<scalar_at, 1536 / sizeof(scalar_at)>;
 
     std::size_t seconds = 10;
-    std::size_t threads = std::thread::hardware_concurrency(); // 1;
+    std::size_t threads = 1; // std::thread::hardware_concurrency(); // 1;
     std::string name_dims = name + "_" + std::to_string(pair_dims_t{}.dimensions()) + "d";
     std::string name_bytes = name + "_" + std::to_string(pair_bytes_t{}.size_bytes()) + "b";
 
@@ -95,7 +95,8 @@ int main(int argc, char** argv) {
     bool compiled_with_sve = false;
     bool compiled_with_neon = false;
     bool compiled_with_avx2 = false;
-    bool compiled_with_avx512popcnt = false;
+    bool compiled_with_avx512vpopcntdq = false;
+    bool compiled_with_avx512vnni = false;
 
 #if defined(__ARM_FEATURE_SVE)
     compiled_with_sve = true;
@@ -107,7 +108,10 @@ int main(int argc, char** argv) {
     compiled_with_avx2 = true;
 #endif
 #if defined(__AVX512VPOPCNTDQ__)
-    compiled_with_avx512popcnt = true;
+    compiled_with_avx512vpopcntdq = true;
+#endif
+#if defined(__AVX512VNNI__)
+    compiled_with_avx512vnni = true;
 #endif
 
     // Log supported functionality
@@ -117,7 +121,8 @@ int main(int argc, char** argv) {
     std::printf("- Arm NEON support enabled: %s\n", flags[compiled_with_neon]);
     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("- x86 AVX512VPOPCNTDQ support enabled: %s\n", flags[compiled_with_avx512vpopcntdq]);
+    std::printf("- x86 AVX512VNNI support enabled: %s\n", flags[compiled_with_avx512vnni]);
     std::printf("\n");
 
     // Run the benchmarks

package/simsimd/include/simsimd/binary.h

@@ -133,41 +133,55 @@ simsimd_sve_b8_jaccard(simsimd_b8_t const* a, simsimd_b8_t const* b, simsimd_siz
 
 #if SIMSIMD_TARGET_X86_AVX512
 
-__attribute__((target("avx512vpopcntdq,avx512vl,avx512bw,avx512f"))) //
+__attribute__((target("avx512vpopcntdq,avx512vl,avx512bw,avx512f,bmi2"))) //
 inline static simsimd_f32_t
 simsimd_avx512_b8_hamming(simsimd_b8_t const* a, simsimd_b8_t const* b, simsimd_size_t n_words) {
     __m512i differences_vec = _mm512_setzero_si512();
-    for (simsimd_size_t i = 0; i < n_words; i += 64) {
-
-        // Compute mask for tail elements
-        __mmask64 mask = (i + 64 <= n_words) ? 0xFFFFFFFFFFFFFFFF : (((1ull << (n_words - i)) - 1ull));
-        __m512i a_vec = _mm512_maskz_loadu_epi8(mask, a + i);
-        __m512i b_vec = _mm512_maskz_loadu_epi8(mask, b + i);
-        __m512i xor_vec = _mm512_xor_si512(a_vec, b_vec);
-
-        differences_vec = _mm512_add_epi64(differences_vec, _mm512_popcnt_epi64(xor_vec));
+    __m512i a_vec, b_vec;
+
+simsimd_avx512_b8_hamming_cycle:
+    if (n_words < 64) {
+        __mmask64 mask = _bzhi_u64(0xFFFFFFFFFFFFFFFF, n_words);
+        a_vec = _mm512_maskz_loadu_epi8(mask, a);
+        b_vec = _mm512_maskz_loadu_epi8(mask, b);
+        n_words = 0;
+    } else {
+        a_vec = _mm512_loadu_epi8(a);
+        b_vec = _mm512_loadu_epi8(b);
+        a += 64, b += 64, n_words -= 64;
     }
+    __m512i xor_vec = _mm512_xor_si512(a_vec, b_vec);
+    differences_vec = _mm512_add_epi64(differences_vec, _mm512_popcnt_epi64(xor_vec));
+    if (n_words)
+        goto simsimd_avx512_b8_hamming_cycle;
 
     simsimd_size_t differences = _mm512_reduce_add_epi64(differences_vec);
     return (simsimd_f32_t)differences;
 }
 
-__attribute__((target("avx512vpopcntdq,avx512vl,avx512bw,avx512f"))) //
+__attribute__((target("avx512vpopcntdq,avx512vl,avx512bw,avx512f,bmi2"))) //
 inline static simsimd_f32_t
 simsimd_avx512_b8_jaccard(simsimd_b8_t const* a, simsimd_b8_t const* b, simsimd_size_t n_words) {
     __m512i intersection_vec = _mm512_setzero_si512(), union_vec = _mm512_setzero_si512();
-    for (simsimd_size_t i = 0; i < n_words; i += 64) {
-
-        // Compute mask for tail elements
-        __mmask64 mask = (i + 64 <= n_words) ? 0xFFFFFFFFFFFFFFFF : (((1ull << (n_words - i)) - 1ull));
-        __m512i a_vec = _mm512_maskz_loadu_epi8(mask, a + i);
-        __m512i b_vec = _mm512_maskz_loadu_epi8(mask, b + i);
-        __m512i and_vec = _mm512_and_si512(a_vec, b_vec);
-        __m512i or_vec = _mm512_or_si512(a_vec, b_vec);
-
-        intersection_vec = _mm512_add_epi64(intersection_vec, _mm512_popcnt_epi64(and_vec));
-        union_vec = _mm512_add_epi64(union_vec, _mm512_popcnt_epi64(or_vec));
+    __m512i a_vec, b_vec;
+
+simsimd_avx512_b8_jaccard_cycle:
+    if (n_words < 64) {
+        __mmask64 mask = _bzhi_u64(0xFFFFFFFFFFFFFFFF, n_words);
+        a_vec = _mm512_maskz_loadu_epi8(mask, a);
+        b_vec = _mm512_maskz_loadu_epi8(mask, b);
+        n_words = 0;
+    } else {
+        a_vec = _mm512_loadu_epi8(a);
+        b_vec = _mm512_loadu_epi8(b);
+        a += 64, b += 64, n_words -= 64;
     }
+    __m512i and_vec = _mm512_and_si512(a_vec, b_vec);
+    __m512i or_vec = _mm512_or_si512(a_vec, b_vec);
+    intersection_vec = _mm512_add_epi64(intersection_vec, _mm512_popcnt_epi64(and_vec));
+    union_vec = _mm512_add_epi64(union_vec, _mm512_popcnt_epi64(or_vec));
+    if (n_words)
+        goto simsimd_avx512_b8_jaccard_cycle;
 
     simsimd_size_t intersection = _mm512_reduce_add_epi64(intersection_vec),
                    union_ = _mm512_reduce_add_epi64(union_vec);