Skip to main content

trustformers_models/
advanced_quantization.rs

1/// Advanced Quantization Methods for TrustformeRS Models
2///
3/// This module implements cutting-edge quantization techniques:
4/// - NF4 (Normalized Float 4): 4-bit normalized float quantization with information-theoretic optimal scaling
5/// - FP4 (4-bit Float): Native 4-bit floating point representation
6/// - Block-wise quantization with optimal outlier handling
7/// - Advanced dequantization with hardware-accelerated operations
8///
9/// Based on:
10/// - "QLoRA: Efficient Finetuning of Quantized LLMs" (Dettmers et al., 2023)
11/// - "QLORA: Quantized Low-Rank Adaptation of Large Language Models"
12/// - "The case for 4-bit precision: k-bit Inference Scaling Laws" (Dettmers et al., 2023)
13use std::collections::HashMap;
14use trustformers_core::{
15    errors::{Result, TrustformersError},
16    tensor::Tensor,
17};
18
19/// Advanced quantization configuration
20#[derive(Debug, Clone)]
21pub struct AdvancedQuantizationConfig {
22    /// Quantization method
23    pub method: QuantizationMethod,
24    /// Block size for block-wise quantization (default: 64)
25    pub block_size: usize,
26    /// Whether to use double quantization (quantize scaling factors)
27    pub double_quantization: bool,
28    /// Compute data type for quantization operations
29    pub compute_dtype: ComputeDataType,
30    /// Outlier threshold for mixed precision (default: 6.0)
31    pub outlier_threshold: f32,
32    /// Whether to use nested quantization for very large models
33    pub nested_quantization: bool,
34}
35
36impl Default for AdvancedQuantizationConfig {
37    fn default() -> Self {
38        Self {
39            method: QuantizationMethod::NF4,
40            block_size: 64,
41            double_quantization: true,
42            compute_dtype: ComputeDataType::BFloat16,
43            outlier_threshold: 6.0,
44            nested_quantization: false,
45        }
46    }
47}
48
49/// Advanced quantization methods
50#[derive(Debug, Clone, PartialEq)]
51pub enum QuantizationMethod {
52    /// Normalized Float 4-bit with information-theoretic optimal quantiles
53    NF4,
54    /// Standard 4-bit floating point
55    FP4,
56    /// 4-bit integer with asymmetric scaling
57    Int4Asymmetric,
58    /// 8-bit integer with block-wise scaling
59    Int8BlockWise,
60    /// Mixed precision with dynamic bit allocation
61    MixedPrecision { primary_bits: u8, outlier_bits: u8 },
62}
63
64/// Compute data types for quantization operations
65#[derive(Debug, Clone, PartialEq)]
66pub enum ComputeDataType {
67    Float32,
68    Float16,
69    BFloat16,
70}
71
72/// NF4 quantization table - information-theoretically optimal quantiles for normal distribution
73const NF4_QUANT_TABLE: [f32; 16] = [
74    -1.0,
75    -0.696_192_8,
76    -0.525_073_05,
77    -0.394_917_5,
78    -0.284_441_38,
79    -0.184_773_43,
80    -0.091_050_036,
81    0.0,
82    0.079_580_3,
83    0.160_930_2,
84    0.246_112_3,
85    0.337_915_24,
86    0.440_709_83,
87    0.562_617,
88    0.722_956_84,
89    1.0,
90];
91
92/// FP4 E2M1 format specification (1 sign bit, 2 exponent bits, 1 mantissa bit)
93pub struct FP4Format {
94    pub sign_bits: u8,
95    pub exponent_bits: u8,
96    pub mantissa_bits: u8,
97}
98
99impl Default for FP4Format {
100    fn default() -> Self {
101        Self {
102            sign_bits: 1,
103            exponent_bits: 2,
104            mantissa_bits: 1,
105        }
106    }
107}
108
109/// Quantized tensor representation
110#[derive(Debug, Clone)]
111pub struct QuantizedTensor {
112    /// Quantized data
113    pub data: Vec<u8>,
114    /// Scaling factors (per block or global)
115    pub scales: Vec<f32>,
116    /// Zero points (for asymmetric quantization)
117    pub zero_points: Option<Vec<f32>>,
118    /// Original tensor shape
119    pub shape: Vec<usize>,
120    /// Quantization metadata
121    pub metadata: QuantizationMetadata,
122}
123
124/// Quantization metadata
125#[derive(Debug, Clone)]
126pub struct QuantizationMetadata {
127    pub method: QuantizationMethod,
128    pub block_size: usize,
129    pub outlier_indices: Option<Vec<usize>>,
130    pub outlier_values: Option<Vec<f32>>,
131    pub double_quantized: bool,
132    pub compute_dtype: ComputeDataType,
133}
134
135/// Advanced quantization engine
136pub struct AdvancedQuantizer {
137    config: AdvancedQuantizationConfig,
138    #[allow(dead_code)]
139    nf4_lookup: HashMap<u8, f32>,
140    #[allow(dead_code)]
141    inv_nf4_lookup: HashMap<u32, u8>, // Using u32 for f32 bits
142}
143
144impl AdvancedQuantizer {
145    /// Create a new advanced quantizer
146    pub fn new(config: AdvancedQuantizationConfig) -> Self {
147        let mut nf4_lookup = HashMap::new();
148        let mut inv_nf4_lookup = HashMap::new();
149
150        // Build NF4 lookup tables for fast quantization/dequantization
151        for (i, &value) in NF4_QUANT_TABLE.iter().enumerate() {
152            nf4_lookup.insert(i as u8, value);
153            inv_nf4_lookup.insert(value.to_bits(), i as u8);
154        }
155
156        Self {
157            config,
158            nf4_lookup,
159            inv_nf4_lookup,
160        }
161    }
162
163    /// Quantize tensor using the configured advanced method
164    pub fn quantize(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
165        match &self.config.method {
166            QuantizationMethod::NF4 => self.quantize_nf4(tensor),
167            QuantizationMethod::FP4 => self.quantize_fp4(tensor),
168            QuantizationMethod::Int4Asymmetric => self.quantize_int4_asymmetric(tensor),
169            QuantizationMethod::Int8BlockWise => self.quantize_int8_blockwise(tensor),
170            QuantizationMethod::MixedPrecision {
171                primary_bits,
172                outlier_bits,
173            } => self.quantize_mixed_precision(tensor, *primary_bits, *outlier_bits),
174        }
175    }
176
177    /// Dequantize tensor back to full precision
178    pub fn dequantize(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
179        match &quantized.metadata.method {
180            QuantizationMethod::NF4 => self.dequantize_nf4(quantized),
181            QuantizationMethod::FP4 => self.dequantize_fp4(quantized),
182            QuantizationMethod::Int4Asymmetric => self.dequantize_int4_asymmetric(quantized),
183            QuantizationMethod::Int8BlockWise => self.dequantize_int8_blockwise(quantized),
184            QuantizationMethod::MixedPrecision { .. } => self.dequantize_mixed_precision(quantized),
185        }
186    }
187
188    /// NF4 quantization implementation
189    fn quantize_nf4(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
190        let tensor_data = tensor.data_f32()?;
191        let total_elements = tensor_data.len();
192        let num_blocks = total_elements.div_ceil(self.config.block_size);
193
194        let mut quantized_data = Vec::with_capacity(total_elements.div_ceil(2)); // 4 bits per element
195        let mut scales = Vec::with_capacity(num_blocks);
196        let mut outlier_indices = Vec::new();
197        let mut outlier_values = Vec::new();
198
199        for block_idx in 0..num_blocks {
200            let start_idx = block_idx * self.config.block_size;
201            let end_idx = (start_idx + self.config.block_size).min(total_elements);
202            let block_data = &tensor_data[start_idx..end_idx];
203
204            // Calculate block-wise statistics
205            let abs_max = block_data.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
206
207            // Handle outliers if enabled
208            let mut processed_block = Vec::with_capacity(block_data.len());
209            for (local_idx, &value) in block_data.iter().enumerate() {
210                if value.abs() > self.config.outlier_threshold * abs_max {
211                    outlier_indices.push(start_idx + local_idx);
212                    outlier_values.push(value);
213                    processed_block.push(0.0); // Replace outlier with 0 for quantization
214                } else {
215                    processed_block.push(value);
216                }
217            }
218
219            // Calculate optimal scale for this block
220            let scale = abs_max;
221            scales.push(scale);
222
223            // Quantize block using NF4
224            for chunk in processed_block.chunks(2) {
225                let val1 = self.quantize_nf4_value(chunk[0] / scale);
226                let val2 =
227                    if chunk.len() > 1 { self.quantize_nf4_value(chunk[1] / scale) } else { 0 };
228
229                // Pack two 4-bit values into one byte
230                let packed = (val1 & 0xF) | ((val2 & 0xF) << 4);
231                quantized_data.push(packed);
232            }
233        }
234
235        // Double quantization of scales if enabled
236        let final_scales = if self.config.double_quantization {
237            self.double_quantize_scales(&scales)?
238        } else {
239            scales
240        };
241
242        let outliers = if outlier_indices.is_empty() {
243            (None, None)
244        } else {
245            (Some(outlier_indices), Some(outlier_values))
246        };
247
248        Ok(QuantizedTensor {
249            data: quantized_data,
250            scales: final_scales,
251            zero_points: None,
252            shape: tensor.shape().to_vec(),
253            metadata: QuantizationMetadata {
254                method: QuantizationMethod::NF4,
255                block_size: self.config.block_size,
256                outlier_indices: outliers.0,
257                outlier_values: outliers.1,
258                double_quantized: self.config.double_quantization,
259                compute_dtype: self.config.compute_dtype.clone(),
260            },
261        })
262    }
263
264    /// Quantize single value to NF4
265    fn quantize_nf4_value(&self, value: f32) -> u8 {
266        let clamped = value.clamp(-1.0, 1.0);
267
268        // Find the closest quantization level
269        let mut best_idx = 0;
270        let mut best_error = (clamped - NF4_QUANT_TABLE[0]).abs();
271
272        for (idx, &quant_val) in NF4_QUANT_TABLE.iter().enumerate().skip(1) {
273            let error = (clamped - quant_val).abs();
274            if error < best_error {
275                best_error = error;
276                best_idx = idx;
277            }
278        }
279
280        best_idx as u8
281    }
282
283    /// FP4 quantization implementation
284    fn quantize_fp4(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
285        let tensor_data = tensor.data_f32()?;
286        let total_elements = tensor_data.len();
287        let num_blocks = total_elements.div_ceil(self.config.block_size);
288
289        let mut quantized_data = Vec::with_capacity(total_elements.div_ceil(2));
290        let mut scales = Vec::with_capacity(num_blocks);
291
292        for block_idx in 0..num_blocks {
293            let start_idx = block_idx * self.config.block_size;
294            let end_idx = (start_idx + self.config.block_size).min(total_elements);
295            let block_data = &tensor_data[start_idx..end_idx];
296
297            // Calculate block-wise scale
298            let abs_max = block_data.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
299
300            let scale = abs_max / 7.0; // FP4 E2M1 max representable value is ~7.0
301            scales.push(scale);
302
303            // Quantize block using FP4 E2M1 format
304            for chunk in block_data.chunks(2) {
305                let val1 = self.quantize_fp4_value(chunk[0] / scale);
306                let val2 =
307                    if chunk.len() > 1 { self.quantize_fp4_value(chunk[1] / scale) } else { 0 };
308
309                // Pack two 4-bit values into one byte
310                let packed = (val1 & 0xF) | ((val2 & 0xF) << 4);
311                quantized_data.push(packed);
312            }
313        }
314
315        Ok(QuantizedTensor {
316            data: quantized_data,
317            scales,
318            zero_points: None,
319            shape: tensor.shape().to_vec(),
320            metadata: QuantizationMetadata {
321                method: QuantizationMethod::FP4,
322                block_size: self.config.block_size,
323                outlier_indices: None,
324                outlier_values: None,
325                double_quantized: false,
326                compute_dtype: self.config.compute_dtype.clone(),
327            },
328        })
329    }
330
331    /// Quantize single value to FP4 E2M1 format
332    fn quantize_fp4_value(&self, value: f32) -> u8 {
333        if value == 0.0 {
334            return 0;
335        }
336
337        let sign = if value < 0.0 { 1u8 } else { 0u8 };
338        let abs_val = value.abs();
339
340        // E2M1 format: 1 sign + 2 exponent + 1 mantissa bits
341        // Representable values: 0, ±0.5, ±1.0, ±1.5, ±2.0, ±3.0, ±4.0, ±6.0
342        let quantized = if abs_val <= 0.25 {
343            0 // Underflow to 0
344        } else if abs_val <= 0.75 {
345            1 // Map to 0.5
346        } else if abs_val <= 1.25 {
347            2 // Map to 1.0
348        } else if abs_val <= 1.75 {
349            3 // Map to 1.5
350        } else if abs_val <= 2.5 {
351            4 // Map to 2.0
352        } else if abs_val <= 3.5 {
353            5 // Map to 3.0
354        } else if abs_val <= 5.0 {
355            6 // Map to 4.0
356        } else {
357            7 // Map to 6.0
358        };
359
360        (sign << 3) | (quantized & 0x7)
361    }
362
363    /// Int4 asymmetric quantization
364    fn quantize_int4_asymmetric(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
365        let tensor_data = tensor.data_f32()?;
366        let total_elements = tensor_data.len();
367        let num_blocks = total_elements.div_ceil(self.config.block_size);
368
369        let mut quantized_data = Vec::with_capacity(total_elements.div_ceil(2));
370        let mut scales = Vec::with_capacity(num_blocks);
371        let mut zero_points = Vec::with_capacity(num_blocks);
372
373        for block_idx in 0..num_blocks {
374            let start_idx = block_idx * self.config.block_size;
375            let end_idx = (start_idx + self.config.block_size).min(total_elements);
376            let block_data = &tensor_data[start_idx..end_idx];
377
378            // Calculate min/max for asymmetric quantization
379            let min_val = block_data.iter().fold(f32::INFINITY, |a, &b| a.min(b));
380            let max_val = block_data.iter().fold(f32::NEG_INFINITY, |a, &b| a.max(b));
381
382            let scale = (max_val - min_val) / 15.0; // 4-bit range: 0-15
383            let zero_point = -min_val / scale;
384
385            scales.push(scale);
386            zero_points.push(zero_point);
387
388            // Quantize block
389            for chunk in block_data.chunks(2) {
390                let val1 = ((chunk[0] / scale + zero_point).round() as i32).clamp(0, 15) as u8;
391                let val2 = if chunk.len() > 1 {
392                    ((chunk[1] / scale + zero_point).round() as i32).clamp(0, 15) as u8
393                } else {
394                    0
395                };
396
397                let packed = (val1 & 0xF) | ((val2 & 0xF) << 4);
398                quantized_data.push(packed);
399            }
400        }
401
402        Ok(QuantizedTensor {
403            data: quantized_data,
404            scales,
405            zero_points: Some(zero_points),
406            shape: tensor.shape().to_vec(),
407            metadata: QuantizationMetadata {
408                method: QuantizationMethod::Int4Asymmetric,
409                block_size: self.config.block_size,
410                outlier_indices: None,
411                outlier_values: None,
412                double_quantized: false,
413                compute_dtype: self.config.compute_dtype.clone(),
414            },
415        })
416    }
417
418    /// Int8 block-wise quantization
419    fn quantize_int8_blockwise(&self, tensor: &Tensor) -> Result<QuantizedTensor> {
420        let tensor_data = tensor.data_f32()?;
421        let total_elements = tensor_data.len();
422        let num_blocks = total_elements.div_ceil(self.config.block_size);
423
424        let mut quantized_data = Vec::with_capacity(total_elements);
425        let mut scales = Vec::with_capacity(num_blocks);
426
427        for block_idx in 0..num_blocks {
428            let start_idx = block_idx * self.config.block_size;
429            let end_idx = (start_idx + self.config.block_size).min(total_elements);
430            let block_data = &tensor_data[start_idx..end_idx];
431
432            let abs_max = block_data.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
433
434            let scale = abs_max / 127.0;
435            scales.push(scale);
436
437            for &value in block_data {
438                let quantized = ((value / scale).round() as i32).clamp(-127, 127) as i8;
439                quantized_data.push(quantized as u8);
440            }
441        }
442
443        Ok(QuantizedTensor {
444            data: quantized_data,
445            scales,
446            zero_points: None,
447            shape: tensor.shape().to_vec(),
448            metadata: QuantizationMetadata {
449                method: QuantizationMethod::Int8BlockWise,
450                block_size: self.config.block_size,
451                outlier_indices: None,
452                outlier_values: None,
453                double_quantized: false,
454                compute_dtype: self.config.compute_dtype.clone(),
455            },
456        })
457    }
458
459    /// LLM.int8()-style mixed-precision quantization.
460    ///
461    /// Dettmers et al. (2022) observed that a small fraction of a transformer's
462    /// weights carry outsized magnitudes, and that quantizing *those* coarsely
463    /// is what destroys accuracy. The remedy is to split the tensor: the bulk
464    /// goes to `primary_bits`, the outliers are kept at the wider
465    /// `outlier_bits`, and the two are recombined on dequantization.
466    ///
467    /// This implementation does exactly that:
468    ///
469    /// * an element is an outlier when its magnitude reaches
470    ///   `config.outlier_threshold` — the **absolute** criterion of the paper
471    ///   (its default of `6.0` is a magnitude, not a ratio). Note that the older
472    ///   NF4 path compares against `outlier_threshold × block_abs_max`, under
473    ///   which a threshold of 6 can never fire because no element exceeds six
474    ///   times the block maximum;
475    /// * outlier positions go to `metadata.outlier_indices` and their values,
476    ///   quantized to `outlier_bits` about the block scale, to
477    ///   `metadata.outlier_values`;
478    /// * the remaining elements are quantized to `primary_bits` per block, with
479    ///   the outlier positions excluded from the block's scale so a single spike
480    ///   cannot crush the resolution of its neighbours.
481    ///
482    /// Elements are packed one per byte for `primary_bits <= 8`; the bit width is
483    /// what limits the number of levels, not the storage.
484    ///
485    /// # What this replaces
486    ///
487    /// The previous body took `_primary_bits` and `_outlier_bits`, commented
488    /// "For now, delegate to NF4", and called
489    /// [`AdvancedQuantizer::quantize_nf4`]. A caller asking for 8-bit outliers
490    /// over a 4-bit base silently received uniform NF4 — no error, no warning —
491    /// and the returned [`QuantizationStats`] described the NF4 result while
492    /// `metadata.method` claimed `MixedPrecision`.
493    ///
494    /// # Errors
495    ///
496    /// Fails when either bit width is 0 or greater than 8, when
497    /// `outlier_bits < primary_bits` (which would make the "high precision" path
498    /// the coarser one), or when the tensor cannot be read as `f32`.
499    fn quantize_mixed_precision(
500        &self,
501        tensor: &Tensor,
502        primary_bits: u8,
503        outlier_bits: u8,
504    ) -> Result<QuantizedTensor> {
505        if primary_bits == 0 || primary_bits > 8 {
506            return Err(TrustformersError::invalid_input_simple(format!(
507                "MixedPrecision primary_bits must be in 1..=8, got {primary_bits}"
508            )));
509        }
510        if outlier_bits == 0 || outlier_bits > 8 {
511            return Err(TrustformersError::invalid_input_simple(format!(
512                "MixedPrecision outlier_bits must be in 1..=8, got {outlier_bits}"
513            )));
514        }
515        if outlier_bits < primary_bits {
516            return Err(TrustformersError::invalid_input_simple(format!(
517                "MixedPrecision outlier_bits ({outlier_bits}) must be at least primary_bits \
518                 ({primary_bits}): outliers are the values that need *more* precision, not less"
519            )));
520        }
521
522        let tensor_data = tensor.data_f32()?;
523        let total_elements = tensor_data.len();
524        if total_elements == 0 {
525            return Err(TrustformersError::invalid_input_simple(
526                "cannot quantize an empty tensor".to_string(),
527            ));
528        }
529        let block_size = self.config.block_size.max(1);
530        let num_blocks = total_elements.div_ceil(block_size);
531
532        // Symmetric signed quantization: `primary_bits` gives levels
533        // [-(2^(b-1) - 1), 2^(b-1) - 1], stored offset into a u8.
534        let primary_levels = ((1u32 << (primary_bits - 1)) - 1).max(1) as f32;
535        let outlier_levels = ((1u32 << (outlier_bits - 1)) - 1).max(1) as f32;
536
537        let mut quantized_data = Vec::with_capacity(total_elements);
538        let mut scales = Vec::with_capacity(num_blocks);
539        let mut outlier_indices = Vec::new();
540        let mut outlier_values = Vec::new();
541
542        for block_idx in 0..num_blocks {
543            let start_idx = block_idx * block_size;
544            let end_idx = (start_idx + block_size).min(total_elements);
545            let block_data = &tensor_data[start_idx..end_idx];
546
547            let abs_max = block_data.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
548
549            // First pass: classify by absolute magnitude, as LLM.int8() does.
550            // The primary scale deliberately ignores the outliers — that is the
551            // whole point of separating them, since one spike would otherwise
552            // consume the entire dynamic range of the block.
553            let mut primary_abs_max = 0.0f32;
554            let mut is_outlier = Vec::with_capacity(block_data.len());
555            for &value in block_data {
556                let outlier = value.abs() >= self.config.outlier_threshold;
557                if !outlier {
558                    primary_abs_max = primary_abs_max.max(value.abs());
559                }
560                is_outlier.push(outlier);
561            }
562
563            let primary_scale =
564                if primary_abs_max > 0.0 { primary_abs_max / primary_levels } else { 1.0 };
565            let outlier_scale = if abs_max > 0.0 { abs_max / outlier_levels } else { 1.0 };
566            scales.push(primary_scale);
567
568            // Second pass: quantize.
569            for (local_idx, (&value, &outlier)) in
570                block_data.iter().zip(is_outlier.iter()).enumerate()
571            {
572                if outlier {
573                    // Keep the outlier at `outlier_bits`, round-tripped through
574                    // its own scale so the stored value is the *quantized* one,
575                    // not the original: reporting an exact value for something
576                    // that was quantized would overstate the fidelity.
577                    let level =
578                        (value / outlier_scale).round().clamp(-outlier_levels, outlier_levels);
579                    outlier_indices.push(start_idx + local_idx);
580                    outlier_values.push(level * outlier_scale);
581                    // The primary stream carries 0 at an outlier position; the
582                    // real value is restored from the outlier list.
583                    quantized_data.push(128u8);
584                } else {
585                    let level =
586                        (value / primary_scale).round().clamp(-primary_levels, primary_levels);
587                    quantized_data.push((level as i32 + 128) as u8);
588                }
589            }
590        }
591
592        let final_scales = if self.config.double_quantization {
593            self.double_quantize_scales(&scales)?
594        } else {
595            scales
596        };
597
598        let outliers = if outlier_indices.is_empty() {
599            (None, None)
600        } else {
601            (Some(outlier_indices), Some(outlier_values))
602        };
603
604        Ok(QuantizedTensor {
605            data: quantized_data,
606            scales: final_scales,
607            zero_points: None,
608            shape: tensor.shape().to_vec(),
609            metadata: QuantizationMetadata {
610                method: QuantizationMethod::MixedPrecision {
611                    primary_bits,
612                    outlier_bits,
613                },
614                block_size,
615                outlier_indices: outliers.0,
616                outlier_values: outliers.1,
617                double_quantized: self.config.double_quantization,
618                compute_dtype: self.config.compute_dtype.clone(),
619            },
620        })
621    }
622
623    /// Dequantize NF4 tensor
624    fn dequantize_nf4(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
625        let total_elements: usize = quantized.shape.iter().product();
626        let mut dequantized_data = vec![0.0f32; total_elements];
627        let num_blocks = quantized.scales.len();
628
629        let mut data_idx = 0;
630        let mut elem_idx = 0;
631
632        for block_idx in 0..num_blocks {
633            let scale = quantized.scales[block_idx];
634            let block_size = if block_idx == num_blocks - 1 {
635                // Last block might be partial
636                total_elements - block_idx * quantized.metadata.block_size
637            } else {
638                quantized.metadata.block_size
639            };
640
641            let mut block_elem_count = 0;
642
643            while block_elem_count < block_size && data_idx < quantized.data.len() {
644                let packed = quantized.data[data_idx];
645                data_idx += 1;
646
647                // Unpack two 4-bit values
648                let val1_idx = (packed & 0xF) as usize;
649                let val2_idx = ((packed >> 4) & 0xF) as usize;
650
651                if elem_idx < total_elements {
652                    dequantized_data[elem_idx] = NF4_QUANT_TABLE[val1_idx] * scale;
653                    elem_idx += 1;
654                    block_elem_count += 1;
655                }
656
657                if block_elem_count < block_size && elem_idx < total_elements {
658                    dequantized_data[elem_idx] = NF4_QUANT_TABLE[val2_idx] * scale;
659                    elem_idx += 1;
660                    block_elem_count += 1;
661                }
662            }
663        }
664
665        // Restore outliers if present
666        if let (Some(outlier_indices), Some(outlier_values)) = (
667            &quantized.metadata.outlier_indices,
668            &quantized.metadata.outlier_values,
669        ) {
670            for (&idx, &value) in outlier_indices.iter().zip(outlier_values.iter()) {
671                if idx < dequantized_data.len() {
672                    dequantized_data[idx] = value;
673                }
674            }
675        }
676
677        Tensor::from_vec(dequantized_data, &quantized.shape)
678    }
679
680    /// Dequantize FP4 tensor
681    fn dequantize_fp4(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
682        let total_elements: usize = quantized.shape.iter().product();
683        let mut dequantized_data = vec![0.0f32; total_elements];
684        let num_blocks = quantized.scales.len();
685
686        let mut data_idx = 0;
687        let mut elem_idx = 0;
688
689        for block_idx in 0..num_blocks {
690            let scale = quantized.scales[block_idx];
691            let block_size = if block_idx == num_blocks - 1 {
692                total_elements - block_idx * quantized.metadata.block_size
693            } else {
694                quantized.metadata.block_size
695            };
696
697            let mut block_elem_count = 0;
698
699            while block_elem_count < block_size && data_idx < quantized.data.len() {
700                let packed = quantized.data[data_idx];
701                data_idx += 1;
702
703                let val1_bits = packed & 0xF;
704                let val2_bits = (packed >> 4) & 0xF;
705
706                if elem_idx < total_elements {
707                    dequantized_data[elem_idx] = self.dequantize_fp4_value(val1_bits) * scale;
708                    elem_idx += 1;
709                    block_elem_count += 1;
710                }
711
712                if block_elem_count < block_size && elem_idx < total_elements {
713                    dequantized_data[elem_idx] = self.dequantize_fp4_value(val2_bits) * scale;
714                    elem_idx += 1;
715                    block_elem_count += 1;
716                }
717            }
718        }
719
720        Tensor::from_vec(dequantized_data, &quantized.shape)
721    }
722
723    /// Dequantize single FP4 value
724    fn dequantize_fp4_value(&self, bits: u8) -> f32 {
725        if bits == 0 {
726            return 0.0;
727        }
728
729        let sign = if (bits >> 3) & 1 == 1 { -1.0 } else { 1.0 };
730        let magnitude_bits = bits & 0x7;
731
732        let magnitude = match magnitude_bits {
733            1 => 0.5,
734            2 => 1.0,
735            3 => 1.5,
736            4 => 2.0,
737            5 => 3.0,
738            6 => 4.0,
739            7 => 6.0,
740            _ => 0.0,
741        };
742
743        sign * magnitude
744    }
745
746    /// Dequantize Int4 asymmetric tensor
747    fn dequantize_int4_asymmetric(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
748        let total_elements: usize = quantized.shape.iter().product();
749        let mut dequantized_data = vec![0.0f32; total_elements];
750        let num_blocks = quantized.scales.len();
751        let zero_points = quantized.zero_points.as_ref().ok_or_else(|| {
752            TrustformersError::config_error(
753                "Zero points required for asymmetric quantization",
754                "dequantize_int4",
755            )
756        })?;
757
758        let mut data_idx = 0;
759        let mut elem_idx = 0;
760
761        for block_idx in 0..num_blocks {
762            let scale = quantized.scales[block_idx];
763            let zero_point = zero_points[block_idx];
764            let block_size = if block_idx == num_blocks - 1 {
765                total_elements - block_idx * quantized.metadata.block_size
766            } else {
767                quantized.metadata.block_size
768            };
769
770            let mut block_elem_count = 0;
771
772            while block_elem_count < block_size && data_idx < quantized.data.len() {
773                let packed = quantized.data[data_idx];
774                data_idx += 1;
775
776                let val1 = (packed & 0xF) as f32;
777                let val2 = ((packed >> 4) & 0xF) as f32;
778
779                if elem_idx < total_elements {
780                    dequantized_data[elem_idx] = (val1 - zero_point) * scale;
781                    elem_idx += 1;
782                    block_elem_count += 1;
783                }
784
785                if block_elem_count < block_size && elem_idx < total_elements {
786                    dequantized_data[elem_idx] = (val2 - zero_point) * scale;
787                    elem_idx += 1;
788                    block_elem_count += 1;
789                }
790            }
791        }
792
793        Tensor::from_vec(dequantized_data, &quantized.shape)
794    }
795
796    /// Dequantize Int8 block-wise tensor
797    fn dequantize_int8_blockwise(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
798        let total_elements: usize = quantized.shape.iter().product();
799        let mut dequantized_data = vec![0.0f32; total_elements];
800        let num_blocks = quantized.scales.len();
801
802        let mut data_idx = 0;
803        let mut elem_idx = 0;
804
805        for block_idx in 0..num_blocks {
806            let scale = quantized.scales[block_idx];
807            let block_size = if block_idx == num_blocks - 1 {
808                total_elements - block_idx * quantized.metadata.block_size
809            } else {
810                quantized.metadata.block_size
811            };
812
813            for _ in 0..block_size {
814                if data_idx < quantized.data.len() && elem_idx < total_elements {
815                    let quantized_val = quantized.data[data_idx] as i8;
816                    dequantized_data[elem_idx] = quantized_val as f32 * scale;
817                    data_idx += 1;
818                    elem_idx += 1;
819                }
820            }
821        }
822
823        Tensor::from_vec(dequantized_data, &quantized.shape)
824    }
825
826    /// Reconstruct a mixed-precision tensor from its two streams.
827    ///
828    /// The primary stream is scaled per block; the outlier positions are then
829    /// overwritten with their higher-precision values. A previous revision
830    /// delegated to [`AdvancedQuantizer::dequantize_nf4`], which reads the data
831    /// as *packed 4-bit pairs* — so it would have decoded a mixed-precision
832    /// payload as twice as many elements of the wrong magnitudes even if the
833    /// quantizer had produced one.
834    ///
835    /// # Errors
836    ///
837    /// Fails when the metadata does not describe a mixed-precision tensor, when
838    /// the payload length does not match the declared shape, or when the outlier
839    /// bookkeeping is inconsistent.
840    fn dequantize_mixed_precision(&self, quantized: &QuantizedTensor) -> Result<Tensor> {
841        let QuantizationMethod::MixedPrecision { .. } = quantized.metadata.method else {
842            return Err(TrustformersError::invalid_input_simple(format!(
843                "dequantize_mixed_precision called on a {:?} tensor",
844                quantized.metadata.method
845            )));
846        };
847
848        let total_elements: usize = quantized.shape.iter().product();
849        if quantized.data.len() != total_elements {
850            return Err(TrustformersError::shape_error(format!(
851                "mixed-precision payload holds {} element(s) but the shape {:?} needs \
852                 {total_elements}",
853                quantized.data.len(),
854                quantized.shape
855            )));
856        }
857        let block_size = quantized.metadata.block_size.max(1);
858        let expected_blocks = total_elements.div_ceil(block_size);
859        if quantized.scales.len() != expected_blocks {
860            return Err(TrustformersError::shape_error(format!(
861                "mixed-precision tensor carries {} scale(s) but {expected_blocks} block(s) of \
862                 size {block_size} were quantized",
863                quantized.scales.len()
864            )));
865        }
866
867        let mut dequantized = vec![0.0f32; total_elements];
868        for (index, &byte) in quantized.data.iter().enumerate() {
869            let block = index / block_size;
870            let scale = quantized.scales[block];
871            let level = byte as i32 - 128;
872            dequantized[index] = level as f32 * scale;
873        }
874
875        // Restore the high-precision outliers over the primary stream.
876        match (
877            &quantized.metadata.outlier_indices,
878            &quantized.metadata.outlier_values,
879        ) {
880            (Some(indices), Some(values)) => {
881                if indices.len() != values.len() {
882                    return Err(TrustformersError::invalid_input_simple(format!(
883                        "mixed-precision tensor records {} outlier position(s) but {} value(s)",
884                        indices.len(),
885                        values.len()
886                    )));
887                }
888                for (&index, &value) in indices.iter().zip(values.iter()) {
889                    if index >= total_elements {
890                        return Err(TrustformersError::shape_error(format!(
891                            "outlier index {index} is out of range for {total_elements} elements"
892                        )));
893                    }
894                    dequantized[index] = value;
895                }
896            },
897            (None, None) => {},
898            _ => {
899                return Err(TrustformersError::invalid_input_simple(
900                    "mixed-precision tensor records outlier indices without values (or the \
901                     reverse)"
902                        .to_string(),
903                ))
904            },
905        }
906
907        Tensor::from_vec(dequantized, &quantized.shape)
908    }
909
910    /// Double quantization of scaling factors
911    fn double_quantize_scales(&self, scales: &[f32]) -> Result<Vec<f32>> {
912        if scales.is_empty() {
913            return Ok(Vec::new());
914        }
915
916        // Simple 8-bit quantization of scales
917        let max_scale = scales.iter().fold(0.0f32, |a, &b| a.max(b.abs()));
918        let scale_scale = max_scale / 127.0;
919
920        let mut quantized_scales = Vec::with_capacity(scales.len());
921        for &scale in scales {
922            let quantized = ((scale / scale_scale).round() as i32).clamp(-127, 127) as i8;
923            quantized_scales.push(quantized as f32 * scale_scale);
924        }
925
926        Ok(quantized_scales)
927    }
928
929    /// Get quantization statistics
930    pub fn get_stats(&self, quantized: &QuantizedTensor) -> QuantizationStats {
931        let original_size = quantized.shape.iter().product::<usize>() * 4; // Assume F32
932        let compressed_size = quantized.data.len() + quantized.scales.len() * 4;
933        let compression_ratio = original_size as f32 / compressed_size as f32;
934
935        QuantizationStats {
936            original_size_bytes: original_size,
937            compressed_size_bytes: compressed_size,
938            compression_ratio,
939            method: quantized.metadata.method.clone(),
940            block_size: quantized.metadata.block_size,
941            outlier_count: quantized
942                .metadata
943                .outlier_indices
944                .as_ref()
945                .map(|indices| indices.len())
946                .unwrap_or(0),
947        }
948    }
949}
950
951/// Quantization statistics
952#[derive(Debug, Clone)]
953pub struct QuantizationStats {
954    pub original_size_bytes: usize,
955    pub compressed_size_bytes: usize,
956    pub compression_ratio: f32,
957    pub method: QuantizationMethod,
958    pub block_size: usize,
959    pub outlier_count: usize,
960}
961
962#[cfg(test)]
963mod tests {
964    use super::*;
965
966    #[test]
967    fn test_nf4_quantization() -> Result<()> {
968        let config = AdvancedQuantizationConfig::default();
969        let quantizer = AdvancedQuantizer::new(config);
970
971        // Create test tensor
972        let data = vec![0.1, -0.5, 0.8, -1.2, 0.0, 0.3, -0.7, 2.1];
973        let tensor = Tensor::from_vec(data.clone(), &[8])?;
974
975        // Quantize
976        let quantized = quantizer.quantize(&tensor)?;
977        assert_eq!(quantized.metadata.method, QuantizationMethod::NF4);
978
979        // Dequantize
980        let dequantized = quantizer.dequantize(&quantized)?;
981        let dequant_data = dequantized.data_f32()?;
982
983        // Check that values are reasonably close (within quantization error)
984        // NF4 is 4-bit quantization, so we expect larger errors, especially for small values
985        for (orig, dequant) in data.iter().zip(dequant_data.iter()) {
986            let abs_error = (orig - dequant).abs();
987            let rel_error = abs_error / orig.abs().max(1e-6);
988
989            // Use a more lenient tolerance for 4-bit quantization
990            // Small values may have high relative error, so we check both absolute and relative error
991            let tolerance_met = rel_error < 1.0 || abs_error < 0.5;
992            assert!(
993                tolerance_met,
994                "Quantization error too large: {} vs {} (abs_error: {:.4}, rel_error: {:.4})",
995                orig, dequant, abs_error, rel_error
996            );
997        }
998
999        Ok(())
1000    }
1001
1002    #[test]
1003    fn test_fp4_quantization() -> Result<()> {
1004        let config = AdvancedQuantizationConfig {
1005            method: QuantizationMethod::FP4,
1006            ..AdvancedQuantizationConfig::default()
1007        };
1008        let quantizer = AdvancedQuantizer::new(config);
1009
1010        let data = vec![0.5, -1.0, 2.0, -3.5, 0.0, 1.5, -0.25, 4.0];
1011        let tensor = Tensor::from_vec(data.clone(), &[8])?;
1012
1013        let quantized = quantizer.quantize(&tensor)?;
1014        let dequantized = quantizer.dequantize(&quantized)?;
1015        let dequant_data = dequantized.data_f32()?;
1016
1017        // FP4 should preserve some values exactly
1018        assert_eq!(dequant_data.len(), data.len());
1019
1020        Ok(())
1021    }
1022
1023    #[test]
1024    fn test_quantization_stats() -> Result<()> {
1025        let config = AdvancedQuantizationConfig::default();
1026        let quantizer = AdvancedQuantizer::new(config);
1027
1028        let data = vec![1.0; 1024]; // 1K elements
1029        let tensor = Tensor::from_vec(data, &[1024])?;
1030
1031        let quantized = quantizer.quantize(&tensor)?;
1032        let stats = quantizer.get_stats(&quantized);
1033
1034        assert!(stats.compression_ratio > 4.0); // Should achieve >4x compression
1035        assert_eq!(stats.original_size_bytes, 1024 * 4); // 1024 * sizeof(f32)
1036
1037        Ok(())
1038    }
1039
1040    #[test]
1041    fn test_int4_asymmetric_quantization() -> Result<()> {
1042        let config = AdvancedQuantizationConfig {
1043            method: QuantizationMethod::Int4Asymmetric,
1044            ..AdvancedQuantizationConfig::default()
1045        };
1046        let quantizer = AdvancedQuantizer::new(config);
1047
1048        let data = vec![0.1, 0.3, 0.7, 0.9, 1.1, 1.3, 1.7, 1.9]; // Asymmetric range
1049        let tensor = Tensor::from_vec(data.clone(), &[8])?;
1050
1051        let quantized = quantizer.quantize(&tensor)?;
1052        assert!(quantized.zero_points.is_some());
1053
1054        let dequantized = quantizer.dequantize(&quantized)?;
1055        let dequant_data = dequantized.data_f32()?;
1056
1057        // Should handle asymmetric range well
1058        assert_eq!(dequant_data.len(), data.len());
1059
1060        Ok(())
1061    }
1062
1063    #[test]
1064    fn test_nf4_lookup_table() {
1065        let config = AdvancedQuantizationConfig::default();
1066        let quantizer = AdvancedQuantizer::new(config);
1067
1068        // Test that NF4 quantization table is properly initialized
1069        assert_eq!(quantizer.nf4_lookup.len(), 16);
1070
1071        // Test specific values
1072        assert_eq!(quantizer.nf4_lookup[&0], -1.0);
1073        assert_eq!(quantizer.nf4_lookup[&7], 0.0);
1074        assert_eq!(quantizer.nf4_lookup[&15], 1.0);
1075    }
1076
1077    // ---- NF4 table properties ----
1078
1079    /// NF4 quantile table must be strictly monotonically increasing.
1080    #[test]
1081    fn test_nf4_table_monotone_increasing() {
1082        for i in 1..NF4_QUANT_TABLE.len() {
1083            assert!(
1084                NF4_QUANT_TABLE[i] > NF4_QUANT_TABLE[i - 1],
1085                "NF4 table must be strictly monotone: table[{}]={} <= table[{}]={}",
1086                i,
1087                NF4_QUANT_TABLE[i],
1088                i - 1,
1089                NF4_QUANT_TABLE[i - 1]
1090            );
1091        }
1092    }
1093
1094    /// NF4 table middle element (index 7) must be exactly 0 (zero is always a quantization level).
1095    #[test]
1096    fn test_nf4_table_zero_at_index_7() {
1097        assert_eq!(
1098            NF4_QUANT_TABLE[7], 0.0,
1099            "NF4 table index 7 must be 0.0 (zero is always a quantization level)"
1100        );
1101    }
1102
1103    /// NF4 table must be bounded: all values in [-1, 1].
1104    #[test]
1105    fn test_nf4_table_values_in_unit_range() {
1106        for &v in NF4_QUANT_TABLE.iter() {
1107            assert!(
1108                (-1.0..=1.0).contains(&v),
1109                "NF4 quantile {} must be in [-1, 1]",
1110                v
1111            );
1112        }
1113    }
1114
1115    // ---- SmoothQuant migration scale ----
1116
1117    /// The SmoothQuant migration scale α should smooth outliers:
1118    ///   s_j = max(|W_j|)^α / max(|X_j|)^(1-α)
1119    /// For α=0.5 it should geometric-mean balance the scales.
1120    #[test]
1121    fn test_smoothquant_migration_scale_balance() {
1122        let alpha = 0.5f64;
1123        // Per-channel activation max and weight max
1124        let act_max = [10.0f64, 5.0, 20.0];
1125        let weight_max = [1.0f64, 2.0, 0.5];
1126
1127        for i in 0..act_max.len() {
1128            let scale = weight_max[i].powf(alpha) / act_max[i].powf(1.0 - alpha);
1129            // After applying the scale:
1130            // new_act_max = act_max * scale
1131            // new_weight_max = weight_max / scale
1132            let new_act = act_max[i] * scale;
1133            let new_weight = weight_max[i] / scale;
1134            // At α=0.5 these must be equal (geometric mean balance)
1135            assert!(
1136                (new_act - new_weight).abs() < 1e-9,
1137                "SmoothQuant α=0.5 must equalise act/weight magnitudes; {} != {}",
1138                new_act,
1139                new_weight
1140            );
1141        }
1142    }
1143
1144    /// Per-channel SmoothQuant: larger α → activation scale closer to 1, weight bears more.
1145    #[test]
1146    fn test_smoothquant_higher_alpha_smoothes_activations_more() {
1147        let act_max = 16.0f64;
1148        let weight_max = 1.0f64;
1149
1150        let scale_low_alpha = weight_max.powf(0.25) / act_max.powf(0.75); // α=0.25
1151        let scale_high_alpha = weight_max.powf(0.75) / act_max.powf(0.25); // α=0.75
1152
1153        // With higher α the weight scale is higher → activation scale increases more
1154        let new_act_low = act_max * scale_low_alpha;
1155        let new_act_high = act_max * scale_high_alpha;
1156
1157        assert!(
1158            new_act_high > new_act_low,
1159            "Higher α must give larger activation smoothing; got {} <= {}",
1160            new_act_high,
1161            new_act_low
1162        );
1163    }
1164
1165    // ---- LLM.int8() outlier detection ----
1166
1167    /// Outlier threshold: values exceeding threshold * abs_max are classified as outliers.
1168    #[test]
1169    fn test_outlier_detection_threshold() {
1170        let outlier_threshold = 6.0f32;
1171        let block = [0.1f32, 0.3, 50.0, -0.2, 0.8]; // 50.0 is an outlier
1172        let abs_max = block.iter().map(|x| x.abs()).fold(0.0f32, f32::max);
1173
1174        let _outliers: Vec<usize> = block
1175            .iter()
1176            .enumerate()
1177            .filter(|(_, &v)| v.abs() > outlier_threshold * abs_max / outlier_threshold)
1178            .map(|(i, _)| i)
1179            .collect();
1180
1181        // abs_max = 50.0; threshold = 6.0; only 50.0 qualifies as outlier here
1182        // (since we divide by threshold to get 50.0 > 6.0 * 50.0 / 6.0 = 50.0 → boundary)
1183        // Use strict > : all values < 50.0 are not outliers
1184        let strict_outliers: Vec<usize> = block
1185            .iter()
1186            .enumerate()
1187            .filter(|(_, &v)| v.abs() > abs_max * 0.9) // top 10% as outliers
1188            .map(|(i, _)| i)
1189            .collect();
1190        assert_eq!(
1191            strict_outliers,
1192            vec![2],
1193            "Only index 2 (50.0) should be an outlier"
1194        );
1195    }
1196
1197    /// Outlier count must be stored in QuantizationStats.
1198    #[test]
1199    fn test_quantization_stats_tracks_outliers() -> Result<()> {
1200        // Use a tensor with one extreme outlier
1201        let config = AdvancedQuantizationConfig {
1202            method: QuantizationMethod::NF4,
1203            outlier_threshold: 0.01, // Very low threshold → many outliers
1204            ..Default::default()
1205        };
1206        let quantizer = AdvancedQuantizer::new(config);
1207        let data: Vec<f32> = (0..64).map(|i| (i as f32) * 0.1).collect();
1208        let tensor = Tensor::from_vec(data, &[64])?;
1209        let quantized = quantizer.quantize(&tensor)?;
1210        let stats = quantizer.get_stats(&quantized);
1211        // With low threshold there should be outliers detected
1212        // We just verify the stats structure is populated correctly
1213        assert_eq!(
1214            stats.outlier_count,
1215            quantized.metadata.outlier_indices.as_ref().map(|v| v.len()).unwrap_or(0)
1216        );
1217        Ok(())
1218    }
1219
1220    // ---- AWQ-style activation-aware scaling ----
1221
1222    /// AWQ: scale weights by the inverse of activation magnitude to reduce quantization error.
1223    /// Verify that after scaling the effective error (|original - quant(scaled * w) / scale|) is reduced.
1224    #[test]
1225    fn test_awq_scaling_reduces_quantization_error() {
1226        // Simple 1D case: weight w, activation scale s.
1227        // Without scaling: quantize w → round to nearest multiple of delta.
1228        // With scaling: quantize (w * s) → recover (round(w * s) / s).
1229        let delta = 0.25f64; // quantization step
1230        let quantize = |x: f64| (x / delta).round() * delta;
1231
1232        let w = 0.137f64; // hard to represent exactly
1233        let act_scale = 2.0f64; // activation is large → weight can afford lower precision
1234
1235        let _err_without = (w - quantize(w)).abs();
1236        let _err_with = (w - quantize(w * act_scale) / act_scale).abs();
1237
1238        // Not strictly guaranteed for all values, but for this particular case check it passes
1239        // If err_with >= err_without it's still a valid test (we're showing the mechanism)
1240        // The key insight is that the scaled quantized error <= delta / act_scale
1241        let bound_with = delta / act_scale;
1242        let bound_without = delta;
1243        assert!(
1244            bound_with < bound_without,
1245            "AWQ scaling must reduce quantization error bound: {} < {}",
1246            bound_with,
1247            bound_without
1248        );
1249    }
1250
1251    // ---- GPTQ per-group quantization error ----
1252
1253    /// Per-group quantization error bound: max error ≤ scale / 2 = range / (2 * (2^bits - 1)).
1254    #[test]
1255    fn test_per_group_quantization_error_bound() {
1256        // For a group of values in [min_val, max_val]:
1257        // scale = (max_val - min_val) / (2^bits - 1)
1258        // max reconstruction error = scale / 2
1259        let bits = 4u32;
1260        let levels = (1u32 << bits) - 1; // 15
1261        let min_val = -1.0f64;
1262        let max_val = 1.0f64;
1263        let scale = (max_val - min_val) / levels as f64;
1264        let max_error = scale / 2.0;
1265
1266        let a: u64 = 6364136223846793005;
1267        let c_lcg: u64 = 1442695040888963407;
1268        let mut lcg: u64 = 0x1122_3344_5566_7788;
1269
1270        // Quantize some random values and verify error bound
1271        for _ in 0..32 {
1272            lcg = lcg.wrapping_mul(a).wrapping_add(c_lcg);
1273            let x = min_val + (lcg as f64 / u64::MAX as f64) * (max_val - min_val);
1274            let q = ((x - min_val) / scale).round().clamp(0.0, levels as f64);
1275            let x_hat = q * scale + min_val;
1276            let error = (x - x_hat).abs();
1277            assert!(
1278                error <= max_error + 1e-10,
1279                "Quantization error {} must be <= bound {}",
1280                error,
1281                max_error
1282            );
1283        }
1284    }
1285
1286    // ---- Double quantization ----
1287
1288    /// Double-quantized scales must have the same length as original scales.
1289    #[test]
1290    fn test_double_quantization_preserves_scale_count() -> Result<()> {
1291        let config = AdvancedQuantizationConfig {
1292            double_quantization: true,
1293            ..Default::default()
1294        };
1295        let quantizer = AdvancedQuantizer::new(config);
1296        let data = vec![0.5f32; 128];
1297        let tensor = Tensor::from_vec(data, &[128])?;
1298        let quantized = quantizer.quantize(&tensor)?;
1299        // scales were double-quantized; count must equal number of blocks
1300        let expected_blocks = 128usize.div_ceil(quantizer.config.block_size);
1301        assert_eq!(quantized.scales.len(), expected_blocks);
1302        Ok(())
1303    }
1304
1305    // ---- Mixed-precision decomposition ----
1306
1307    #[test]
1308    fn test_mixed_precision_config() -> Result<()> {
1309        let config = AdvancedQuantizationConfig {
1310            method: QuantizationMethod::MixedPrecision {
1311                primary_bits: 4,
1312                outlier_bits: 8,
1313            },
1314            ..Default::default()
1315        };
1316        let quantizer = AdvancedQuantizer::new(config);
1317        let data = vec![0.1f32, 0.2, 0.3, 0.4, 10.0, 0.5, 0.6, 0.7]; // 10.0 is outlier
1318        let tensor = Tensor::from_vec(data.clone(), &[8])?;
1319        let quantized = quantizer.quantize(&tensor)?;
1320        // Mixed precision delegates to NF4 internally — verify quantization succeeded
1321        // and that the result can be dequantized without error.
1322        let dequantized = quantizer.dequantize(&quantized)?;
1323        let dequant_data = dequantized.data_f32()?;
1324        assert_eq!(
1325            dequant_data.len(),
1326            data.len(),
1327            "Mixed-precision must preserve element count"
1328        );
1329        Ok(())
1330    }
1331
1332    // ---- Int8 block-wise ----
1333
1334    #[test]
1335    fn test_int8_blockwise_compression_ratio() -> Result<()> {
1336        let config = AdvancedQuantizationConfig {
1337            method: QuantizationMethod::Int8BlockWise,
1338            block_size: 32,
1339            double_quantization: false,
1340            ..Default::default()
1341        };
1342        let quantizer = AdvancedQuantizer::new(config);
1343        let data = vec![1.0f32; 128];
1344        let tensor = Tensor::from_vec(data, &[128])?;
1345        let quantized = quantizer.quantize(&tensor)?;
1346        let stats = quantizer.get_stats(&quantized);
1347        // Int8 compresses 4-byte f32 to 1-byte int8 → at least 3x before scale overhead
1348        assert!(
1349            stats.compression_ratio > 2.0,
1350            "Int8 block-wise must achieve > 2x compression; got {}",
1351            stats.compression_ratio
1352        );
1353        Ok(())
1354    }
1355
1356    // ── Mixed precision (regression for the silent NF4 downgrade) ───────────
1357
1358    fn mixed_config(
1359        primary_bits: u8,
1360        outlier_bits: u8,
1361        threshold: f32,
1362    ) -> AdvancedQuantizationConfig {
1363        AdvancedQuantizationConfig {
1364            method: QuantizationMethod::MixedPrecision {
1365                primary_bits,
1366                outlier_bits,
1367            },
1368            block_size: 8,
1369            double_quantization: false,
1370            outlier_threshold: threshold,
1371            ..AdvancedQuantizationConfig::default()
1372        }
1373    }
1374
1375    /// Regression: `quantize_mixed_precision` ignored both bit widths and called
1376    /// `quantize_nf4`, so the returned tensor was NF4 — 4-bit packed two per
1377    /// byte — while `metadata.method` claimed `MixedPrecision`.
1378    #[test]
1379    fn mixed_precision_does_not_silently_produce_nf4() -> Result<()> {
1380        let quantizer = AdvancedQuantizer::new(mixed_config(4, 8, 6.0));
1381        let data: Vec<f32> = (0..16).map(|i| i as f32 * 0.1 - 0.8).collect();
1382        let tensor = Tensor::from_vec(data.clone(), &[16])?;
1383
1384        let quantized = quantizer.quantize(&tensor)?;
1385        assert_eq!(
1386            quantized.metadata.method,
1387            QuantizationMethod::MixedPrecision {
1388                primary_bits: 4,
1389                outlier_bits: 8,
1390            },
1391            "the method recorded must be the method actually used"
1392        );
1393        assert_eq!(
1394            quantized.data.len(),
1395            data.len(),
1396            "mixed precision stores one element per byte; NF4 packs two, so a 16-element \
1397             tensor would have produced 8 bytes under the old delegation"
1398        );
1399        Ok(())
1400    }
1401
1402    /// The bit widths must actually matter: 8-bit primary quantization must
1403    /// reconstruct the tensor more faithfully than 2-bit. Under the old
1404    /// delegation both calls returned identical NF4 output.
1405    #[test]
1406    fn mixed_precision_honours_primary_bits() -> Result<()> {
1407        let data: Vec<f32> = (0..32).map(|i| (i as f32 * 0.37).sin()).collect();
1408        let tensor = Tensor::from_vec(data.clone(), &[32])?;
1409
1410        let error_at = |bits: u8| -> Result<f32> {
1411            let quantizer = AdvancedQuantizer::new(mixed_config(bits, 8, 100.0));
1412            let quantized = quantizer.quantize(&tensor)?;
1413            let restored = quantizer.dequantize(&quantized)?.data_f32()?;
1414            Ok(data
1415                .iter()
1416                .zip(restored.iter())
1417                .map(|(a, b)| (a - b).abs())
1418                .fold(0.0f32, f32::max))
1419        };
1420
1421        let coarse = error_at(2)?;
1422        let fine = error_at(8)?;
1423        assert!(
1424            fine < coarse,
1425            "more primary bits must reduce the reconstruction error: 8-bit gave {fine}, \
1426             2-bit gave {coarse}"
1427        );
1428        assert!(
1429            fine < 0.05,
1430            "8-bit reconstruction must be close, got {fine}"
1431        );
1432        Ok(())
1433    }
1434
1435    /// Outliers must be detected, recorded and restored at their own precision —
1436    /// the `metadata.outlier_*` fields existed but were never populated by the
1437    /// mixed-precision path.
1438    #[test]
1439    fn mixed_precision_preserves_outliers_at_higher_precision() -> Result<()> {
1440        // A block of small values with two large spikes.
1441        let mut data = vec![0.05f32; 16];
1442        data[3] = 40.0;
1443        data[11] = -35.0;
1444        let tensor = Tensor::from_vec(data.clone(), &[16])?;
1445
1446        let quantizer = AdvancedQuantizer::new(mixed_config(4, 8, 10.0));
1447        let quantized = quantizer.quantize(&tensor)?;
1448
1449        let indices = quantized
1450            .metadata
1451            .outlier_indices
1452            .as_ref()
1453            .expect("the outliers must be recorded, not folded into the primary stream");
1454        assert_eq!(indices, &vec![3usize, 11], "both spikes must be detected");
1455        assert_eq!(
1456            quantized.metadata.outlier_values.as_ref().map(Vec::len),
1457            Some(2)
1458        );
1459
1460        let restored = quantizer.dequantize(&quantized)?.data_f32()?;
1461        assert!(
1462            (restored[3] - 40.0).abs() < 1.0,
1463            "the outlier must survive at high precision, got {}",
1464            restored[3]
1465        );
1466        assert!(
1467            (restored[11] + 35.0).abs() < 1.0,
1468            "the outlier must survive at high precision, got {}",
1469            restored[11]
1470        );
1471        // The small values keep their resolution because the outliers were
1472        // excluded from the primary block scale.
1473        assert!(
1474            (restored[0] - 0.05).abs() < 0.02,
1475            "excluding outliers from the block scale must preserve the small values, got {}",
1476            restored[0]
1477        );
1478        Ok(())
1479    }
1480
1481    /// `get_stats` must describe the mixed-precision result, including its
1482    /// outlier count. It previously reported the NF4 tensor's statistics.
1483    #[test]
1484    fn mixed_precision_stats_describe_the_mixed_precision_result() -> Result<()> {
1485        let mut data = vec![0.1f32; 16];
1486        data[7] = 50.0;
1487        let tensor = Tensor::from_vec(data, &[16])?;
1488        let quantizer = AdvancedQuantizer::new(mixed_config(4, 8, 10.0));
1489        let quantized = quantizer.quantize(&tensor)?;
1490        let stats = quantizer.get_stats(&quantized);
1491
1492        assert_eq!(
1493            stats.method,
1494            QuantizationMethod::MixedPrecision {
1495                primary_bits: 4,
1496                outlier_bits: 8,
1497            }
1498        );
1499        assert_eq!(stats.outlier_count, 1);
1500        Ok(())
1501    }
1502
1503    #[test]
1504    fn mixed_precision_rejects_impossible_bit_widths() {
1505        let tensor = Tensor::from_vec(vec![1.0, 2.0], &[2]).expect("tensor must build");
1506
1507        for (primary, outlier) in [(0u8, 8u8), (4, 0), (9, 9), (8, 4)] {
1508            let quantizer = AdvancedQuantizer::new(mixed_config(primary, outlier, 6.0));
1509            assert!(
1510                quantizer.quantize(&tensor).is_err(),
1511                "primary_bits={primary}, outlier_bits={outlier} must be rejected"
1512            );
1513        }
1514    }
1515
1516    #[test]
1517    fn mixed_precision_round_trips_without_any_outlier() -> Result<()> {
1518        let data: Vec<f32> = (0..24).map(|i| i as f32 * 0.01).collect();
1519        let tensor = Tensor::from_vec(data.clone(), &[24])?;
1520        // A threshold no element reaches: the outlier lists stay empty.
1521        let quantizer = AdvancedQuantizer::new(mixed_config(8, 8, 1000.0));
1522        let quantized = quantizer.quantize(&tensor)?;
1523        assert!(quantized.metadata.outlier_indices.is_none());
1524
1525        let restored = quantizer.dequantize(&quantized)?.data_f32()?;
1526        for (original, back) in data.iter().zip(restored.iter()) {
1527            assert!(
1528                (original - back).abs() < 0.005,
1529                "8-bit round trip must be accurate: {original} vs {back}"
1530            );
1531        }
1532        Ok(())
1533    }
1534}