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
//! Yukawa Force (f64) with PBC + Potential Energy
//!
//! **Physics**: Screened Coulomb with f64 precision, validated against Sarkas
//! **Algorithm**: All-pairs O(N²) with PBC minimum-image convention
//! **Precision**: Full f64 via `math_f64.wgsl` preamble
//!
//! **hotSpring Validation**: 9/9 Yukawa OCP cases pass (0.000% energy drift)
//!
//! **Deep Debt Compliance**:
//! - ✅ Pure WGSL shader
//! - ✅ Zero unsafe code
//! - ✅ f64 precision

use crate::device::capabilities::{DeviceCapabilities, Fp64Strategy, WORKGROUP_SIZE_COMPACT};
use crate::device::compute_pipeline::ComputeDispatch;
use crate::error::{BarracudaError, Result};
use crate::tensor::Tensor;

const WGSL_DF64_CORE: &str = include_str!("../../../shaders/math/df64_core.wgsl");
const WGSL_DF64_TRANSCENDENTALS: &str =
    include_str!("../../../shaders/math/df64_transcendentals.wgsl");
const YUKAWA_SHADER_DF64: &str = include_str!("yukawa_df64.wgsl");

/// f64 Yukawa force with PBC minimum-image and potential energy accumulation
///
/// **Key differences from f32 version**:
/// - Full f64 precision via `math_f64.wgsl` preamble
/// - PBC minimum-image integrated into force loop
/// - Accumulates per-particle potential energy alongside force
/// - Force sign: repulsive (fx = fx - `force_mag` * dx * `inv_r`)
pub struct YukawaForceF64 {
    positions: Tensor,
    n_particles: usize,
    kappa: f64,
    prefactor: f64,
    cutoff: f64,
    box_side: f64,
    epsilon: f64,
}

impl YukawaForceF64 {
    /// Create a new f64 Yukawa force computation
    /// # Arguments
    /// * `positions` - Position tensor [N, 3] (f64)
    /// * `kappa` - Screening parameter (inverse Debye length)
    /// * `prefactor` - Force prefactor (1.0 in OCP reduced units)
    /// * `cutoff` - Cutoff radius (reduced units)
    /// * `box_side` - Simulation box side length (reduced units)
    /// * `epsilon` - Softening parameter (typically 0 or 1e-30)
    /// # Errors
    /// Returns error if positions tensor has wrong shape.
    pub fn new(
        positions: Tensor,
        kappa: f64,
        prefactor: f64,
        cutoff: f64,
        box_side: f64,
        epsilon: Option<f64>,
    ) -> Result<Self> {
        let shape = positions.shape();
        if shape.len() != 2 || shape[1] != 3 {
            return Err(BarracudaError::InvalidShape {
                expected: vec![0, 3],
                actual: shape.to_vec(),
            });
        }

        if kappa < 0.0 {
            return Err(BarracudaError::Device(
                "Screening parameter κ must be non-negative".to_string(),
            ));
        }

        Ok(Self {
            n_particles: shape[0],
            positions,
            kappa,
            prefactor,
            cutoff,
            box_side,
            epsilon: epsilon.unwrap_or(0.0),
        })
    }

    /// Execute the force computation
    /// # Returns
    /// A tuple of (forces [N, 3], `potential_energy` [N]) tensors
    ///
    /// # Errors
    ///
    /// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
    /// readback fails (e.g. device lost or out of memory).
    pub fn execute(self) -> Result<(Tensor, Tensor)> {
        let device = self.positions.device();
        let n = self.n_particles;

        // Output buffers for forces and PE (f64)
        let forces_size = (n * 3 * std::mem::size_of::<f64>()) as u64;
        let forces_buffer = device.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("Yukawa F64 Forces"),
            size: forces_size,
            usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
            mapped_at_creation: false,
        });

        let pe_size = (n * std::mem::size_of::<f64>()) as u64;
        let pe_buffer = device.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("Yukawa F64 PE"),
            size: pe_size,
            usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
            mapped_at_creation: false,
        });

        // Params buffer: [n, kappa, prefactor, cutoff_sq, box_x, box_y, box_z, epsilon]
        let params: Vec<f64> = vec![
            n as f64,
            self.kappa,
            self.prefactor,
            self.cutoff * self.cutoff,
            self.box_side,
            self.box_side,
            self.box_side,
            self.epsilon,
        ];
        let params_bytes: &[u8] = bytemuck::cast_slice(&params);
        let params_buffer = device
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("Yukawa F64 Params"),
                contents: params_bytes,
                usage: wgpu::BufferUsages::STORAGE,
            });

        let caps = DeviceCapabilities::from_device(device);
        let strategy = caps.fp64_strategy();
        tracing::info!(
            ?strategy,
            "YukawaForceF64: using {:?} FP64 strategy",
            strategy
        );
        let shader_src = match strategy {
            Fp64Strategy::Sovereign | Fp64Strategy::Native | Fp64Strategy::Concurrent => {
                include_str!("yukawa_f64.wgsl").to_string()
            }
            Fp64Strategy::Hybrid => {
                format!("{WGSL_DF64_CORE}\n{WGSL_DF64_TRANSCENDENTALS}\n{YUKAWA_SHADER_DF64}")
            }
        };

        let workgroups = (n as u32).div_ceil(WORKGROUP_SIZE_COMPACT);
        ComputeDispatch::new(device, "Yukawa F64")
            .shader(&shader_src, "main")
            .f64()
            .storage_read(0, self.positions.buffer())
            .storage_rw(1, &forces_buffer)
            .storage_rw(2, &pe_buffer)
            .storage_read(3, &params_buffer)
            .dispatch(workgroups, 1, 1)
            .submit()?;

        let forces = Tensor::from_buffer(forces_buffer, vec![n, 3], device.clone());
        let pe = Tensor::from_buffer(pe_buffer, vec![n], device.clone());

        Ok((forces, pe))
    }
}

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

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

        // Check for f64 support
        if !device
            .device
            .features()
            .contains(wgpu::Features::SHADER_F64)
        {
            return;
        }

        // Two particles at distance 1.0 in a box
        let positions: Vec<f64> = vec![0.0, 0.0, 0.0, 1.0, 0.0, 0.0];
        let n = 2;

        // Create position tensor (f64)
        let pos_bytes: &[u8] = bytemuck::cast_slice(&positions);
        let pos_buffer = device
            .device
            .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                label: Some("Test Positions"),
                contents: pos_bytes,
                usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
            });
        let pos_tensor = Tensor::from_buffer(pos_buffer, vec![n, 3], device);

        // κ=1, prefactor=1, cutoff=10, box=10
        let yukawa = YukawaForceF64::new(pos_tensor, 1.0, 1.0, 10.0, 10.0, None).unwrap();

        let (forces, pe) = yukawa.execute().unwrap();
        assert_eq!(forces.shape(), &[2, 3]);
        assert_eq!(pe.shape(), &[2]);
    }
}