Struct BinaryHash 

pub struct BinaryHash {
    pub bits: Vec<u64>,
    pub dim: usize,
}

Binary hash for fast approximate nearest neighbor search.

Research Background

Binary embeddings enable sub-linear search via Hamming distance. Key insight from our research synthesis: binary embeddings are for blocking, not primary retrieval. The sign-rank limitation means they cannot represent all similarity relationships, but they excel at fast candidate filtering.

Two-Stage Retrieval Pattern

Query → [Binary Hash] → Hamming Filter (fast) → Candidates
                                                     ↓
                                             [Dense Similarity]
                                                     ↓
                                              Final Results

Example

use anno::backends::inference::BinaryHash;

// Create hashes from embeddings
let hash1 = BinaryHash::from_embedding(&[0.1, -0.2, 0.3, -0.4, 0.5, -0.6, 0.7, -0.8]);
let hash2 = BinaryHash::from_embedding(&[0.15, -0.25, 0.35, -0.45, 0.55, -0.65, 0.75, -0.85]);

// Similar embeddings → low Hamming distance
assert!(hash1.hamming_distance(&hash2) < 2);

Fields

bits: Vec<u64>

Packed bits (each u64 holds 64 bits)

dim: usize

Original dimension (number of bits)

Implementations

impl BinaryHash

pub fn from_embedding(embedding: &[f32]) -> Self

Create from a dense embedding using sign function.

Each positive value → 1, each negative/zero value → 0.

pub fn from_embedding_f64(embedding: &[f64]) -> Self

Create from a dense f64 embedding.

pub fn hamming_distance(&self, other: &Self) -> u32

Compute Hamming distance (number of differing bits).

Uses POPCNT instruction when available for hardware acceleration.

pub fn hamming_distance_normalized(&self, other: &Self) -> f64

Compute normalized Hamming distance (0.0 to 1.0).

pub fn approximate_cosine(&self, other: &Self) -> f64

Convert Hamming distance to approximate cosine similarity.

Based on the relationship: cos(θ) ≈ 1 - 2 * (hamming_distance / dim) This is an approximation valid for random hyperplane hashing.

Trait Implementations

impl Clone for BinaryHash

fn clone(&self) -> BinaryHash

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BinaryHash

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for BinaryHash

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for BinaryHash

fn eq(&self, other: &BinaryHash) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for BinaryHash

impl StructuralPartialEq for BinaryHash