usearch 2.8.16 → 2.9.0

package/simsimd/Cargo.toml

@@ -0,0 +1,36 @@
+[package]
+name = "simsimd"
+description = "Fastest SIMD-Accelerated Vector Similarity Functions for x86 and Arm"
+version = "3.8.0"
+edition = "2021"
+license = "Apache-2.0"
+authors = [
+  "Ash Vardanian <1983160+ashvardanian@users.noreply.github.com>",
+  "Pedro Planel <pplanel@gmail.com>",
+]
+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"]
+
+[lib]
+name = "simsimd"
+path = "rust/lib.rs"
+
+[build-dependencies]
+cc = "1.0.83"
+
+[[bench]]
+name = "cosine"
+harness = false
+path = "rust/benches/cosine.rs"
+
+[[bench]]
+name = "sqeuclidean"
+harness = false
+path = "rust/benches/sqeuclidean.rs"
+
+[dev-dependencies]
+criterion = { version = "0.5.1" }
+rand = { version = "0.8.5" }

package/simsimd/README.md

@@ -3,12 +3,14 @@
 <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>
 <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/ashvardanian/simsimd">
 </div>
 
 ## Hardware-Accelerated Similarity Metrics and Distance Functions
 
-- Zero-dependency [header-only C 99](#using-simsimd-in-c) library with bindings for [Python](#using-simsimd-in-python) and [JavaScript](#using-simsimd-in-javascript).
+- 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.
@@ -139,6 +141,32 @@ metric = CompiledMetric(
 index = Index(256, metric=metric)
 ```
 
+## Using SimSIMD in Rust
+
+To install, add the following to your `Cargo.toml`:
+
+```toml
+[dependencies]
+simsimd = "..."
+```
+
+To use it:
+
+```rust
+use simsimd::{cosine, sqeuclidean};
+
+fn main() {
+    let vector_a = vec![1.0, 2.0, 3.0];
+    let vector_b = vec![4.0, 5.0, 6.0];
+
+    let distance = cosine(&vector_a, &vector_b);
+    println!("Cosine Distance: {}", distance);
+
+    let distance = sqeuclidean(&vector_a, &vector_b);
+    println!("Squared Euclidean Distance: {}", distance);
+}
+```
+
 ## Using SimSIMD in JavaScript
 
 To install, choose one of the following options depending on your environment:
@@ -237,3 +265,11 @@ 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/build.rs

@@ -0,0 +1,20 @@
+fn main() {
+    cc::Build::new()
+        .file("rust/lib.c")
+        .include("include")
+        .flag("-O3")
+        .flag("-DSIMSIMD_NATIVE_F16=0")
+        .flag("-std=c99") // Enforce C99 standard
+        .flag("-pedantic") // Ensure strict compliance with the C standard
+        .warnings(false)
+        .compile("simsimd");
+
+    println!("cargo:rerun-if-changed=rust/lib.c");
+    println!("cargo:rerun-if-changed=rust/lib.rs");
+    println!("cargo:rerun-if-changed=include/simsimd/simsimd.h");
+
+    println!("cargo:rerun-if-changed=include/simsimd/binary.h");
+    println!("cargo:rerun-if-changed=include/simsimd/probability.h");
+    println!("cargo:rerun-if-changed=include/simsimd/spatial.h");
+    println!("cargo:rerun-if-changed=include/simsimd/types.h");
+}

package/simsimd/include/simsimd/simsimd.h

@@ -15,7 +15,7 @@
 #define SIMSIMD_H
 
 #define SIMSIMD_VERSION_MAJOR 3
-#define SIMSIMD_VERSION_MINOR 6
+#define SIMSIMD_VERSION_MINOR 8
 #define SIMSIMD_VERSION_PATCH 0
 
 #include "binary.h"      // Hamming, Jaccard
@@ -69,7 +69,7 @@ typedef enum {
  */
 typedef enum {
     simsimd_cap_serial_k = 1,       ///< Serial (non-SIMD) capability
-    simsimd_cap_any_k = 0xFFFFFFFF, ///< Mask representing any capability
+    simsimd_cap_any_k = 0x7FFFFFFF, ///< Mask representing any capability with `INT_MAX`
 
     simsimd_cap_arm_neon_k = 1 << 10, ///< ARM NEON capability
     simsimd_cap_arm_sve_k = 1 << 11,  ///< ARM SVE capability
@@ -112,11 +112,11 @@ typedef simsimd_f32_t (*simsimd_metric_punned_t)(void const* a, void const* b, s
  *  @brief  Function to determine the SIMD capabilities of the current machine at @b runtime.
  *  @return A bitmask of the SIMD capabilities represented as a `simsimd_capability_t` enum value.
  */
-inline static simsimd_capability_t simsimd_capabilities() {
+inline static simsimd_capability_t simsimd_capabilities(void) {
 
 #if SIMSIMD_TARGET_X86
 
-    /// The states of 4 registers populated for a specific "cpuid" assmebly call
+    /// The states of 4 registers populated for a specific "cpuid" assembly call
     union four_registers_t {
         int array[4];
         struct separate_t {

package/simsimd/include/simsimd/spatial.h

@@ -1172,4 +1172,4 @@ simsimd_avx512_f64_cos_cycle:
 }
 #endif
 
-#endif
+#endif

package/simsimd/include/simsimd/types.h

@@ -102,7 +102,7 @@ typedef signed char simsimd_i8_t;
 typedef unsigned char simsimd_b8_t;
 typedef unsigned long long simsimd_size_t;
 
-#if !defined(SIMSIMD_NATIVE_F16)
+#if !defined(SIMSIMD_NATIVE_F16) || SIMSIMD_NATIVE_F16
 /**
  *  @brief  Half-precision floating-point type.
  *
@@ -112,12 +112,16 @@ typedef unsigned long long simsimd_size_t;
  */
 #if (defined(__GNUC__) || defined(__clang__)) && (defined(__ARM_ARCH) || defined(__aarch64__)) &&                      \
     (defined(__ARM_FP16_FORMAT_IEEE))
+#if !defined(SIMSIMD_NATIVE_F16)
 #define SIMSIMD_NATIVE_F16 1
+#endif
 typedef __fp16 simsimd_f16_t;
 #elif ((defined(__GNUC__) || defined(__clang__)) && (defined(__x86_64__) || defined(__i386__)) &&                      \
        (defined(__SSE2__) || defined(__AVX512F__)))
 typedef _Float16 simsimd_f16_t;
+#if !defined(SIMSIMD_NATIVE_F16)
 #define SIMSIMD_NATIVE_F16 1
+#endif
 #else // Unknown compiler or architecture
 #define SIMSIMD_NATIVE_F16 0
 #endif // Unknown compiler or architecture

package/simsimd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simsimd",
-  "version": "3.6.7",
+  "version": "3.8.0",
   "description": "Fastest SIMD-Accelerated Vector Similarity Functions for x86 and Arm",
   "homepage": "https://github.com/ashvardanian/simsimd",
   "author": "Ash Vardanian",

package/simsimd/rust/benches/cosine.rs

@@ -0,0 +1,27 @@
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
+use simsimd::SimSIMD;
+
+mod native;
+
+const DIMENSIONS: usize = 1536;
+
+pub fn cosine_benchmark(c: &mut Criterion) {
+    let inputs: (Vec<f32>, Vec<f32>) = (
+        native::generate_random_vector(DIMENSIONS),
+        native::generate_random_vector(DIMENSIONS),
+    );
+
+    let mut group = c.benchmark_group("SIMD Cosine");
+
+    for i in 0..=5 {
+        group.bench_with_input(BenchmarkId::new("SimSIMD", i), &i, |b, _| {
+            b.iter(|| SimSIMD::cosine(&inputs.0, &inputs.1))
+        });
+        group.bench_with_input(BenchmarkId::new("Rust Native", i), &i, |b, _| {
+            b.iter(|| native::cosine_similarity_cpu(&inputs.0, &inputs.1))
+        });
+    }
+}
+
+criterion_group!(benches, cosine_benchmark);
+criterion_main!(benches);

package/simsimd/rust/benches/native.rs

@@ -0,0 +1,27 @@
+#![allow(unused)]
+use rand::Rng;
+
+pub(crate) fn generate_random_vector(dim: usize) -> Vec<f32> {
+    (0..dim).map(|_| rand::thread_rng().gen()).collect()
+}
+
+pub(crate) fn cosine_similarity_cpu(a: &[f32], b: &[f32]) -> Option<f32> {
+    if a.len() != b.len() {
+        return None;
+    }
+
+    let dot_product: f32 = a.iter().zip(b.iter()).map(|(a, b)| a * b).sum();
+    let norm_a: f32 = a.iter().map(|a| a.powf(2.0)).sum();
+    let norm_b: f32 = b.iter().map(|b| b.powf(2.0)).sum();
+
+    Some(1.0 - (dot_product / (norm_a.sqrt() * norm_b.sqrt())))
+}
+
+pub(crate) fn squared_euclidean_cpu(a: &[f32], b: &[f32]) -> f32 {
+    assert_eq!(a.len(), b.len());
+
+    a.iter()
+        .zip(b.iter())
+        .map(|(x, y)| ((*x) - (*y)) * ((*x) - (*y)))
+        .fold(0.0, ::std::ops::Add::add)
+}

package/simsimd/rust/benches/sqeuclidean.rs

@@ -0,0 +1,27 @@
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
+use simsimd::SimSIMD;
+
+mod native;
+
+const DIMENSIONS: usize = 1536;
+
+pub fn sqeuclidean_benchmark(c: &mut Criterion) {
+    let inputs: (Vec<f32>, Vec<f32>) = (
+        native::generate_random_vector(DIMENSIONS),
+        native::generate_random_vector(DIMENSIONS),
+    );
+
+    let mut group = c.benchmark_group("SIMD SqEuclidean");
+
+    for i in 0..=5 {
+        group.bench_with_input(BenchmarkId::new("SimSIMD", i), &i, |b, _| {
+            b.iter(|| SimSIMD::sqeuclidean(&inputs.0, &inputs.1))
+        });
+        group.bench_with_input(BenchmarkId::new("Rust Native", i), &i, |b, _| {
+            b.iter(|| native::squared_euclidean_cpu(&inputs.0, &inputs.1))
+        });
+    }
+}
+
+criterion_group!(benches, sqeuclidean_benchmark);
+criterion_main!(benches);

package/simsimd/rust/lib.c

@@ -0,0 +1,68 @@
+#include <simsimd/simsimd.h>
+
+simsimd_capability_t cached_capabilities(void) {
+    static simsimd_capability_t static_capabilities = 0;
+    if (static_capabilities == 0)
+        static_capabilities = simsimd_capabilities();
+    return static_capabilities;
+}
+
+simsimd_f32_t cosine_i8(simsimd_i8_t const* a, simsimd_i8_t const* b, simsimd_size_t d) {
+    static simsimd_metric_punned_t metric = 0;
+    if (metric == 0) {
+        simsimd_capability_t used_capability;
+        simsimd_find_metric_punned(simsimd_metric_cosine_k, simsimd_datatype_i8_k, cached_capabilities(),
+                                   simsimd_cap_any_k, &metric, &used_capability);
+    }
+    return metric(a, b, d, d);
+}
+
+simsimd_f32_t cosine_f32(simsimd_f32_t const* a, simsimd_f32_t const* b, simsimd_size_t d) {
+    static simsimd_metric_punned_t metric = 0;
+    if (metric == 0) {
+        simsimd_capability_t used_capability;
+        simsimd_find_metric_punned(simsimd_metric_cosine_k, simsimd_datatype_f32_k, cached_capabilities(),
+                                   simsimd_cap_any_k, &metric, &used_capability);
+    }
+    return metric(a, b, d, d);
+}
+
+simsimd_f32_t inner_i8(simsimd_i8_t const* a, simsimd_i8_t const* b, simsimd_size_t d) {
+    static simsimd_metric_punned_t metric = 0;
+    if (metric == 0) {
+        simsimd_capability_t used_capability;
+        simsimd_find_metric_punned(simsimd_metric_inner_k, simsimd_datatype_i8_k, cached_capabilities(),
+                                   simsimd_cap_any_k, &metric, &used_capability);
+    }
+    return metric(a, b, d, d);
+}
+
+simsimd_f32_t inner_f32(simsimd_f32_t const* a, simsimd_f32_t const* b, simsimd_size_t d) {
+    static simsimd_metric_punned_t metric = 0;
+    if (metric == 0) {
+        simsimd_capability_t used_capability;
+        simsimd_find_metric_punned(simsimd_metric_inner_k, simsimd_datatype_f32_k, cached_capabilities(),
+                                   simsimd_cap_any_k, &metric, &used_capability);
+    }
+    return metric(a, b, d, d);
+}
+
+simsimd_f32_t sqeuclidean_i8(simsimd_i8_t const* a, simsimd_i8_t const* b, simsimd_size_t d) {
+    static simsimd_metric_punned_t metric = 0;
+    if (metric == 0) {
+        simsimd_capability_t used_capability;
+        simsimd_find_metric_punned(simsimd_metric_sqeuclidean_k, simsimd_datatype_i8_k, cached_capabilities(),
+                                   simsimd_cap_any_k, &metric, &used_capability);
+    }
+    return metric(a, b, d, d);
+}
+
+simsimd_f32_t sqeuclidean_f32(simsimd_f32_t const* a, simsimd_f32_t const* b, simsimd_size_t d) {
+    static simsimd_metric_punned_t metric = 0;
+    if (metric == 0) {
+        simsimd_capability_t used_capability;
+        simsimd_find_metric_punned(simsimd_metric_sqeuclidean_k, simsimd_datatype_f32_k, cached_capabilities(),
+                                   simsimd_cap_any_k, &metric, &used_capability);
+    }
+    return metric(a, b, d, d);
+}

package/simsimd/rust/lib.rs

@@ -0,0 +1,232 @@
+//! # SimSIMD - Hardware-Accelerated Similarity Metrics and Distance Functions
+//!
+//! * Zero-dependency header-only C 99 library with bindings for Python, JavaScript and Rust.
+//! * 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.
+//! * Up to 200x faster than scipy.spatial.distance and numpy.inner.
+//! * Used in USearch and several DBMS products.
+//!
+//! ## Implemented distance functions include:
+//!
+//! * Euclidean (L2), Inner Distance, and Cosine (Angular) spatial distances.
+//! * Hamming (~ Manhattan) and Jaccard (~ Tanimoto) binary distances.
+//! * Kullback-Leibler and Jensen–Shannon divergences for probability distributions.
+//!
+//! The functions in this module are exposed through a trait `SimSIMD`, which is
+//! implemented for types with SIMD support (e.g., i8 and f32). The trait provides
+//! methods for computing cosine similarity, inner product, and squared Euclidean
+//! distance between slices of these types.
+//!
+//! # Example
+//!
+//! ```rust
+//! use simsimd::SimSIMD;
+//!
+//! let a = &[1, 2, 3];
+//! let b = &[4, 5, 6];
+//!
+//! // Compute cosine similarity
+//! let cosine_sim = i8::cosine(a, b);
+//!
+//! // Compute inner product
+//! let inner_product = i8::inner(a, b);
+//!
+//! // Compute squared Euclidean distance
+//! let sqeuclidean_dist = i8::sqeuclidean(a, b);
+//! ```
+//!
+//! # Safety
+//!
+//! The functions declared in the `extern "C"` block are low-level bindings to
+//! SimSIMD implementation. It is crucial to ensure that the input slices have the
+//! same length (`c` parameter) to avoid undefined behavior.
+//!
+//!
+//! # Trait Implementation
+//!
+//! The `SimSIMD` trait is implemented for types with SIMD support and provides
+//! three associated methods:
+//!
+//! - `cosine(a: &[Self], b: &[Self]) -> Option<f32>`: Computes cosine similarity between two slices.
+//! - `inner(a: &[Self], b: &[Self]) -> Option<f32>`: Computes inner product between two slices.
+//! - `sqeuclidean(a: &[Self], b: &[Self]) -> Option<f32>`: Computes squared Euclidean distance between two slices.
+//!
+#![allow(non_camel_case_types)]
+
+extern "C" {
+    /// Computes cosine similarity for i8 types.
+    fn cosine_i8(a: *const i8, b: *const i8, c: usize) -> f32;
+
+    /// Computes cosine similarity for f32 types.
+    fn cosine_f32(a: *const f32, b: *const f32, c: usize) -> f32;
+
+    /// Computes inner product for i8 types.
+    fn inner_i8(a: *const i8, b: *const i8, c: usize) -> f32;
+
+    /// Computes inner product for f32 types.
+    fn inner_f32(a: *const f32, b: *const f32, c: usize) -> f32;
+
+    /// Computes squared Euclidean distance for i8 types.
+    fn sqeuclidean_i8(a: *const i8, b: *const i8, c: usize) -> f32;
+
+    /// Computes squared Euclidean distance for f32 types.
+    fn sqeuclidean_f32(a: *const f32, b: *const f32, c: usize) -> f32;
+}
+
+/// A trait for SIMD similarity functions.
+pub trait SimSIMD
+where
+    Self: Sized,
+{
+    /// Computes cosine similarity between two slices.
+    fn cosine(a: &[Self], b: &[Self]) -> Option<f32>;
+
+    /// Computes inner product between two slices.
+    fn inner(a: &[Self], b: &[Self]) -> Option<f32>;
+
+    /// Computes squared Euclidean distance between two slices.
+    fn sqeuclidean(a: &[Self], b: &[Self]) -> Option<f32>;
+}
+
+impl SimSIMD for i8 {
+    fn cosine(a: &[Self], b: &[Self]) -> Option<f32> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        let operation = unsafe { cosine_i8(a.as_ptr(), b.as_ptr(), a.len()) };
+
+        Some(operation)
+    }
+
+    fn inner(a: &[Self], b: &[Self]) -> Option<f32> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        let operation = unsafe { inner_i8(a.as_ptr(), b.as_ptr(), a.len()) };
+
+        Some(operation)
+    }
+
+    fn sqeuclidean(a: &[Self], b: &[Self]) -> Option<f32> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        let operation = unsafe { sqeuclidean_i8(a.as_ptr(), b.as_ptr(), a.len()) };
+
+        Some(operation)
+    }
+}
+
+impl SimSIMD for f32 {
+    fn cosine(a: &[Self], b: &[Self]) -> Option<f32> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        let operation = unsafe { cosine_f32(a.as_ptr(), b.as_ptr(), a.len()) };
+
+        Some(operation)
+    }
+
+    fn inner(a: &[Self], b: &[Self]) -> Option<f32> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        let operation = unsafe { inner_f32(a.as_ptr(), b.as_ptr(), a.len()) };
+
+        Some(operation)
+    }
+
+    fn sqeuclidean(a: &[Self], b: &[Self]) -> Option<f32> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        let operation = unsafe { sqeuclidean_f32(a.as_ptr(), b.as_ptr(), a.len()) };
+
+        Some(operation)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    //
+    fn assert_almost_equal(left: f32, right: f32, tolerance: f32) {
+        let lower = right - tolerance;
+        let upper = right + tolerance;
+
+        assert!(left >= lower && left <= upper);
+    }
+
+    #[test]
+    fn test_cosine_i8() {
+        let a = &[3, 97, 127];
+        let b = &[3, 97, 127];
+
+        if let Some(result) = SimSIMD::cosine(a, b) {
+            assert_almost_equal(0.00012027938, result, 0.01);
+            println!("The result of cosine_i8 is {:.8}", result);
+        }
+    }
+
+    #[test]
+    fn test_cosine_f32() {
+        let a = &[1.0, 2.0, 3.0];
+        let b = &[1.0, 2.0, 3.0];
+
+        if let Some(result) = SimSIMD::cosine(a, b) {
+            assert_almost_equal(0.004930496, result, 0.01);
+            println!("The result of cosine_f32 is {:.8}", result);
+        }
+    }
+
+    #[test]
+    fn test_inner_i8() {
+        let a = &[1, 2, 3];
+        let b = &[4, 5, 6];
+
+        if let Some(result) = SimSIMD::inner(a, b) {
+            assert_almost_equal(0.029403687, result, 0.01);
+            println!("The result of inner_i8 is {:.8}", result);
+        }
+    }
+
+    #[test]
+    fn test_inner_f32() {
+        let a = &[1.0, 2.0, 3.0];
+        let b = &[4.0, 5.0, 6.0];
+
+        if let Some(result) = SimSIMD::inner(a, b) {
+            assert_almost_equal(-31.0, result, 0.01);
+            println!("The result of inner_f32 is {:.8}", result);
+        }
+    }
+
+    #[test]
+    fn test_sqeuclidean_i8() {
+        let a = &[1, 2, 3];
+        let b = &[4, 5, 6];
+
+        if let Some(result) = SimSIMD::sqeuclidean(a, b) {
+            assert_almost_equal(27.0, result, 0.01);
+            println!("The result of sqeuclidean_i8 is {:.8}", result);
+        }
+    }
+
+    #[test]
+    fn test_sqeuclidean_f32() {
+        let a = &[1.0, 2.0, 3.0];
+        let b = &[4.0, 5.0, 6.0];
+
+        if let Some(result) = SimSIMD::sqeuclidean(a, b) {
+            assert_almost_equal(27.0, result, 0.01);
+            println!("The result of sqeuclidean_f32 is {:.8}", result);
+        }
+    }
+}