1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
// 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(¶ms);
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, ¶ms_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]);
}
}