Crate innr 

SIMD-accelerated vector similarity primitives.

Fast building blocks for embedding similarity with automatic hardware dispatch.

Which Function Should I Use?

Task	Function	Notes
Similarity (normalized)	cosine	Most embeddings are normalized
Similarity (raw)	dot	When you know norms
Distance (L2)	l2_distance	For k-NN, clustering
Token-level matching	maxsim	ColBERT-style late interaction
Sparse vectors	sparse_dot	BM25 scores, SPLADE
INT8 embeddings	dot_u8	Quantized vector search
Binary embeddings	hamming_distance	Byte-packed bit vectors
MinHash sketches	slot_hamming_u32 / minhash_jaccard	Integer-slot match counting
Generic metric backend	distance::Distance	Plug innr into a generic index

SIMD Dispatch

All functions automatically dispatch to the fastest available instruction set:

Architecture	Instructions	Detection
x86_64	AVX-512F	Runtime
x86_64	AVX2 + FMA	Runtime
aarch64	NEON	Always available
Other	Portable	LLVM auto-vectorizes

Short vectors use portable code (SIMD overhead not worthwhile); the threshold is per module: 16 dimensions for dense f32 ops, 32 for the quantized u8 ops, 8 for integer-slot ops.

Contracts

• Length mismatch: the dispatching functions (dot, cosine, l1_distance, l2_distance, dot_u8, hamming_distance, slot_hamming_u32, maxsim, …) panic. The *_portable variants and the dense_f64 module compare over the shorter length; each such function documents this.
• Zero norms: similarity functions return 0.0 when either norm is below 1e-9 (compared in squared space against NORM_EPSILON_SQ).
• NaN: propagates through dot/distances; cosine returns 0.0 for NaN inputs because the zero-norm guard absorbs them.
• Empty inputs: reductions return 0.0; minhash_jaccard of two empty sketches returns 1.0.

Historical Context

The inner product (dot product) dates to Grassmann’s 1844 “Ausdehnungslehre” and Hamilton’s quaternions, formalized in Gibbs and Heaviside’s vector calculus (~1880s). Modern embedding similarity (Word2Vec 2013, BERT 2018) relies on inner products in high-dimensional spaces where SIMD acceleration is essential.

ColBERT’s MaxSim (Khattab & Zaharia, 2020) extends this to token-level late interaction, requiring O(|Q| x |D|) inner products per query-document pair.

Example

use innr::{dot, cosine, norm};

let a = [1.0_f32, 0.0, 0.0];
let b = [0.707, 0.707, 0.0];

// Dot product
let d = dot(&a, &b);
assert!((d - 0.707).abs() < 0.01);

// Cosine similarity (normalized dot product)
let c = cosine(&a, &b);
assert!((c - 0.707).abs() < 0.01);

// L2 norm
let n = norm(&a);
assert!((n - 1.0).abs() < 1e-6);

References

• Gibbs, J.W. (1881). “Elements of Vector Analysis”
• Mikolov et al. (2013). “Efficient Estimation of Word Representations” (Word2Vec)
• Khattab & Zaharia (2020). “ColBERT: Efficient and Effective Passage Search”

Re-exports

pub use dense::angular_distance;

pub use dense::cosine;

pub use dense::dot;

pub use dense::l1_distance;

pub use dense::l2_distance;

pub use dense::l2_distance_squared;

pub use dense::matryoshka_cosine;

pub use dense::matryoshka_dot;

pub use dense::norm;

pub use dense::normalize;

pub use dense::normalize_with_norm;

pub use binary::binary_dot;

pub use binary::binary_hamming;

pub use binary::binary_jaccard;

pub use binary::encode_binary;

pub use binary::PackedBinary;

pub use fast_math::fast_cosine;

pub use fast_math::fast_cosine_dispatch;

pub use fast_math::fast_rsqrt;

pub use fast_math::fast_rsqrt_precise;

pub use quant::dot_u8;

pub use quant::hamming_distance;

pub use slot::jaccard_distance;

pub use slot::minhash_jaccard;

pub use slot::slot_compare_counts;

pub use slot::slot_hamming;

pub use slot::slot_hamming_u16;

pub use slot::slot_hamming_u32;

pub use slot::slot_hamming_u64;

pub use slot::SlotCounts;

pub use topk::TopK;

Modules

backend

Binary (1-bit) quantization: encode, Hamming distance, dot product, Jaccard. SIMD backend introspection: which kernel family will actually run.

batch

Batch vector operations with columnar (PDX-style) layout. Batch vector operations with columnar (PDX-style) data layout.

binary

SIMD-accelerated binary (1-bit) vector operations.

dense

Dense vector primitives: dot, cosine, norm, L2/L1 distance, matryoshka. Dense vector operations with SIMD acceleration.

dense_f64

f64 vector primitives for higher-precision consumers (scientific computing, PageRank-style accumulation, statistical reductions). Mirrors the f32 API in dense; the reductions dispatch to SIMD (AVX-512 / AVX2 / NEON) with a portable fallback. f64 vector primitives.

distance

Generic Distance trait for using innr’s metrics as a pluggable backend for generic indexes. Generic Distance trait for using innr’s metrics as a pluggable backend.

fast_math

Fast math operations using hardware-aware approximations (rsqrt, NR iteration). Fast math operations using hardware-aware approximations.

quant

Integer quantization primitives: u8 dot product and Hamming distance. Integer quantization primitives: u8 dot product and Hamming distance.

scalar

Scalar quantization (uint8) for memory-efficient asymmetric similarity. Scalar quantization (uint8) for memory-efficient similarity search.

slot

Integer-slot Hamming distance and MinHash Jaccard estimation. Integer-slot Hamming distance and MinHash Jaccard estimation.

sparse_ext

Sparse vector primitives for learned sparse retrieval (tuple-based API). Sparse vector primitives for learned sparse retrieval.

ternary

Ternary quantization (1.58-bit) for ultra-compressed embeddings. SIMD-accelerated ternary vector operations.

topk

Fixed-capacity top-K nearest neighbor tracker for ANN inner-loop use. Fixed-capacity top-K nearest neighbor tracker.

Functions

maxsim

MaxSim: sum over query tokens of max dot product with any doc token.

maxsim_cosine

MaxSim with cosine similarity instead of dot product.

sparse_dot

Sparse dot product for sorted index arrays.

sparse_maxsim

Sparse MaxSim (SPLADE-style) scoring.