Struct VectorQuantizer 

pub struct VectorQuantizer {
    pub config: QuantizationConfig,
    pub codebooks: Vec<Codebook>,
    pub trained: bool,
    pub stats: QuantizationStats,
}

Product-quantization based vector compressor.

Example

use ipfrs_semantic::vector_quantizer::{VectorQuantizer, QuantizationConfig};

let config = QuantizationConfig::new(4, 16, 50, 1e-6);
let mut vq = VectorQuantizer::new(config);

// Train on representative data (must have >= codes_per_subspace vectors)
let training_data: Vec<Vec<f64>> = (0..32)
    .map(|i| (0..16).map(|d| (i * 16 + d) as f64 * 0.01).collect())
    .collect();
vq.train(&training_data).unwrap();

let code = vq.encode(&vec![0.5_f64; 16]).unwrap();
let reconstructed = vq.decode(&code).unwrap();
assert_eq!(reconstructed.len(), 16);

Fields

config: QuantizationConfig

Quantization parameters.

codebooks: Vec<Codebook>

One codebook per subspace; populated after train.

trained: bool

Whether the quantizer has been trained.

stats: QuantizationStats

Runtime statistics.

Implementations

impl VectorQuantizer

pub fn new(config: QuantizationConfig) -> Self

Create a new, untrained quantizer with the given configuration.

pub fn train(&mut self, vectors: &[Vec<f64>]) -> Result<(), VqError>

Train the quantizer by running k-means over vectors for each subspace.

Errors

• VqError::InsufficientData when vectors.len() < codes_per_subspace.
• VqError::DimensionMismatch when vectors have inconsistent length.

pub fn encode(&mut self, vector: &[f64]) -> Result<QuantizerCode, VqError>

Encode a vector into a compact QuantizerCode.

For each subspace the sub-vector is mapped to the index of its nearest centroid.

Errors

• VqError::NotTrained when the quantizer has not been trained.
• VqError::DimensionMismatch when vector.len() does not match training dimension.

pub fn decode(&mut self, code: &QuantizerCode) -> Result<Vec<f64>, VqError>

Decode a QuantizerCode back into an approximate full-dimensional vector.

Reconstructs the vector by concatenating the centroid vectors from each codebook.

Errors

• VqError::NotTrained when the quantizer has not been trained.
• VqError::InvalidCode when the code length does not match the number of subspaces.

pub fn encode_batch( &mut self, vectors: &[Vec<f64>], ) -> Result<Vec<QuantizerCode>, VqError>

Encode a batch of vectors.

All vectors must have the same dimension as the training data.

Errors

Propagates the first error encountered (see encode).

pub fn asymmetric_distance( &self, query: &[f64], code: &QuantizerCode, ) -> Result<f64, VqError>

Compute the asymmetric squared L2 distance between a raw query vector and a code.

This is more accurate than symmetric_distance because the query is not quantized — only the database vector is approximated.

Errors

• VqError::NotTrained when not trained.
• VqError::DimensionMismatch when query length is wrong.
• VqError::InvalidCode when the code is malformed.

pub fn symmetric_distance( &mut self, a: &QuantizerCode, b: &QuantizerCode, ) -> Result<f64, VqError>

Compute the symmetric squared L2 distance between two quantizer codes.

Both codes are decoded to full vectors before computing the distance. This is less accurate than asymmetric_distance but useful when the query is also stored as a code.

Errors

• VqError::NotTrained when not trained.
• VqError::InvalidCode when either code is malformed.

pub fn quantization_error(&mut self, vector: &[f64]) -> Result<f64, VqError>

Compute the per-dimension mean squared reconstruction error for a vector.

||vector - decode(encode(vector))||^2 / dim

Errors

Propagates errors from encode and decode.

pub fn avg_error_on_batch( &mut self, vectors: &[Vec<f64>], ) -> Result<f64, VqError>

Compute the mean quantization error over a batch of vectors.

Errors

Propagates the first error encountered.

pub fn codebook_stats(&self) -> Vec<(usize, usize)>

Return (subspace_idx, num_centroids) pairs for each codebook.

Trait Implementations

impl Debug for VectorQuantizer

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

Formats the value using the given formatter.