Struct ADCTable 

pub struct ADCTable { /* private fields */ }

Asymmetric Distance Computation (ADC) lookup table for fast quantized search

Precomputes partial squared distances from a query vector to all possible quantized codes. This enables O(1) distance computation per dimension instead of O(dim) decompression + distance calculation.

Performance

• Memory: For 4-bit: dim * 16 * 4 bytes (e.g., 1536D = 96KB per query)
• Speedup: 5-10x faster distance computation vs full decompression
• Use case: Scanning many candidate vectors during HNSW search

Algorithm

Instead of:

for each candidate:
    decompress(candidate) -> O(dim)
    distance(query, decompressed) -> O(dim)

With ADC:

precompute table[code] = (query_value - dequantize(code))^2 for all codes
for each candidate:
    sum(table[candidate[i]]) -> O(1) per dimension

Implementations

impl ADCTable

pub fn new_trained( query: &[f32], trained: &TrainedParams, params: &RaBitQParams, ) -> Self

Build ADC lookup table using trained quantization parameters

This is the production method that computes correct distances. Uses per-dimension min/max ranges from training.

Arguments

• query - The uncompressed query vector
• trained - Trained parameters with per-dimension min/max
• params - Quantization parameters (bits per dimension)

pub fn new(query: &[f32], scale: f32, params: &RaBitQParams) -> Self

Build ADC lookup table for a query vector (DEPRECATED)

For each dimension and each possible quantized code, precomputes the squared distance contribution: (query[i] - dequantize(code, scale))^2

WARNING: This method uses a fixed scale which produces incorrect distances when vectors were quantized with different scales. Use new_trained() instead.

Arguments

• query - The uncompressed query vector
• scale - The scale factor used for quantization (from training or default)
• params - Quantization parameters (bits per dimension)

Returns

An ADCTable that can compute distances via distance() method

Note

Prefer ADCTable::new_trained() with TrainedParams for correct ADC distances. This method uses per-vector scale which gives lower accuracy.

pub fn distance_squared(&self, data: &[u8]) -> f32

Compute approximate L2 squared distance using lookup table

This is the hot path for search! Instead of decompressing and computing distance, we just sum up precomputed values from the table.

Performance

• 4-bit: ~5-10x faster than decompression + distance
• Cache-friendly: sequential access patterns
• SIMD-friendly: can vectorize the summation

Arguments

• data - Packed quantized bytes

Returns

Approximate squared L2 distance (not square-rooted for efficiency)

pub fn distance(&self, data: &[u8]) -> f32

Compute distance and return square root (actual L2 distance)

Uses SIMD-accelerated distance computation (AVX2 on x86_64, NEON on aarch64).

pub fn distance_squared_simd(&self, data: &[u8]) -> f32

SIMD-accelerated distance computation for 4-bit quantization

Uses AVX2 on x86_64 or NEON on aarch64 to process multiple lookups in parallel. Falls back to scalar implementation if SIMD not available.

pub fn bits(&self) -> u8

Get bits per dimension

pub fn dimensions(&self) -> usize

Get number of dimensions

pub fn get(&self, dim: usize, code: usize) -> f32

Get partial distance for a dimension and code

Returns 0.0 if indices are out of bounds.

pub fn memory_bytes(&self) -> usize

Get memory usage in bytes

Trait Implementations

impl Clone for ADCTable

fn clone(&self) -> ADCTable

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ADCTable

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

Formats the value using the given formatter.