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
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
// SPDX-License-Identifier: AGPL-3.0-or-later
//! `BatchedRK4F64` — General-purpose N-trajectory RK4/RK45 orchestration.
//!
//! Wraps [`RkIntegrator`] to run N independent ODE instances in parallel,
//! each with its own `f(t, y) → dy/dt` closure (parameters baked in via closure).
//!
//! ## When to use
//! - Parameter sweeps: N ODE instances with different rate constants
//! - Monte Carlo: N independent trajectories from different initial conditions
//! - Ensemble integration: uncertainty quantification over N parameter draws
//!
//! ## When NOT to use
//! - Fixed structured ODE across batches → `BatchedOdeRK4F64` (full-GPU, zero CPU callback)
//!
//! ## Design
//! - CPU orchestration: `std::thread::scope` — one thread per instance
//! - GPU state updates: each `RkIntegrator` dispatches GPU compute for D ≥ 128
//! - For D < 128 each integrator falls back to pure-CPU (no device saturation needed)
//! - Zero `unsafe` code; thread safety via `Fn + Send + Sync` bound on closures
//!
//! Resolves D-S21-001 from DEBT.md (Feb 2026 wetSpring handoff).
use crate::device::WgpuDevice;
use crate::error::{BarracudaError, Result};
use crate::ops::rk_stage::RkIntegrator;
use std::sync::Arc;
/// Type alias for ODE right-hand-side functions: `f(t, y) -> dy/dt`.
///
/// Must be `Send + Sync` for parallel trajectory integration.
pub type OdeFn = Box<dyn Fn(f64, &[f64]) -> Vec<f64> + Send + Sync>;
// ─── Result type ─────────────────────────────────────────────────────────────
/// Integration result for one trajectory in a batched run.
#[derive(Debug, Clone)]
pub struct TrajectoryResult {
/// Time points at which state was recorded.
pub times: Vec<f64>,
/// State snapshots; `states[i]` corresponds to `times[i]`.
pub states: Vec<Vec<f64>>,
/// Zero-based index of this instance within the batch.
pub instance: usize,
}
impl TrajectoryResult {
/// Final state vector (last element of `states`).
pub fn final_state(&self) -> &[f64] {
self.states.last().map(Vec::as_slice).unwrap_or_default()
}
/// Final time reached.
#[must_use]
pub fn final_time(&self) -> f64 {
self.times.last().copied().unwrap_or(0.0)
}
}
// ─── Main orchestrator ───────────────────────────────────────────────────────
/// N-trajectory RK4/RK45 orchestrator.
///
/// # Example — three exponential decays with different rates
///
/// ```rust,ignore
/// # use barracuda::prelude::WgpuDevice;
/// # use barracuda::ops::batched_rk4_sweep::BatchedRK4F64;
/// # crate::device::test_pool::tokio_block_on(async {
/// let device = WgpuDevice::new().await.unwrap();
/// let batcher = BatchedRK4F64::new(&device);
///
/// let rates = [0.5_f64, 1.0, 2.0];
/// let odes: Vec<Box<dyn Fn(f64, &[f64]) -> Vec<f64> + Send + Sync>> = rates
/// .iter()
/// .map(|&k| -> Box<dyn Fn(f64, &[f64]) -> Vec<f64> + Send + Sync> {
/// Box::new(move |_t, y| vec![-k * y[0]])
/// })
/// .collect();
///
/// let y0_batch = vec![vec![1.0_f64]; 3];
/// let results = batcher.integrate_fixed(&odes, 0.0, &y0_batch, 5.0, 0.01).unwrap();
/// for r in &results {
/// tracing::info!("instance {}: final y = {:.4}", r.instance, r.final_state()[0]);
/// }
/// # });
/// ```
pub struct BatchedRK4F64 {
device: Arc<WgpuDevice>,
}
impl BatchedRK4F64 {
/// Create a new batcher bound to `device`.
#[must_use]
pub fn new(device: &WgpuDevice) -> Self {
Self::with_device(Arc::new(device.clone()))
}
/// Create a new batcher with an explicit device `Arc`.
#[must_use]
pub fn with_device(device: Arc<WgpuDevice>) -> Self {
Self { device }
}
// ─── Fixed-step RK4 ──────────────────────────────────────────────────────
/// Run N ODE instances in parallel with fixed-step RK4.
///
/// # Arguments
/// - `odes` : one closure per instance; each captures its own parameters
/// - `t0` : start time (shared across instances)
/// - `y0_batch` : initial conditions `[N][D]`; all must have the same D
/// - `t_end` : end time (shared)
/// - `h` : fixed step size (shared)
///
/// # Returns
/// `Vec<TrajectoryResult>` in the same order as `odes`.
///
/// # Panics
/// Panics if a spawned thread panics during integration.
///
/// # Errors
///
/// Returns [`Err`] if batch validation fails, device creation fails, or any
/// trajectory integration fails (e.g. device lost, numerical error).
pub fn integrate_fixed(
&self,
odes: &[OdeFn],
t0: f64,
y0_batch: &[Vec<f64>],
t_end: f64,
h: f64,
) -> Result<Vec<TrajectoryResult>> {
self.validate_batch(odes.len(), y0_batch)?;
if odes.is_empty() {
return Ok(vec![]);
}
let device = &self.device;
let results: Vec<Result<TrajectoryResult>> = std::thread::scope(|scope| {
let mut handles = Vec::with_capacity(odes.len());
for (idx, (f, y0)) in odes.iter().zip(y0_batch.iter()).enumerate() {
let dev = device.clone();
handles.push(scope.spawn(move || -> Result<TrajectoryResult> {
let integrator = RkIntegrator::new(dev)?;
let (times, states) = integrator.integrate_fixed(f, t0, y0, t_end, h)?;
Ok(TrajectoryResult {
times,
states,
instance: idx,
})
}));
}
handles
.into_iter()
.enumerate()
.map(|(i, h)| {
h.join().unwrap_or_else(|_| {
Err(BarracudaError::Internal(format!(
"BatchedRK4F64::integrate_fixed: thread panic for instance {i}"
)))
})
})
.collect()
});
results.into_iter().collect()
}
// ─── Adaptive RK45 ───────────────────────────────────────────────────────
/// Run N ODE instances in parallel with adaptive-step RK45 (Dormand-Prince).
///
/// # Arguments
/// - `odes` : one closure per instance
/// - `t0` : start time
/// - `y0_batch` : initial conditions `[N][D]`
/// - `t_end` : end time
/// - `h_init` : initial step size
/// - `tol` : local error tolerance for adaptive stepping
///
/// # Panics
/// Panics if a spawned thread panics during integration.
///
/// # Errors
///
/// Returns [`Err`] if batch validation fails, device creation fails, or any
/// trajectory integration fails (e.g. device lost, numerical error).
pub fn integrate_adaptive(
&self,
odes: &[OdeFn],
t0: f64,
y0_batch: &[Vec<f64>],
t_end: f64,
h_init: f64,
tol: f64,
) -> Result<Vec<TrajectoryResult>> {
self.validate_batch(odes.len(), y0_batch)?;
if odes.is_empty() {
return Ok(vec![]);
}
let device = &self.device;
let results: Vec<Result<TrajectoryResult>> = std::thread::scope(|scope| {
let mut handles = Vec::with_capacity(odes.len());
for (idx, (f, y0)) in odes.iter().zip(y0_batch.iter()).enumerate() {
let dev = device.clone();
handles.push(scope.spawn(move || -> Result<TrajectoryResult> {
let integrator = RkIntegrator::new(dev)?;
let (times, states) =
integrator.integrate_adaptive(f, t0, y0, t_end, h_init, tol)?;
Ok(TrajectoryResult {
times,
states,
instance: idx,
})
}));
}
handles
.into_iter()
.enumerate()
.map(|(i, h)| {
h.join().unwrap_or_else(|_| {
Err(BarracudaError::Internal(format!(
"BatchedRK4F64::integrate_adaptive: thread panic for instance {i}"
)))
})
})
.collect()
});
results.into_iter().collect()
}
// ─── Private helpers ─────────────────────────────────────────────────────
fn validate_batch(&self, n_odes: usize, y0_batch: &[Vec<f64>]) -> Result<()> {
if y0_batch.len() != n_odes {
return Err(BarracudaError::InvalidInput {
message: format!(
"BatchedRK4F64: odes.len()={n_odes} but y0_batch.len()={}",
y0_batch.len()
),
});
}
if n_odes == 0 {
return Ok(());
}
let d = y0_batch[0].len();
for (i, y) in y0_batch.iter().enumerate() {
if y.len() != d {
return Err(BarracudaError::InvalidInput {
message: format!(
"BatchedRK4F64: instance {i} has D={} but expected D={d}",
y.len()
),
});
}
}
Ok(())
}
}
// ─── Tests ───────────────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
/// Exponential decay: dy/dt = -k*y → y(t) = y0 * exp(-k*t)
fn decay_ode(k: f64) -> OdeFn {
Box::new(move |_t, y| vec![-k * y[0]])
}
#[tokio::test]
async fn test_fixed_three_decay_rates() {
let device = crate::device::test_pool::get_test_device().await;
let batcher = BatchedRK4F64::new(&device);
let rates = [0.5_f64, 1.0, 2.0];
let odes: Vec<_> = rates.iter().map(|&k| decay_ode(k)).collect();
let y0_batch: Vec<_> = (0..3).map(|_| vec![1.0_f64]).collect();
let results = batcher
.integrate_fixed(&odes, 0.0, &y0_batch, 5.0, 0.01)
.unwrap();
assert_eq!(results.len(), 3);
for (r, &k) in results.iter().zip(&rates) {
let y_final = r.final_state()[0];
let y_exact = (-k * 5.0_f64).exp();
let rel_error = (y_final - y_exact).abs() / y_exact;
assert!(
rel_error < 1e-4,
"instance {}: y_final={y_final:.6}, y_exact={y_exact:.6}, rel_err={rel_error:.2e}",
r.instance
);
}
}
#[tokio::test]
async fn test_adaptive_single_instance() {
let device = crate::device::test_pool::get_test_device().await;
let batcher = BatchedRK4F64::new(&device);
let odes: Vec<_> = vec![decay_ode(1.0)];
let y0_batch = vec![vec![1.0_f64]];
let results = batcher
.integrate_adaptive(&odes, 0.0, &y0_batch, 3.0, 0.1, 1e-6)
.unwrap();
let y_final = results[0].final_state()[0];
let y_exact = (-3.0_f64).exp();
let rel_error = (y_final - y_exact).abs() / y_exact;
assert!(
rel_error < 1e-4,
"y_final={y_final:.6}, y_exact={y_exact:.6}"
);
}
#[tokio::test]
async fn test_empty_batch() {
let device = crate::device::test_pool::get_test_device().await;
let batcher = BatchedRK4F64::new(&device);
let results = batcher.integrate_fixed(&[], 0.0, &[], 1.0, 0.01).unwrap();
assert!(results.is_empty());
}
#[tokio::test]
async fn test_dimension_mismatch_error() {
let device = crate::device::test_pool::get_test_device().await;
let batcher = BatchedRK4F64::new(&device);
let odes: Vec<_> = vec![decay_ode(1.0), decay_ode(2.0)];
// y0_batch has wrong inner dimension for instance 1
let y0_batch = vec![vec![1.0_f64], vec![1.0_f64, 0.0_f64]];
assert!(
batcher
.integrate_fixed(&odes, 0.0, &y0_batch, 1.0, 0.01)
.is_err()
);
}
}