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
//! Variance/Std Reduction (f64) — GPU-Accelerated via WGSL
//!
//! Computes variance and standard deviation of f64 arrays using
//! Welford's numerically stable online algorithm.
//!
//! **Use cases**:
//! - Statistical analysis
//! - Error estimation (standard error)
//! - Convergence metrics
//! - Scientific measurements
//!
//! **Deep Debt Principles**:
//! - Pure WGSL implementation (hardware-agnostic)
//! - Full f64 precision via SPIR-V/Vulkan
//! - Numerically stable (Welford's algorithm)
//! - Safe Rust wrapper (no unsafe code)

use crate::device::WgpuDevice;
use crate::device::capabilities::WORKGROUP_SIZE_1D;
use crate::device::capabilities::{DeviceCapabilities, Fp64Strategy};
use crate::device::compute_pipeline::ComputeDispatch;
use crate::error::Result;
use bytemuck::{Pod, Zeroable};
use std::sync::Arc;

/// Parameters for reduce shader
#[repr(C)]
#[derive(Copy, Clone, Pod, Zeroable)]
struct ReduceParams {
    size: u32,
    _pad1: u32,
    _pad2: u32,
    _pad3: u32,
}

/// Welford state for parallel merging
#[derive(Clone, Copy, Debug)]
struct WelfordState {
    count: f64,
    mean: f64,
    m2: f64,
}

impl WelfordState {
    fn merge(self, other: Self) -> Self {
        let count = self.count + other.count;
        if count == 0.0 {
            return Self {
                count: 0.0,
                mean: 0.0,
                m2: 0.0,
            };
        }
        let delta = other.mean - self.mean;
        let mean = self.mean + delta * other.count / count;
        let m2 = self.m2 + other.m2 + delta * delta * self.count * other.count / count;
        Self { count, mean, m2 }
    }
}

/// Native f64 variance-reduce shader (workgroup shared memory uses f64).
const SHADER_NATIVE: &str = include_str!("../shaders/reduce/variance_reduce_f64.wgsl");
/// DF64 variance-reduce shader (workgroup shared memory uses f32 pairs).
/// Compiled via `compile_shader_df64` which prepends the DF64 core preamble.
const SHADER_DF64: &str = include_str!("../shaders/reduce/variance_reduce_df64.wgsl");

/// Select the variance-reduce shader and compilation mode based on the device's FP64 strategy.
///
/// Native/Concurrent/Sovereign: native f64 workgroup memory is reliable → `.f64()`.
/// Hybrid: f64 shared memory returns zeros on some devices → DF64 source + `.df64()`.
fn shader_config_for_device(device: &WgpuDevice) -> (&'static str, bool) {
    let caps = DeviceCapabilities::from_device(device);
    match caps.fp64_strategy() {
        Fp64Strategy::Sovereign | Fp64Strategy::Native | Fp64Strategy::Concurrent => {
            (SHADER_NATIVE, false)
        }
        Fp64Strategy::Hybrid => (SHADER_DF64, true),
    }
}

/// GPU-accelerated f64 variance/std operations
pub struct VarianceReduceF64;

impl VarianceReduceF64 {
    /// Compute sample variance: Var(X) = sum((x - mean)^2) / (n - 1)
    /// Uses Bessel's correction (n-1 denominator) for unbiased estimation.
    /// # Errors
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or readback fails
    /// (e.g. device lost, out of memory, buffer mapping channel closed).
    pub fn variance(device: Arc<WgpuDevice>, data: &[f64]) -> Result<f64> {
        let state = Self::compute_welford_state(device, data)?;
        if state.count < 2.0 {
            return Ok(0.0);
        }
        Ok(state.m2 / (state.count - 1.0))
    }

    /// Compute population variance: Var(X) = sum((x - mean)^2) / n
    /// # Errors
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or readback fails
    /// (e.g. device lost, out of memory, buffer mapping channel closed).
    pub fn population_variance(device: Arc<WgpuDevice>, data: &[f64]) -> Result<f64> {
        let state = Self::compute_welford_state(device, data)?;
        if state.count < 1.0 {
            return Ok(0.0);
        }
        Ok(state.m2 / state.count)
    }

    /// Compute sample standard deviation: sqrt(variance)
    /// # Errors
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or readback fails
    /// (e.g. device lost, out of memory, buffer mapping channel closed).
    pub fn std(device: Arc<WgpuDevice>, data: &[f64]) -> Result<f64> {
        let var = Self::variance(device, data)?;
        Ok(var.sqrt())
    }

    /// Compute population standard deviation
    /// # Errors
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or readback fails
    /// (e.g. device lost, out of memory, buffer mapping channel closed).
    pub fn population_std(device: Arc<WgpuDevice>, data: &[f64]) -> Result<f64> {
        let var = Self::population_variance(device, data)?;
        Ok(var.sqrt())
    }

    /// Compute mean using Welford state (bonus: numerically stable)
    /// # Errors
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or readback fails
    /// (e.g. device lost, out of memory, buffer mapping channel closed).
    pub fn mean(device: Arc<WgpuDevice>, data: &[f64]) -> Result<f64> {
        let state = Self::compute_welford_state(device, data)?;
        Ok(state.mean)
    }

    /// Compute both mean and variance in one pass
    /// # Errors
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or readback fails
    /// (e.g. device lost, out of memory, buffer mapping channel closed).
    pub fn mean_and_variance(device: Arc<WgpuDevice>, data: &[f64]) -> Result<(f64, f64)> {
        let state = Self::compute_welford_state(device, data)?;
        let var = if state.count < 2.0 {
            0.0
        } else {
            state.m2 / (state.count - 1.0)
        };
        Ok((state.mean, var))
    }

    /// Compute all statistics: (count, mean, variance, std)
    /// # Errors
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or readback fails
    /// (e.g. device lost, out of memory, buffer mapping channel closed).
    pub fn statistics(device: Arc<WgpuDevice>, data: &[f64]) -> Result<(usize, f64, f64, f64)> {
        let state = Self::compute_welford_state(device, data)?;
        let var = if state.count < 2.0 {
            0.0
        } else {
            state.m2 / (state.count - 1.0)
        };
        Ok((state.count as usize, state.mean, var, var.sqrt()))
    }

    fn compute_welford_state(device: Arc<WgpuDevice>, data: &[f64]) -> Result<WelfordState> {
        if data.is_empty() {
            return Ok(WelfordState {
                count: 0.0,
                mean: 0.0,
                m2: 0.0,
            });
        }
        if data.len() == 1 {
            return Ok(WelfordState {
                count: 1.0,
                mean: data[0],
                m2: 0.0,
            });
        }

        let (shader_src, use_df64) = shader_config_for_device(&device);

        let n = data.len();
        let wg_size = WORKGROUP_SIZE_1D as usize;
        let n_workgroups = n.div_ceil(wg_size);

        let input_bytes: &[u8] = bytemuck::cast_slice(data);
        let input_buffer = device
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("VarianceReduce input"),
                contents: input_bytes,
                usage: wgpu::BufferUsages::STORAGE,
            });

        let partial_buffer = device.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("VarianceReduce partials"),
            size: (n_workgroups * 3 * 8) as u64,
            usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
            mapped_at_creation: false,
        });

        let params = ReduceParams {
            size: n as u32,
            _pad1: 0,
            _pad2: 0,
            _pad3: 0,
        };
        let params_buffer = device.create_uniform_buffer("VarianceReduce params", &params);

        let mut dispatch = ComputeDispatch::new(&device, "variance_reduce_f64")
            .shader(shader_src, "variance_reduce_f64")
            .storage_read(0, &input_buffer)
            .storage_rw(1, &partial_buffer)
            .uniform(2, &params_buffer)
            .dispatch(n_workgroups as u32, 1, 1);
        dispatch = if use_df64 {
            dispatch.df64()
        } else {
            dispatch.f64()
        };
        dispatch.submit()?;

        let partials = device.read_f64_buffer(&partial_buffer, n_workgroups * 3)?;

        let mut final_state = WelfordState {
            count: 0.0,
            mean: 0.0,
            m2: 0.0,
        };
        for chunk in partials.chunks_exact(3) {
            let state = WelfordState {
                count: chunk[0],
                mean: chunk[1],
                m2: chunk[2],
            };
            final_state = final_state.merge(state);
        }

        Ok(final_state)
    }
}

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

    #[tokio::test]
    async fn test_variance_simple() {
        let Some(device) = crate::device::test_pool::get_test_device_if_f64_gpu_available().await
        else {
            return;
        };

        let data: Vec<f64> = vec![2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0];
        let var = VarianceReduceF64::variance(device, &data).unwrap();
        // Expected sample variance: 4.571...
        let expected = 4.571428571428571;
        assert!(
            (var - expected).abs() < 1e-6,
            "Variance should be ~{expected}, got {var}"
        );
    }

    #[tokio::test]
    async fn test_std_simple() {
        let Some(device) = crate::device::test_pool::get_test_device_if_f64_gpu_available().await
        else {
            return;
        };

        let data: Vec<f64> = vec![2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0];
        let std = VarianceReduceF64::std(device, &data).unwrap();
        let expected = 4.571428571428571_f64.sqrt();
        assert!(
            (std - expected).abs() < 1e-6,
            "Std should be ~{expected}, got {std}"
        );
    }

    #[tokio::test]
    async fn test_mean() {
        let Some(device) = crate::device::test_pool::get_test_device_if_f64_gpu_available().await
        else {
            return;
        };

        let data: Vec<f64> = vec![1.0, 2.0, 3.0, 4.0, 5.0];
        let mean = VarianceReduceF64::mean(device, &data).unwrap();
        assert!((mean - 3.0).abs() < 1e-6, "Mean should be 3, got {mean}");
    }

    #[tokio::test]
    async fn test_population_vs_sample_variance() {
        let Some(device) = crate::device::test_pool::get_test_device_if_f64_gpu_available().await
        else {
            return;
        };

        let data: Vec<f64> = vec![1.0, 2.0, 3.0, 4.0, 5.0];
        let sample_var = VarianceReduceF64::variance(device.clone(), &data).unwrap();
        let pop_var = VarianceReduceF64::population_variance(device, &data).unwrap();

        // Population variance uses n, sample uses n-1
        // So sample_var * (n-1) / n = pop_var
        let n = data.len() as f64;
        let expected_ratio = (n - 1.0) / n;
        let actual_ratio = pop_var / sample_var;
        assert!(
            (actual_ratio - expected_ratio).abs() < 1e-6,
            "Variance ratio should be (n-1)/n, got {actual_ratio}"
        );
    }

    #[tokio::test]
    async fn test_statistics() {
        let Some(device) = crate::device::test_pool::get_test_device_if_f64_gpu_available().await
        else {
            return;
        };

        let data: Vec<f64> = (1..=100).map(|x| x as f64).collect();
        let (count, mean, var, std) = VarianceReduceF64::statistics(device, &data).unwrap();

        assert_eq!(count, 100);
        assert!((mean - 50.5).abs() < 1e-6);
        // Sample variance of 1..100: 841.666...
        assert!((var - 841.6666666666666).abs() < 1e-3);
        assert!((std - var.sqrt()).abs() < 1e-6);
    }
}