Skip to main content

lattice_simd/
tier.rs

1//! Quantization tiers, prepared queries, and unified distance dispatch.
2//!
3//! Tiers trade storage for fidelity; prepared queries avoid repeated
4//! quantization in homogeneous candidate searches.
5//!
6//! See docs/simd.md for tier selection and dispatch semantics.
7
8use super::binary::BinaryVector;
9use super::int4::Int4Vector;
10use super::quantized::{QuantizedVector, cosine_similarity_i8_trusted, dot_product_i8_trusted};
11use super::{cosine_similarity, dot_product};
12use crate::error::{Result, SimdError};
13
14/// Caller assertion that a vector is L2-unit-normalized (norm ≈ 1).
15///
16/// When both query and stored vectors carry `UnitNorm`, cosine similarity equals
17/// the dot product — the norm division can be skipped entirely.
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
19#[non_exhaustive]
20pub enum NormalizationHint {
21    /// No guarantee — full cosine (with norm division) is required.
22    Unknown,
23    /// Caller asserts this vector is L2-unit-normalized (norm ≈ 1 within 1e-4).
24    Unit,
25}
26
27/// **Unstable**: tier design is under active iteration; tier boundaries may change.
28///
29/// Quantization precision tier, ordered from highest to lowest fidelity.
30#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
31#[non_exhaustive]
32pub enum QuantizationTier {
33    /// Full f32 precision (4 bytes/dim, 1x baseline).
34    Full,
35    /// INT8 symmetric quantization (1 byte/dim, 4x compression).
36    Int8,
37    /// INT4 packed nibble quantization (0.5 bytes/dim, 8x compression).
38    Int4,
39    /// Binary sign-bit quantization (0.125 bytes/dim, 32x compression).
40    Binary,
41}
42
43impl QuantizationTier {
44    /// **Unstable**: bytes-per-dimension constant; may change with new tiers.
45    pub fn bytes_per_dim(&self) -> f32 {
46        match self {
47            Self::Full => 4.0,
48            Self::Int8 => 1.0,
49            Self::Int4 => 0.5,
50            Self::Binary => 0.125,
51        }
52    }
53
54    /// **Unstable**: compression ratio; derived from `bytes_per_dim`, may be removed.
55    pub fn compression_ratio(&self) -> f32 {
56        4.0 / self.bytes_per_dim()
57    }
58
59    /// **Unstable**: storage byte computation; may change with new tiers.
60    pub fn storage_bytes(&self, dims: usize) -> usize {
61        match self {
62            Self::Full => dims * 4,
63            Self::Int8 => dims,
64            Self::Int4 => dims.div_ceil(2),
65            Self::Binary => dims.div_ceil(8),
66        }
67    }
68
69    /// **Warning**: this is a placeholder storage policy, not evidence that older vectors
70    /// tolerate lower precision. Callers should measure retrieval quality for their workload.
71    ///
72    /// **Unstable**: tier boundaries may be tuned.
73    pub fn from_age_seconds(age_secs: u64) -> Self {
74        const HOUR: u64 = 3600;
75        const DAY: u64 = 86400;
76        const WEEK: u64 = 604800;
77
78        if age_secs < HOUR {
79            Self::Full
80        } else if age_secs < DAY {
81            Self::Int8
82        } else if age_secs < WEEK {
83            Self::Int4
84        } else {
85            Self::Binary
86        }
87    }
88}
89
90/// **Unstable**: unified quantized data container; variants may change with tier redesign.
91///
92/// Wraps the tier-specific vector types into a single enum for
93/// uniform storage and distance dispatch.
94#[derive(Debug, Clone)]
95#[non_exhaustive]
96pub enum QuantizedData {
97    /// Full-precision f32 vector.
98    Full(Vec<f32>),
99    /// INT8 quantized vector.
100    Int8(QuantizedVector),
101    /// INT4 packed quantized vector.
102    Int4(Int4Vector),
103    /// Binary sign-bit vector.
104    Binary(BinaryVector),
105}
106
107impl QuantizedData {
108    /// **Unstable**: returns `QuantizationTier` which is itself Unstable.
109    pub fn tier(&self) -> QuantizationTier {
110        match self {
111            Self::Full(_) => QuantizationTier::Full,
112            Self::Int8(_) => QuantizationTier::Int8,
113            Self::Int4(_) => QuantizationTier::Int4,
114            Self::Binary(_) => QuantizationTier::Binary,
115        }
116    }
117
118    /// **Unstable**: dimension accessor; may be removed if `QuantizedData` gains a dims field.
119    pub fn dims(&self) -> usize {
120        match self {
121            Self::Full(v) => v.len(),
122            Self::Int8(q) => q.len(),
123            Self::Int4(q) => q.dims,
124            Self::Binary(q) => q.dims,
125        }
126    }
127
128    /// **Unstable**: storage byte count; may change with tier redesign.
129    pub fn storage_bytes(&self) -> usize {
130        match self {
131            Self::Full(v) => v.len() * 4,
132            Self::Int8(q) => q.len(),
133            Self::Int4(q) => q.data.len(),
134            Self::Binary(q) => q.data.len(),
135        }
136    }
137
138    /// **Unstable**: quantization factory; tier dispatch logic may change.
139    pub fn from_f32(vector: &[f32], tier: QuantizationTier) -> Self {
140        match tier {
141            QuantizationTier::Full => Self::Full(vector.to_vec()),
142            QuantizationTier::Int8 => Self::Int8(QuantizedVector::from_f32(vector)),
143            QuantizationTier::Int4 => Self::Int4(Int4Vector::from_f32(vector)),
144            QuantizationTier::Binary => Self::Binary(BinaryVector::from_f32(vector)),
145        }
146    }
147
148    /// **Unstable**: dequantization; output precision is tier-dependent.
149    pub fn to_f32(&self) -> Vec<f32> {
150        match self {
151            Self::Full(v) => v.clone(),
152            Self::Int8(q) => q.to_f32(),
153            Self::Int4(q) => q.to_f32(),
154            Self::Binary(q) => q.to_f32(),
155        }
156    }
157
158    /// **Unstable**: re-quantizes through `f32`; lost information is not recovered.
159    pub fn promote(&self, target: QuantizationTier) -> Self {
160        let f32_data = self.to_f32();
161        Self::from_f32(&f32_data, target)
162    }
163
164    /// **Unstable**: tier demotion; delegates to `promote`; may be removed.
165    pub fn demote(&self, target: QuantizationTier) -> Self {
166        self.promote(target) // Same operation, just going the other direction
167    }
168}
169
170/// **Unstable**: pre-quantized query for repeated same-tier distance computation.
171#[derive(Debug, Clone)]
172#[non_exhaustive]
173pub enum PreparedQuery {
174    /// Full f32 query.
175    Full(Vec<f32>),
176    /// INT8 quantized query.
177    Int8(QuantizedVector),
178    /// INT4 packed quantized query.
179    Int4(Int4Vector),
180    /// Binary sign-bit query.
181    Binary(BinaryVector),
182}
183
184impl PreparedQuery {
185    /// Quantize a query at the given tier for repeated distance calls.
186    #[inline]
187    pub fn from_f32(query_f32: &[f32], tier: QuantizationTier) -> Self {
188        match tier {
189            QuantizationTier::Full => Self::Full(query_f32.to_vec()),
190            QuantizationTier::Int8 => Self::Int8(QuantizedVector::from_f32(query_f32)),
191            QuantizationTier::Int4 => Self::Int4(Int4Vector::from_f32(query_f32)),
192            QuantizationTier::Binary => Self::Binary(BinaryVector::from_f32(query_f32)),
193        }
194    }
195
196    /// Returns the quantization tier of this prepared query.
197    #[inline]
198    pub fn tier(&self) -> QuantizationTier {
199        match self {
200            Self::Full(_) => QuantizationTier::Full,
201            Self::Int8(_) => QuantizationTier::Int8,
202            Self::Int4(_) => QuantizationTier::Int4,
203            Self::Binary(_) => QuantizationTier::Binary,
204        }
205    }
206
207    /// Returns the number of dimensions.
208    #[inline]
209    pub fn dims(&self) -> usize {
210        match self {
211            Self::Full(v) => v.len(),
212            Self::Int8(q) => q.len(),
213            Self::Int4(q) => q.dims,
214            Self::Binary(q) => q.dims,
215        }
216    }
217}
218
219/// Prepare a query vector for repeated distance computation against a homogeneous tier.
220#[inline]
221pub fn prepare_query(query_f32: &[f32], tier: QuantizationTier) -> PreparedQuery {
222    PreparedQuery::from_f32(query_f32, tier)
223}
224
225/// A prepared query with caller-provided normalization metadata.
226#[derive(Debug, Clone)]
227pub struct PreparedQueryWithMeta {
228    /// The quantized query (owns the data).
229    pub query: PreparedQuery,
230    /// Caller assertion about the query vector's normalization state.
231    pub norm: NormalizationHint,
232}
233
234impl PreparedQueryWithMeta {
235    /// Create a prepared query from an f32 vector, asserting its normalization state.
236    #[inline]
237    pub fn from_f32(query_f32: &[f32], tier: QuantizationTier, norm: NormalizationHint) -> Self {
238        Self {
239            query: PreparedQuery::from_f32(query_f32, tier),
240            norm,
241        }
242    }
243
244    /// Returns the quantization tier.
245    #[inline]
246    pub fn tier(&self) -> QuantizationTier {
247        self.query.tier()
248    }
249
250    /// Returns the number of dimensions.
251    #[inline]
252    pub fn dims(&self) -> usize {
253        self.query.dims()
254    }
255}
256
257/// Returns `true` when the squared norm of `v` is within 1e-4 of 1.0.
258///
259/// Uses the SIMD-dispatched [`dot_product`] for the self-dot rather than a plain
260/// scalar reduction. This helper is no longer called on the cosine hot path
261/// (`approximate_cosine_distance_prepared_with_meta` delegates to the fused
262/// path instead of guarding a hint-selected shortcut), but any caller checking
263/// norms per candidate gets the SIMD cost model, not a scalar one.
264#[inline]
265pub fn is_unit_norm(v: &[f32]) -> bool {
266    let sq = dot_product(v, v);
267    (sq - 1.0).abs() < 1e-4
268}
269
270/// Prepare a query annotated with the given normalization hint.
271#[inline]
272pub fn prepare_query_with_norm(
273    query_f32: &[f32],
274    tier: QuantizationTier,
275    norm: NormalizationHint,
276) -> PreparedQueryWithMeta {
277    PreparedQueryWithMeta::from_f32(query_f32, tier, norm)
278}
279
280/// **Unstable**: computes prepared cosine distance in `[0, 2]` for matching tiers.
281///
282/// Returns [`SimdError::TierMismatch`] for a different stored tier.
283/// See [`docs/simd.md`](../docs/simd.md#prepared-queries-and-tier-matching) for the per-tier paths.
284#[inline]
285pub fn approximate_cosine_distance_prepared(
286    query: &PreparedQuery,
287    stored: &QuantizedData,
288) -> Result<f32> {
289    match (query, stored) {
290        (PreparedQuery::Full(q), QuantizedData::Full(s)) => Ok(1.0 - cosine_similarity(q, s)),
291        (PreparedQuery::Int8(q), QuantizedData::Int8(s)) => {
292            Ok(1.0 - cosine_similarity_i8_trusted(s, q))
293        }
294        (PreparedQuery::Int4(q), QuantizedData::Int4(s)) => Ok(s.cosine_distance(q)),
295        (PreparedQuery::Binary(q), QuantizedData::Binary(s)) => Ok(s.cosine_distance_approx(q)),
296        _ => Err(SimdError::TierMismatch {
297            op: "approximate_cosine_distance_prepared",
298            expected: stored.tier(),
299            actual: query.tier(),
300        }),
301    }
302}
303
304/// Alias for [`approximate_cosine_distance_prepared`] retained for compatibility.
305#[inline]
306pub fn try_approximate_cosine_distance_prepared(
307    query: &PreparedQuery,
308    stored: &QuantizedData,
309) -> Result<f32> {
310    approximate_cosine_distance_prepared(query, stored)
311}
312
313/// Alias for [`approximate_dot_product_prepared`] retained for compatibility.
314#[inline]
315pub fn try_approximate_dot_product_prepared(
316    query: &PreparedQuery,
317    stored: &QuantizedData,
318) -> Result<f32> {
319    approximate_dot_product_prepared(query, stored)
320}
321
322/// Computes prepared cosine distance; hints are accepted but do not select a
323/// separate code path.
324///
325/// The former `Full` unit-norm "fast path" (skip norm division when both sides
326/// assert unit norm) was measurably slower than the general path it guarded:
327/// verifying the stored side's norm plus the query dot takes two O(d) passes,
328/// while [`cosine_similarity`] computes the dot and both norms in one fused
329/// pass. With the guard it was also a correctness risk, trusting release-time
330/// hints. Delegating unconditionally is both the fastest and the safest shape.
331///
332/// Returns [`SimdError::TierMismatch`] for a tier mismatch.
333/// See [`docs/simd.md`](../docs/simd.md#prepared-queries-and-tier-matching) for hint semantics.
334#[inline]
335pub fn approximate_cosine_distance_prepared_with_meta(
336    meta: &PreparedQueryWithMeta,
337    stored: &QuantizedData,
338    _stored_norm: NormalizationHint,
339) -> Result<f32> {
340    approximate_cosine_distance_prepared(&meta.query, stored)
341}
342
343/// **Unstable**: computes a prepared dot product for matching non-binary tiers.
344///
345/// Returns [`SimdError::TierMismatch`] for different tiers or [`SimdError::Internal`] for binary.
346/// See [`docs/simd.md`](../docs/simd.md#prepared-queries-and-tier-matching) for supported paths.
347#[inline]
348pub fn approximate_dot_product_prepared(
349    query: &PreparedQuery,
350    stored: &QuantizedData,
351) -> Result<f32> {
352    match (query, stored) {
353        (PreparedQuery::Full(q), QuantizedData::Full(s)) => Ok(dot_product(q, s)),
354        (PreparedQuery::Int8(q), QuantizedData::Int8(s)) => Ok(dot_product_i8_trusted(q, s)),
355        (PreparedQuery::Int4(q), QuantizedData::Int4(s)) => Ok(s.dot_product(q)),
356        (PreparedQuery::Binary(_), QuantizedData::Binary(_)) => Err(SimdError::Internal(
357            "Binary has no prepared dot product; use approximate_cosine_distance_prepared".into(),
358        )),
359        _ => Err(SimdError::TierMismatch {
360            op: "approximate_dot_product_prepared",
361            expected: stored.tier(),
362            actual: query.tier(),
363        }),
364    }
365}
366
367/// Computes distances from one prepared query to all stored vectors.
368///
369/// Returns [`SimdError::TierMismatch`] if any stored tier differs.
370#[inline]
371pub fn batch_approximate_cosine_distance_prepared(
372    query: &PreparedQuery,
373    stored: &[QuantizedData],
374) -> Result<Vec<f32>> {
375    stored
376        .iter()
377        .map(|item| approximate_cosine_distance_prepared(query, item))
378        .collect()
379}
380
381/// Writes prepared-query distances into a reusable buffer, clearing it on error.
382///
383/// Returns [`SimdError::TierMismatch`] if any stored tier differs.
384/// See [`docs/simd.md`](../docs/simd.md#prepared-queries-and-tier-matching) for buffer semantics.
385#[inline]
386pub fn batch_approximate_cosine_distance_prepared_into(
387    query: &PreparedQuery,
388    stored: &[QuantizedData],
389    out: &mut Vec<f32>,
390) -> Result<()> {
391    out.clear();
392    out.reserve(stored.len());
393    for item in stored {
394        match approximate_cosine_distance_prepared(query, item) {
395            Ok(distance) => out.push(distance),
396            Err(e) => {
397                out.clear();
398                return Err(e);
399            }
400        }
401    }
402    Ok(())
403}
404
405/// Computes distances from one prepared INT8 query without re-quantizing it.
406///
407/// Returns [`SimdError::TierMismatch`] unless the query is INT8.
408#[inline]
409pub fn approximate_int8_batch_prepared(
410    query: &PreparedQuery,
411    candidates: &[QuantizedVector],
412) -> Result<Vec<f32>> {
413    let PreparedQuery::Int8(q) = query else {
414        return Err(SimdError::TierMismatch {
415            op: "approximate_int8_batch_prepared",
416            expected: QuantizationTier::Int8,
417            actual: query.tier(),
418        });
419    };
420    Ok(candidates
421        .iter()
422        .map(|candidate| 1.0 - cosine_similarity_i8_trusted(candidate, q))
423        .collect())
424}
425
426/// Writes prepared INT8 distances into a reusable buffer, clearing it on error.
427///
428/// Returns [`SimdError::TierMismatch`] unless the query is INT8.
429#[inline]
430pub fn approximate_int8_batch_prepared_into(
431    query: &PreparedQuery,
432    candidates: &[QuantizedVector],
433    out: &mut Vec<f32>,
434) -> Result<()> {
435    out.clear();
436    let PreparedQuery::Int8(q) = query else {
437        return Err(SimdError::TierMismatch {
438            op: "approximate_int8_batch_prepared_into",
439            expected: QuantizationTier::Int8,
440            actual: query.tier(),
441        });
442    };
443    out.reserve(candidates.len());
444    out.extend(
445        candidates
446            .iter()
447            .map(|candidate| 1.0 - cosine_similarity_i8_trusted(candidate, q)),
448    );
449    Ok(())
450}
451
452/// Computes distances from one prepared INT4 query without re-quantizing it.
453///
454/// Returns [`SimdError::TierMismatch`] unless the query is INT4.
455#[inline]
456pub fn approximate_int4_batch_prepared(
457    query: &PreparedQuery,
458    candidates: &[Int4Vector],
459) -> Result<Vec<f32>> {
460    let PreparedQuery::Int4(q) = query else {
461        return Err(SimdError::TierMismatch {
462            op: "approximate_int4_batch_prepared",
463            expected: QuantizationTier::Int4,
464            actual: query.tier(),
465        });
466    };
467    Ok(candidates
468        .iter()
469        .map(|candidate| candidate.cosine_distance(q))
470        .collect())
471}
472
473/// Writes prepared INT4 distances into a reusable buffer, clearing it on error.
474///
475/// Returns [`SimdError::TierMismatch`] unless the query is INT4.
476#[inline]
477pub fn approximate_int4_batch_prepared_into(
478    query: &PreparedQuery,
479    candidates: &[Int4Vector],
480    out: &mut Vec<f32>,
481) -> Result<()> {
482    out.clear();
483    let PreparedQuery::Int4(q) = query else {
484        return Err(SimdError::TierMismatch {
485            op: "approximate_int4_batch_prepared_into",
486            expected: QuantizationTier::Int4,
487            actual: query.tier(),
488        });
489    };
490    out.reserve(candidates.len());
491    out.extend(
492        candidates
493            .iter()
494            .map(|candidate| candidate.cosine_distance(q)),
495    );
496    Ok(())
497}
498
499/// **Unstable**: quantizes an `f32` query and computes tiered cosine distance.
500///
501/// `query_f32.len()` must match stored dimensionality.
502/// See [`docs/simd.md`](../docs/simd.md#prepared-queries-and-tier-matching) for hot-loop guidance.
503pub fn approximate_cosine_distance(query_f32: &[f32], stored: &QuantizedData) -> f32 {
504    debug_assert_eq!(
505        query_f32.len(),
506        stored.dims(),
507        "approximate_cosine_distance: query length {} != stored dims {}",
508        query_f32.len(),
509        stored.dims(),
510    );
511    match stored {
512        QuantizedData::Full(v) => {
513            // Exact cosine distance
514            1.0 - cosine_similarity(query_f32, v)
515        }
516        QuantizedData::Int8(q) => {
517            let query_q = QuantizedVector::from_f32(query_f32);
518            1.0 - q.cosine_similarity(&query_q)
519        }
520        QuantizedData::Int4(q) => {
521            let query_q = Int4Vector::from_f32(query_f32);
522            q.cosine_distance(&query_q)
523        }
524        QuantizedData::Binary(q) => {
525            let query_q = BinaryVector::from_f32(query_f32);
526            q.cosine_distance_approx(&query_q)
527        }
528    }
529}
530
531/// **Unstable**: approximate tiered dot-product dispatch.
532pub fn approximate_dot_product(query_f32: &[f32], stored: &QuantizedData) -> f32 {
533    match stored {
534        QuantizedData::Full(v) => dot_product(query_f32, v),
535        QuantizedData::Int8(q) => {
536            let query_q = QuantizedVector::from_f32(query_f32);
537            q.dot_product(&query_q)
538        }
539        QuantizedData::Int4(q) => {
540            let query_q = Int4Vector::from_f32(query_f32);
541            q.dot_product(&query_q)
542        }
543        QuantizedData::Binary(_q) => {
544            // Binary doesn't have a meaningful dot product; fall back to dequantize
545            let stored_f32 = _q.to_f32();
546            dot_product(query_f32, &stored_f32)
547        }
548    }
549}
550
551#[cfg(test)]
552mod tests;