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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
// SPDX-License-Identifier: AGPL-3.0-or-later
//! `KmdGroupingF64` — Kendrick Mass Defect homologue grouping (f64)
//!
//! Computes `[KM, NKM, KMD]` per ion. Ions with matching NKM and KMD within
//! a tolerance window belong to the same homologous series.
//!
//! Reference: Kendrick (1963), J. Am. Chem. Soc.
//! PFAS-specific application: CF₂ repeat unit (49.9969 Da → nominal 50).
//!
//! `WetSpring` Exp018: 259 Jones Lab PFAS ions grouped by CH₂ / CF₂ homology.
use crate::device::WgpuDevice;
use crate::device::capabilities::WORKGROUP_SIZE_1D;
use crate::error::Result;
use bytemuck::{Pod, Zeroable};
use std::sync::Arc;
#[repr(C)]
#[derive(Copy, Clone, Pod, Zeroable)]
struct KmdConfig {
n_ions: u32,
_pad: u32,
exact_unit: f64,
nominal_unit: f64,
}
/// GPU-accelerated Kendrick Mass Defect calculation.
///
/// # Common repeat units
/// | Series | Exact mass | Nominal |
/// |--------|-----------|---------|
/// | CH₂ | 14.01565 | 14 |
/// | CF₂ | 49.9969 | 50 |
/// | C₂H₄ | 28.0313 | 28 |
pub struct KmdGroupingF64 {
device: Arc<WgpuDevice>,
/// Exact monoisotopic mass of the repeat unit.
pub exact_unit: f64,
/// Nominal (integer) mass of the repeat unit.
pub nominal_unit: f64,
}
/// Per-ion KMD result.
#[derive(Debug, Clone, Copy)]
pub struct KmdResult {
/// Kendrick mass: m × (nominal/exact)
pub km: f64,
/// Nominal Kendrick mass: round(KM)
pub nkm: f64,
/// Kendrick mass defect: NKM − KM
pub kmd: f64,
}
/// Common repeat units for PFAS and other homologous series.
pub mod repeat_units {
/// CH₂ (methylene) — general hydrocarbon series
pub const CH2: (f64, f64) = (14.01565, 14.0);
/// CF₂ (difluoromethylene) — PFAS backbone repeat unit
pub const CF2: (f64, f64) = (49.9969, 50.0);
/// C₂H₄ (ethylene) — polyethylene, surfactants
pub const C2H4: (f64, f64) = (28.0313, 28.0);
}
impl KmdGroupingF64 {
fn wgsl_shader() -> &'static str {
include_str!("../shaders/bio/kmd_grouping_f64.wgsl")
}
/// Create a KMD calculator for the given repeat unit.
///
/// Use `repeat_units::CF2` for PFAS, `repeat_units::CH2` for hydrocarbons.
#[must_use]
pub fn new(device: Arc<WgpuDevice>, exact_unit: f64, nominal_unit: f64) -> Self {
Self {
device,
exact_unit,
nominal_unit,
}
}
/// Compute `[KM, NKM, KMD]` for each ion mass.
///
/// Returns one `KmdResult` per input mass.
///
/// # Errors
///
/// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
/// readback fails (e.g. device lost or out of memory).
pub fn compute(&self, masses: &[f64]) -> Result<Vec<KmdResult>> {
let n = masses.len();
if n == 0 {
return Ok(Vec::new());
}
let dev = &self.device;
let cfg = KmdConfig {
n_ions: n as u32,
_pad: 0,
exact_unit: self.exact_unit,
nominal_unit: self.nominal_unit,
};
let cfg_buf = dev
.device
.create_buffer_init(&wgpu::util::BufferInitDescriptor {
label: Some("KMD Config"),
contents: bytemuck::bytes_of(&cfg),
usage: wgpu::BufferUsages::UNIFORM,
});
let mass_buf = dev
.device
.create_buffer_init(&wgpu::util::BufferInitDescriptor {
label: Some("KMD Masses"),
contents: bytemuck::cast_slice(masses),
usage: wgpu::BufferUsages::STORAGE,
});
let out_buf = dev.device.create_buffer(&wgpu::BufferDescriptor {
label: Some("KMD Output"),
size: (n * 3 * std::mem::size_of::<f64>()) as u64,
usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
mapped_at_creation: false,
});
let bgl = dev
.device
.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("KMD BGL"),
entries: &[
bgl_entry(0, wgpu::BufferBindingType::Uniform),
bgl_entry(1, wgpu::BufferBindingType::Storage { read_only: true }),
bgl_entry(2, wgpu::BufferBindingType::Storage { read_only: false }),
],
});
let bg = dev.device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("KMD BG"),
layout: &bgl,
entries: &[
wgpu::BindGroupEntry {
binding: 0,
resource: cfg_buf.as_entire_binding(),
},
wgpu::BindGroupEntry {
binding: 1,
resource: mass_buf.as_entire_binding(),
},
wgpu::BindGroupEntry {
binding: 2,
resource: out_buf.as_entire_binding(),
},
],
});
let shader = dev.compile_shader_f64(Self::wgsl_shader(), Some("KmdGrouping"));
let pl = dev
.device
.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
label: Some("KMD PL"),
bind_group_layouts: &[&bgl],
immediate_size: 0,
});
let pipeline = dev
.device
.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
label: Some("KMD Pipeline"),
layout: Some(&pl),
module: &shader,
entry_point: Some("main"),
cache: None,
compilation_options: Default::default(),
});
let mut encoder = dev.create_encoder_guarded(&wgpu::CommandEncoderDescriptor {
label: Some("KMD Encoder"),
});
{
let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
label: Some("KMD Pass"),
timestamp_writes: None,
});
pass.set_pipeline(&pipeline);
pass.set_bind_group(0, Some(&bg), &[]);
pass.dispatch_workgroups((n as u32).div_ceil(WORKGROUP_SIZE_1D), 1, 1);
}
dev.submit_commands(Some(encoder.finish()));
let raw = crate::utils::read_buffer_f64(dev, &out_buf, n * 3)?;
Ok(raw
.chunks_exact(3)
.map(|c| KmdResult {
km: c[0],
nkm: c[1],
kmd: c[2],
})
.collect())
}
/// Group ions by homologous series.
///
/// Two ions belong to the same series if `|KMD_i − KMD_j| < kmd_tol`.
/// Returns a `Vec<usize>` of group IDs (0-indexed, CPU post-pass).
///
/// # Errors
///
/// Returns [`Err`] if buffer allocation, GPU dispatch, or buffer
/// readback fails (e.g. device lost or out of memory).
pub fn group(&self, masses: &[f64], kmd_tol: f64) -> Result<Vec<usize>> {
let kmd_results = self.compute(masses)?;
let n = kmd_results.len();
let mut groups = vec![usize::MAX; n];
let mut next_group = 0usize;
for i in 0..n {
if groups[i] != usize::MAX {
continue;
}
groups[i] = next_group;
for j in (i + 1)..n {
if (kmd_results[i].kmd - kmd_results[j].kmd).abs() < kmd_tol {
groups[j] = next_group;
}
}
next_group += 1;
}
Ok(groups)
}
}
fn bgl_entry(idx: u32, ty: wgpu::BufferBindingType) -> wgpu::BindGroupLayoutEntry {
wgpu::BindGroupLayoutEntry {
binding: idx,
visibility: wgpu::ShaderStages::COMPUTE,
ty: wgpu::BindingType::Buffer {
ty,
has_dynamic_offset: false,
min_binding_size: None,
},
count: None,
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::device::test_pool::get_test_device_if_f64_gpu_available;
#[tokio::test]
async fn test_kmd_ch2_series() {
let Some(device) = get_test_device_if_f64_gpu_available().await else {
return;
};
// Simple alkane homologues: CH4 (16.0313), C2H6 (30.0469), C3H8 (44.0626)
// These differ by CH2 (14.01565), so should have matching KMDs.
let (exact, nominal) = repeat_units::CH2;
let kmd = KmdGroupingF64::new(device, exact, nominal);
let masses = vec![16.0313_f64, 30.0469, 44.0626];
let results = kmd.compute(&masses).unwrap();
// KMDs should be within ~0.001 Da of each other for a true homologous series
let kmd_0 = results[0].kmd;
let kmd_1 = results[1].kmd;
let kmd_2 = results[2].kmd;
assert!(
(kmd_0 - kmd_1).abs() < 0.01,
"CH2 homologues should have similar KMD: {kmd_0:.4} vs {kmd_1:.4}"
);
assert!(
(kmd_1 - kmd_2).abs() < 0.01,
"CH2 homologues should have similar KMD: {kmd_1:.4} vs {kmd_2:.4}"
);
}
#[tokio::test]
async fn test_kmd_nkm_is_round() {
let Some(device) = get_test_device_if_f64_gpu_available().await else {
return;
};
let (exact, nominal) = repeat_units::CF2;
let kmd = KmdGroupingF64::new(device, exact, nominal);
let masses = vec![499.9_f64, 549.8, 599.7];
let results = kmd.compute(&masses).unwrap();
for r in &results {
let diff = (r.nkm - r.nkm.round()).abs();
assert!(diff < 1e-9, "NKM should be an integer, got {}", r.nkm);
assert!((r.nkm - r.km - r.kmd).abs() < 1e-9, "NKM = KM + KMD");
}
}
}