Struct GsSq8Codec 

pub struct GsSq8Codec {
    pub min: Vec<f32>,
    pub gs: f32,
    pub gs_sq: f32,
    pub anisotropy_ratio: f32,
}

Global-scale SQ8 codec for L2 distance — the Vamana acquisition path.

A single shared scale gs = max_range_across_dims / 255 is used for all dims; per-dim offsets are still subtracted before quantizing. Encoding is lossy (rounded + clamped to u8); L2² in code space is exact after that lossy encode, but round-trip error vs. true f32 L2² can reach ~15% for anisotropic/OOD data — no residual pass, no gate, no silent fallback. Callers needing correctness on OOD queries must check Self::is_in_distribution and fall back to exact f32 themselves. See docs/api/codecs.md for the full accuracy discussion and docs/design.md for why this replaced the earlier per-dim anisotropy-gated design.

Fields

min: Vec<f32>

Per-dimension minimum values.

gs: f32

Global scale: max_range / 255 where max_range = max_i(max_i - min_i).

gs_sq: f32

gs² precomputed for L2.

anisotropy_ratio: f32

Anisotropy ratio measured at train time: max(range_i) / min(nonzero range_i). Informational only — never used for dispatch decisions.

Implementations

impl GsSq8Codec

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

Train 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.

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]) -> GsEncodedVector

Encode a single vector.

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<GsEncodedVector, QuantError>

Fallible variant of Self::encode. Validates v.len() against the codec’s trained dims before encoding — an unchecked shape mismatch (e.g. v = &[]) could otherwise score as a false exact match; see docs/design.md (QUANT-AUD-002).

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

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<GsEncodedVector>, 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 l2_sq(&self, a: &GsEncodedVector, b: &GsEncodedVector) -> f32

Approximate squared L2 distance.

||a-b||² ≈ gs² × Σ (a_i - b_i)²

Exact in code space (offset terms cancel, gs² factorizes) after the lossy f32→u8 encode. Per-round-trip L2 error can reach ~15%; recall safety is established by probe, not by this formula. The NEON path runs ~13 ns at 384-d.

pub fn l2_sq_codes(&self, a: &[u8], b: &[u8]) -> f32

Self::l2_sq over raw code slices, for callers that store codes in a flat (possibly memory-mapped) buffer rather than per-vector allocations.

pub fn dims(&self) -> usize

Number of dimensions.

pub fn is_in_distribution(&self, v: &[f32]) -> bool

Returns true if every component of v falls within the trained range [min_d, min_d + 255 * gs] (i.e., encoding would produce no clamping).

When this returns false at least one dimension is out-of-distribution; callers that need correctness guarantees should fall back to exact f32.

Trait Implementations

impl Clone for GsSq8Codec

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 GsSq8Codec

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

Formats the value using the given formatter.