Struct ResidualCodec 

pub struct ResidualCodec {
    pub nbits: usize,
    pub centroids: CentroidStore,
    pub avg_residual: Array1<f32>,
    pub bucket_cutoffs: Option<Array1<f32>>,
    pub bucket_weights: Option<Array1<f32>>,
    pub byte_reversed_bits_map: Vec<u8>,
    pub bucket_weight_indices_lookup: Option<Array2<usize>>,
}

A codec that manages quantization parameters and lookup tables for the index.

This struct contains all tensors required to compress embeddings during indexing and decompress vectors during search. It uses pre-computed lookup tables to accelerate bit unpacking operations.

Fields

nbits: usize

Number of bits used to represent each residual bucket (e.g., 2 or 4)

centroids: CentroidStore

Coarse centroids (codebook) of shape [num_centroids, dim]. Can be either owned (in-memory) or memory-mapped for reduced RAM usage.

avg_residual: Array1<f32>

Average residual vector, used to reduce reconstruction error

bucket_cutoffs: Option<Array1<f32>>

Boundaries defining which bucket a residual value falls into

bucket_weights: Option<Array1<f32>>

Values (weights) corresponding to each quantization bucket

byte_reversed_bits_map: Vec<u8>

Lookup table (256 entries) for byte-to-bits unpacking

bucket_weight_indices_lookup: Option<Array2<usize>>

Maps byte values directly to bucket indices for fast decompression

Implementations

impl ResidualCodec

pub fn new( nbits: usize, centroids: Array2<f32>, avg_residual: Array1<f32>, bucket_cutoffs: Option<Array1<f32>>, bucket_weights: Option<Array1<f32>>, ) -> Result<Self>

Creates a new ResidualCodec and pre-computes lookup tables.

Arguments

• nbits - Number of bits per code (e.g., 2 bits = 4 buckets)
• centroids - Coarse centroids of shape [num_centroids, dim]
• avg_residual - Global average residual
• bucket_cutoffs - Quantization boundaries (optional, for indexing)
• bucket_weights - Reconstruction values (optional, for search)

pub fn new_with_store( nbits: usize, centroids: CentroidStore, avg_residual: Array1<f32>, bucket_cutoffs: Option<Array1<f32>>, bucket_weights: Option<Array1<f32>>, ) -> Result<Self>

Creates a new ResidualCodec with a specified centroid storage backend.

This is the internal constructor that supports both owned and mmap centroids.

pub fn embedding_dim(&self) -> usize

Returns the embedding dimension

pub fn num_centroids(&self) -> usize

Returns the number of centroids

pub fn centroids_view(&self) -> ArrayView2<'_, f32>

Returns a view of the centroids.

This is zero-copy for both owned and mmap centroids.

pub fn compress_into_codes(&self, embeddings: &Array2<f32>) -> Array1<usize>

Compress embeddings into centroid codes using nearest neighbor search.

Uses batch matrix multiplication for efficiency: scores = embeddings @ centroids.T -> [N, K] codes = argmax(scores, axis=1) -> [N]

Arguments

• embeddings - Embeddings of shape [N, dim]

Returns

Centroid indices of shape [N]

pub fn quantize_residuals(&self, residuals: &Array2<f32>) -> Result<Array2<u8>>

Quantize residuals into packed bytes.

Uses vectorized bucket search and parallel processing for efficiency.

Arguments

• residuals - Residual vectors of shape [N, dim]

Returns

Packed residuals of shape [N, dim * nbits / 8] as bytes

pub fn decompress( &self, packed_residuals: &Array2<u8>, codes: &ArrayView1<'_, usize>, ) -> Result<Array2<f32>>

Decompress residuals from packed bytes using lookup tables.

Arguments

• packed_residuals - Packed residuals of shape [N, packed_dim]
• codes - Centroid codes of shape [N]

Returns

Reconstructed embeddings of shape [N, dim]

Trait Implementations

impl Clone for ResidualCodec

fn clone(&self) -> ResidualCodec

Returns a duplicate of the value.

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

Performs copy-assignment from source.