oxidelm 0.2.0

Bare-metal pure-Rust Transformer engine with reverse-mode autograd, BPE tokenization, and wgpu acceleration
Documentation
//! Quantization correctness suite: dequant error bounds, CPU↔GPU parity,
//! and packed-layout fuzz / validation.

#[path = "common/mod.rs"]
mod common;

#[cfg(feature = "gpu")]
use common::gpu_or_skip;
use oxidelm::layers::{Linear, QuantGranularity, QuantScheme, ScaleMethod, WeightQuantization};
use oxidelm::weight_quant::{
    pack_weights, read_packed_public, validate_packed, write_packed_public, PackedLinearWeight,
};
use oxidelm::Tensor;
use proptest::prelude::*;
use proptest::test_runner::FileFailurePersistence;
use rand::rngs::StdRng;
use rand::{RngExt, SeedableRng};

fn prop_config(cases: u32) -> ProptestConfig {
    let mut config = ProptestConfig::with_cases(cases);
    config.failure_persistence = Some(Box::new(FileFailurePersistence::Off));
    config
}

fn maximum_difference(left: &[f32], right: &[f32]) -> f32 {
    left.iter()
        .zip(right)
        .map(|(left, right)| (left - right).abs())
        .fold(0.0, f32::max)
}

fn schemes_under_test() -> Vec<QuantScheme> {
    vec![
        QuantScheme::default_for(WeightQuantization::Int8),
        QuantScheme {
            format: WeightQuantization::Int4,
            granularity: QuantGranularity::PerChannel,
            symmetric: true,
            scale_method: ScaleMethod::AbsMax,
            percentile: 99.99,
        },
        QuantScheme {
            format: WeightQuantization::Int4,
            granularity: QuantGranularity::PerGroup { size: 32 },
            symmetric: false,
            scale_method: ScaleMethod::MinMax,
            percentile: 99.99,
        },
        QuantScheme {
            format: WeightQuantization::Int3,
            granularity: QuantGranularity::PerChannel,
            symmetric: true,
            scale_method: ScaleMethod::AbsMax,
            percentile: 99.99,
        },
        QuantScheme {
            format: WeightQuantization::Int2,
            granularity: QuantGranularity::PerTensor,
            symmetric: true,
            scale_method: ScaleMethod::AbsMax,
            percentile: 99.99,
        },
        QuantScheme::default_for(WeightQuantization::Nf4),
        QuantScheme::default_for(WeightQuantization::Fp8E4M3),
        QuantScheme::default_for(WeightQuantization::Fp8E5M2),
    ]
}

fn fixture_matrix(in_features: usize, out_features: usize, seed: u64) -> Vec<f32> {
    let mut rng = StdRng::seed_from_u64(seed);
    (0..in_features * out_features)
        .map(|_| rng.random_range(-1.5f32..1.5))
        .collect()
}

#[test]
fn dequant_error_stays_within_scheme_bounds() {
    let in_features = 64;
    let out_features = 8;
    let data = fixture_matrix(in_features, out_features, 7);
    for scheme in schemes_under_test() {
        let packed = pack_weights(in_features, out_features, scheme, |i, o| {
            data[i * out_features + o]
        })
        .unwrap_or_else(|error| panic!("{scheme:?}: {error}"));
        let error = packed.max_abs_dequant_error(|i, o| data[i * out_features + o]);
        let bound = packed.dequant_error_bound();
        assert!(
            error <= bound,
            "{scheme:?}: max dequant error {error} exceeds bound {bound}"
        );
    }
}

#[test]
fn cpu_forward_tracks_dequant_matmul_within_bound() {
    let in_features = 32;
    let out_features = 4;
    let data = fixture_matrix(in_features, out_features, 11);
    let input = Tensor::new(
        (0..2 * in_features)
            .map(|index| ((index % 7) as f32) * 0.05 - 0.15)
            .collect(),
        vec![2, in_features],
        false,
    );
    for scheme in schemes_under_test() {
        let mut linear = Linear::new(in_features, out_features, 3);
        linear.weight.set_data(data.clone());
        linear.quantize_weight_with(scheme);
        let weight = linear.quantized_weight().unwrap();
        let dequant = weight.dequantized_values(false);
        let reference = Linear::new(in_features, out_features, 3);
        reference.weight.set_data(dequant);
        let expected = reference.forward(&input).data();
        let actual = linear.forward(&input).data();
        assert!(
            maximum_difference(&actual, &expected) <= 1e-5,
            "{scheme:?}: packed forward drifted from explicit dequant matmul"
        );
    }
}

#[cfg(feature = "gpu")]
#[test]
fn cpu_gpu_mismatch_is_bounded_across_schemes() {
    let Some(gpu) = gpu_or_skip() else {
        return;
    };
    let in_features = 16;
    let out_features = 4;
    let data = fixture_matrix(in_features, out_features, 19);
    let input = Tensor::new(
        (0..2 * in_features)
            .map(|index| ((index % 5) as f32) * 0.1 - 0.2)
            .collect(),
        vec![2, in_features],
        false,
    );
    for scheme in schemes_under_test() {
        let mut linear = Linear::new(in_features, out_features, 5);
        linear.weight.set_data(data.clone());
        linear.quantize_weight_with(scheme);
        let expected = linear.forward(&input).data();
        let actual = linear
            .forward_gpu(&input, &gpu)
            .unwrap()
            .to_cpu()
            .unwrap()
            .data();
        let mismatch = maximum_difference(&actual, &expected);
        assert!(
            mismatch <= 1e-4,
            "{scheme:?}: CPU↔GPU mismatch {mismatch} exceeds 1e-4 (actual={actual:?}, expected={expected:?})"
        );
    }
}

#[test]
fn validate_packed_rejects_corrupt_layouts() {
    let scheme = QuantScheme {
        format: WeightQuantization::Int4,
        granularity: QuantGranularity::PerGroup { size: 32 },
        symmetric: true,
        scale_method: ScaleMethod::AbsMax,
        percentile: 99.99,
    };
    let packed = pack_weights(64, 2, scheme, |i, o| ((i + o) as f32) * 0.01 - 0.1).unwrap();

    let mut bad_scales = packed.scales.clone();
    bad_scales.pop();
    assert!(validate_packed(
        scheme,
        &packed.packed_values,
        &bad_scales,
        None,
        packed.in_features,
        packed.out_features,
    )
    .is_err());

    let mut bad_words = packed.packed_values.clone();
    bad_words.push(0);
    assert!(validate_packed(
        scheme,
        &bad_words,
        &packed.scales,
        None,
        packed.in_features,
        packed.out_features,
    )
    .is_err());

    let asymmetric = QuantScheme {
        symmetric: false,
        scale_method: ScaleMethod::MinMax,
        ..scheme
    };
    assert!(validate_packed(
        asymmetric,
        &packed.packed_values,
        &packed.scales,
        None,
        packed.in_features,
        packed.out_features,
    )
    .is_err());
}

proptest! {
    #![proptest_config(prop_config(64))]

    #[test]
    fn packed_layout_roundtrip_fuzz(
        format in prop_oneof![
            Just(WeightQuantization::Int8),
            Just(WeightQuantization::Int4),
            Just(WeightQuantization::Int2),
            Just(WeightQuantization::Nf4),
            Just(WeightQuantization::Fp8E4M3),
        ],
        in_features in 1usize..=48,
        out_features in 1usize..=8,
        seed in any::<u64>(),
    ) {
        let scheme = QuantScheme::default_for(format);
        let data = fixture_matrix(in_features, out_features, seed);
        let packed = pack_weights(in_features, out_features, scheme, |i, o| {
            data[i * out_features + o]
        })
        .map_err(|error| TestCaseError::fail(error))?;
        validate_packed(
            scheme,
            &packed.packed_values,
            &packed.scales,
            packed.zero_points.as_deref(),
            in_features,
            out_features,
        )
        .map_err(|error| TestCaseError::fail(error))?;

        let numel = in_features * out_features;
        for index in 0..numel {
            let raw = read_packed_public(&packed.packed_values, index, format);
            let mut scratch = vec![0u32; packed.packed_values.len()];
            write_packed_public(&mut scratch, index, raw, format);
            let roundtrip = read_packed_public(&scratch, index, format);
            prop_assert_eq!(raw, roundtrip);
        }

        let error = packed.max_abs_dequant_error(|i, o| data[i * out_features + o]);
        prop_assert!(
            error <= packed.dequant_error_bound(),
            "dequant error {error} > bound {}",
            packed.dequant_error_bound()
        );
    }

    #[test]
    fn validate_packed_rejects_dimension_fuzz(
        format in prop_oneof![
            Just(WeightQuantization::Int8),
            Just(WeightQuantization::Int4),
        ],
        in_features in 8usize..=64,
        out_features in 1usize..=8,
        drop_scales in 1usize..=4,
    ) {
        let scheme = QuantScheme::default_for(format);
        let packed = pack_weights(in_features, out_features, scheme, |i, o| {
            ((i * 3 + o) as f32) * 0.02 - 0.4
        })
        .map_err(|error| TestCaseError::fail(error))?;
        let mut scales = packed.scales.clone();
        let drop = drop_scales.min(scales.len());
        scales.truncate(scales.len() - drop);
        prop_assert!(validate_packed(
            scheme,
            &packed.packed_values,
            &scales,
            None,
            in_features,
            out_features,
        )
        .is_err());
    }
}

#[test]
fn storage_bytes_shrink_vs_fp32() {
    let data = fixture_matrix(128, 16, 23);
    for format in [
        WeightQuantization::Int8,
        WeightQuantization::Int4,
        WeightQuantization::Int2,
        WeightQuantization::Nf4,
    ] {
        let packed: PackedLinearWeight =
            pack_weights(128, 16, QuantScheme::default_for(format), |i, o| {
                data[i * 16 + o]
            })
            .unwrap();
        let fp32_bytes = 128 * 16 * std::mem::size_of::<f32>();
        assert!(
            packed.storage_bytes() < fp32_bytes,
            "{format:?} pack did not shrink vs FP32"
        );
    }
}