Skip to main content

qualia_core_db/platform/compute_bridge/
matrix.rs

1//! The per-class capability matrix and the built-in backends (plan §3).
2//!
3//! `benchmark_devices` (the existing AH-track probe) measures ONE GEMV and ranks
4//! circuits globally. This extends that to a **per-kernel-class** matrix: each class
5//! is measured on every available backend, and a winner is recorded *per class*
6//! (the fastest backend for GEMV is not the fastest for an FFT). The result is what
7//! `ComputePolicy::select` consults.
8//!
9//! Built-in backends registered by default:
10//! - [`CpuBackend`] — the native `rayon` reference kernels (`super::reference`),
11//!   always available, a row for every class.
12//! - [`WgpuBackend`] — the portable wgpu path. Today it measures the `DenseLinear`
13//!   class via the existing `device_benchmark` GEMV (a real GPU number); the other
14//!   classes have no portable GPU microkernel *yet*, so it returns no rows for them
15//!   (recorded honestly as "not probed on GPU", never faked). Those per-class GPU
16//!   kernels land per module (plan P2/P5) and appear here with zero further wiring.
17
18use std::time::Instant;
19
20use super::backend::{BackendId, KernelPanel, ProbeableBackend};
21use super::kernel_class::KernelClass;
22use super::reference;
23#[cfg(feature = "gpu-runtime")]
24use crate::device_benchmark::benchmark_devices;
25use crate::device_benchmark::{CircuitBench, CircuitKind};
26
27/// Measured per-class capability: for each class, the backend rows ranked
28/// fastest-first. `best_for` is the O(1)-ish lookup the STEM call sites use.
29#[derive(Debug, Clone)]
30pub struct ClassMatrix {
31    per_class: Vec<(KernelClass, Vec<CircuitBench>)>,
32}
33
34impl ClassMatrix {
35    /// Construct directly from per-class ranked rows — used by the passport loader
36    /// (a cached matrix) and by tests that synthesise a matrix without a GPU.
37    pub fn from_per_class(per_class: Vec<(KernelClass, Vec<CircuitBench>)>) -> Self {
38        Self { per_class }
39    }
40
41    /// Ranked rows for a class (fastest first); empty if the class was not probed.
42    pub fn rows(&self, class: KernelClass) -> &[CircuitBench] {
43        self.per_class
44            .iter()
45            .find(|(c, _)| *c == class)
46            .map(|(_, r)| r.as_slice())
47            .unwrap_or(&[])
48    }
49
50    /// The measured fastest (circuit, backend) for a class, if any was probed.
51    pub fn best_for(&self, class: KernelClass) -> Option<&CircuitBench> {
52        self.rows(class).first()
53    }
54
55    /// Summary.
56    pub fn summary(&self) -> String {
57        let mut s = String::from("ClassMatrix (per kernel-class, ranked fastest-first):\n");
58        for (class, rows) in &self.per_class {
59            s.push_str(&format!("  {}:\n", class.label()));
60            for (i, r) in rows.iter().enumerate() {
61                s.push_str(&format!(
62                    "    {}. {:<26} [{:?}/{}] {:>9.4} ms  score {:.3}\n",
63                    i + 1,
64                    r.label,
65                    r.kind,
66                    r.backend,
67                    r.ms_per_gemv,
68                    r.rel_score
69                ));
70            }
71        }
72        s
73    }
74}
75
76/// Time `f` over `iters` runs (with one warmup) and return ms/run.
77fn time_ms(iters: u32, mut f: impl FnMut()) -> f64 {
78    f(); // warmup
79    let t0 = Instant::now();
80    for _ in 0..iters {
81        f();
82    }
83    t0.elapsed().as_secs_f64() * 1e3 / iters as f64
84}
85
86/// Native-CPU backend: the `rayon` reference kernels. Always available.
87pub struct CpuBackend;
88
89impl ProbeableBackend for CpuBackend {
90    fn id(&self) -> BackendId {
91        BackendId::CPU
92    }
93    fn available(&self) -> bool {
94        true // CPU is always present (plan §7)
95    }
96    fn probe_class(&self, class: KernelClass, panel: &KernelPanel) -> Vec<CircuitBench> {
97        let label = format!("CPU native (rayon, {} cores)", num_cpus::get());
98        let ms = match class {
99            KernelClass::DenseLinear => {
100                let n = panel.dense_n;
101                let w = vec![0.05f32; n * n];
102                let x = vec![0.1f32; n];
103                let mut y = vec![0.0f32; n];
104                time_ms(5, || reference::gemv(&w, &x, &mut y))
105            }
106            KernelClass::ElementwiseMap => {
107                let x = vec![0.1f32; panel.vector_len];
108                let mut y = vec![0.0f32; panel.vector_len];
109                time_ms(10, || reference::axpb(2.0, &x, 1.0, &mut y))
110            }
111            KernelClass::Reduction => {
112                let x = vec![0.1f32; panel.vector_len];
113                time_ms(10, || {
114                    let _ = reference::reduce_sum(&x);
115                })
116            }
117            KernelClass::Stencil => {
118                let x = vec![0.1f32; panel.grid_n];
119                let mut y = vec![0.0f32; panel.grid_n];
120                time_ms(10, || reference::stencil3(&x, &mut y))
121            }
122            KernelClass::AllPairs => {
123                let pts: Vec<f32> = (0..panel.nbody_n * 3)
124                    .map(|i| (i % 97) as f32 * 0.1)
125                    .collect();
126                time_ms(3, || {
127                    let _ = reference::allpairs_potential(&pts);
128                })
129            }
130            KernelClass::Fft => {
131                let n = panel.fft_n.next_power_of_two();
132                let base: Vec<f32> = (0..n).map(|i| (i as f32 * 0.01).sin()).collect();
133                time_ms(5, || {
134                    let mut re = base.clone();
135                    let mut im = vec![0.0f32; n];
136                    reference::fft_radix2(&mut re, &mut im, false);
137                })
138            }
139            KernelClass::Scan => {
140                let x = vec![0.1f32; panel.vector_len];
141                let mut y = vec![0.0f32; panel.vector_len];
142                time_ms(10, || reference::prefix_sum(&x, &mut y))
143            }
144            KernelClass::Divergent => time_ms(3, || {
145                let _ = reference::monte_carlo_pi(panel.mc_steps);
146            }),
147        };
148        vec![CircuitBench {
149            label,
150            kind: CircuitKind::Cpu,
151            backend: "native".to_string(),
152            ms_per_gemv: ms,
153            gflops: 0.0, // throughput proxy not derived here; ranking uses ms
154            upload_gbps: f64::INFINITY, // data already in the CPU pool — no transfer
155            rel_score: 1.0,
156            decode_proxy_tok_s: None,
157        }]
158    }
159}
160
161/// Portable wgpu backend. Measures `DenseLinear` via the existing GEMV probe; other
162/// classes have no portable GPU microkernel yet (returns no rows — honest).
163#[cfg(feature = "gpu-runtime")]
164pub struct WgpuBackend;
165
166#[cfg(feature = "gpu-runtime")]
167impl ProbeableBackend for WgpuBackend {
168    fn id(&self) -> BackendId {
169        BackendId::WGPU
170    }
171    fn available(&self) -> bool {
172        // Available if any non-CPU wgpu adapter enumerates. Cheap-ish; only at boot.
173        let instance = etalon::Instance::default();
174        pollster::block_on(instance.enumerate_adapters(etalon::Backends::all()))
175            .iter()
176            .any(|a| {
177                let info = a.get_info();
178                info.device_type != etalon::DeviceType::Cpu && info.device != 0
179            })
180    }
181    fn probe_class(&self, class: KernelClass, panel: &KernelPanel) -> Vec<CircuitBench> {
182        match class {
183            KernelClass::DenseLinear => {
184                // Reuse the real GEMV probe; keep only the GPU rows (the CPU row is
185                // contributed by CpuBackend).
186                benchmark_devices(panel.dense_n)
187                    .circuits
188                    .into_iter()
189                    .filter(|c| c.kind != CircuitKind::Cpu)
190                    .collect()
191            }
192            // No portable GPU microkernel for these classes yet → no rows (plan P2/P5).
193            _ => Vec::new(),
194        }
195    }
196}
197
198/// Probe every available backend across every kernel class and assemble the ranked
199/// per-class matrix. Boot-time only (cache it in the passport).
200pub fn probe_class_matrix(
201    registry: &super::backend::BackendRegistry,
202    panel: &KernelPanel,
203) -> ClassMatrix {
204    let mut per_class = Vec::with_capacity(KernelClass::ALL.len());
205    for class in KernelClass::ALL {
206        let mut rows: Vec<CircuitBench> = Vec::new();
207        for backend in registry.available() {
208            rows.extend(backend.probe_class(class, panel));
209        }
210        // Rank fastest-first by measured ms, fill relative scores.
211        rows.sort_by(|a, b| {
212            a.ms_per_gemv
213                .partial_cmp(&b.ms_per_gemv)
214                .unwrap_or(std::cmp::Ordering::Equal)
215        });
216        if let Some(best) = rows.first().map(|c| c.ms_per_gemv) {
217            for r in &mut rows {
218                r.rel_score = if r.ms_per_gemv > 0.0 {
219                    best / r.ms_per_gemv
220                } else {
221                    0.0
222                };
223            }
224        }
225        per_class.push((class, rows));
226    }
227    ClassMatrix { per_class }
228}
229
230#[cfg(test)]
231mod tests {
232    use super::super::backend::BackendRegistry;
233    use super::*;
234
235    #[test]
236    fn cpu_backend_probes_every_class_with_real_rows() {
237        let cpu = CpuBackend;
238        let panel = KernelPanel::quick();
239        for class in KernelClass::ALL {
240            let rows = cpu.probe_class(class, &panel);
241            assert_eq!(rows.len(), 1, "CPU must yield a row for {}", class.label());
242            assert!(
243                rows[0].ms_per_gemv > 0.0,
244                "{} CPU time must be positive",
245                class.label()
246            );
247            assert!(rows[0].upload_gbps.is_infinite(), "CPU is in-pool");
248        }
249    }
250
251    #[test]
252    fn class_matrix_has_cpu_winner_for_every_class_headless() {
253        // CPU-only registry (deterministic, no GPU): every class gets a ranked row,
254        // and the best is score 1.0.
255        let mut reg = BackendRegistry::new();
256        reg.register(Box::new(CpuBackend));
257        let m = probe_class_matrix(&reg, &KernelPanel::quick());
258        for class in KernelClass::ALL {
259            let best = m.best_for(class).expect("a class winner must exist");
260            assert_eq!(best.kind, CircuitKind::Cpu);
261            assert!((best.rel_score - 1.0).abs() < 1e-9);
262        }
263    }
264}