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 (min_i) are still subtracted before quantizing so codes span [0, 255] for the widest dim and fewer levels for narrower dims (honest trade-off).

Encoding is lossy: f32 components are rounded and clamped to u8 before storage. L2² in code space (gs² × Σ (a_i - b_i)²) is exact after that lossy encode — offset terms cancel and gs² factorizes — but the round-trip error relative to the original f32 L2² can reach ~15% for anisotropic or out-of-distribution data. Recall safety must be established by probe (see sq8_recall_parity_vs_f32_oracle and sq8_ood_fallback_deterministic_ranking_flip), not by an exactness argument. No residual pass, no gate, no silent fallback for anisotropic data.

Historical note: the predecessor per-dim codec required approx_l2_sq_fast + an anisotropy gate (ratio ≤ 4.0) to achieve the integer-only hot path. The gate was calibrated on an LCG corpus that gave ratio ≈ 4.0; real transformer embeddings have rogue dimensions (ratio 10–32) that silently fell back to the full residual path, defeating the purpose. Global-scale eliminates the gate entirely — see ADR-052.

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, replacing the prior debug-only length assertion (which was compiled out in release builds and could silently produce a malformed code vector, e.g. an empty v yields an empty code vector that is_in_distribution vacuously accepts and l2_sq scores as 0.0).

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

Encode a batch of flat-row vectors in parallel.

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, replacing the prior unchecked division (panics on dims == 0) and silent truncation.

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 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) -> GsSq8Codec

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.