Struct ProductQuantizer 

pub struct ProductQuantizer {
    pub codebook: PQCodebook,
    pub rotation: Option<Vec<f32>>,
}

Product quantizer model and helpers for train/encode/decode.

Fields

codebook: PQCodebook

Trained codebook.

rotation: Option<Vec<f32>>

OPQ rotation matrix (flattened row-major D x D). None if OPQ disabled.

Implementations

impl ProductQuantizer

pub fn train( vectors: &[Vec<f32>], num_subspaces: usize, num_centroids: usize, ) -> Result<Self, Error>

Train a PQ codebook using simplified k-means for each subspace.

Errors

Returns Error::InvalidQuantizerConfig if:

• vectors is empty
• num_subspaces is 0
• num_centroids is 0 or exceeds u16::MAX
• vector dimension is not divisible by num_subspaces
• num_centroids exceeds vectors.len()

pub fn quantize(&self, vector: &[f32]) -> Result<PQVector, Error>

Quantize a full-precision vector into PQ codes.

Applies OPQ rotation (if present) before encoding, so that codebook centroids — which were trained on rotated vectors — remain consistent with the encoded representation.

Errors

Returns Error::InvalidQuantizerConfig if vector.len() does not match the codebook dimension.

pub fn reconstruct(&self, pq_vector: &PQVector) -> Result<Vec<f32>, Error>

Reconstruct an approximate vector from PQ codes.

Errors

Returns Error::InvalidQuantizerConfig if the number of codes does not match the number of subspaces, or if a code index is out of range.

impl ProductQuantizer

pub fn validate_loaded(&self) -> Result<(), Error>

Validate a deserialized quantizer’s structural invariants.

Must be called once on every quantizer loaded from untrusted bytes (see Self::load_codebook) before it is used for search. After this returns Ok, the codebook layout matches its declared dimensions and the rotation matrix (if present) is dimension * dimension, so the unchecked indexing in apply_rotation operates only on in-bounds offsets.

Errors

Returns Error::IndexCorrupted if the centroid table shape, subspace dimension, or rotation length is inconsistent with the declared dimension / num_subspaces / num_centroids.

pub fn validate_codes(&self, pq_vector: &PQVector) -> Result<(), Error>

Verify every code in pq_vector is a valid centroid index < num_centroids and that the code count matches num_subspaces.

This is the precondition the unsafe SIMD ADC kernels rely on: once it returns Ok, code[i] < num_centroids for all i, so every gather index subspace * num_centroids + code stays within the LUT bounds.

Errors

Returns Error::IndexCorrupted if a code is out of range or the code count is wrong.

pub fn precompute_lut(&self, query: &[f32]) -> Vec<f32>

Precompute ADC lookup table for a query vector.

Returns flat [m * k] table indexed as lut[subspace * k + centroid_id]. Applies OPQ rotation if present.

impl ProductQuantizer

Persistence methods for codebook and rotation matrix storage.

pub fn save_codebook(&self, dir: &Path) -> Result<(), Error>

Save trained codebook to <dir>/codebook.pq using postcard. Uses atomic write (write to .tmp, then rename).

Errors

Returns Error::Io if serialization or file I/O fails.

pub fn load_codebook(dir: &Path) -> Result<Option<Self>, Error>

Load codebook from <dir>/codebook.pq. Returns None if file doesn’t exist.

The decoded quantizer is structurally validated (Self::validate_loaded) before being returned, so a corrupt or tampered codebook is rejected here rather than producing out-of-bounds indexing during search.

Errors

Returns Error::Io if deserialization or file I/O fails, or Error::IndexCorrupted if the decoded codebook/rotation is inconsistent or the file exceeds MAX_PQ_ARTIFACT_BYTES.

pub fn save_rotation(&self, dir: &Path) -> Result<(), Error>

Save OPQ rotation matrix to <dir>/rotation.opq using postcard.

Errors

Returns Error::Io if the rotation is None, serialization, or file I/O fails.

pub fn load_rotation(dir: &Path) -> Result<Option<Vec<f32>>, Error>

Load OPQ rotation matrix from <dir>/rotation.opq. Returns None if file doesn’t exist.

Errors

Returns Error::Io if deserialization or file I/O fails.

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<'de> Deserialize<'de> for ProductQuantizer

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ProductQuantizer

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.