Struct RaBitQ 

pub struct RaBitQ { /* private fields */ }

RaBitQ quantizer

Implements scalar quantization with trained per-dimension ranges. Training computes min/max per dimension from sample data, enabling consistent quantization across all vectors and correct ADC distances.

Usage

// Create and train quantizer
let mut quantizer = RaBitQ::new(RaBitQParams::bits4());
quantizer.train(&sample_vectors);

// Quantize vectors
let quantized = quantizer.quantize(&vector);

// ADC search (distances are mathematically correct)
let adc = quantizer.build_adc_table(&query);
let dist = adc.distance(&quantized.data);

Implementations

impl RaBitQ

pub fn new(params: RaBitQParams) -> Self

Create a new RaBitQ quantizer (untrained)

Call train() before use to enable correct ADC distances.

pub fn new_trained(params: RaBitQParams, trained: TrainedParams) -> Self

Create a trained RaBitQ quantizer

pub fn default_4bit() -> Self

Create with default 4-bit quantization

pub fn params(&self) -> &RaBitQParams

Get quantization parameters

pub fn is_trained(&self) -> bool

Check if quantizer has been trained

pub fn trained_params(&self) -> Option<&TrainedParams>

Get trained parameters (if any)

pub fn train(&mut self, vectors: &[&[f32]]) -> Result<(), &'static str>

Train quantizer on sample vectors

Computes per-dimension min/max ranges from the sample. Must be called before quantization for correct ADC distances.

Arguments

• vectors - Representative sample of vectors to train from

Errors

Returns error if vectors is empty or have inconsistent dimensions.

pub fn train_owned(&mut self, vectors: &[Vec<f32>]) -> Result<(), &'static str>

Train with owned vectors (convenience method)

Errors

Returns error if vectors is empty or have inconsistent dimensions.

pub fn quantize(&self, vector: &[f32]) -> QuantizedVector

Quantize a vector using trained parameters

If trained: uses per-dimension min/max for consistent quantization If untrained: falls back to legacy per-vector scaling (deprecated)

pub fn unpack_quantized( &self, packed: &[u8], bits: u8, dimensions: usize, ) -> Vec<u8>

Unpack quantized bytes into individual values

pub fn reconstruct( &self, quantized: &[u8], scale: f32, dimensions: usize, ) -> Vec<f32>

Reconstruct (dequantize) a quantized vector

Algorithm (Extended RaBitQ):

1. Unpack bytes to quantized values [0, 2^bits-1]
2. Denormalize: v’ = q / (2^bits - 1)
3. Unscale: v = v’ / scale

pub fn distance_l2(&self, qv1: &QuantizedVector, qv2: &QuantizedVector) -> f32

Compute L2 (Euclidean) distance between two quantized vectors

This reconstructs both vectors and computes standard L2 distance. For maximum accuracy, use this with original vectors for reranking.

pub fn distance_cosine( &self, qv1: &QuantizedVector, qv2: &QuantizedVector, ) -> f32

Compute cosine distance between two quantized vectors

Cosine distance = 1 - cosine similarity

pub fn distance_dot(&self, qv1: &QuantizedVector, qv2: &QuantizedVector) -> f32

Compute dot product between two quantized vectors

pub fn distance_approximate( &self, qv1: &QuantizedVector, qv2: &QuantizedVector, ) -> f32

Compute approximate distance using quantized values directly (fast path)

This computes distance in the quantized space without full reconstruction. Faster but less accurate than distance_l2.

pub fn distance_asymmetric_l2( &self, query: &[f32], quantized: &QuantizedVector, ) -> f32

Compute asymmetric L2 distance (query vs quantized) without full reconstruction

This is the hot path for search! It unpacks quantized values on the fly and computes distance against the uncompressed query vector.

When trained: Uses per-dimension min/max for correct distance computation. When untrained: Falls back to per-vector scale (deprecated, lower accuracy).

pub fn distance_asymmetric_l2_flat( &self, query: &[f32], data: &[u8], scale: f32, ) -> f32

Asymmetric L2 distance from flat storage (no QuantizedVector wrapper)

This is the preferred method for flat contiguous storage layouts. When trained: Uses per-dimension min/max (scale ignored). When untrained: Falls back to per-vector scale.

pub fn build_adc_table(&self, query: &[f32]) -> Option<ADCTable>

Build an ADC (Asymmetric Distance Computation) lookup table for a query

If trained: uses per-dimension min/max for correct distances If untrained: uses provided scale (deprecated, incorrect distances)

Example

// Preferred: train first, then build ADC table
quantizer.train(&sample_vectors);
let adc_table = quantizer.build_adc_table(&query);
for candidate in candidates {
    let dist = adc_table.distance(&candidate.data);
}

pub fn build_adc_table_with_scale(&self, query: &[f32], scale: f32) -> ADCTable

Build ADC table with explicit scale

Note

Prefer build_adc_table() on a trained quantizer for correct ADC distances. This method uses per-vector scale which gives lower accuracy.

pub fn distance_with_adc( &self, query: &[f32], quantized: &QuantizedVector, ) -> Option<f32>

Compute distance using ADC table (convenience wrapper)

Returns None if quantizer is not trained.

pub fn distance_asymmetric_l2_raw( &self, query: &[f32], data: &[u8], scale: f32, bits: u8, ) -> f32

Low-level asymmetric distance computation on raw bytes

Enables zero-copy access from mmap (no QuantizedVector allocation needed). Uses SmallVec to unpack on stack and SIMD for distance computation.

pub fn distance_l2_simd( &self, qv1: &QuantizedVector, qv2: &QuantizedVector, ) -> f32

Compute L2 distance using SIMD acceleration

Uses runtime CPU detection to select the best SIMD implementation:

• x86_64: AVX2 > SSE2 > scalar
• aarch64: NEON > scalar

pub fn distance_cosine_simd( &self, qv1: &QuantizedVector, qv2: &QuantizedVector, ) -> f32

Compute cosine distance using SIMD acceleration

Trait Implementations

impl Clone for RaBitQ

fn clone(&self) -> RaBitQ

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RaBitQ

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RaBitQ

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for RaBitQ

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

where __S: Serializer,

Serialize this value into the given Serde serializer.