Struct RaBitQCodec 

pub struct RaBitQCodec {
    pub dim: usize,
    pub bias_correct: bool,
    /* private fields */
}

RaBitQ codec: 1-bit quantization with O(1/√D) MSE error bound.

See module-level documentation for algorithm details.

Fields

dim: usize

bias_correct: bool

If true, subtract dot_quantized from the asymmetric distance estimate as a TurboQuant-style IP-bias correction term.

Implementations

impl RaBitQCodec

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

Calibrate a new codec from a set of training vectors.

• Computes the centroid as the coordinate-wise mean of vectors.
• Stores rotation_seed for reproducible signed-diagonal generation.

Errors (none — returns Self directly)

Returns a zero-centroid codec if vectors is empty.

pub fn apply_rotation(&self, v: &[f32]) -> Vec<f32>

Apply the randomised WHT rotation to a residual vector.

Steps:

1. Apply signed-diagonal D (deterministic from rotation_seed).
2. Zero-pad to the next power of two if dim is not pow2.
3. WHT in-place.
4. Truncate back to dim.

Trait Implementations

impl VectorCodec for RaBitQCodec

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

Symmetric distance estimate: both q and v are quantized.

approx_l2 = ‖v-c‖² + ‖q-c‖² − 2·‖v-c‖·‖q-c‖·(1 − 2·hamming/D)

The angular factor 1 − 2·hamming/D approximates cos(θ) between the two sign-vectors. Error bound: O(1/√D) MSE.

fn exact_asymmetric_distance(&self, q: &Self::Query, v: &Self::Quantized) -> f32

Asymmetric distance estimate: q is a prepared RaBitQQuery, v is a stored quantized vector.

Uses query_norm (exact ‖q−c‖) against v.residual_norm (exact ‖v−c‖) for higher fidelity than the symmetric variant.

If self.bias_correct = true, subtract v.dot_quantized as a first- order IP-bias correction term (TurboQuant-style).

type Quantized = RaBitQQuantized

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

type Query = RaBitQQuery

The prepared query form (codec-specific).

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

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

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

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.