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]

When the cuda feature is enabled and a GPU is available, this function automatically uses CUDA acceleration. No code changes required.

Arguments

• embeddings - Embeddings of shape [N, dim]

Returns

Centroid indices of shape [N]

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

CPU implementation of compress_into_codes. This is useful when you want to explicitly avoid CUDA overhead for small batches.

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]

pub fn load_from_dir(index_path: &Path) -> Result<Self>

Load codec from index directory

pub fn load_mmap_from_dir(index_path: &Path) -> Result<Self>

Load codec from index directory with memory-mapped centroids.

This is similar to load_from_dir but uses memory-mapped I/O for the centroids file, reducing RAM usage. The other small tensors (bucket weights, etc.) are still loaded into memory as they are negligible in size.

Use this when loading for MmapIndex to minimize memory footprint.

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.