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 Velocity Autocorrelation Function (VACF)
//!
//! **Physics**: C(τ) = <v(t) · v(t+τ)> / <v(0)·v(0)>
//!
//! The VACF reveals the frequency spectrum of particle motion and yields
//! the self-diffusion coefficient via the Green-Kubo relation:
//!   D* = (1/3) ∫_0^∞ C(τ) dτ
//!
//! **GPU implementation**: Each thread handles one (t0, lag) pair and
//! accumulates the N-particle dot-product in O(N) work.  Total compute
//! is O(T × L × N) — fully parallel over the T×L grid, vs the CPU
//! O(T²×N) sequential loop.
//!
//! **Performance**: For T=1000 frames, N=1000 particles, L=500 lags:
//! - CPU: ~500 M multiply-adds, ~2-10 s
//! - GPU: dispatches 500K threads, each ~1000 MADs — ~1-10 ms (100-1000× faster)
//!
//! **Deep Debt Compliance**:
//! - ✅ Pure WGSL shader (`vacf_f64.wgsl`)
//! - ✅ Full f64 precision throughout
//! - ✅ Zero unsafe code
//! - ✅ Capability-based: skips to CPU fallback when no GPU available

use crate::device::WgpuDevice;
use crate::device::capabilities::WORKGROUP_SIZE_2D;
use crate::error::Result;
use crate::ops::md::observables::{Vacf, compute_vacf};
use std::sync::Arc;

const VACF_SHADER: &str = include_str!("vacf_f64.wgsl");

/// GPU-accelerated VACF computation.
///
/// Construct once per device; call `compute()` for each trajectory batch.
pub struct VacfGpu {
    device: Arc<WgpuDevice>,
}

impl VacfGpu {
    /// Create a new `VacfGpu` for the given device.
    #[must_use]
    pub fn new(device: Arc<WgpuDevice>) -> Self {
        Self { device }
    }

    /// Compute the VACF from `vel_snapshots` on the GPU.
    ///
    /// # Arguments
    /// * `vel_snapshots` — velocity snapshots, each `[N × 3]` flattened (row-major)
    /// * `n`             — number of particles
    /// * `dt_dump`       — time between snapshots in reduced units
    /// * `max_lag`       — maximum lag in snapshot steps
    ///
    /// # Returns
    /// A `Vacf` struct with normalised C(τ) values and the diffusion coefficient.
    /// Falls back to the CPU implementation when `max_lag == 0` or there is only
    /// one snapshot.
    ///
    /// # Errors
    ///
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
    /// readback fails (e.g. device lost or out of memory).
    pub fn compute(
        &self,
        vel_snapshots: &[Vec<f64>],
        n: usize,
        dt_dump: f64,
        max_lag: usize,
    ) -> Result<Vacf> {
        let n_frames = vel_snapshots.len();
        let actual_lag = max_lag.min(n_frames.saturating_sub(1));
        if actual_lag == 0 || n_frames < 2 {
            // Degenerate case — delegate to CPU reference implementation
            return Ok(compute_vacf(vel_snapshots, n, dt_dump, actual_lag.max(1)));
        }

        let gpu_d = &self.device;

        // ── Pack velocity data (flatten all frames into one f64 array) ─────────
        let total_vels = n_frames * n * 3;
        let mut flat: Vec<f64> = Vec::with_capacity(total_vels);
        for frame in vel_snapshots {
            debug_assert_eq!(frame.len(), n * 3, "frame length must be N*3");
            flat.extend_from_slice(frame);
        }

        // ── Params buffer: array<u32>[4] = [n_particles, n_frames, max_lag, 0] ─
        let params_u32: [u32; 4] = [n_particles_u32(n), n_frames as u32, actual_lag as u32, 0];
        let params_buf = gpu_d
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("VACF Params"),
                contents: bytemuck::cast_slice(&params_u32),
                usage: wgpu::BufferUsages::STORAGE,
            });

        let vel_bytes: &[u8] = bytemuck::cast_slice(&flat);
        let vel_buf = gpu_d
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("VACF Velocities"),
                contents: vel_bytes,
                usage: wgpu::BufferUsages::STORAGE,
            });

        // ── Output buffer c_raw[T × L] initialised to 0.0 ─────────────────────
        let out_size = (n_frames * actual_lag) as u64 * 8; // 8 bytes per f64
        let c_raw_buf = gpu_d.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("VACF c_raw"),
            size: out_size.max(8),
            usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
            mapped_at_creation: false,
        });

        // ── Pipeline ────────────────────────────────────────────────────────────
        let module = gpu_d.compile_shader_f64(VACF_SHADER, Some("vacf_f64"));

        let bgl = gpu_d
            .device
            .create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("VACF BGL"),
                entries: &[
                    storage_bgl(0, true),
                    storage_bgl(1, true),
                    storage_bgl(2, false),
                ],
            });
        let pl_layout = gpu_d
            .device
            .create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
                label: Some("VACF PL"),
                bind_group_layouts: &[&bgl],
                immediate_size: 0,
            });
        let pipeline = gpu_d
            .device
            .create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
                label: Some("VACF Pipeline"),
                layout: Some(&pl_layout),
                module: &module,
                entry_point: Some("vacf_pair"),
                cache: None,
                compilation_options: Default::default(),
            });
        let bg = gpu_d.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("VACF BG"),
            layout: &bgl,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: params_buf.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: vel_buf.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 2,
                    resource: c_raw_buf.as_entire_binding(),
                },
            ],
        });

        // ── Dispatch: ceil(L/16) × ceil(T/16) workgroups ─────────────────────
        let wg_x = (actual_lag as u32).div_ceil(WORKGROUP_SIZE_2D);
        let wg_y = (n_frames as u32).div_ceil(WORKGROUP_SIZE_2D);

        let mut encoder = gpu_d.create_encoder_guarded(&wgpu::CommandEncoderDescriptor {
            label: Some("VACF"),
        });
        {
            let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor::default());
            pass.set_pipeline(&pipeline);
            pass.set_bind_group(0, Some(&bg), &[]);
            pass.dispatch_workgroups(wg_x, wg_y, 1);
        }
        gpu_d.submit_commands(Some(encoder.finish()));

        // ── Readback c_raw[T × L] ─────────────────────────────────────────────
        let c_raw_f64: Vec<f64> = gpu_d.read_buffer_f64(&c_raw_buf, n_frames * actual_lag)?;

        // ── Host post-processing: average over time origins ───────────────────
        let mut c_values = vec![0.0f64; actual_lag];
        let mut counts = vec![0usize; actual_lag];

        for t0 in 0..n_frames {
            for lag in 0..actual_lag {
                let t1 = t0 + lag;
                if t1 < n_frames {
                    c_values[lag] += c_raw_f64[t0 * actual_lag + lag];
                    counts[lag] += 1;
                }
            }
        }
        for i in 0..actual_lag {
            if counts[i] > 0 {
                c_values[i] /= counts[i] as f64;
            }
        }

        // Normalise by C(0)
        let c0 = c_values.first().copied().unwrap_or(1.0).max(1e-30);
        let c_norm: Vec<f64> = c_values.iter().map(|&c| c / c0).collect();

        // Green-Kubo integral: D* = (1/3) ∫ C(τ) dτ  (trapezoidal)
        let mut integral = 0.0f64;
        for i in 1..actual_lag {
            integral = (0.5 * (c_values[i - 1] + c_values[i])).mul_add(dt_dump, integral);
        }

        let t_values: Vec<f64> = (0..actual_lag).map(|i| i as f64 * dt_dump).collect();

        Ok(Vacf {
            t_values,
            c_values: c_norm,
            diffusion_coeff: integral / 3.0,
        })
    }
}

fn n_particles_u32(n: usize) -> u32 {
    debug_assert!(u32::try_from(n).is_ok(), "n_particles must fit in u32");
    n as u32
}

fn storage_bgl(binding: u32, read_only: bool) -> wgpu::BindGroupLayoutEntry {
    wgpu::BindGroupLayoutEntry {
        binding,
        visibility: wgpu::ShaderStages::COMPUTE,
        ty: wgpu::BindingType::Buffer {
            ty: wgpu::BufferBindingType::Storage { read_only },
            has_dynamic_offset: false,
            min_binding_size: None,
        },
        count: None,
    }
}

// ─── Tests ────────────────────────────────────────────────────────────────────

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

    /// Generate a simple velocity trajectory: constant unit velocities.
    fn constant_vels(n: usize, n_frames: usize) -> Vec<Vec<f64>> {
        (0..n_frames)
            .map(|_| (0..n).flat_map(|_| [1.0_f64, 0.0, 0.0]).collect())
            .collect()
    }

    #[test]
    fn test_vacf_gpu_constant_velocities() {
        let Some(device) = test_pool::get_test_device_if_f64_gpu_available_sync() else {
            return;
        };
        let gpu = VacfGpu::new(device);
        let n = 10;
        let n_frames = 20;
        let max_lag = 10;
        let dt = 0.01;
        let vels = constant_vels(n, n_frames);

        let vacf = gpu.compute(&vels, n, dt, max_lag).unwrap();

        // With constant velocities v=(1,0,0) every frame, C(lag)=1 for all lags
        assert_eq!(vacf.c_values.len(), max_lag);
        for (i, &c) in vacf.c_values.iter().enumerate() {
            assert!(
                (c - 1.0).abs() < 1e-10,
                "C({i}) = {c}, expected 1.0 for constant velocity"
            );
        }
    }

    #[test]
    fn test_vacf_gpu_matches_cpu() {
        let Some(device) = test_pool::get_test_device_if_f64_gpu_available_sync() else {
            return;
        };
        let gpu = VacfGpu::new(device);

        // Decaying sinusoidal velocity trajectory
        let n = 8;
        let n_frames = 32;
        let dt = 0.05;
        let max_lag = 15;
        let vels: Vec<Vec<f64>> = (0..n_frames)
            .map(|t| {
                let phase = t as f64 * 0.3;
                (0..n)
                    .flat_map(|_| {
                        let v = phase.cos() * (-0.05 * t as f64).exp();
                        [v, 0.0, 0.0]
                    })
                    .collect()
            })
            .collect();

        let gpu_vacf = gpu.compute(&vels, n, dt, max_lag).unwrap();
        let cpu_vacf = compute_vacf(&vels, n, dt, max_lag);

        assert_eq!(gpu_vacf.c_values.len(), cpu_vacf.c_values.len());
        for (i, (&gv, &cv)) in gpu_vacf
            .c_values
            .iter()
            .zip(cpu_vacf.c_values.iter())
            .enumerate()
        {
            assert!(
                (gv - cv).abs() < 1e-8,
                "C({i}) GPU={gv} CPU={cv} diff={}",
                (gv - cv).abs()
            );
        }
        assert!((gpu_vacf.diffusion_coeff - cpu_vacf.diffusion_coeff).abs() < 1e-9);
    }
}