usearch 2.9.1 → 2.9.2

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.9.1
+version: 2.9.2
 doi: 10.5281/zenodo.7949416
 date-released: 2023-10-22
 url: "https://github.com/unum-cloud/usearch"

package/CONTRIBUTING.md

@@ -104,6 +104,13 @@ cppcheck --enable=all --force --suppress=cstyleCast --suppress=unusedFunction \
     include/index_plugins.hpp
 ```
 
+I'd recommend putting the following breakpoints when debugging the code in GDB:
+
+- `__asan::ReportGenericError` - to detect illegal memory accesses.
+- `__ubsan::ScopedReport::~ScopedReport` - to catch undefined behavior.
+- `__GI_exit` - to stop at exit points - the end of running any executable.
+- `__builtin_unreachable` - to catch all the places where the code is expected to be unreachable.
+
 ## Python 3
 
 Python bindings are built using PyBind11 and are available on [PyPi](https://pypi.org/project/usearch/).
@@ -215,10 +222,11 @@ USearch provides both Objective-C and Swift bindings through the [Swift Package
 The compilation settings are controlled by the `Package.swift` and are independent from CMake used for C/C++ builds.
 
 ```sh
-swift build
-swift test -v
+swift build && swift test -v
 ```
 
+Those depend on Apple's `Foundation` library and can only run on Apple devices.
+
 ## GoLang
 
 USearch provides GoLang bindings, that depend on the C library that must be installed beforehand.

package/Cargo.toml

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

package/README.md

@@ -30,19 +30,18 @@ Spatial • Binary • Probabilistic • User-Defined Metrics
 <a href="https://unum-cloud.github.io/usearch/swift">Swift</a> •
 <a href="https://unum-cloud.github.io/usearch/csharp">C#</a> •
 <a href="https://unum-cloud.github.io/usearch/golang">GoLang</a> •
-<a href="https://unum-cloud.github.io/usearch/wolfram">Wolfram</a> •
-<a href="https://unum-cloud.github.io/usearch/sqlite">SQLite3</a>
+<a href="https://unum-cloud.github.io/usearch/wolfram">Wolfram</a>
 <br/>
-Linux • MacOS • Windows • iOS • WebAssembly
+Linux • MacOS • Windows • iOS • WebAssembly •
+<a href="https://unum-cloud.github.io/usearch/sqlite">SQLite3</a>
 </p>
 
 <div align="center">
-<a href="https://pepy.tech/project/usearch"> <img alt="PyPI" src="https://static.pepy.tech/personalized-badge/usearch?period=total&units=abbreviation&left_color=black&right_color=blue&left_text=USearch%20Python%20installs"> </a>
-<a href="https://www.npmjs.com/package/usearch"> <img alt="NPM" src="https://img.shields.io/npm/dy/usearch?label=NPM%20installs"> </a>
-<a href="https://crates.io/crates/usearch"> <img alt="Crate" src="https://img.shields.io/crates/d/usearch?label=Crate%20installs"> </a>
-<a href="https://www.nuget.org/packages/Cloud.Unum.USearch"> <img alt="NuGet" src="https://img.shields.io/nuget/dt/Cloud.Unum.USearch?label=NuGet%20installs"> </a>
-<a href="https://central.sonatype.com/artifact/cloud.unum/usearch/overview"> <img alt="Maven" src="https://img.shields.io/nexus/r/cloud.unum/usearch?server=https%3A%2F%2Fs01.oss.sonatype.org%2F&label=Maven%20version"> </a>
-<a href="https://hub.docker.com/r/unum/usearch"> <img alt="Docker" src="https://img.shields.io/docker/pulls/unum/usearch?label=Docker%20installs"> </a>
+<a href="https://pepy.tech/project/usearch"> <img alt="PyPI" src="https://static.pepy.tech/personalized-badge/usearch?period=total&units=abbreviation&left_color=black&right_color=blue&left_text=Python%20PyPi%20installs"> </a>
+<a href="https://www.npmjs.com/package/usearch"> <img alt="NPM" src="https://img.shields.io/npm/dy/usearch?label=JavaScript%20NPM%20installs"> </a>
+<a href="https://crates.io/crates/usearch"> <img alt="Crate" src="https://img.shields.io/crates/d/usearch?label=Rust%20Crate%20installs"> </a>
+<a href="https://www.nuget.org/packages/Cloud.Unum.USearch"> <img alt="NuGet" src="https://img.shields.io/nuget/dt/Cloud.Unum.USearch?label=CSharp%20NuGet%20installs"> </a>
+<a href="https://central.sonatype.com/artifact/cloud.unum/usearch/overview"> <img alt="Maven" src="https://img.shields.io/nexus/r/cloud.unum/usearch?server=https%3A%2F%2Fs01.oss.sonatype.org%2F&label=Java%20Maven%20version"> </a>
 <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/unum-cloud/usearch?label=Repo%20size">
 </div>
 
@@ -50,18 +49,16 @@ Linux • MacOS • Windows • iOS • WebAssembly
 
 - ✅ __[10x faster][faster-than-faiss]__ [HNSW][hnsw-algorithm] implementation than [FAISS][faiss].
 - ✅ Simple and extensible [single C++11 header][usearch-header] __library__.
-- ✅ Compatible with a dozen programming languages out of the box.
 - ✅ [Trusted](#integrations) by giants like Google and databases like [ClickHouse][clickhouse-docs].
 - ✅ [SIMD][simd]-optimized and [user-defined metrics](#user-defined-functions) with JIT compilation.
 - ✅ Hardware-agnostic `f16` & `i8` - [half-precision & quarter-precision support](#memory-efficiency-downcasting-and-quantization).
 - ✅ [View large indexes from disk](#serving-index-from-disk) without loading into RAM.
 - ✅ Heterogeneous lookups, renaming/relabeling, and on-the-fly deletions.
-- ✅ Variable dimensionality vectors for unique applications, including search over compressed data.
 - ✅ Binary Tanimoto and Sorensen coefficients for [Genomics and Chemistry applications](#usearch--rdkit--molecular-search).
 - ✅ Space-efficient point-clouds with `uint40_t`, accommodating 4B+ size.
-- ✅ Compatible with OpenMP and custom "executors" for fine-grained control over CPU utilization.
-- ✅ Near-real-time [clustering and sub-clustering](#clustering) for Tens or Millions of clusters.
+- ✅ Compatible with OpenMP and custom "executors" for fine-grained parallelism.
 - ✅ [Semantic Search](#usearch--ai--multi-modal-semantic-search) and [Joins](#joins-one-to-one-one-to-many-and-many-to-many-mappings).
+- 🔄 Near-real-time [clustering and sub-clustering](#clustering) for Tens or Millions of clusters.
 
 [faiss]: https://github.com/facebookresearch/faiss
 [usearch-header]: https://github.com/unum-cloud/usearch/blob/main/include/usearch/index.hpp
@@ -133,7 +130,7 @@ matches = index.search(vector, 10)
 
 assert matches[0].key == 42
 assert matches[0].distance <= 0.001
-assert np.allclose(index[42], vector)
+assert np.allclose(index[42], vector, atol=0.1) # Ensure high tolerance in mixed-precision comparisons
 ```
 
 More settings are always available, and the API is designed to be as flexible as possible.
@@ -434,7 +431,7 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.9.1},
+version = {2.9.2},
 year = {2023},
 month = oct,
 }

package/VERSION

@@ -1 +1 @@
-2.9.1
+2.9.2

package/c/test.c

@@ -35,6 +35,7 @@ usearch_init_options_t create_options(size_t const dimensions) {
     opts.metric_kind = usearch_metric_ip_k;
     opts.metric = NULL;
     opts.quantization = usearch_scalar_f32_k;
+    opts.multi = false;
     return opts;
 }
 
@@ -45,7 +46,7 @@ usearch_init_options_t create_options(size_t const dimensions) {
  *  dimensions, and connectivity after each operation.
  */
 void test_init(size_t const collection_size, size_t const dimensions) {
-    printf("Test: Index Initialization...\n");
+    printf("Test: Index Initialization... %zu vectors, %zu dimensions \n", collection_size, dimensions);
 
     // Init index
     usearch_error_t error = NULL;
@@ -84,7 +85,7 @@ void test_init(size_t const collection_size, size_t const dimensions) {
  *  size, capacity, and presence of each vector in the index.
  */
 void test_add_vector(size_t const collection_size, size_t const dimensions) {
-    printf("Test: Add Vector...\n");
+    printf("Test: Add Vector... %zu vectors, %zu dimensions \n", collection_size, dimensions);
 
     usearch_error_t error = NULL;
     usearch_init_options_t opts = create_options(dimensions);
@@ -120,7 +121,7 @@ void test_add_vector(size_t const collection_size, size_t const dimensions) {
  *  found in the index, validating the count of found vectors.
  */
 void test_find_vector(size_t const collection_size, size_t const dimensions) {
-    printf("Test: Find Vector...\n");
+    printf("Test: Find Vector... %zu vectors, %zu dimensions \n", collection_size, dimensions);
 
     usearch_error_t error = NULL;
     usearch_init_options_t opts = create_options(dimensions);
@@ -161,7 +162,7 @@ void test_find_vector(size_t const collection_size, size_t const dimensions) {
  *  retrieves vectors associated with the key from the index and checks the count of retrieved vectors.
  */
 void test_get_vector(size_t const collection_size, size_t const dimensions) {
-    printf("Test: Get Vector...\n");
+    printf("Test: Get Vector... %zu vectors, %zu dimensions \n", collection_size, dimensions);
 
     usearch_error_t error = NULL;
     usearch_init_options_t opts = create_options(dimensions);
@@ -198,7 +199,7 @@ void test_get_vector(size_t const collection_size, size_t const dimensions) {
  *  the assert in this test expects an error, indicating that the remove functionality is not currently supported.
  */
 void test_remove_vector(size_t const collection_size, size_t const dimensions) {
-    printf("Test: Remove Vector...\n");
+    printf("Test: Remove Vector... %zu vectors, %zu dimensions \n", collection_size, dimensions);
 
     usearch_error_t error = NULL;
     usearch_init_options_t opts = create_options(dimensions);
@@ -232,7 +233,8 @@ void test_remove_vector(size_t const collection_size, size_t const dimensions) {
  *  from the saved index.
  */
 void test_save_load(size_t const collection_size, size_t const dimensions) {
-    printf("Test: Save/Load...\n");
+    printf("Test: Save/Load... %zu vectors, %zu dimensions \n", collection_size, dimensions);
+    float* data = create_vectors(collection_size, dimensions);
 
     usearch_error_t error = NULL;
     usearch_init_options_t opts = create_options(dimensions);
@@ -242,23 +244,26 @@ void test_save_load(size_t const collection_size, size_t const dimensions) {
     weird_ops.expansion_search = 19;
     weird_ops.metric_kind = usearch_metric_pearson_k;
     weird_ops.quantization = usearch_scalar_f64_k;
-    usearch_index_t index = usearch_init(&weird_ops, &error);
-    usearch_reserve(index, collection_size, &error);
 
-    // Add vectors
-    float* data = create_vectors(collection_size, dimensions);
-    for (size_t i = 0; i < collection_size; ++i) {
-        usearch_key_t key = i;
-        usearch_add(index, key, data + i * dimensions, usearch_scalar_f32_k, &error);
+    {
+
+        usearch_index_t index = usearch_init(&weird_ops, &error);
+        usearch_reserve(index, collection_size, &error);
+
+        // Add vectors
+        for (size_t i = 0; i < collection_size; ++i) {
+            usearch_key_t key = i;
+            usearch_add(index, key, data + i * dimensions, usearch_scalar_f32_k, &error);
+            ASSERT(!error, error);
+        }
+
+        // Save and free the index
+        usearch_save(index, "tmp.usearch", &error);
+        ASSERT(!error, error);
+        usearch_free(index, &error);
         ASSERT(!error, error);
     }
 
-    // Save and free the index
-    usearch_save(index, "tmp.usearch", &error);
-    ASSERT(!error, error);
-    usearch_free(index, &error);
-    ASSERT(!error, error);
-
     // Reset the options
     opts.connectivity = 0;
     opts.dimensions = 0;
@@ -269,45 +274,48 @@ void test_save_load(size_t const collection_size, size_t const dimensions) {
     opts.metric_kind = usearch_metric_unknown_k;
 
     // Reinit
-    index = usearch_init(&opts, &error);
-    ASSERT(!error, error);
-    ASSERT(usearch_size(index, &error) == 0, error);
+    {
 
-    // Load
-    usearch_load(index, "tmp.usearch", &error);
-    ASSERT(!error, error);
-    ASSERT(usearch_size(index, &error) == collection_size, error);
-    ASSERT(usearch_capacity(index, &error) == collection_size, error);
-    ASSERT(usearch_dimensions(index, &error) == dimensions, error);
-    ASSERT(usearch_connectivity(index, &error) == weird_ops.connectivity, error);
+        usearch_index_t index = usearch_init(&opts, &error);
+        ASSERT(!error, error);
+        ASSERT(usearch_size(index, &error) == 0, error);
 
-    // Check vectors in the index
-    for (size_t i = 0; i < collection_size; ++i) {
-        usearch_key_t key = i;
-        ASSERT(usearch_contains(index, key, &error), error);
-    }
+        // Load
+        usearch_load(index, "tmp.usearch", &error);
+        ASSERT(!error, error);
+        ASSERT(usearch_size(index, &error) == collection_size, error);
+        ASSERT(usearch_capacity(index, &error) == collection_size, error);
+        ASSERT(usearch_dimensions(index, &error) == dimensions, error);
+        ASSERT(usearch_connectivity(index, &error) == weird_ops.connectivity, error);
+
+        // Check vectors in the index
+        for (size_t i = 0; i < collection_size; ++i) {
+            usearch_key_t key = i;
+            ASSERT(usearch_contains(index, key, &error), error);
+        }
 
-    // Create result buffers
-    usearch_key_t* keys = (usearch_key_t*)malloc(collection_size * sizeof(usearch_key_t));
-    float* distances = (float*)malloc(collection_size * sizeof(float));
-    ASSERT(keys && distances, "Failed to allocate memory");
+        // Create result buffers
+        usearch_key_t* keys = (usearch_key_t*)malloc(collection_size * sizeof(usearch_key_t));
+        float* distances = (float*)malloc(collection_size * sizeof(float));
+        ASSERT(keys && distances, "Failed to allocate memory");
+
+        // Find the vectors
+        for (size_t i = 0; i < collection_size; i++) {
+            size_t found_count = usearch_search(index, data + i * dimensions, usearch_scalar_f32_k, collection_size,
+                                                keys, distances, &error);
+            ASSERT(!error, error);
+            ASSERT(found_count >= 1 && found_count <= collection_size, "Vector is missing");
+        }
 
-    // Find the vectors
-    for (size_t i = 0; i < collection_size; i++) {
-        size_t found_count = usearch_search(index, data + i * dimensions, usearch_scalar_f32_k, collection_size, keys,
-                                            distances, &error);
-        ASSERT(!error, error);
-        ASSERT(found_count >= 1 && found_count <= collection_size, "Vector is missing");
+        free(keys);
+        free(distances);
+        usearch_free(index, &error);
     }
 
     free(data);
-    free(keys);
-    free(distances);
-    usearch_free(index, &error);
 
     // Remove the file from disk
     remove("tmp.usearch");
-
     printf("Test: Save/Load - PASSED\n");
 }
 
@@ -318,7 +326,7 @@ void test_save_load(size_t const collection_size, size_t const dimensions) {
  *  not verify the properties or contents of the viewed index.
  */
 void test_view(size_t const collection_size, size_t const dimensions) {
-    printf("Test: View...\n");
+    printf("Test: View... %zu vectors, %zu dimensions \n", collection_size, dimensions);
 
     usearch_error_t error = NULL;
     usearch_init_options_t opts = create_options(dimensions);
@@ -355,7 +363,7 @@ void test_view(size_t const collection_size, size_t const dimensions) {
 int main(int argc, char const* argv[]) {
 
     size_t collection_sizes[] = {11, 512};
-    size_t dimensions[] = {83, 1};
+    size_t dimensions[] = {83, 2}; // Not all distance functions make sense for 1 dimensional data
     for (size_t index = 0; index < sizeof(collection_sizes) / sizeof(collection_sizes[0]); ++index) {
         for (size_t jdx = 0; jdx < sizeof(dimensions) / sizeof(dimensions[0]); ++jdx) {
             test_init(collection_sizes[index], dimensions[jdx]);

package/conanfile.py

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

package/include/usearch/index.hpp

@@ -11,7 +11,7 @@
 
 #define USEARCH_VERSION_MAJOR 2
 #define USEARCH_VERSION_MINOR 9
-#define USEARCH_VERSION_PATCH 1
+#define USEARCH_VERSION_PATCH 2
 
 // Inferring C++ version
 // https://stackoverflow.com/a/61552074

package/include/usearch/index_plugins.hpp

@@ -926,7 +926,7 @@ class i8_converted_t {
     std::int8_t int8_{};
 
   public:
-    constexpr static float divisor_k = 100.f;
+    constexpr static f32_t divisor_k = 100.f;
     constexpr static std::int8_t min_k = -100;
     constexpr static std::int8_t max_k = 100;
 
@@ -938,9 +938,9 @@ class i8_converted_t {
     inline i8_converted_t(i8_converted_t const&) = default;
     inline i8_converted_t& operator=(i8_converted_t const&) = default;
 
-    inline operator float() const noexcept { return float(int8_) / divisor_k; }
-    inline operator f16_t() const noexcept { return float(int8_) / divisor_k; }
-    inline operator double() const noexcept { return double(int8_) / divisor_k; }
+    inline operator f16_t() const noexcept { return static_cast<f16_t>(f32_t(int8_) / divisor_k); }
+    inline operator f32_t() const noexcept { return f32_t(int8_) / divisor_k; }
+    inline operator f64_t() const noexcept { return f64_t(int8_) / divisor_k; }
     inline explicit operator bool() const noexcept { return int8_ > (max_k / 2); }
     inline explicit operator std::int8_t() const noexcept { return int8_; }
     inline explicit operator std::int16_t() const noexcept { return int8_; }
@@ -949,9 +949,9 @@ class i8_converted_t {
 
     inline i8_converted_t(f16_t v)
         : int8_(usearch::clamp<std::int8_t>(static_cast<std::int8_t>(v * divisor_k), min_k, max_k)) {}
-    inline i8_converted_t(float v)
+    inline i8_converted_t(f32_t v)
         : int8_(usearch::clamp<std::int8_t>(static_cast<std::int8_t>(v * divisor_k), min_k, max_k)) {}
-    inline i8_converted_t(double v)
+    inline i8_converted_t(f64_t v)
         : int8_(usearch::clamp<std::int8_t>(static_cast<std::int8_t>(v * divisor_k), min_k, max_k)) {}
 };
 
@@ -1165,13 +1165,20 @@ template <typename scalar_at = std::int32_t, typename result_at = float> struct
 };
 
 /**
- *  @brief  Measures Pearson Correlation between two sequences.
+ *  @brief  Measures Pearson Correlation between two sequences in a single pass.
  */
 template <typename scalar_at = float, typename result_at = float> struct metric_pearson_gt {
     using scalar_t = scalar_at;
     using result_t = result_at;
 
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t dim) const noexcept {
+        // The correlation coefficient can't be defined for one or zero-dimensional data.
+        if (dim <= 1)
+            return 0;
+        // Conventional Pearson Correlation Coefficient definiton subtracts the mean value of each
+        // sequence from each element, before dividing them. WikiPedia article suggests a convenient
+        // single-pass algorithm for calculating sample correlations, though depending on the numbers
+        // involved, it can sometimes be numerically unstable.
         result_t a_sum{}, b_sum{}, ab_sum{};
         result_t a_sq_sum{}, b_sq_sum{};
 #if USEARCH_USE_OPENMP
@@ -1190,9 +1197,12 @@ template <typename scalar_at = float, typename result_at = float> struct metric_
             a_sq_sum += ai * ai;
             b_sq_sum += bi * bi;
         }
-        result_t denom = std::sqrt((dim * a_sq_sum - a_sum * a_sum) * (dim * b_sq_sum - b_sum * b_sum));
-        result_t corr = (dim * ab_sum - a_sum * b_sum) / denom;
-        return -corr;
+        result_t denom = (dim * a_sq_sum - a_sum * a_sum) * (dim * b_sq_sum - b_sum * b_sum);
+        if (denom == 0)
+            return 0;
+        result_t corr = dim * ab_sum - a_sum * b_sum;
+        denom = std::sqrt(denom);
+        return -corr / denom;
     }
 };
 

package/javascript/types/usearch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usearch.d.ts","sourceRoot":"","sources":["../usearch.js"],"names":[],"mappings":"AAsIA;IAEI;;;;;;;;;;;OAWG;IACH;oBATkC,MAAM;gBAAU,UAAU;sBAAiC,UAAU;sBAAiC,MAAM;uBAAqB,MAAM;0BAAwB,MAAM;eAAa,OAAO;gBAChN,UAAU,iBACV,UAAU,iBACV,MAAM,kBACN,MAAM,qBACN,MAAM,UACN,OAAO,EAgCjB;IADG,oBAAwI;IAG5I;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAPW,MAAM,GAAC,MAAM,EAAE,GAAC,cAAc,WAE9B,YAAY,GAAC,YAAY,GAAC,SAAS,QAoB7C;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBANW,YAAY,GAAC,YAAY,GAAC,SAAS,GAAC,MAAM,MAAM,MAAM,CAAC,CAAC,KACxD,MAAM,GACL,OAAO,GAAC,YAAY,CAqB/B;IAED;;;;;;;;;OASG;IACH,eAJW,MAAM,GAAC,MAAM,EAAE,GAAC,cAAc,GAC7B,OAAO,GAAC,OAAO,EAAE,CAU5B;IAED;;;;;;OAMG;IACH,YAJW,MAAM,GAAC,MAAM,EAAE,GAAC,cAAc,GAC7B,MAAM,GAAC,MAAM,EAAE,CAU1B;IAED;;;;;;;;;OASG;IACH,aAJW,MAAM,GAAC,MAAM,EAAE,GAAC,cAAc,GAC7B,MAAM,GAAC,MAAM,EAAE,CAU1B;IAED;;;OAGG;IACH,cAFY,MAAM,CAEsC;IAExD;;;OAGG;IACH,gBAFY,MAAM,CAE0C;IAE5D;;;OAGG;IACH,QAFY,MAAM,CAE0B;IAE5C;;;OAGG;IACH,YAFY,MAAM,CAEkC;IAEpD;;;;OAIG;IACH,WAHW,MAAM,QAMhB;IAED;;;;OAIG;IACH,WAHW,MAAM,QAMhB;IAED;;;;OAIG;IACH,WAHW,MAAM,QAMhB;CACJ;;;;yBAzWS,MAAM;;;;;;;;;;;;;;;;;yBAmBN,MAAM;;;;;;;;;;AAYhB;;GAEG;AACH;IACI;;;;;OAKG;IACH,kBAHW,cAAc,aACd,YAAY,EAKtB;IAFG,qBAAgB;IAChB,wBAA0B;CAEjC;AAED;;GAEG;AACH;IACI;;;;;;;OAOG;IACH,kBALW,cAAc,aACd,YAAY,UACZ,cAAc,KACd,MAAM,EAOhB;IAJG,qBAAgB;IAChB,wBAA0B;IAC1B,uBAAoB;IACpB,UAAU;IAGd;;;;;OAKG;IACH,OAHW,MAAM,GACJ,OAAO,CAQnB;CACJ;AA4RD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qCA1BW,YAAY,GAAC,YAAY,GAAC,SAAS,GAAC,MAAM,MAAM,MAAM,CAAC,CAAC,WACxD,YAAY,GAAC,YAAY,GAAC,SAAS,GAAC,MAAM,MAAM,MAAM,CAAC,CAAC,cACxD,MAAM,SACN,MAAM,UACN,UAAU,GACT,OAAO,GAAC,YAAY,CA0D/B"}
+{"version":3,"file":"usearch.d.ts","sourceRoot":"","sources":["../usearch.js"],"names":[],"mappings":"AAsIA;IAEI;;;;;;;;;;;OAWG;IACH;oBATkC,MAAM;gBAAU,UAAU;sBAAiC,UAAU;sBAAiC,MAAM;uBAAqB,MAAM;0BAAwB,MAAM;eAAa,OAAO;gBAChN,UAAU,iBACV,UAAU,iBACV,MAAM,kBACN,MAAM,qBACN,MAAM,UACN,OAAO,EAmCjB;IADG,oBAAwI;IAG5I;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAPW,MAAM,GAAC,MAAM,EAAE,GAAC,cAAc,WAE9B,YAAY,GAAC,YAAY,GAAC,SAAS,QAoB7C;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBANW,YAAY,GAAC,YAAY,GAAC,SAAS,GAAC,MAAM,MAAM,MAAM,CAAC,CAAC,KACxD,MAAM,GACL,OAAO,GAAC,YAAY,CAqB/B;IAED;;;;;;;;;OASG;IACH,eAJW,MAAM,GAAC,MAAM,EAAE,GAAC,cAAc,GAC7B,OAAO,GAAC,OAAO,EAAE,CAU5B;IAED;;;;;;OAMG;IACH,YAJW,MAAM,GAAC,MAAM,EAAE,GAAC,cAAc,GAC7B,MAAM,GAAC,MAAM,EAAE,CAU1B;IAED;;;;;;;;;OASG;IACH,aAJW,MAAM,GAAC,MAAM,EAAE,GAAC,cAAc,GAC7B,MAAM,GAAC,MAAM,EAAE,CAU1B;IAED;;;OAGG;IACH,cAFY,MAAM,CAEsC;IAExD;;;OAGG;IACH,gBAFY,MAAM,CAE0C;IAE5D;;;OAGG;IACH,QAFY,MAAM,CAE0B;IAE5C;;;OAGG;IACH,YAFY,MAAM,CAEkC;IAEpD;;;;OAIG;IACH,WAHW,MAAM,QAMhB;IAED;;;;OAIG;IACH,WAHW,MAAM,QAMhB;IAED;;;;OAIG;IACH,WAHW,MAAM,QAMhB;CACJ;;;;yBA5WS,MAAM;;;;;;;;;;;;;;;;;yBAmBN,MAAM;;;;;;;;;;AAYhB;;GAEG;AACH;IACI;;;;;OAKG;IACH,kBAHW,cAAc,aACd,YAAY,EAKtB;IAFG,qBAAgB;IAChB,wBAA0B;CAEjC;AAED;;GAEG;AACH;IACI;;;;;;;OAOG;IACH,kBALW,cAAc,aACd,YAAY,UACZ,cAAc,KACd,MAAM,EAOhB;IAJG,qBAAgB;IAChB,wBAA0B;IAC1B,uBAAoB;IACpB,UAAU;IAGd;;;;;OAKG;IACH,OAHW,MAAM,GACJ,OAAO,CAQnB;CACJ;AA+RD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qCA1BW,YAAY,GAAC,YAAY,GAAC,SAAS,GAAC,MAAM,MAAM,MAAM,CAAC,CAAC,WACxD,YAAY,GAAC,YAAY,GAAC,SAAS,GAAC,MAAM,MAAM,MAAM,CAAC,CAAC,cACxD,MAAM,SACN,MAAM,UACN,UAAU,GACT,OAAO,GAAC,YAAY,CA0D/B"}

package/javascript/usearch.js

@@ -158,7 +158,10 @@ class Index {
             throw new Error("Invalid arguments. Expected either individual arguments or a single object argument.");
         }
 
-        if (!Number.isInteger(dimensions) || !Number.isInteger(connectivity) || !Number.isInteger(expansion_add) || !Number.isInteger(expansion_search) || dimensions <= 0 || connectivity < 0 || expansion_add < 0 || expansion_search < 0) {
+        if ((typeof dimensions !== 'bigint' && (!Number.isInteger(dimensions) || dimensions <= 0)) || 
+            (typeof connectivity !== 'bigint' && (!Number.isInteger(connectivity) || connectivity < 0)) ||
+            (typeof expansion_add !== 'bigint' && (!Number.isInteger(expansion_add) || expansion_add < 0)) ||
+            (typeof expansion_search !== 'bigint' && (!Number.isInteger(expansion_search) || expansion_search < 0))) {
             throw new Error("`dimensions`, `connectivity`, `expansion_add`, and `expansion_search` must be non-negative integers, with `dimensions` being positive.");
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.9.1",
+    "version": "2.9.2",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian (https://ashvardanian.com/)",
     "license": "Apache 2.0",

package/simsimd/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+
+## C and C++
+
+To rerun experiments utilize the following command:
+
+```sh
+cmake -DCMAKE_BUILD_TYPE=Release -DSIMSIMD_BUILD_BENCHMARKS=1 -B ./build_release
+cmake --build build_release --config Release
+./build_release/simsimd_bench
+./build_release/simsimd_bench --benchmark_filter=js
+```
+
+## Python
+
+Testing:
+
+```sh
+pip install -e .                # to install the package in editable mode
+pytest python/test.py -s -x -Wd # to run tests
+```
+
+Here, `-s` will output the logs.
+The `-x` will stop on the first failure.
+The `-Wd` will silence overflows and runtime warnings.
+
+Benchmarking:
+
+```sh
+pip install numpy scipy scikit-learn    # for comparison baselines
+python python/bench.py                  # to run default benchmarks
+python python/bench.py --n 1000 --ndim 1000000 # batch size and dimensions
+```
+
+Before merging your changes you may want to test your changes against the entire matrix of Python versions USearch supports.
+For that you need the `cibuildwheel`, which is tricky to use on MacOS and Windows, as it would target just the local environment.
+Still, if you have Docker running on any desktop OS, you can use it to build and test the Python bindings for all Python versions for Linux:
+
+```sh
+pip install cibuildwheel
+cibuildwheel
+cibuildwheel --platform linux                   # works on any OS and builds all Linux backends
+cibuildwheel --platform linux --archs x86_64    # 64-bit x86, the most common on desktop and servers
+cibuildwheel --platform linux --archs aarch64   # 64-bit Arm for mobile devices, Apple M-series, and AWS Graviton
+cibuildwheel --platform linux --archs i686      # 32-bit Linux
+cibuildwheel --platform linux --archs s390x     # emulating big-endian IBM Z
+cibuildwheel --platform macos                   # works only on MacOS
+cibuildwheel --platform windows                 # works only on Windows
+```
+
+You may need root previligies for multi-architecture builds:
+
+```sh
+sudo $(which cibuildwheel) --platform linux
+```
+
+On Windows and MacOS, to avoid frequent path resolution issues, you may want to use:
+
+```sh
+python -m cibuildwheel --platform windows
+```
+
+## Rust
+
+```sh
+cargo test
+cargo bench
+open ./target/criterion/report/index.html
+```
+
+## JavaScript
+
+Testing and benchmarking:
+
+```sh
+npm install --dev
+npm test
+npm run bench
+```
+
+## GoLang
+
+```sh
+cd golang
+go test # To test
+go test -run=^$ -bench=. -benchmem # To benchmark
+```
+

package/simsimd/Cargo.lock

@@ -210,9 +210,9 @@ dependencies = [
 
 [[package]]
 name = "half"
-version = "2.3.1"
+version = "2.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bc52e53916c08643f1b56ec082790d1e86a32e58dc5268f897f313fbae7b4872"
+checksum = "b5eceaaeec696539ddaf7b333340f1af35a5aa87ae3e4f3ead0532f72affab2e"
 dependencies = [
  "cfg-if",
  "crunchy",
@@ -496,10 +496,11 @@ dependencies = [
 
 [[package]]
 name = "simsimd"
-version = "3.7.7"
+version = "3.8.1"
 dependencies = [
  "cc",
  "criterion",
+ "half",
  "rand",
 ]
 

package/simsimd/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "simsimd"
 description = "Fastest SIMD-Accelerated Vector Similarity Functions for x86 and Arm"
-version = "3.8.0"
+version = "3.9.0"
 edition = "2021"
 license = "Apache-2.0"
 authors = [
@@ -12,7 +12,13 @@ repository = "https://github.com/ashvardanian/SimSIMD"
 documentation = "https://docs.rs/simsimd"
 homepage = "https://ashvardanian.com/posts/simsimd-faster-scipy"
 keywords = ["simd", "search", "linear-algebra", "vector"]
-categories = ["mathematics", "hardware-support", "no-std", "wasm", "external-ffi-bindings"]
+categories = [
+  "mathematics",
+  "hardware-support",
+  "no-std",
+  "wasm",
+  "external-ffi-bindings",
+]
 
 [lib]
 name = "simsimd"
@@ -21,6 +27,7 @@ path = "rust/lib.rs"
 [build-dependencies]
 cc = "1.0.83"
 
+
 [[bench]]
 name = "cosine"
 harness = false
@@ -34,3 +41,4 @@ path = "rust/benches/sqeuclidean.rs"
 [dev-dependencies]
 criterion = { version = "0.5.1" }
 rand = { version = "0.8.5" }
+half = { version = "2.4.0" }