Struct ProductQuantizer 

pub struct ProductQuantizer { /* private fields */ }

Product quantizer: M subvectors × K centroids per subvector.

Build one with ProductQuantizer::new for the standard M = 8, K = 256 shape, or ProductQuantizer::with_config to pick M, K, and the training seed explicitly. Train it once with a representative sample, then quantize and compare. The trained quantizer is callable from multiple threads — it owns its calibration by value and exposes no interior mutability.

Examples

use iqdb_quantize::{ProductQuantizer, Quantizer};
use iqdb_types::DistanceMetric;

let mut pq = ProductQuantizer::with_config(2, 4, 7);
let training: Vec<Vec<f32>> = (0..16)
    .map(|i| {
        let f = i as f32;
        vec![f, f + 1.0, f + 2.0, f + 3.0]
    })
    .collect();
let refs: Vec<&[f32]> = training.iter().map(Vec::as_slice).collect();
pq.train(&refs).expect("training succeeds");

let code = pq.quantize(&[1.0_f32, 2.0, 3.0, 4.0]).expect("quantize");
let d = pq
    .distance(&[1.0_f32, 2.0, 3.0, 4.0], &code, DistanceMetric::Euclidean)
    .expect("supported metric");
assert!(d.is_finite());

Implementations

impl ProductQuantizer

pub fn new() -> Self

Build an untrained PQ with the standard shape (M = 8, K = 256, seed = 0).

Every hot method returns IqdbError::InvalidConfig until Quantizer::train succeeds. The trained dimension must be a multiple of M, so new()’s M = 8 works for the common embedding dimensions (128, 256, 384, 512, 768, 1024, …) but not for, say, dim 50; use ProductQuantizer::with_config when that matters.

Examples

use iqdb_quantize::ProductQuantizer;
let pq = ProductQuantizer::new();
assert_eq!(pq.n_subvectors(), 8);
assert_eq!(pq.n_centroids(), 256);

pub fn with_config(n_subvectors: usize, n_centroids: usize, seed: u64) -> Self

Build an untrained PQ with the given shape and training seed.

All three parameters take effect at Quantizer::train time; invalid combinations (e.g. n_centroids == 0, n_centroids > 256, training dim not divisible by n_subvectors) surface as IqdbError::InvalidConfig from train. The constructor itself is infallible — it just stores the configuration.

Examples

use iqdb_quantize::ProductQuantizer;
let pq = ProductQuantizer::with_config(16, 256, 42);
assert_eq!(pq.n_subvectors(), 16);
assert_eq!(pq.n_centroids(), 256);
assert_eq!(pq.seed(), 42);

pub fn dim(&self) -> Option<usize>

The trained dimension, if any.

Examples

use iqdb_quantize::{ProductQuantizer, Quantizer};
let mut pq = ProductQuantizer::with_config(2, 4, 7);
assert_eq!(pq.dim(), None);
let data: Vec<Vec<f32>> = (0..8).map(|i| vec![i as f32; 4]).collect();
let refs: Vec<&[f32]> = data.iter().map(Vec::as_slice).collect();
pq.train(&refs).expect("ok");
assert_eq!(pq.dim(), Some(4));

pub fn n_subvectors(&self) -> usize

The configured number of subvectors M.

Examples

use iqdb_quantize::ProductQuantizer;
assert_eq!(ProductQuantizer::with_config(4, 16, 1).n_subvectors(), 4);

pub fn n_centroids(&self) -> usize

The configured number of centroids per subvector codebook K.

Examples

use iqdb_quantize::ProductQuantizer;
assert_eq!(ProductQuantizer::with_config(4, 16, 1).n_centroids(), 16);

pub fn seed(&self) -> u64

The configured training seed.

Same seed + same training data ⇒ byte-identical codebooks.

Examples

use iqdb_quantize::ProductQuantizer;
assert_eq!(ProductQuantizer::with_config(4, 16, 99).seed(), 99);

impl ProductQuantizer

pub fn build_query_tables( &self, query: &[f32], metric: DistanceMetric, ) -> Result<PqAdcTables>

Build the ADC lookup tables for (query, metric) once so the caller can score many PqCodes against the same query without rebuilding the M × K table per call.

This is the primitive that Quantizer::distance is built on; callers scoring a single code can keep using distance directly. Use this method when scoring a batch — e.g. IVF-PQ’s intra-cluster scan, which builds the table once per query and then scores every code in every probed cluster.

Errors

Returns IqdbError::InvalidConfig if the quantizer is untrained, IqdbError::InvalidVector if query is empty or non-finite, IqdbError::DimensionMismatch if query.len() doesn’t match the trained dim, or IqdbError::InvalidMetric for DistanceMetric::Cosine / DistanceMetric::Hamming.

Examples

use iqdb_quantize::{ProductQuantizer, Quantizer};
use iqdb_types::DistanceMetric;

let mut pq = ProductQuantizer::with_config(2, 4, 7);
let training: Vec<Vec<f32>> = (0..16)
    .map(|i| {
        let f = i as f32;
        vec![f, f + 1.0, f + 2.0, f + 3.0]
    })
    .collect();
let refs: Vec<&[f32]> = training.iter().map(Vec::as_slice).collect();
pq.train(&refs).expect("training succeeds");

let code_a = pq.quantize(&[1.0_f32, 2.0, 3.0, 4.0]).expect("quantize");
let code_b = pq.quantize(&[5.0_f32, 6.0, 7.0, 8.0]).expect("quantize");

// Build the table ONCE for this (query, metric), then score many codes.
let query = [1.0_f32, 2.0, 3.0, 4.0];
let tables = pq
    .build_query_tables(&query, DistanceMetric::Euclidean)
    .expect("supported metric");
let d_a = tables.distance(&code_a).expect("matching code shape");
let d_b = tables.distance(&code_b).expect("matching code shape");
assert!(d_a.is_finite() && d_b.is_finite());

Trait Implementations

impl Clone for ProductQuantizer

fn clone(&self) -> ProductQuantizer

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ProductQuantizer

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

Formats the value using the given formatter.

impl Default for ProductQuantizer

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for ProductQuantizer

fn eq(&self, other: &ProductQuantizer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Quantizer for ProductQuantizer

type Quantized = PqCode

The compact code produced by Quantizer::quantize.

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

Train the quantizer from a sample of representative vectors.

fn quantize(&self, vector: &[f32]) -> Result<Self::Quantized>

Encode vector as a compact code.

fn dequantize(&self, quantized: &Self::Quantized) -> Result<Vec<f32>>

Decode quantized back to an f32 vector.

fn distance( &self, query: &[f32], quantized: &Self::Quantized, metric: DistanceMetric, ) -> Result<f32>

Compute the asymmetric distance between a raw f32 query and a stored code under metric.

impl StructuralPartialEq for ProductQuantizer