Struct Sq8Codec 

pub struct Sq8Codec {
    pub min: Vec<f32>,
    pub scale: Vec<f32>,
    pub scale_sq: Vec<f32>,
    pub scale_sq_f64: Vec<f64>,
    pub mean_scale_sq: f32,
    pub scale_sq_residual: Vec<f32>,
    pub offset_sq_sum: f32,
    pub offset_sq_sum_f64: f64,
}

Per-dimension affine SQ8 codec for dot product and cosine distance.

Encodes f32 dimensions to u8 via: code = round((x - min) / scale), where scale_i = (max_i - min_i) / 255.

For L2 distance on Vamana builds, use GsSq8Codec instead — its global shared scale makes L2 algebraically exact in code space without a residual pass.

Fields

min: Vec<f32>

Per-dimension minimum values.

scale: Vec<f32>

Per-dimension scale: (max - min) / 255.

scale_sq: Vec<f32>

Per-dimension scale² precomputed for fast L2.

scale_sq_f64: Vec<f64>

Legacy per-dimension f64 scale² cache, retained for public-field compatibility.

mean_scale_sq: f32

Legacy mean of scale_sq; retained for public-field compatibility.

scale_sq_residual: Vec<f32>

Legacy residual: scale_sq_i - mean_scale_sq; distance methods do not use it.

offset_sq_sum: f32

Legacy f32 Σ_i min_i² correction, retained for public-field compatibility.

offset_sq_sum_f64: f64

Legacy f64 Σ_i min_i² cache, retained for public-field compatibility.

Implementations

impl Sq8Codec

pub fn train_flat(vectors: &[f32], dims: usize) -> Self

Train a codec from row-major flat vectors.

Panics on invalid input. See Self::try_train_flat for a fallible variant that returns QuantError instead.

pub fn try_train_flat(vectors: &[f32], dims: usize) -> Result<Self, QuantError>

Fallible variant of Self::train_flat. Validates dims > 0, a non-empty corpus, and that vectors.len() is a multiple of dims.

pub fn train(vectors: &[Vec<f32>]) -> Self

Train from a slice of row vectors (each a Vec<f32>).

Panics on invalid input. See Self::try_train for a fallible variant that returns QuantError instead.

pub fn try_train(vectors: &[Vec<f32>]) -> Result<Self, QuantError>

Fallible variant of Self::train. Validates a non-empty corpus, dims > 0 (row 0’s length), and that every row is the same length (rectangular corpus); a ragged row returns QuantError::RaggedRow instead of panicking on out-of-bounds indexing.

pub fn encode(&self, v: &[f32]) -> EncodedVector

Encode a single vector into SQ8 codes + correction metadata.

Panics if v.len() does not match the codec’s trained dims. See Self::try_encode for a fallible variant that returns QuantError instead.

pub fn try_encode(&self, v: &[f32]) -> Result<EncodedVector, QuantError>

Fallible variant of Self::encode. Validates v.len() against the codec’s trained dims before encoding. See docs/design.md (QUANT-AUD-002) for why this check must be a typed error, not a debug-only assertion.

pub fn encode_flat_par( &self, vectors: &[f32], dims: usize, ) -> Vec<EncodedVector>

Encode a batch of flat-row vectors, using Rayon when the parallel feature is enabled.

Panics on invalid input. See Self::try_encode_flat_par for a fallible variant that returns QuantError instead.

pub fn try_encode_flat_par( &self, vectors: &[f32], dims: usize, ) -> Result<Vec<EncodedVector>, QuantError>

Fallible variant of Self::encode_flat_par. Validates dims > 0, divisibility, and that dims matches the codec’s trained dims before dividing vectors.len() / dims. See docs/design.md (QUANT-AUD-002).

pub fn encode_par(&self, vectors: &[Vec<f32>]) -> Vec<EncodedVector>

Encode a batch of row vectors, using Rayon when the parallel feature is enabled.

Panics if any row’s length does not match the codec’s trained dims. See Self::try_encode_par for a fallible variant that returns QuantError instead.

pub fn try_encode_par( &self, vectors: &[Vec<f32>], ) -> Result<Vec<EncodedVector>, QuantError>

Fallible variant of Self::encode_par. Validates every row’s length against the codec’s trained dims before dispatching to the thread pool.

pub fn approx_dot(&self, a: &EncodedVector, b: &EncodedVector) -> f32

Approximate dot product between two encoded vectors (same codec).

Each dimension contributes (s·a + min)·(s·b + min) in f64 before dimensions are summed. Keeping the affine correction within each dimension avoids cancellation that erases a narrow dimension when another dimension has much larger offsets. Panics if either encoded vector has a different length from this codec.

pub fn approx_cosine_dist(&self, a: &EncodedVector, b: &EncodedVector) -> f32

Approximate cosine distance between two encoded vectors (same codec).

Returns 1 - dot / (norm_a * norm_b). Falls back to 1.0 for zero norms.

pub fn approx_l2_sq(&self, a: &EncodedVector, b: &EncodedVector) -> f32

Approximate squared L2 distance with direct per-dimension weights.

Full-precision identity: ||a-b||² = Σ scale_sq_i * (a_i-b_i)². Offsets cancel because both vectors share the same codec.

Nonnegative terms are accumulated in f64 and rounded to f32 once. This avoids cancellation between a shared f32 mean and residuals in strongly anisotropic corpora. Panics if either encoded vector has a different length from this codec.

For Vamana L2 acquisition use GsSq8Codec::l2_sq — algebraically exact in code space and uses the integer NEON path.

pub fn dims(&self) -> usize

Number of dimensions.

Trait Implementations

impl Clone for Sq8Codec

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Sq8Codec

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

Formats the value using the given formatter.