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
// SPDX-License-Identifier: AGPL-3.0-or-later
//! Device routing and selection logic.
//!
//! Routes workloads to the appropriate hardware based on the nature of the
//! computation. GPUs run arbitrary WGSL shaders, NPUs run pre-compiled neural
//! network models, CPUs handle everything else.
//!
//! Fallback chain: `preferred → auto-route recommendation → GPU → CPU`
use crate::device::capabilities::{is_gpu_available, is_npu_available};
use crate::device::device_types::Device;
/// Workload hints for automatic device selection.
///
/// Carries enough metadata for the router to make intelligent decisions
/// about data size, sparsity, and hardware affinity.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WorkloadHint {
/// Large matrix operations (GPU-preferred)
LargeMatrices,
/// Small workload (CPU-preferred to avoid GPU dispatch overhead)
SmallWorkload,
/// Sparse event processing (NPU-preferred, ultra-low power)
SparseEvents,
/// Event-driven logic (CPU or NPU)
EventProcessing,
/// String operations (CPU-only)
StringOps,
/// General computation (Auto — GPU if available, else CPU)
General,
// --- Science-aware hints (route physics/math to the right device) ---
/// Physics force computation (always GPU — needs WGSL shaders for arbitrary math)
PhysicsForce,
/// FFT computation (always GPU — butterfly stages are massively parallel)
FFT,
/// Eigenvalue decomposition (GPU for large, CPU for small)
EigenDecomp,
/// Linear system solve (GPU for large, CPU for small)
LinearSolve,
/// Training / gradient computation (always GPU — needs gradient shaders)
Training,
/// Neural network inference with a pre-compiled model (NPU if available)
Inference,
/// Binary classification pre-screening (NPU ideal — ultra-low power)
PreScreen,
/// Surrogate model evaluation (GPU for RBF kernel, NPU for pre-filter)
SurrogateEval,
/// Monte Carlo / random sampling (GPU — parallel PRNG)
MonteCarlo,
/// Sparse linear algebra (GPU for large, CPU for small)
SparseMath,
/// Reservoir computing / ESN (NPU natural fit — fixed random weights)
Reservoir,
}
/// Select best device for given workload characteristics (auto-routing).
///
/// Routes workloads to the appropriate hardware. GPUs run arbitrary WGSL
/// shaders, NPUs run pre-compiled neural network models, CPUs handle the rest.
#[must_use]
pub fn select_for_workload(workload: &WorkloadHint) -> Device {
let gpu = is_gpu_available();
let npu = is_npu_available();
match workload {
// === CPU-only workloads ===
WorkloadHint::SmallWorkload | WorkloadHint::StringOps => Device::CPU,
// === NPU-preferred (pre-compiled inference, ultra-low power) ===
WorkloadHint::SparseEvents if npu => Device::NPU,
WorkloadHint::EventProcessing if npu => Device::NPU,
WorkloadHint::PreScreen if npu => Device::NPU,
WorkloadHint::Inference if npu => Device::NPU,
WorkloadHint::Reservoir if npu => Device::NPU,
// === GPU-preferred (arbitrary parallel math) ===
WorkloadHint::LargeMatrices if gpu => Device::GPU,
WorkloadHint::PhysicsForce if gpu => Device::GPU,
WorkloadHint::FFT if gpu => Device::GPU,
WorkloadHint::EigenDecomp if gpu => Device::GPU,
WorkloadHint::LinearSolve if gpu => Device::GPU,
WorkloadHint::Training if gpu => Device::GPU,
WorkloadHint::SurrogateEval if gpu => Device::GPU,
WorkloadHint::MonteCarlo if gpu => Device::GPU,
WorkloadHint::SparseMath if gpu => Device::GPU,
// === Fallback chain: GPU → CPU ===
_ => {
if gpu {
Device::GPU
} else {
Device::CPU
}
}
}
}
/// Select device with an explicit user preference.
///
/// If the user requests a specific device and it is available, honour that
/// choice regardless of what the auto-router would recommend.
///
/// Fallback chain when the preferred device is unavailable:
/// `preferred → auto-route recommendation → GPU → CPU`
#[must_use]
pub fn select_with_preference(preferred: Option<Device>, workload: &WorkloadHint) -> Device {
match preferred {
Some(Device::Auto) | None => select_for_workload(workload),
Some(dev) if device_is_available(dev) => dev,
Some(_) => select_for_workload(workload),
}
}
/// Check if a device is available (used by `select_with_preference`).
fn device_is_available(device: Device) -> bool {
match device {
Device::CPU | Device::Auto => true,
Device::GPU => is_gpu_available(),
Device::NPU => is_npu_available(),
Device::TPU => false,
Device::Sovereign => device.is_available(),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn cpu_only_workloads_always_route_to_cpu() {
assert_eq!(
select_for_workload(&WorkloadHint::SmallWorkload),
Device::CPU
);
assert_eq!(select_for_workload(&WorkloadHint::StringOps), Device::CPU);
}
#[test]
fn general_fallback_never_panics() {
let device = select_for_workload(&WorkloadHint::General);
assert!(device == Device::GPU || device == Device::CPU);
}
#[test]
fn preference_none_delegates_to_auto() {
let auto = select_for_workload(&WorkloadHint::General);
let pref = select_with_preference(None, &WorkloadHint::General);
assert_eq!(auto, pref);
}
#[test]
fn preference_auto_delegates_to_auto() {
let auto = select_for_workload(&WorkloadHint::General);
let pref = select_with_preference(Some(Device::Auto), &WorkloadHint::General);
assert_eq!(auto, pref);
}
#[test]
fn preference_cpu_always_honoured() {
let dev = select_with_preference(Some(Device::CPU), &WorkloadHint::LargeMatrices);
assert_eq!(dev, Device::CPU);
}
#[test]
fn tpu_unavailable_falls_back() {
let dev = select_with_preference(Some(Device::TPU), &WorkloadHint::General);
assert_ne!(dev, Device::TPU);
}
#[test]
fn device_is_available_cpu_always_true() {
assert!(device_is_available(Device::CPU));
}
#[test]
fn device_is_available_tpu_always_false() {
assert!(!device_is_available(Device::TPU));
}
#[test]
fn device_is_available_auto_always_true() {
assert!(device_is_available(Device::Auto));
}
#[test]
fn all_workload_hints_produce_valid_device() {
let hints = [
WorkloadHint::LargeMatrices,
WorkloadHint::SmallWorkload,
WorkloadHint::SparseEvents,
WorkloadHint::EventProcessing,
WorkloadHint::StringOps,
WorkloadHint::General,
WorkloadHint::PhysicsForce,
WorkloadHint::FFT,
WorkloadHint::EigenDecomp,
WorkloadHint::LinearSolve,
WorkloadHint::Training,
WorkloadHint::Inference,
WorkloadHint::PreScreen,
WorkloadHint::SurrogateEval,
WorkloadHint::MonteCarlo,
WorkloadHint::SparseMath,
WorkloadHint::Reservoir,
];
for hint in &hints {
let dev = select_for_workload(hint);
assert!(
matches!(dev, Device::CPU | Device::GPU | Device::NPU),
"Hint {hint:?} produced unexpected device {dev:?}"
);
}
}
}