usearch 2.9.0 → 2.9.2

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)) {}
 };
 
@@ -1006,10 +1006,11 @@ template <typename scalar_at = float, typename result_at = scalar_at> struct met
 #elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
-        for (std::size_t i = 0; i != dim; ++i)
-            ab += result_t(a[i]) * result_t(b[i]), //
-                a2 += square<result_t>(a[i]),      //
-                b2 += square<result_t>(b[i]);
+        for (std::size_t i = 0; i != dim; ++i) {
+            result_t ai = static_cast<result_t>(a[i]);
+            result_t bi = static_cast<result_t>(b[i]);
+            ab += ai * bi, a2 += square(ai), b2 += square(bi);
+        }
 
         result_t result_if_zero[2][2];
         result_if_zero[0][0] = 1 - ab / (std::sqrt(a2) * std::sqrt(b2));
@@ -1036,8 +1037,11 @@ template <typename scalar_at = float, typename result_at = scalar_at> struct met
 #elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
-        for (std::size_t i = 0; i != dim; ++i)
-            ab_deltas_sq += square(result_t(a[i]) - result_t(b[i]));
+        for (std::size_t i = 0; i != dim; ++i) {
+            result_t ai = static_cast<result_t>(a[i]);
+            result_t bi = static_cast<result_t>(b[i]);
+            ab_deltas_sq += square(ai - bi);
+        }
         return ab_deltas_sq;
     }
 };
@@ -1095,9 +1099,10 @@ template <typename scalar_at = std::uint64_t, typename result_at = float> struct
 #elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
-        for (std::size_t i = 0; i != words; ++i)
-            and_count += std::bitset<bits_per_word_k>(a[i] & b[i]).count(),
-                or_count += std::bitset<bits_per_word_k>(a[i] | b[i]).count();
+        for (std::size_t i = 0; i != words; ++i) {
+            and_count += std::bitset<bits_per_word_k>(a[i] & b[i]).count();
+            or_count += std::bitset<bits_per_word_k>(a[i] | b[i]).count();
+        }
         return 1 - result_t(and_count) / or_count;
     }
 };
@@ -1126,9 +1131,10 @@ template <typename scalar_at = std::uint64_t, typename result_at = float> struct
 #elif defined(USEARCH_DEFINED_GCC)
 #pragma GCC ivdep
 #endif
-        for (std::size_t i = 0; i != words; ++i)
-            and_count += std::bitset<bits_per_word_k>(a[i] & b[i]).count(),
-                any_count += std::bitset<bits_per_word_k>(a[i]).count() + std::bitset<bits_per_word_k>(b[i]).count();
+        for (std::size_t i = 0; i != words; ++i) {
+            and_count += std::bitset<bits_per_word_k>(a[i] & b[i]).count();
+            any_count += std::bitset<bits_per_word_k>(a[i]).count() + std::bitset<bits_per_word_k>(b[i]).count();
+        }
         return 1 - 2 * result_t(and_count) / any_count;
     }
 };
@@ -1159,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
@@ -1176,15 +1189,20 @@ template <typename scalar_at = float, typename result_at = float> struct metric_
 #pragma GCC ivdep
 #endif
         for (std::size_t i = 0; i != dim; ++i) {
-            a_sum += result_t(a[i]);
-            b_sum += result_t(b[i]);
-            ab_sum += result_t(a[i]) * result_t(b[i]);
-            a_sq_sum += result_t(a[i]) * result_t(a[i]);
-            b_sq_sum += result_t(b[i]) * result_t(b[i]);
+            result_t ai = static_cast<result_t>(a[i]);
+            result_t bi = static_cast<result_t>(b[i]);
+            a_sum += ai;
+            b_sum += bi;
+            ab_sum += ai * bi;
+            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;
     }
 };
 
@@ -1197,7 +1215,7 @@ template <typename scalar_at = float, typename result_at = float> struct metric_
 
     inline result_t operator()(scalar_t const* p, scalar_t const* q, std::size_t dim) const noexcept {
         result_t kld_pm{}, kld_qm{};
-        scalar_t epsilon = std::numeric_limits<scalar_t>::epsilon();
+        result_t epsilon = std::numeric_limits<result_t>::epsilon();
 #if USEARCH_USE_OPENMP
 #pragma omp simd reduction(+ : kld_pm, kld_qm)
 #elif defined(USEARCH_DEFINED_CLANG)
@@ -1206,9 +1224,11 @@ template <typename scalar_at = float, typename result_at = float> struct metric_
 #pragma GCC ivdep
 #endif
         for (std::size_t i = 0; i != dim; ++i) {
-            result_t mi = result_t(p[i] + q[i]) / 2 + epsilon;
-            kld_pm += p[i] * std::log((p[i] + epsilon) / mi);
-            kld_qm += q[i] * std::log((q[i] + epsilon) / mi);
+            result_t pi = static_cast<result_t>(p[i]);
+            result_t qi = static_cast<result_t>(q[i]);
+            result_t mi = (pi + qi) / 2 + epsilon;
+            kld_pm += pi * std::log((pi + epsilon) / mi);
+            kld_qm += qi * std::log((qi + epsilon) / mi);
         }
         return (kld_pm + kld_qm) / 2;
     }
@@ -1253,7 +1273,7 @@ struct l2sq_i8_t {
 #endif
         for (std::size_t i = 0; i != dim; i++)
             ab_deltas_sq += square(std::int16_t(a[i]) - std::int16_t(b[i]));
-        return ab_deltas_sq;
+        return static_cast<result_t>(ab_deltas_sq);
     }
 };
 

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.0",
+    "version": "2.9.2",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian (https://ashvardanian.com/)",
     "license": "Apache 2.0",
@@ -34,7 +34,8 @@
     "exports": {
         ".": {
             "types": "./javascript/types/usearch.d.ts",
-            "require": "./javascript/usearch.js"
+            "require": "./javascript/usearch.js",
+            "import": "./javascript/usearch.js"
         },
         "./package.json": "./package.json"
     },

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" }

package/simsimd/README.md

@@ -1,20 +1,41 @@
 # SimSIMD 📏
 
 <div>
-<a href="https://pepy.tech/project/simsimd"> <img alt="PyPI" src="https://static.pepy.tech/personalized-badge/simsimd?period=total&units=abbreviation&left_color=black&right_color=blue&left_text=SimSIMD%20Python%20installs"> </a>
-<a href="https://www.npmjs.com/package/simsimd"> <img alt="npm" src="https://img.shields.io/npm/dy/simsimd?label=npm%20dowloads"> </a>
-<a href="https://crates.io/crates/simsimd"> <img alt="rust" src="https://img.shields.io/crates/d/simsimd?logo=rust" /> </a>
+<a href="https://pepy.tech/project/simsimd">
+    <img alt="PyPI" src="https://static.pepy.tech/personalized-badge/simsimd?period=total&units=abbreviation&left_color=black&right_color=blue&left_text=SimSIMD%20Python%20installs">
+</a>
+<a href="https://www.npmjs.com/package/simsimd">
+    <img alt="npm" src="https://img.shields.io/npm/dy/simsimd?label=npm%20dowloads">
+</a>
+<a href="https://crates.io/crates/simsimd">
+    <img alt="rust" src="https://img.shields.io/crates/d/simsimd?logo=rust" />
+</a>
 <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/ashvardanian/simsimd">
+<a href="https://github.com/ashvardanian/SimSIMD/actions/workflows/release.yml">
+    <img alt="GitHub Actions Ubuntu" src="https://img.shields.io/github/actions/workflow/status/ashvardanian/SimSIMD/release.yml?branch=main&label=Ubuntu&logo=github&color=blue">
+</a>
+<a href="https://github.com/ashvardanian/SimSIMD/actions/workflows/release.yml">
+    <img alt="GitHub Actions Windows" src="https://img.shields.io/github/actions/workflow/status/ashvardanian/SimSIMD/release.yml?branch=main&label=Windows&logo=windows&color=blue">
+</a>
+<a href="https://github.com/ashvardanian/SimSIMD/actions/workflows/release.yml">
+    <img alt="GitHub Actions MacOS" src="https://img.shields.io/github/actions/workflow/status/ashvardanian/SimSIMD/release.yml?branch=main&label=MacOS&logo=apple&color=blue">
+</a>
+<a href="https://github.com/ashvardanian/SimSIMD/actions/workflows/release.yml">
+    <img alt="GitHub Actions CentOS Linux" src="https://img.shields.io/github/actions/workflow/status/ashvardanian/SimSIMD/release.yml?branch=main&label=CentOS&logo=centos&color=blue">
+</a>
+
 </div>
 
+
 ## Hardware-Accelerated Similarity Metrics and Distance Functions
 
 - Zero-dependency [header-only C 99](#using-simsimd-in-c) library.
-- Bindings for [Python](#using-simsimd-in-python), [Rust](#using-simsimd-in-rust) and [JavaScript](#using-simsimd-in-javascript).
-- Targets ARM NEON, SVE, x86 AVX2, AVX-512 (VNNI, FP16) hardware backends.
-- Zero-copy compatible with NumPy, PyTorch, TensorFlow, and other tensors.
 - Handles `f64` double-, `f32` single-, and `f16` half-precision, `i8` integral, and binary vectors.
+- Targets ARM NEON, SVE, x86 AVX2, AVX-512 (VNNI, FP16) hardware backends.
+- Bindings for [Python](#using-simsimd-in-python), [Rust](#using-simsimd-in-rust) and [JavaScript](#using-simsimd-in-javascript).
 - __Up to 200x faster__ than [`scipy.spatial.distance`][scipy] and [`numpy.inner`][numpy].
+- [Supports more Python versions][compatibility] than SciPy and NumPy.
+- Zero-copy compatible with NumPy, PyTorch, TensorFlow, and other tensors.
 - Used in [USearch](https://github.com/unum-cloud/usearch) and several DBMS products.
 
 __Implemented distance functions__ include:
@@ -25,6 +46,7 @@ __Implemented distance functions__ include:
 
 [scipy]: https://docs.scipy.org/doc/scipy/reference/spatial.distance.html#module-scipy.spatial.distance
 [numpy]: https://numpy.org/doc/stable/reference/generated/numpy.inner.html
+[compatibility]: https://pypi.org/project/simsimd/#files
 
 __Technical Insights__ and related articles:
 
@@ -67,6 +89,11 @@ __Broader Benchmarking Results__:
 
 ## Using SimSIMD in Python
 
+The package is intended to replace the usage of `numpy.inner`, `numpy.dot`, and `scipy.spatial.distance`.
+Aside from drastic performance improvements, SimSIMD significantly improves accuracy in mixed precision setups.
+NumPy and SciPy, processing `i8` or `f16` vectors, will use the same types for accumulators, while SimSIMD can combine `i8` enumeration, `i16` multiplication, and `i32` accumulation to entirely avoid overflows.
+The same applies to processing `f16` values with `f32` precision.
+
 ### Installation
 
 ```sh
@@ -85,6 +112,14 @@ dist = simsimd.cosine(vec1, vec2)
 ```
 
 Supported functions include `cosine`, `inner`, `sqeuclidean`, `hamming`, and `jaccard`.
+Unlike SciPy, SimSIMD allows explicitly stating the precision of the input vectors, which is especially useful for mixed-precision setups.
+
+```py
+dist = simsimd.cosine(vec1, vec2, "i8")
+dist = simsimd.cosine(vec1, vec2, "f16")
+dist = simsimd.cosine(vec1, vec2, "f32")
+dist = simsimd.cosine(vec1, vec2, "f64")
+```
 
 ### Distance Between 2 Batches
 
@@ -150,20 +185,73 @@ To install, add the following to your `Cargo.toml`:
 simsimd = "..."
 ```
 
-To use it:
+Before using the SimSIMD library, ensure you have imported the necessary traits and types into your Rust source file.
+The library provides several traits for different distance/similarity kinds - `SpatialSimilarity`, `BinarySimilarity`, and `ProbabilitySimilarity`.
 
 ```rust
-use simsimd::{cosine, sqeuclidean};
+use simsimd::SpatialSimilarity;
 
 fn main() {
-    let vector_a = vec![1.0, 2.0, 3.0];
-    let vector_b = vec![4.0, 5.0, 6.0];
+    let vector_a: Vec<f32> = vec![1.0, 2.0, 3.0];
+    let vector_b: Vec<f32> = vec![4.0, 5.0, 6.0];
 
-    let distance = cosine(&vector_a, &vector_b);
-    println!("Cosine Distance: {}", distance);
+    // Compute the cosine similarity between vector_a and vector_b
+    let cosine_similarity = f32::cosine(&vector_a, &vector_b)
+        .expect("Vectors must be of the same length");
 
-    let distance = sqeuclidean(&vector_a, &vector_b);
-    println!("Squared Euclidean Distance: {}", distance);
+    println!("Cosine Similarity: {}", cosine_similarity);
+
+    // Compute the squared Euclidean distance between vector_a and vector_b
+    let sq_euclidean_distance = f32::sqeuclidean(&vector_a, &vector_b)
+        .expect("Vectors must be of the same length");
+
+    println!("Squared Euclidean Distance: {}", sq_euclidean_distance);
+}
+```
+
+Similarly, one can compute bit-level distance functions between slices of unsigned integers:
+
+```rust
+use simsimd::BinarySimilarity;
+
+fn main() {
+    let vector_a = &[0b11110000, 0b00001111, 0b10101010];
+    let vector_b = &[0b11110000, 0b00001111, 0b01010101];
+
+    // Compute the Hamming distance between vector_a and vector_b
+    let hamming_distance = u8::hamming(&vector_a, &vector_b)
+        .expect("Vectors must be of the same length");
+
+    println!("Hamming Distance: {}", hamming_distance);
+
+    // Compute the Jaccard distance between vector_a and vector_b
+    let jaccard_distance = u8::jaccard(&vector_a, &vector_b)
+        .expect("Vectors must be of the same length");
+
+    println!("Jaccard Distance: {}", jaccard_distance);
+}
+```
+
+Rust has no native support for half-precision floating-point numbers, but SimSIMD provides a `f16` type for this purpose.
+It doesn't have any functionality and is a `transparent` wrapper around `u16`, so it can be used with `half`, or any other half-precision library.
+
+```rust
+use simsimd::SpatialSimilarity;
+use simsimd::f16 as SimF16;
+use half::f16 as HalfF16;
+
+fn main() {
+    let vector_a: Vec<HalfF16> = ...
+    let vector_b: Vec<HalfF16> = ...
+
+    let buffer_a: &[SimF16] = unsafe { std::slice::from_raw_parts(a_half.as_ptr() as *const SimF16, a_half.len()) };
+    let buffer_b: &[SimF16] = unsafe { std::slice::from_raw_parts(b_half.as_ptr() as *const SimF16, b_half.len()) };
+
+    // Compute the cosine similarity between vector_a and vector_b
+    let cosine_similarity = SimF16::cosine(&vector_a, &vector_b)
+        .expect("Vectors must be of the same length");
+
+    println!("Cosine Similarity: {}", cosine_similarity);
 }
 ```
 
@@ -227,49 +315,3 @@ All of the functions names follow the same pattern: `simsimd_{backend}_{type}_{m
 - The metric can be `cos`, `ip`, `l2sq`, `hamming`, `jaccard`, `kl`, or `js`.
 
 In case you want to avoid hard-coding the backend, you can use the `simsimd_metric_punned_t` to pun the function pointer, and `simsimd_capabilities` function to get the available backends at runtime.
-
-## Benchmarking and Contributing
-
-__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
-```
-
-__To test and benchmark with Python bindings__:
-
-```sh
-pip install -e .
-pytest python/test.py -s -x 
-
-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
-```
-
-__To test and benchmark JavaScript bindings__:
-
-```sh
-npm install --dev
-npm test
-npm run bench
-```
-
-__To test and benchmark GoLang bindings__:
-
-```sh
-cd golang
-go test # To test
-go test -run=^$ -bench=. -benchmem # To benchmark
-```
-
-__To test and benchmark Rust bindings__:
-
-```sh
-cargo test 
-cargo bench 
-open ./target/criterion/report/index.html
-```

package/simsimd/include/simsimd/binary.h

@@ -190,6 +190,50 @@ simsimd_avx512_b8_jaccard_cycle:
 }
 
 #endif // SIMSIMD_TARGET_X86_AVX512
+
+/*
+ *  @file   x86_avx2_b8.h
+ *  @brief  x86 AVX2 implementation of the most common similarity metrics for bitsets.
+ *  @author Ash Vardanian
+ *
+ *  - Implements: Hamming and Jaccard similarity.
+ *  - Requires compiler capabilities: avx2.
+ *
+ *  AVX2 provides no built-in functionality for popcount, so we use the BMI2 instruction set.
+ *  Wojciech Mu la, Nathan Kurz and Daniel Lemire propose an alternative solution based on Harley-Seal
+ *  transforms and lookup tables. Those are very fast on large vectors, but on short vectors they lose
+ *  to built-in scalar population counts. https://arxiv.org/pdf/1611.07612.pdf
+ */
+
+#if SIMSIMD_TARGET_X86_AVX2
+
+__attribute__((target("popcnt"))) //
+inline static simsimd_f32_t
+simsimd_avx2_b8_hamming(simsimd_b8_t const* a, simsimd_b8_t const* b, simsimd_size_t n_words) {
+    // x86 supports unaligned loads and works just fine with the scalar version for small vectors.
+    simsimd_size_t differences = 0;
+    for (; n_words >= 8; n_words -= 8, a += 8, b += 8)
+        differences += _mm_popcnt_u64(*(simsimd_u64_t const*)a ^ *(simsimd_u64_t const*)b);
+    for (; n_words; --n_words, ++a, ++b)
+        differences += _mm_popcnt_u32(*a ^ *b);
+    return (simsimd_f32_t)differences;
+}
+
+__attribute__((target("popcnt"))) //
+inline static simsimd_f32_t
+simsimd_avx2_b8_jaccard(simsimd_b8_t const* a, simsimd_b8_t const* b, simsimd_size_t n_words) {
+    // x86 supports unaligned loads and works just fine with the scalar version for small vectors.
+    simsimd_size_t intersection = 0, union_ = 0;
+    for (; n_words >= 8; n_words -= 8, a += 8, b += 8)
+        intersection += _mm_popcnt_u64(*(simsimd_u64_t const*)a & *(simsimd_u64_t const*)b),
+            union_ += _mm_popcnt_u64(*(simsimd_u64_t const*)a | *(simsimd_u64_t const*)b);
+    for (; n_words; --n_words, ++a, ++b)
+        intersection += _mm_popcnt_u32(*a & *b), union_ += _mm_popcnt_u32(*a | *b);
+    return (union_ != 0) ? 1 - (simsimd_f32_t)intersection / (simsimd_f32_t)union_ : 0;
+}
+
+#endif // SIMSIMD_TARGET_X86_AVX2
+
 #endif // SIMSIMD_TARGET_X86
 
 #undef popcount64