rvf-quant 0.2.0

RuVector Format temperature-tiered vector quantization (f32/f16/u8/binary)
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
84
85
86
87
88
89
90
91
92
93
94
95

//! Temperature tier assignment for vector blocks.

/// Access count above which a block is considered "hot" (Tier 0).
pub const HOT_THRESHOLD: u8 = 128;

/// Access count above which a block is considered "warm" (Tier 1).
/// Below this threshold, a block is "cold" (Tier 2).
pub const WARM_THRESHOLD: u8 = 16;

/// Temperature tier for a vector block.
///
/// Determines the quantization level and storage layout.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(u8)]
pub enum TemperatureTier {
    /// Frequently accessed. Scalar quantized (int8), interleaved layout.
    Hot = 0,
    /// Moderately accessed. Product quantized, columnar layout.
    Warm = 1,
    /// Rarely accessed. Binary quantized, columnar + heavy compression.
    Cold = 2,
}

/// Assign a temperature tier based on the estimated access count.
///
/// Uses the thresholds from the RVF spec:
/// - `count > HOT_THRESHOLD`  -> Hot
/// - `count > WARM_THRESHOLD` -> Warm
/// - otherwise                -> Cold
pub fn assign_tier(access_count: u8) -> TemperatureTier {
    if access_count > HOT_THRESHOLD {
        TemperatureTier::Hot
    } else if access_count > WARM_THRESHOLD {
        TemperatureTier::Warm
    } else {
        TemperatureTier::Cold
    }
}

impl TemperatureTier {
    /// Returns the wire representation (0, 1, or 2).
    #[inline]
    pub const fn as_u8(self) -> u8 {
        self as u8
    }
}

impl TryFrom<u8> for TemperatureTier {
    type Error = u8;

    fn try_from(value: u8) -> Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::Hot),
            1 => Ok(Self::Warm),
            2 => Ok(Self::Cold),
            other => Err(other),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn tier_assignment() {
        assert_eq!(assign_tier(255), TemperatureTier::Hot);
        assert_eq!(assign_tier(129), TemperatureTier::Hot);
        assert_eq!(assign_tier(128), TemperatureTier::Warm); // not >128
        assert_eq!(assign_tier(64), TemperatureTier::Warm);
        assert_eq!(assign_tier(17), TemperatureTier::Warm);
        assert_eq!(assign_tier(16), TemperatureTier::Cold); // not >16
        assert_eq!(assign_tier(1), TemperatureTier::Cold);
        assert_eq!(assign_tier(0), TemperatureTier::Cold);
    }

    #[test]
    fn round_trip() {
        for raw in 0..=2u8 {
            let t = TemperatureTier::try_from(raw).unwrap();
            assert_eq!(t.as_u8(), raw);
        }
    }

    #[test]
    fn invalid_tier() {
        assert_eq!(TemperatureTier::try_from(3), Err(3));
    }

    #[test]
    fn ordering() {
        assert!(TemperatureTier::Hot < TemperatureTier::Warm);
        assert!(TemperatureTier::Warm < TemperatureTier::Cold);
    }
}