Struct BbqCodec 

pub struct BbqCodec {
    pub dim: usize,
    pub oversample: u8,
    /* private fields */
}

BBQ centroid-centered asymmetric 1-bit quantization codec.

Calibration computes the dataset centroid which is subtracted from each vector before sign quantization. The resulting 1-bit codes are Hamming- coarse-comparable; exact rerank uses the 14-byte corrective factors stored in the unified header.

Fields

dim: usize

oversample: u8

Oversample multiplier for the caller’s rerank pass. Caller fetches oversample × top_k coarse candidates from the Hamming coarse pass, then calls exact_asymmetric_distance on each.

Implementations

impl BbqCodec

pub fn calibrate(vectors: &[&[f32]], dim: usize, oversample: u8) -> Self

Calibrate a new BbqCodec from a set of training vectors.

Computes the centroid as the mean of all training vectors.

Panics

Does not panic; returns a zero-centroid codec if vectors is empty.

Trait Implementations

impl VectorCodec for BbqCodec

fn fast_symmetric_distance(&self, q: &BbqQuantized, v: &BbqQuantized) -> f32

Fast Hamming-based symmetric distance estimate.

Uses the asymmetric corrective distance formula: approx = q_n² + v_n² − 2 · q_n · v_n · dot_estimate where dot_estimate = 1 − 2·hamming/dim maps the Hamming count to a normalised cosine-like similarity on {−1,+1} codes.

fn exact_asymmetric_distance(&self, q: &BbqQuery, v: &BbqQuantized) -> f32

Exact asymmetric L2 distance using the dequantized stored vector.

The query is exact centered FP32 (q.centered). The stored vector is reconstructed from its sign bits and residual_norm via BbqCodec::dequantize: each dimension ≈ ±residual_norm / √dim. This is the high-fidelity asymmetric path invoked during rerank on the oversample × top_k candidates returned by the coarse Hamming pass.

type Quantized = BbqQuantized

The packed quantized form. Must be convertible to a UnifiedQuantizedVector reference via AsRef.

type Query = BbqQuery

The prepared query form (codec-specific).

fn encode(&self, v: &[f32]) -> BbqQuantized

Encode a single FP32 vector into the codec’s packed form.

fn prepare_query(&self, q: &[f32]) -> BbqQuery

Prepare a query for distance computations against this codec. May rotate, normalize, build a LUT, etc.

fn adc_lut(&self, _q: &Self::Query) -> Option<AdcLut>

Optional: precompute ADC lookup table for codecs that use one (PQ, IVF-PQ, TurboQuant). Returns None for codecs that don’t (RaBitQ, BBQ, ternary, binary).

fn train(&mut self, samples: &[&[f32]]) -> Result<(), CodecError>

Optional: fit the codec’s learned parameters on a set of training vectors.