Skip to main content

qualia_audio/models/audio_tokens/
fsq.rs

1//! Finite Scalar Quantization (FSQ) — the codebook-free discrete token structure from
2//! "Finite Scalar Quantization: VQ-VAE Made Simple" (Mentzer et al., 2023). Each latent
3//! dimension is independently rounded to one of `L` evenly-spaced levels spanning a bounded
4//! range `[lo, hi]`; the implicit codebook is the Cartesian product of the per-dim level grids,
5//! so no codebook needs to be stored or learned. This is pure quantizer math — real and
6//! buildable now. The neural encoder that produces the (bounded) latents is a separate,
7//! `NeedsWeights` concern.
8//!
9//! Per-dimension level counts may differ (e.g. `[8, 5, 5, 5]`), matching the FSQ convention.
10//! On-grid values (`lo + k·step`) round-trip exactly; off-grid values snap to the nearest level.
11//! Zero-heap: caller supplies the level table and all buffers.
12
13use crate::types::AudioError;
14
15/// Quantize each component of `input` to its per-dimension level grid, writing level indices.
16///
17/// - `input`: at least `levels.len()` floats.
18/// - `levels`: per-dimension level counts `L_d` (each `≥ 1`); `dim = levels.len()`.
19/// - `lo`, `hi`: shared inclusive bounds for the grid (`hi > lo`).
20/// - `out_tokens`: at least `dim` slots; slot `d` receives the level index in `0..L_d`.
21///
22/// For dim `d` with `L` levels the step is `(hi - lo)/(L - 1)`; the index is
23/// `round((x - lo)/step)` clamped to `0..=L-1`. A degenerate `L == 1` collapses to index 0.
24/// Returns the number of tokens written (`dim`). Zero-heap.
25///
26/// # Errors
27/// - [`AudioError::InvalidParameter`] if `levels` is empty, any `L_d == 0`, or `hi <= lo`.
28/// - [`AudioError::OutputBufferTooSmall`] if `input` or `out_tokens` are shorter than `dim`.
29pub fn fsq_quantize(
30    input: &[f32],
31    levels: &[u16],
32    lo: f32,
33    hi: f32,
34    out_tokens: &mut [u16],
35) -> Result<usize, AudioError> {
36    let dim = levels.len();
37    if dim == 0 || hi <= lo || levels.contains(&0) {
38        return Err(AudioError::InvalidParameter);
39    }
40    if input.len() < dim || out_tokens.len() < dim {
41        return Err(AudioError::OutputBufferTooSmall);
42    }
43    for d in 0..dim {
44        let l = levels[d];
45        if l == 1 {
46            out_tokens[d] = 0;
47            continue;
48        }
49        let step = (hi - lo) / ((l - 1) as f32);
50        // Nearest level index, clamped to the valid range.
51        let raw = ((input[d] - lo) / step).round();
52        let idx = if raw < 0.0 {
53            0.0
54        } else if raw > (l - 1) as f32 {
55            (l - 1) as f32
56        } else {
57            raw
58        };
59        out_tokens[d] = idx as u16;
60    }
61    Ok(dim)
62}
63
64/// Reconstruct latent components from FSQ level indices: `out[d] = lo + tokens[d]·step_d`.
65///
66/// - `tokens`: at least `dim` level indices (each clamped into `0..L_d`).
67/// - `levels`, `lo`, `hi`: same as [`fsq_quantize`].
68/// - `out`: at least `dim` floats; fully overwritten.
69///
70/// # Errors
71/// - [`AudioError::InvalidParameter`] if `levels` is empty, any `L_d == 0`, or `hi <= lo`.
72/// - [`AudioError::OutputBufferTooSmall`] if `tokens` or `out` are shorter than `dim`.
73pub fn fsq_dequantize(
74    tokens: &[u16],
75    levels: &[u16],
76    lo: f32,
77    hi: f32,
78    out: &mut [f32],
79) -> Result<(), AudioError> {
80    let dim = levels.len();
81    if dim == 0 || hi <= lo || levels.contains(&0) {
82        return Err(AudioError::InvalidParameter);
83    }
84    if tokens.len() < dim || out.len() < dim {
85        return Err(AudioError::OutputBufferTooSmall);
86    }
87    for d in 0..dim {
88        let l = levels[d];
89        if l == 1 {
90            out[d] = lo;
91            continue;
92        }
93        let step = (hi - lo) / ((l - 1) as f32);
94        let idx = tokens[d].min(l - 1);
95        out[d] = lo + (idx as f32) * step;
96    }
97    Ok(())
98}
99
100#[cfg(test)]
101mod tests {
102    use super::*;
103
104    #[test]
105    fn on_grid_values_round_trip_exactly() {
106        // dim 3, levels [5,5,5] over [-1,1] -> step 0.5, grid {-1,-0.5,0,0.5,1}.
107        let levels = [5u16, 5, 5];
108        let input = [-1.0f32, 0.0, 0.5]; // all on-grid
109        let mut tokens = [0u16; 3];
110        fsq_quantize(&input, &levels, -1.0, 1.0, &mut tokens).expect("quant");
111        assert_eq!(tokens, [0, 2, 3]); // indices for -1, 0, 0.5
112
113        let mut recon = [0.0f32; 3];
114        fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut recon).expect("dequant");
115        assert_eq!(recon, input, "on-grid values must reconstruct bit-exactly");
116    }
117
118    #[test]
119    fn off_grid_snaps_to_nearest_level() {
120        // step 0.5; 0.24 -> nearest level 0 (0.0), 0.26 -> level 0.5.
121        let levels = [5u16];
122        let mut tokens = [0u16; 1];
123
124        fsq_quantize(&[0.24f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
125        assert_eq!(tokens[0], 2); // 0.0
126        let mut r = [0.0f32; 1];
127        fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut r).expect("d");
128        assert!((r[0] - 0.0).abs() < 1e-6, "0.24 -> {}", r[0]);
129
130        fsq_quantize(&[0.26f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
131        assert_eq!(tokens[0], 3); // 0.5
132        fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut r).expect("d");
133        assert!((r[0] - 0.5).abs() < 1e-6, "0.26 -> {}", r[0]);
134    }
135
136    #[test]
137    fn out_of_range_input_clamps_to_end_levels() {
138        let levels = [4u16];
139        let mut tokens = [0u16; 1];
140        fsq_quantize(&[10.0f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
141        assert_eq!(tokens[0], 3); // top level
142        fsq_quantize(&[-10.0f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
143        assert_eq!(tokens[0], 0); // bottom level
144    }
145
146    #[test]
147    fn per_dim_level_counts() {
148        // Mixed levels [8,2]; check both dims quantize independently on their own grid.
149        let levels = [8u16, 2];
150        let input = [1.0f32, -1.0]; // top of dim0 grid, bottom of dim1 grid
151        let mut tokens = [0u16; 2];
152        fsq_quantize(&input, &levels, -1.0, 1.0, &mut tokens).expect("q");
153        assert_eq!(tokens, [7, 0]);
154        let mut recon = [0.0f32; 2];
155        fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut recon).expect("d");
156        assert_eq!(recon, input);
157    }
158
159    #[test]
160    fn single_level_dim_collapses_to_lo() {
161        let levels = [1u16];
162        let mut tokens = [99u16; 1];
163        fsq_quantize(&[0.7f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
164        assert_eq!(tokens[0], 0);
165        let mut r = [0.0f32; 1];
166        fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut r).expect("d");
167        assert_eq!(r[0], -1.0);
168    }
169
170    #[test]
171    fn rejects_bad_params() {
172        let levels = [5u16];
173        let mut tokens = [0u16; 1];
174        assert_eq!(
175            fsq_quantize(&[0.0], &[], 0.0, 1.0, &mut tokens),
176            Err(AudioError::InvalidParameter)
177        );
178        assert_eq!(
179            fsq_quantize(&[0.0], &levels, 1.0, 1.0, &mut tokens),
180            Err(AudioError::InvalidParameter)
181        );
182        assert_eq!(
183            fsq_quantize(&[0.0], &[0u16], -1.0, 1.0, &mut tokens),
184            Err(AudioError::InvalidParameter)
185        );
186        let mut empty: [u16; 0] = [];
187        assert_eq!(
188            fsq_quantize(&[0.0], &levels, -1.0, 1.0, &mut empty),
189            Err(AudioError::OutputBufferTooSmall)
190        );
191    }
192}