Crate iqdb_distance 

iqdb-distance

Distance and similarity functions for the iQDB vector-database spine. The crate owns the math: given two &[f32] slices and a iqdb_types::DistanceMetric it computes the requested distance and returns it as f32. The five metrics — Cosine, DotProduct, Euclidean (L2), Manhattan (L1), and Hamming — sit behind the single Distance trait, with one zero-sized type per metric (Cosine, DotProduct, Euclidean, Manhattan, Hamming). The top-level compute and compute_batch functions take the metric tag and route to the right implementation.

For pre-normalized embeddings, cosine_normalized is a fast path that skips the norm and division (1 - a · b), and normalize produces the unit vectors it expects.

Performance: every distance call is allocation-free (normalize, which returns a new vector, is the sole documented exception). SIMD kernels (AVX2 on x86_64, NEON on aarch64) are picked at runtime from detect_features and short-circuit to the scalar reference when the host lacks the feature or when force_scalar has been called.

Example

use iqdb_distance::{Cosine, Distance};

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

// Perpendicular unit vectors -> cosine distance ~ 1.0.
let d = Cosine::compute(&a, &b).expect("non-empty, same length");
assert!((d - 1.0).abs() < 1e-6);

Errors

Every fallible call returns iqdb_types::Result. Empty inputs and length mismatches surface as iqdb_types::IqdbError::InvalidVector and iqdb_types::IqdbError::DimensionMismatch respectively; the library never panics on bad input.

Structs

Cosine

Cosine distance: 1 - cos(angle(a, b)).

CpuFeatures

Snapshot of the host CPU features detect_features cares about.

DotProduct

Dot-product similarity: the inner product sum(a[i] * b[i]).

Euclidean

Euclidean (L2) distance: sqrt(sum((a[i] - b[i])^2)).

Hamming

Hamming distance on &[f32]: the count of positions where the two values differ at the bit level, returned as f32.

Manhattan

Manhattan (L1) distance: sum(|a[i] - b[i]|).

Constants

VERSION

The version of this crate, taken from Cargo.toml at compile time.

Traits

Distance

Compute a distance between two &[f32] slices.

Functions

compute

Compute the distance for metric between a and b.

compute_batch

Compute distances for metric between query and each entry in candidates, writing into out.

compute_scalartesting

Compute metric between a and b on the scalar reference path, bypassing runtime dispatch — a per-call scalar oracle.

cosine_normalized

Cosine distance for two already unit-length vectors: 1 - (a · b).

detect_features

Return the host CPU-feature snapshot, computing it on first call.

force_scalartesting

Force every dispatched distance call in this process onto the scalar reference path.

forced_scalar

Return true if force_scalar has been called in this process.

normalize

Return the L2-normalized (unit-length) copy of v: v / ‖v‖.

which_kerneltesting

Return the kernel a distance call would dispatch to right now, as a short identifier: "scalar", "avx2", or "neon".