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 const ENVELOPE_MAGIC: &'static [u8; 5] = b"NDBBQ"

On-disk magic for BBQ codec envelopes.

pub const ENVELOPE_VERSION: u8 = 1

Current on-disk envelope version for BBQ codecs.

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.

pub fn to_bytes(&self) -> Result<Vec<u8>, CodecError>

Serialize this codec to a self-describing byte buffer.

pub fn from_bytes(buf: &[u8]) -> Result<Self, CodecError>

Deserialize a codec from a byte buffer produced by Self::to_bytes.

Trait Implementations

impl<'de> Deserialize<'de> for BbqCodec

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'__msgpack_de> FromMessagePack<'__msgpack_de> for BbqCodec

fn read<R: Read<'__msgpack_de>>(reader: &mut R) -> Result<Self, Error>

where Self: Sized,

Reads the MessagePack representation of this value from the provided reader.

impl Serialize for BbqCodec

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ToMessagePack for BbqCodec

fn write<W: Write>(&self, writer: &mut W) -> Result<(), Error>

Writes the MessagePack representation of this value into the provided writer.

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.