tracel-ai/burn · error

a per-tensor scale should come with a two-level scheme

Error message

a per-tensor scale should come with a two-level scheme

What it means

Invariant check in the ndarray backend's `quantize`: a per-tensor scale was supplied, but the quantization scheme is not a two-level scheme (there is no global scale slot for it), so the qparams are inconsistent with the scheme and quantization panics.

Source

Thrown at crates/burn-ndarray/src/ops/qtensor.rs:98

    }

    fn quantize(
        tensor: FloatTensor<Self>,
        scheme: &QuantScheme,
        qparams: QuantizationParametersPrimitive<Self>,
    ) -> QuantizedTensor<Self> {
        let shape = tensor.shape();
        let data_f = tensor.into_data();
        let scales = qparams.scales.into_data().convert::<f32>();
        // Quantize against the scale that will actually be stored, so a save/load round trip
        // reproduces these values instead of drifting by the scale dtype's rounding error.
        let scales: Vec<f32> = scales
            .iter::<f32>()
            .map(|s| scale_to_dtype(s, scheme.scale_dtype()))
            .collect();
        let global = qparams.global.map(|global| {
            let dtype = global_scale_dtype(scheme)
                .expect("a per-tensor scale should come with a two-level scheme");
            let global = global.into_data().convert::<f32>();
            scale_to_dtype(global.iter::<f32>().next().unwrap(), dtype)
        });

        // Implement with ndarray instead of QuantizationStrategy?
        let (data, qparams) = match (scheme.block_size(), scheme) {
            (
                None,
                QuantScheme {
                    mode: QuantMode::Symmetric,
                    // `Q2S` is supported natively (stored as i8): it feeds the multiply-free
                    // ternary matmul fast path in `q_matmul` (BitNet b1.58).
                    #[cfg(not(feature = "export_tests"))]
                        value: QuantValue::Q8F | QuantValue::Q8S | QuantValue::Q2S,
                    // For tests, "native" sub-byte quant serves as a reference for value equality.
                    // Values are stored as i8 regardless.
                    #[cfg(feature = "export_tests")]
                        value:

View on GitHub (pinned to d16f7ba2ed)

Solutions

1. Provide only the scales the scheme expects (single scale for one-level schemes)
2. Use a two-level scheme when a global per-tensor scale is needed
3. Verify how QuantizationParametersPrimitive was constructed

When it happens

Trigger: Thrown at crates/burn-ndarray/src/ops/qtensor.rs:98 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/71a6de7e2c298603. Report an issue: GitHub.