qntz 0.1.2

Vector quantization primitives (RaBitQ, ternary, bit packing) for ANN systems.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

//! # qntz
//!
//! Vector quantization primitives for ANN systems.
//!
//! Scope: small, reusable pieces (bit packing, low-bit codes) that higher-level ANN
//! crates can build on. This crate intentionally does **not** implement full indices.
//!
//! ## Contract
//!
//! - **No silent meaning**: packed codes have explicit conventions (e.g. 1-bit codes use
//!   `bit=1 -> +1`, `bit=0 -> -1` where stated).
//! - **No hidden geometry**: this crate provides code operations; it does not define a distance
//!   metric for your original vectors.
//! - **Determinism**: operations are pure and deterministic.
//!
//! ## Example
//!
//! Pack two binary code vectors and compute Hamming distance.
//!
//! ```rust
//! use qntz::simd_ops::{hamming_distance, pack_binary_fast};
//!
//! // Two 8-bit binary vectors (as 0/1 bytes).
//! let a_bits = [1u8, 0, 1, 0, 1, 0, 1, 0];
//! let b_bits = [1u8, 1, 1, 0, 0, 0, 1, 0];
//!
//! let mut a_packed = [0u8; 1];
//! let mut b_packed = [0u8; 1];
//! pack_binary_fast(&a_bits, &mut a_packed).unwrap();
//! pack_binary_fast(&b_bits, &mut b_packed).unwrap();
//!
//! let d = hamming_distance(&a_packed, &b_packed);
//! assert_eq!(d, 2);
//! ```

use thiserror::Error;

/// Convenience result type for this crate.
pub type Result<T> = std::result::Result<T, VQuantError>;

/// Errors for quantization code operations.
#[derive(Debug, Error)]
pub enum VQuantError {
    /// Dimension or element count mismatch.
    #[error("dimension mismatch: expected {expected}, got {got}")]
    DimensionMismatch { expected: usize, got: usize },

    /// A configuration parameter is outside its valid range.
    #[error("invalid config: {field} -- {reason}")]
    InvalidConfig {
        /// Which parameter.
        field: &'static str,
        /// Why it is invalid.
        reason: &'static str,
    },

    /// Catch-all for errors that don't have a dedicated variant yet.
    #[error("{0}")]
    Other(String),
}

#[cfg(feature = "rabitq")]
/// RaBitQ-style 1-bit quantization (feature-gated).
pub mod rabitq;

#[cfg(feature = "ternary")]
/// Ternary quantization utilities (feature-gated).
pub mod ternary;

#[cfg(feature = "distquant")]
/// Distributional quantization: optimal codebooks under distributional priors (feature-gated).
pub mod distquant;

#[cfg(feature = "adaptive")]
/// Per-vector adaptive scalar quantization (feature-gated).
pub mod adaptive;

#[cfg(feature = "binary")]
/// Rotation-based binary quantization (feature-gated).
pub mod binary;

/// Bit packing + popcount-based operations for low-bit codes.
pub mod simd_ops;