Crate simsimd

Crate simsimd 

Source
Expand description

§SpatialSimilarity - Hardware-Accelerated Similarity Metrics and Distance Functions

  • Targets ARM NEON, SVE, x86 AVX2, AVX-512 (VNNI, FP16) hardware backends.
  • Handles f64 double- and f32 single-precision, integral, and binary vectors.
  • Exposes half-precision (f16) and brain floating point (bf16) types.
  • Zero-dependency header-only C 99 library with bindings for Rust and other languages.

§Implemented distance functions include:

  • Euclidean (L2), inner product, and cosine (angular) spatial distances.
  • Hamming (~ Manhattan) and Jaccard (~ Tanimoto) binary distances.
  • Kullback-Leibler and Jensen-Shannon divergences for probability distributions.

§Example

use simsimd::SpatialSimilarity;

let a = &[1, 2, 3];
let b = &[4, 5, 6];

// Compute cosine distance
let cos_dist = i8::cos(a, b);

// Compute dot product distance
let dot_product = i8::dot(a, b);

// Compute squared Euclidean distance
let l2sq_dist = i8::l2sq(a, b);

// Optimize performance by flushing denormals
simsimd::capabilities::flush_denormals();

§Mixed Precision Support

use simsimd::{SpatialSimilarity, f16, bf16};

// Work with half-precision floats
let half_a: Vec<f16> = vec![1.0, 2.0, 3.0].iter().map(|&x| f16::from_f32(x)).collect();
let half_b: Vec<f16> = vec![4.0, 5.0, 6.0].iter().map(|&x| f16::from_f32(x)).collect();
let half_cos_dist = f16::cos(&half_a, &half_b);

// Work with brain floats
let brain_a: Vec<bf16> = vec![1.0, 2.0, 3.0].iter().map(|&x| bf16::from_f32(x)).collect();
let brain_b: Vec<bf16> = vec![4.0, 5.0, 6.0].iter().map(|&x| bf16::from_f32(x)).collect();
let brain_cos_dist = bf16::cos(&brain_a, &brain_b);

// Direct bit manipulation
let half = f16::from_f32(3.14);
let bits = half.0; // Access raw u16 representation
let reconstructed = f16(bits);

§Traits

The SpatialSimilarity trait covers following methods:

  • cosine(a: &[Self], b: &[Self]) -> Option<Distance>: Computes cosine distance (1 - similarity) between two slices.
  • dot(a: &[Self], b: &[Self]) -> Option<Distance>: Computes dot product distance between two slices.
  • sqeuclidean(a: &[Self], b: &[Self]) -> Option<Distance>: Computes squared Euclidean distance between two slices.

The BinarySimilarity trait covers following methods:

  • hamming(a: &[Self], b: &[Self]) -> Option<Distance>: Computes Hamming distance between two slices.
  • jaccard(a: &[Self], b: &[Self]) -> Option<Distance>: Computes Jaccard distance between two slices.

The ProbabilitySimilarity trait covers following methods:

  • jensenshannon(a: &[Self], b: &[Self]) -> Option<Distance>: Computes Jensen-Shannon divergence between two slices.
  • kullbackleibler(a: &[Self], b: &[Self]) -> Option<Distance>: Computes Kullback-Leibler divergence between two slices.

Modules§

capabilities
The capabilities module provides functions for detecting the hardware features available on the current system.

Structs§

bf16
A brain floating point (bfloat16) number.
f16
A half-precision (16-bit) floating point number.

Traits§

BinarySimilarity
BinarySimilarity provides trait methods for computing similarity metrics that are commonly used with binary data vectors, such as Hamming distance and Jaccard index.
ComplexProducts
ComplexProducts provides trait methods for computing products between complex number vectors. This includes standard and Hermitian dot products.
ProbabilitySimilarity
ProbabilitySimilarity provides trait methods for computing similarity or divergence measures between probability distributions, such as the Jensen-Shannon divergence and the Kullback-Leibler divergence.
Sparse
Sparse provides trait methods for sparse vectors.
SpatialSimilarity
SpatialSimilarity provides a set of trait methods for computing similarity or distance between spatial data vectors in SIMD (Single Instruction, Multiple Data) context. These methods can be used to calculate metrics like cosine distance, dot product, and squared Euclidean distance between two slices of data.

Type Aliases§

ComplexProduct
Distance