Struct BinaryCode 

pub struct BinaryCode {
    pub words: Vec<u64>,
    pub norm: f32,
    pub dim: usize,
}

A packed binary code representing one vector (D bits).

Fields

words: Vec<u64>

Packed u64 words (ceil(D/64) words).

norm: f32

Original L2 norm before normalisation (needed for the IP estimator).

dim: usize

Number of dimensions.

Implementations

impl BinaryCode

pub fn encode(rotated: &[f32], norm: f32) -> Self

Encode a (possibly rotated) vector into a binary code.

norm should be the L2 norm of the pre-rotation vector so the estimator can rescale correctly.

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

Raw XNOR-popcount across all stored bits. Do not use when D % 64 != 0 — the padding bits in the last word are zero in every code and XNOR-popcount counts them as matches, biasing the estimator. Retained as a fast path for the aligned case (D multiple of 64).

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

Padding-safe XNOR-popcount. Masks the trailing 64·n_words − D bits of the last word so padding zeros don’t inflate the agreement count. Correct at any D ≥ 1; same cost as the raw version up to one extra AND on the last word.

pub fn estimated_sq_distance(&self, query_code: &Self) -> f32

Symmetric angular estimator (Charikar-style) — both operands are 1-bit codes of rotated unit vectors.

For normalized database x̂ (self.norm holds the original ‖x‖) and normalized query q̂ (query_code.norm holds the original ‖q‖):

E[B/D] = 1 − θ/π where θ = arccos(⟨x̂, q̂⟩) ⟹ est cos(θ) = cos(π · (1 − B/D)) ⟹ est ⟨q, x⟩ = ‖q‖ · ‖x‖ · est cos(θ)

Returns estimated squared-L2: ‖q − x‖² = ‖q‖² + ‖x‖² − 2⟨q, x⟩.

pub fn estimated_sq_distance_asymmetric( &self, q_rotated_unit: &[f32], q_norm: f32, ) -> f32

Asymmetric inner-product estimator (RaBitQ-style, keeps the query in f32). More accurate than the symmetric path, at the cost of O(D) arithmetic per candidate instead of O(D/64) popcount.

Given the rotated-unit query q_rot (‖q_rot‖ = 1) and the stored 1-bit code b_x ∈ {−1/√D, +1/√D}ᴰ, the unbiased inner-product estimate is:

⟨q̂_rot, u_x⟩ ≈ (1/√D) · Σᵢ sign(x_rot,i) · q_rot,i

where u_x is the rotated unit vector and b_x,i = sign(x_rot,i)/√D. The unbiasing factor accounts for the concentration of Σ|q_rot,i| on a Haar-uniform rotation of q (which preserves norm).

Returns estimated squared-L2: ‖q − x‖² = ‖q‖² + ‖x‖² − 2‖q‖·‖x‖·ŝ where ŝ = ⟨q̂_rot, u_x⟩ is the unit-sphere IP estimate above.

q_rotated must be length self.dim; caller pre-normalises and pre-rotates the query once per search (amortised across n candidates).

Trait Implementations

impl Clone for BinaryCode

fn clone(&self) -> BinaryCode

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BinaryCode

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for BinaryCode

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for BinaryCode

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.