primal-barracuda 0.4.0

barraCuda — BARrier-free Rust Abstracted Cross-platform Unified Dimensional Algebra. Vendor-agnostic GPU compute via WGSL.
Documentation
// SPDX-License-Identifier: AGPL-3.0-or-later
//! GPU-accelerated histogram via atomic binning.

#[cfg(feature = "gpu")]
use crate::device::WgpuDevice;
#[cfg(feature = "gpu")]
use crate::device::capabilities::WORKGROUP_SIZE_1D;
#[cfg(feature = "gpu")]
use crate::device::compute_pipeline::ComputeDispatch;
#[cfg(feature = "gpu")]
use crate::error::{BarracudaError, Result};
#[cfg(feature = "gpu")]
use bytemuck::{Pod, Zeroable};
#[cfg(feature = "gpu")]
use std::sync::Arc;

#[cfg(feature = "gpu")]
#[repr(C)]
#[derive(Copy, Clone, Pod, Zeroable)]
struct HistogramParamsF64 {
    n_values: u32,
    n_bins: u32,
    min_val: f64,
    inv_bin_width: f64,
}

#[cfg(feature = "gpu")]
#[repr(C)]
#[derive(Copy, Clone, Pod, Zeroable)]
struct HistogramParamsF32 {
    n_values: u32,
    n_bins: u32,
    min_val: f32,
    inv_bin_width: f32,
}

/// GPU-accelerated histogram via atomic binning.
#[cfg(feature = "gpu")]
pub struct HistogramGpu {
    device: Arc<WgpuDevice>,
}

#[cfg(feature = "gpu")]
impl HistogramGpu {
    /// Creates a new GPU-accelerated histogram from a WGPU device.
    ///
    /// # Errors
    ///
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
    /// readback fails (e.g. device lost or out of memory).
    pub fn new(device: Arc<WgpuDevice>) -> Result<Self> {
        Ok(Self { device })
    }

    /// Dispatch GPU histogram: bin `values` into `n_bins` bins over [min, max].
    ///
    /// # Errors
    ///
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
    /// readback fails (e.g. device lost or out of memory).
    pub fn dispatch(&self, values: &[f64], n_bins: u32) -> Result<Vec<u32>> {
        let n_values = values.len();
        if n_values == 0 {
            return Err(BarracudaError::InvalidInput {
                message: "values cannot be empty".to_string(),
            });
        }
        if n_bins == 0 {
            return Err(BarracudaError::InvalidInput {
                message: "n_bins must be > 0".to_string(),
            });
        }

        let (min_val, max_val) = values
            .iter()
            .fold((f64::INFINITY, f64::NEG_INFINITY), |(min, max), &v| {
                (min.min(v), max.max(v))
            });

        let range = max_val - min_val;
        let inv_bin_width = if range > 0.0 && range.is_finite() {
            n_bins as f64 / range
        } else {
            // Constant data or degenerate range: put everything in bin 0
            0.0
        };

        let bins_buf = self.device.create_buffer_u32_zeros(n_bins as usize)?;

        if self.device.has_f64_shaders() {
            self.dispatch_f64(values, n_bins, min_val, inv_bin_width, &bins_buf)
        } else {
            self.dispatch_f32(values, n_bins, min_val, inv_bin_width, &bins_buf)
        }
    }

    fn dispatch_f64(
        &self,
        values: &[f64],
        n_bins: u32,
        min_val: f64,
        inv_bin_width: f64,
        bins_buf: &wgpu::Buffer,
    ) -> Result<Vec<u32>> {
        let n_values = values.len() as u32;

        let params = HistogramParamsF64 {
            n_values,
            n_bins,
            min_val,
            inv_bin_width,
        };
        let params_buf = self
            .device
            .create_uniform_buffer("histogram:params", &params);

        let values_buf = self
            .device
            .create_buffer_f64_init("histogram:values", values);

        let wg_count = n_values.div_ceil(WORKGROUP_SIZE_1D);
        ComputeDispatch::new(&self.device, "histogram")
            .shader(super::WGSL_HISTOGRAM_F64, "histogram")
            .f64()
            .storage_read(0, &values_buf)
            .storage_rw(1, bins_buf)
            .uniform(2, &params_buf)
            .dispatch(wg_count, 1, 1)
            .submit()?;

        self.device.read_buffer_u32(bins_buf, n_bins as usize)
    }

    fn dispatch_f32(
        &self,
        values: &[f64],
        n_bins: u32,
        min_val: f64,
        inv_bin_width: f64,
        bins_buf: &wgpu::Buffer,
    ) -> Result<Vec<u32>> {
        let n_values = values.len() as u32;

        let values_f32: Vec<f32> = values.iter().map(|&v| v as f32).collect();

        let params = HistogramParamsF32 {
            n_values,
            n_bins,
            min_val: min_val as f32,
            inv_bin_width: inv_bin_width as f32,
        };
        let params_buf = self
            .device
            .create_uniform_buffer("histogram:params", &params);

        let values_buf = self
            .device
            .create_buffer_f32_init("histogram:values", &values_f32);

        let wg_count = n_values.div_ceil(WORKGROUP_SIZE_1D);
        ComputeDispatch::new(&self.device, "histogram_f32")
            .shader(super::WGSL_HISTOGRAM_F32.as_str(), "histogram")
            .storage_read(0, &values_buf)
            .storage_rw(1, bins_buf)
            .uniform(2, &params_buf)
            .dispatch(wg_count, 1, 1)
            .submit()?;

        self.device.read_buffer_u32(bins_buf, n_bins as usize)
    }
}

#[cfg(all(test, feature = "gpu"))]
mod tests {
    #![expect(clippy::unwrap_used, reason = "tests")]

    use super::*;
    use crate::device::test_pool::test_prelude::test_f64_device;
    use std::sync::Arc;

    async fn get_device() -> Option<Arc<WgpuDevice>> {
        // dispatch() selects f64 path on f64-capable devices, so require a
        // device that passes the f64 computation probe.
        test_f64_device().await
    }

    #[tokio::test]
    async fn test_histogram_uniform() {
        let Some(device) = get_device().await else {
            return;
        };
        let hist = HistogramGpu::new(device).unwrap();
        let n_bins = 10u32;
        // Uniform data in [0, 1) — each bin should get ~10% of values
        let values: Vec<f64> = (0..1000).map(|i| i as f64 / 1000.0).collect();
        let bins = hist.dispatch(&values, n_bins).unwrap();
        assert_eq!(bins.len(), n_bins as usize);
        let total: u32 = bins.iter().sum();
        assert_eq!(total, 1000);
        // Each bin should have roughly 100 (allow 50–150 for tolerance)
        for (i, &count) in bins.iter().enumerate() {
            assert!(
                (50..=150).contains(&count),
                "Bin {i}: count {count} should be roughly 100 for uniform data"
            );
        }
    }

    #[tokio::test]
    async fn test_histogram_single_bin() {
        let Some(device) = get_device().await else {
            return;
        };
        let hist = HistogramGpu::new(device).unwrap();
        let n_bins = 5u32;
        // All same value — everything in one bin
        let values = vec![std::f64::consts::PI; 100];
        let bins = hist.dispatch(&values, n_bins).unwrap();
        assert_eq!(bins.len(), n_bins as usize);
        let total: u32 = bins.iter().sum();
        assert_eq!(total, 100);
        // Exactly one bin should have count 100
        let non_zero: Vec<_> = bins.iter().enumerate().filter(|(_, c)| **c > 0).collect();
        assert_eq!(non_zero.len(), 1);
        assert_eq!(*non_zero[0].1, 100);
    }

    #[tokio::test]
    async fn test_histogram_empty_error() {
        let Some(device) = get_device().await else {
            return;
        };
        let hist = HistogramGpu::new(device).unwrap();
        let values: Vec<f64> = vec![];
        let result = hist.dispatch(&values, 10);
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn test_histogram_zero_bins_error() {
        let Some(device) = get_device().await else {
            return;
        };
        let hist = HistogramGpu::new(device).unwrap();
        let values = vec![1.0, 2.0, 3.0];
        let result = hist.dispatch(&values, 0);
        assert!(result.is_err());
    }
}