usearch 2.15.2 → 2.16.0

package/simsimd/package.json

@@ -1,7 +1,7 @@
 {
   "name": "simsimd",
-  "version": "5.0.0",
-  "description": "Fastest SIMD-Accelerated Vector Similarity Functions for x86 and Arm",
+  "version": "5.9.6",
+  "description": "Portable mixed-precision BLAS-like vector math library for x86 and ARM",
   "homepage": "https://github.com/ashvardanian/simsimd",
   "author": "Ash Vardanian",
   "license": "Apache 2.0",
@@ -27,8 +27,8 @@
     "prebuild-arm64": "prebuildify --arch arm64 --napi --strip --target=10.4.0",
     "prebuild-darwin-x64+arm64": "prebuildify --arch arm64+x64 --napi --strip --target=10.4.0",
     "build-js": "rm -fr javascript/dist/* && tsc -p javascript/tsconfig-esm.json && tsc -p javascript/tsconfig-cjs.json && cp javascript/dist-package-esm.json javascript/dist/esm/package.json && cp javascript/dist-package-cjs.json javascript/dist/cjs/package.json",
-    "test": "node --test ./javascript/test.mjs",
-    "bench": "node ./javascript/bench.js"
+    "test": "node --test ./scripts/test.mjs",
+    "bench": "node ./scripts/bench.js"
   },
   "main": "javascript/dist/cjs/simsimd.js",
   "module": "javascript/dist/esm/simsimd.js",

package/simsimd/rust/lib.rs

@@ -54,24 +54,29 @@ type ComplexProduct = (f64, f64);
 extern "C" {
 
     fn simsimd_dot_f16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
+    fn simsimd_dot_bf16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
     fn simsimd_dot_f32(a: *const f32, b: *const f32, c: usize, d: *mut Distance);
     fn simsimd_dot_f64(a: *const f64, b: *const f64, c: usize, d: *mut Distance);
 
     fn simsimd_dot_f16c(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
+    fn simsimd_dot_bf16c(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
     fn simsimd_dot_f32c(a: *const f32, b: *const f32, c: usize, d: *mut Distance);
     fn simsimd_dot_f64c(a: *const f64, b: *const f64, c: usize, d: *mut Distance);
 
     fn simsimd_vdot_f16c(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
+    fn simsimd_vdot_bf16c(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
     fn simsimd_vdot_f32c(a: *const f32, b: *const f32, c: usize, d: *mut Distance);
     fn simsimd_vdot_f64c(a: *const f64, b: *const f64, c: usize, d: *mut Distance);
 
     fn simsimd_cos_i8(a: *const i8, b: *const i8, c: usize, d: *mut Distance);
     fn simsimd_cos_f16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
+    fn simsimd_cos_bf16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
     fn simsimd_cos_f32(a: *const f32, b: *const f32, c: usize, d: *mut Distance);
     fn simsimd_cos_f64(a: *const f64, b: *const f64, c: usize, d: *mut Distance);
 
     fn simsimd_l2sq_i8(a: *const i8, b: *const i8, c: usize, d: *mut Distance);
     fn simsimd_l2sq_f16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
+    fn simsimd_l2sq_bf16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
     fn simsimd_l2sq_f32(a: *const f32, b: *const f32, c: usize, d: *mut Distance);
     fn simsimd_l2sq_f64(a: *const f64, b: *const f64, c: usize, d: *mut Distance);
 
@@ -79,10 +84,12 @@ extern "C" {
     fn simsimd_jaccard_b8(a: *const u8, b: *const u8, c: usize, d: *mut Distance);
 
     fn simsimd_js_f16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
+    fn simsimd_js_bf16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
     fn simsimd_js_f32(a: *const f32, b: *const f32, c: usize, d: *mut Distance);
     fn simsimd_js_f64(a: *const f64, b: *const f64, c: usize, d: *mut Distance);
 
     fn simsimd_kl_f16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
+    fn simsimd_kl_bf16(a: *const u16, b: *const u16, c: usize, d: *mut Distance);
     fn simsimd_kl_f32(a: *const f32, b: *const f32, c: usize, d: *mut Distance);
     fn simsimd_kl_f64(a: *const f64, b: *const f64, c: usize, d: *mut Distance);
 
@@ -99,6 +106,8 @@ extern "C" {
     fn simsimd_uses_ice() -> i32;
     fn simsimd_uses_genoa() -> i32;
     fn simsimd_uses_sapphire() -> i32;
+    fn simsimd_uses_turin() -> i32;
+    fn simsimd_uses_sierra() -> i32;
 }
 
 /// A half-precision floating point number.
@@ -107,6 +116,12 @@ pub struct f16(u16);
 
 impl f16 {}
 
+/// A half-precision floating point number, called brain float.
+#[repr(transparent)]
+pub struct bf16(u16);
+
+impl bf16 {}
+
 /// The `capabilities` module provides functions for detecting the hardware features
 /// available on the current system.
 pub mod capabilities {
@@ -162,6 +177,14 @@ pub mod capabilities {
     pub fn uses_sapphire() -> bool {
         unsafe { crate::simsimd_uses_sapphire() != 0 }
     }
+
+    pub fn uses_turin() -> bool {
+        unsafe { crate::simsimd_uses_turin() != 0 }
+    }
+
+    pub fn uses_sierra() -> bool {
+        unsafe { crate::simsimd_uses_sierra() != 0 }
+    }
 }
 
 /// `SpatialSimilarity` provides a set of trait methods for computing similarity
@@ -370,6 +393,50 @@ impl SpatialSimilarity for f16 {
     }
 }
 
+impl SpatialSimilarity for bf16 {
+    fn cos(a: &[Self], b: &[Self]) -> Option<Distance> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        // Explicitly cast `*const bf16` to `*const u16`
+        let a_ptr = a.as_ptr() as *const u16;
+        let b_ptr = b.as_ptr() as *const u16;
+        let mut distance_value: Distance = 0.0;
+        let distance_ptr: *mut Distance = &mut distance_value as *mut Distance;
+        unsafe { simsimd_cos_bf16(a_ptr, b_ptr, a.len(), distance_ptr) };
+        Some(distance_value)
+    }
+
+    fn dot(a: &[Self], b: &[Self]) -> Option<Distance> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        // Explicitly cast `*const bf16` to `*const u16`
+        let a_ptr = a.as_ptr() as *const u16;
+        let b_ptr = b.as_ptr() as *const u16;
+        let mut distance_value: Distance = 0.0;
+        let distance_ptr: *mut Distance = &mut distance_value as *mut Distance;
+        unsafe { simsimd_dot_bf16(a_ptr, b_ptr, a.len(), distance_ptr) };
+        Some(distance_value)
+    }
+
+    fn l2sq(a: &[Self], b: &[Self]) -> Option<Distance> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        // Explicitly cast `*const bf16` to `*const u16`
+        let a_ptr = a.as_ptr() as *const u16;
+        let b_ptr = b.as_ptr() as *const u16;
+        let mut distance_value: Distance = 0.0;
+        let distance_ptr: *mut Distance = &mut distance_value as *mut Distance;
+        unsafe { simsimd_l2sq_bf16(a_ptr, b_ptr, a.len(), distance_ptr) };
+        Some(distance_value)
+    }
+}
+
 impl SpatialSimilarity for f32 {
     fn cos(a: &[Self], b: &[Self]) -> Option<Distance> {
         if a.len() != b.len() {
@@ -464,6 +531,36 @@ impl ProbabilitySimilarity for f16 {
     }
 }
 
+impl ProbabilitySimilarity for bf16 {
+    fn jensenshannon(a: &[Self], b: &[Self]) -> Option<Distance> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        // Explicitly cast `*const bf16` to `*const u16`
+        let a_ptr = a.as_ptr() as *const u16;
+        let b_ptr = b.as_ptr() as *const u16;
+        let mut distance_value: Distance = 0.0;
+        let distance_ptr: *mut Distance = &mut distance_value as *mut Distance;
+        unsafe { simsimd_js_bf16(a_ptr, b_ptr, a.len(), distance_ptr) };
+        Some(distance_value)
+    }
+
+    fn kullbackleibler(a: &[Self], b: &[Self]) -> Option<Distance> {
+        if a.len() != b.len() {
+            return None;
+        }
+
+        // Explicitly cast `*const bf16` to `*const u16`
+        let a_ptr = a.as_ptr() as *const u16;
+        let b_ptr = b.as_ptr() as *const u16;
+        let mut distance_value: Distance = 0.0;
+        let distance_ptr: *mut Distance = &mut distance_value as *mut Distance;
+        unsafe { simsimd_kl_bf16(a_ptr, b_ptr, a.len(), distance_ptr) };
+        Some(distance_value)
+    }
+}
+
 impl ProbabilitySimilarity for f32 {
     fn jensenshannon(a: &[Self], b: &[Self]) -> Option<Distance> {
         if a.len() != b.len() {
@@ -536,6 +633,36 @@ impl ComplexProducts for f16 {
     }
 }
 
+impl ComplexProducts for bf16 {
+    fn dot(a: &[Self], b: &[Self]) -> Option<ComplexProduct> {
+        if a.len() != b.len() {
+            return None;
+        }
+        // Prepare the output array where the real and imaginary parts will be stored
+        let mut product: [Distance; 2] = [0.0, 0.0];
+        let product_ptr: *mut Distance = &mut product[0] as *mut _;
+        // Explicitly cast `*const bf16` to `*const u16`
+        let a_ptr = a.as_ptr() as *const u16;
+        let b_ptr = b.as_ptr() as *const u16;
+        unsafe { simsimd_dot_bf16c(a_ptr, b_ptr, a.len(), product_ptr) };
+        Some((product[0], product[1]))
+    }
+
+    fn vdot(a: &[Self], b: &[Self]) -> Option<ComplexProduct> {
+        if a.len() != b.len() {
+            return None;
+        }
+        // Prepare the output array where the real and imaginary parts will be stored
+        let mut product: [Distance; 2] = [0.0, 0.0];
+        let product_ptr: *mut Distance = &mut product[0] as *mut _;
+        // Explicitly cast `*const bf16` to `*const u16`
+        let a_ptr = a.as_ptr() as *const u16;
+        let b_ptr = b.as_ptr() as *const u16;
+        unsafe { simsimd_vdot_bf16c(a_ptr, b_ptr, a.len(), product_ptr) };
+        Some((product[0], product[1]))
+    }
+}
+
 impl ComplexProducts for f32 {
     fn dot(a: &[Self], b: &[Self]) -> Option<ComplexProduct> {
         if a.len() != b.len() {
@@ -583,6 +710,7 @@ impl ComplexProducts for f64 {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use half::bf16 as HalfBF16;
     use half::f16 as HalfF16;
 
     #[test]
@@ -592,7 +720,8 @@ mod tests {
             || capabilities::uses_skylake()
             || capabilities::uses_ice()
             || capabilities::uses_genoa()
-            || capabilities::uses_sapphire();
+            || capabilities::uses_sapphire()
+            || capabilities::uses_turin();
 
         // The CPU can't simultaneously support ARM and x86 SIMD extensions
         if uses_arm {
@@ -609,6 +738,8 @@ mod tests {
         println!("- uses_ice: {}", capabilities::uses_ice());
         println!("- uses_genoa: {}", capabilities::uses_genoa());
         println!("- uses_sapphire: {}", capabilities::uses_sapphire());
+        println!("- uses_turin: {}", capabilities::uses_turin());
+        println!("- uses_sierra: {}", capabilities::uses_sierra());
     }
 
     //
@@ -786,6 +917,26 @@ mod tests {
         }
     }
 
+    #[test]
+    fn test_cos_bf16_same() {
+        // Assuming these u16 values represent bf16 bit patterns, and they are identical
+        let a_u16: &[u16] = &[15360, 16384, 17408]; // Corresponding to some bf16 values
+        let b_u16: &[u16] = &[15360, 16384, 17408]; // Same as above for simplicity
+
+        // Reinterpret cast from &[u16] to &[bf16]
+        // SAFETY: This is safe as long as the representations are guaranteed to be identical,
+        // which they are for transparent structs wrapping the same type.
+        let a_bf16: &[bf16] =
+            unsafe { std::slice::from_raw_parts(a_u16.as_ptr() as *const bf16, a_u16.len()) };
+        let b_bf16: &[bf16] =
+            unsafe { std::slice::from_raw_parts(b_u16.as_ptr() as *const bf16, b_u16.len()) };
+
+        if let Some(result) = SpatialSimilarity::cosine(a_bf16, b_bf16) {
+            println!("The result of cos_bf16 is {:.8}", result);
+            assert_almost_equal(0.0, result, 0.01); // Example value, adjust according to actual expected value
+        }
+    }
+
     #[test]
     fn test_cos_f16_interop() {
         let a_half: Vec<HalfF16> = vec![1.0, 2.0, 3.0]
@@ -812,4 +963,31 @@ mod tests {
             assert_almost_equal(0.025, result, 0.01);
         }
     }
+
+    #[test]
+    fn test_cos_bf16_interop() {
+        let a_half: Vec<HalfBF16> = vec![1.0, 2.0, 3.0]
+            .iter()
+            .map(|&x| HalfBF16::from_f32(x))
+            .collect();
+        let b_half: Vec<HalfBF16> = vec![4.0, 5.0, 6.0]
+            .iter()
+            .map(|&x| HalfBF16::from_f32(x))
+            .collect();
+
+        // SAFETY: This is safe as long as the memory representations are guaranteed to be identical,
+        // which they are due to both being #[repr(transparent)] wrappers around u16.
+        let a_simsimd: &[bf16] =
+            unsafe { std::slice::from_raw_parts(a_half.as_ptr() as *const bf16, a_half.len()) };
+        let b_simsimd: &[bf16] =
+            unsafe { std::slice::from_raw_parts(b_half.as_ptr() as *const bf16, b_half.len()) };
+
+        // Use the reinterpret-casted slices with your SpatialSimilarity implementation
+        if let Some(result) = SpatialSimilarity::cosine(a_simsimd, b_simsimd) {
+            // Expected value might need adjustment depending on actual cosine functionality
+            // Assuming identical vectors yield cosine similarity of 1.0
+            println!("The result of cos_bf16 (interop) is {:.8}", result);
+            assert_almost_equal(0.025, result, 0.01);
+        }
+    }
 }