burn-ndarray 0.22.0-pre.3

use crate::rand::NdArrayRng;
use crate::{NdArrayQTensor, NdArrayTensor};
use alloc::string::String;
use burn_backend::quantization::{QuantMode, QuantScheme, QuantStore, QuantValue, quantizable};
use burn_backend::tensor::{BoolTensor, FloatTensor, IntTensor, QuantizedTensor};
use burn_backend::{Backend, BackendTypes, DType, DeviceId, DeviceOps};
use burn_ir::{BackendIr, HandleKind, TensorHandle};
use burn_std::sync::Mutex;
use burn_std::{BoolStore, DeviceSettings, QuantConfig};
use rand::SeedableRng;

pub(crate) static SEED: Mutex<Option<NdArrayRng>> = Mutex::new(None);

/// The device type for the ndarray backend.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
pub enum NdArrayDevice {
    /// The CPU device.
    #[default]
    Cpu,
}

impl DeviceOps for NdArrayDevice {
    fn defaults(&self) -> DeviceSettings {
        // E = f32, I = i64
        DeviceSettings::new(
            DType::F32,
            DType::I64,
            DType::Bool(BoolStore::Native),
            QuantConfig::new(
                QuantScheme::default().with_store(QuantStore::Native),
                Default::default(),
            ),
        )
    }
}

impl burn_backend::Device for NdArrayDevice {
    fn from_id(_device_id: DeviceId) -> Self {
        Self::Cpu
    }

    fn to_id(&self) -> DeviceId {
        DeviceId {
            type_id: 0,
            index_id: 0,
        }
    }
}

/// Tensor backend that uses the [ndarray](ndarray) crate for executing tensor operations.
///
/// This backend is compatible with CPUs and can be compiled for almost any platform, including
/// `wasm`, `arm`, and `x86`.
#[derive(Clone, Copy, Default, Debug)]
pub struct NdArray;

impl BackendTypes for NdArray {
    type Device = NdArrayDevice;

    type FloatTensorPrimitive = NdArrayTensor;
    type IntTensorPrimitive = NdArrayTensor;
    type BoolTensorPrimitive = NdArrayTensor;
    type QuantizedTensorPrimitive = NdArrayQTensor;

    type GraphPrimitive = burn_backend::GraphUnsupported;
}

impl Backend for NdArray {
    fn ad_enabled(_device: &Self::Device) -> bool {
        false
    }

    fn name(_device: &Self::Device) -> String {
        String::from("ndarray")
    }

    fn seed(_device: &Self::Device, seed: u64) {
        let rng = NdArrayRng::seed_from_u64(seed);
        let mut seed = SEED.lock();
        *seed = Some(rng);
    }

    fn dtype_usage(_device: &Self::Device, dtype: DType) -> burn_backend::DTypeUsageSet {
        match dtype {
            DType::F64
            | DType::F32
            | DType::Flex32
            | DType::I64
            | DType::I32
            | DType::I16
            | DType::I8
            | DType::U64
            | DType::U32
            | DType::U16
            | DType::U8
            | DType::Bool(BoolStore::Native) => burn_backend::DTypeUsage::general(),
            DType::F16 | DType::BF16 | DType::Bool(_) => burn_backend::DTypeUsageSet::empty(),
            DType::QFloat(scheme) => {
                match scheme {
                    QuantScheme {
                        mode: QuantMode::Symmetric,
                        #[cfg(not(feature = "export_tests"))]
                            value: QuantValue::Q8F | QuantValue::Q8S,
                        // For tests, "native" sub-byte quant serves as a reference for value equality.
                        // Values are stored as i8 regardless.
                        #[cfg(feature = "export_tests")]
                            value:
                            QuantValue::Q8F
                            | QuantValue::Q8S
                            | QuantValue::Q4F
                            | QuantValue::Q4S
                            | QuantValue::Q2F
                            | QuantValue::Q2S,
                        store: QuantStore::Native,
                        ..
                    // The value and store alone do not say which levels `quantize` will accept.
                    } if quantizable(&scheme) => burn_backend::DTypeUsage::general(),
                    _scheme => burn_backend::DTypeUsageSet::empty(),
                }
            }
        }
    }

    fn device_count(_: u16) -> usize {
        1
    }

    fn flush(_device: &Self::Device) {}
}

impl BackendIr for NdArray {
    type Handle = HandleKind<Self>;

    fn float_tensor(handle: TensorHandle<Self::Handle>) -> FloatTensor<Self> {
        match handle.handle {
            HandleKind::Float(handle) => handle,
            _ => panic!("Expected float handle, got {}", handle.handle.name()),
        }
    }

    fn int_tensor(handle: TensorHandle<Self::Handle>) -> IntTensor<Self> {
        match handle.handle {
            HandleKind::Int(handle) => handle,
            _ => panic!("Expected int handle, got {}", handle.handle.name()),
        }
    }

    fn bool_tensor(handle: TensorHandle<Self::Handle>) -> BoolTensor<Self> {
        match handle.handle {
            HandleKind::Bool(handle) => handle,
            _ => panic!("Expected bool handle, got {}", handle.handle.name()),
        }
    }

    fn quantized_tensor(handle: TensorHandle<Self::Handle>) -> QuantizedTensor<Self> {
        match handle.handle {
            HandleKind::Quantized(handle) => handle,
            _ => panic!("Expected quantized handle, got {}", handle.handle.name()),
        }
    }

    fn float_tensor_handle(tensor: FloatTensor<Self>) -> Self::Handle {
        HandleKind::Float(tensor)
    }

    fn int_tensor_handle(tensor: IntTensor<Self>) -> Self::Handle {
        HandleKind::Int(tensor)
    }

    fn bool_tensor_handle(tensor: BoolTensor<Self>) -> Self::Handle {
        HandleKind::Bool(tensor)
    }

    fn quantized_tensor_handle(tensor: QuantizedTensor<Self>) -> Self::Handle {
        HandleKind::Quantized(tensor)
    }
}

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

    #[test]
    fn should_support_dtypes() {
        type B = NdArray;
        let device = NdArrayDevice::Cpu;
        let scheme = device.defaults().quantization.scheme;

        assert!(B::supports_dtype(&device, DType::F64));
        assert!(B::supports_dtype(&device, DType::F32));
        assert!(B::supports_dtype(&device, DType::Flex32));
        assert!(B::supports_dtype(&device, DType::I64));
        assert!(B::supports_dtype(&device, DType::I32));
        assert!(B::supports_dtype(&device, DType::I16));
        assert!(B::supports_dtype(&device, DType::I8));
        assert!(B::supports_dtype(&device, DType::U64));
        assert!(B::supports_dtype(&device, DType::U32));
        assert!(B::supports_dtype(&device, DType::U16));
        assert!(B::supports_dtype(&device, DType::U8));
        assert!(B::supports_dtype(&device, DType::Bool(BoolStore::Native)));
        assert!(B::supports_dtype(&device, DType::QFloat(scheme)));

        assert!(!B::supports_dtype(&device, DType::F16));
        assert!(!B::supports_dtype(&device, DType::BF16));
        // QuantStore::U32 not supported
        assert!(!B::supports_dtype(
            &device,
            DType::QFloat(QuantScheme::default())
        ));
    }

    /// A scheme this claims and then panics on is worse than one it declines, because the panic
    /// lands on the first tensor rather than where the scheme was chosen.
    #[test]
    fn should_support_the_two_level_schemes_it_can_quantize() {
        use burn_backend::ops::{FloatTensorOps, QTensorOps};
        use burn_std::{ScaleDtype, TensorData};

        type B = NdArray;
        let device = NdArrayDevice::Cpu;
        let scheme = device
            .defaults()
            .quantization
            .scheme
            .with_value(QuantValue::Q8S)
            .per_block([4], ScaleDtype::UE4M3)
            .per_tensor(ScaleDtype::F32);

        assert!(B::supports_dtype(&device, DType::QFloat(scheme)));

        let tensor = B::float_from_data(
            TensorData::from([0.1f32, -0.4, 0.2, 0.9, -1.5, 0.3, 0.05, -0.02]),
            &device,
        );
        let quantized = B::quantize_dynamic(tensor, &scheme);
        assert_eq!(quantized.scheme.num_levels(), 2);

        // Block scales already spanning f32's range are rejected by `quantize`.
        assert!(!B::supports_dtype(
            &device,
            DType::QFloat(scheme.per_block([4], ScaleDtype::F32))
        ));
    }
}