Struct PqRerank 

pub struct PqRerank { /* private fields */ }

Object-safe RerankCodec wrapper around PqCodec.

The codec starts untrained. encode and prepare_query return RerankError::NotTrained until train() has been called with a representative sample of vectors.

from_codec accepts a pre-trained PqCodec (used when restoring from a snapshot).

Implementations

impl PqRerank

pub fn new(dim: usize, m: usize, k: usize) -> Self

Construct an untrained PQ codec configuration.

m is the number of subspaces; k is centroids per subspace. Defaults used by higher-level callers: m = 8, k = 256. encode / distance_prepared return RerankError::NotTrained until train() has been called.

pub fn from_codec(codec: PqCodec) -> Self

Construct from a pre-trained codec (used when restoring from snapshot).

Trait Implementations

impl RerankCodec for PqRerank

fn encode(&self, v: &[f32]) -> Result<Vec<u8>, RerankError>

Encode a full-precision vector to PQ bytes (one centroid index per subspace).

The serialized form is the raw UnifiedQuantizedVector buffer (as_bytes()): 32-byte QuantHeader followed by m code bytes.

fn prepare_query(&self, q: &[f32]) -> Result<PreparedQuery, RerankError>

Prepare the query by precomputing the M×K asymmetric distance table.

The prepared form is PreparedQuery::Lut where lut[sub][centroid] holds the squared L2 distance from the query’s sub-vector to each centroid of subspace sub. This is the standard ADC lookup table.

fn distance_prepared( &self, prepared: &PreparedQuery, encoded: &[u8], ) -> Result<f32, RerankError>

Compute asymmetric ADC distance from a prepared query to a PQ-encoded candidate.

Expects PreparedQuery::Lut produced by prepare_query.

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

Train PQ codebooks via k-means on a sample of vectors.

Validates that:

• samples is non-empty.
• Every sample has length self.dim.
• self.dim % self.m == 0 (PQ requires divisible dimensionality).
• At least self.k samples are provided (k-means needs ≥ k points).

On success, stores the trained codec and subsequent encode / distance_prepared calls will succeed.

fn name(&self) -> CodecName

Identity tag for mismatch detection.

fn to_bytes(&self) -> Result<Vec<u8>, RerankError>

Serialize trained state to bytes. Each codec uses its own magic header (NDSQ / NDBIN / NDPQ / NDRBQ / NDBBQ). The bytes are codec-specific; rerank_codec_from_bytes is used for restore, paired with name().