Struct Sq8Codec 

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

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 and dot product.

mean_scale_sq: f32

Mean of scale_sq across all dimensions — used as the integer-pass multiplier.

scale_sq_residual: Vec<f32>

Residual: scale_sq_i - mean_scale_sq (zero-mean, small magnitude).

offset_sq_sum: f32

Σ_i min_i² precomputed for dot-product correction.

Implementations

impl Sq8Codec

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

Train a codec from row-major flat vectors.

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

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

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

Encode a single vector into SQ8 codes + correction metadata.

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

Encode a batch of flat-row vectors in parallel.

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

Encode a batch of row vectors in parallel.

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

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

Full-precision correction identity (same min/scale for both): dot(a, b) = Σ s²·a·b + soc_a + soc_b + offset_sq_sum

The integer pass (u8_dot_u32) computes raw = Σ a_i*b_i as u32 using NEON (16-wide on aarch64). The scale correction then applies mean_scale_sq plus a compact per-dim residual f32 pass for accuracy.

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 — per-dim residual corrected.

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

The integer pass (u8_l2sq_u32) computes raw = Σ (a_i-b_i)² using NEON vabdq_u8 + vmull_u8. The residual correction keeps ordinal accuracy across anisotropic corpora.

For Vamana L2 acquisition use GsSq8Codec::l2_sq — algebraically exact in code space and ~2× faster (no residual pass).

pub fn dims(&self) -> usize

Number of dimensions.

Trait Implementations

impl Clone for Sq8Codec

fn clone(&self) -> Sq8Codec

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.