Struct Sq8Codec 

pub struct Sq8Codec {
    pub dim: usize,
    /* private fields */
}

SQ8 calibration parameters: per-dimension min/max.

Fields

dim: usize

Implementations

impl Sq8Codec

pub fn calibrate(vectors: &[&[f32]], dim: usize) -> Self

Calibrate min/max from a set of training vectors.

Scans all vectors to find per-dimension min/max bounds. At least 1000 vectors recommended for stable calibration; for fewer vectors the bounds may be tight, causing clipping on future inserts outside the calibration range.

pub fn quantize(&self, vector: &[f32]) -> Vec<u8>

Quantize a single FP32 vector to INT8.

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

Batch quantize: quantize all vectors into a contiguous byte array.

Returns dim * N bytes laid out as [v0_d0, v0_d1, ..., v1_d0, ...].

pub fn dequantize(&self, quantized: &[u8]) -> Vec<f32>

Dequantize INT8 back to FP32 (lossy reconstruction).

pub fn asymmetric_l2(&self, query: &[f32], candidate: &[u8]) -> f32

Asymmetric L2 squared distance: query (FP32) vs candidate (INT8).

This is the hot-path function used during HNSW traversal. The query stays in full precision; only the candidate is quantized.

pub fn asymmetric_cosine(&self, query: &[f32], candidate: &[u8]) -> f32

Asymmetric cosine distance: query (FP32) vs candidate (INT8).

pub fn asymmetric_ip(&self, query: &[f32], candidate: &[u8]) -> f32

Asymmetric negative inner product: query (FP32) vs candidate (INT8).

pub fn dim(&self) -> usize

Dimension count.

pub fn to_bytes(&self) -> Vec<u8>

Serialize the codec to bytes with a versioned magic header.

Format: [NDSQ\0\0 (6 bytes)][version: u8 = 1][msgpack payload]

pub fn from_bytes(bytes: &[u8]) -> Result<Self, VectorError>

Deserialize the codec from bytes produced by Self::to_bytes.

Returns VectorError::InvalidMagic if the header does not match NDSQ\0\0, and VectorError::UnsupportedVersion for unknown versions.

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<'de> Deserialize<'de> for Sq8Codec

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'__msgpack_de> FromMessagePack<'__msgpack_de> for Sq8Codec

fn read<R: Read<'__msgpack_de>>(reader: &mut R) -> Result<Self, Error>

where Self: Sized,

Reads the MessagePack representation of this value from the provided reader.

impl Serialize for Sq8Codec

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ToMessagePack for Sq8Codec

fn write<W: Write>(&self, writer: &mut W) -> Result<(), Error>

Writes the MessagePack representation of this value into the provided writer.

impl VectorCodec for Sq8Codec

type Query = Vec<f32>

Raw FP32 query — asymmetric distance; query is never quantized.

fn encode(&self, v: &[f32]) -> Self::Quantized

Encode a single FP32 vector into an SQ8 UnifiedQuantizedVector.

Panics

The UnifiedQuantizedVector::new call will only fail if the outlier count mismatches the bitmask, or an outlier dim_index ≥ 64. Neither condition can arise here: outlier_bitmask is 0 and outliers is empty. The expect is therefore unreachable in practice.

fn prepare_query(&self, q: &[f32]) -> Self::Query

Prepare the FP32 query for asymmetric distance computations.

For SQ8 the query is used directly without rotation or normalization.

fn adc_lut(&self, _q: &Self::Query) -> Option<AdcLut>

SQ8 has no precomputed ADC table — returns None.

fn fast_symmetric_distance( &self, q: &Self::Quantized, v: &Self::Quantized, ) -> f32

Symmetric L2 squared distance between two SQ8-quantized vectors.

Both codes are dequantized to FP32 via self.mins + self.scales, then the squared difference is accumulated. This is slower than an exact INT8-INT8 Hamming estimate but SQ8 has no faster bitwise symmetric form.

fn exact_asymmetric_distance(&self, q: &Self::Query, v: &Self::Quantized) -> f32

Asymmetric L2 squared distance: FP32 query vs INT8 candidate.

Delegates directly to Sq8Codec::asymmetric_l2. Cosine / IP variants require a separate codec wrapper that normalizes or negates at encode time.

type Quantized = Sq8Quantized

The packed quantized form. Must be convertible to a UnifiedQuantizedVector reference via AsRef.

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

Optional: fit the codec’s learned parameters on a set of training vectors.