Skip to main content

qualia_core_db/platform/compute_bridge/
execute.rs

1//! The dispatch entry the STEM substrate calls: `accelerated_gemm_f32` runs `C = A·B`
2//! on the GPU when `gpu-runtime` is on, the **measured** capability matrix says it
3//! wins, and the job is big enough to be worth the dispatch; otherwise a `rayon` CPU
4//! path. The CPU path is always present and never hard-fails (§7).
5//!
6//! With `gpu-runtime`, the machine benchmark ([`crate::device_benchmark`]) runs
7//! **once** here, lazily, to build the shared [`ComputePolicy`]; every subsequent
8//! call is the O(1) `select`. Without that feature there is no GPU probe and no
9//! matrix — the path is always CPU (`RanOn::Cpu`).
10//!
11//! f64 vs f32: this accelerated path is **f32** (the GPU/WGSL reality and what the
12//! throughput-bound callers want). The exact-f64 scientific GEMM
13//! ([`crate::solvers::linear_algebra::gemm`]) is unchanged and stays on the CPU — the
14//! bridge never silently downcasts a caller that asked for f64.
15
16use std::sync::OnceLock;
17
18#[cfg(feature = "gpu-runtime")]
19use super::gpu_gemm;
20#[cfg(feature = "gpu-runtime")]
21use super::kernel_class::KernelClass;
22use super::policy::ComputePolicy;
23#[cfg(feature = "gpu-runtime")]
24use crate::platform::hetero_dispatch::{HostCapabilities, PowerThermalBudget};
25
26/// Below this FLOP count a GEMM stays on the CPU regardless of the matrix — GPU upload
27/// + dispatch + readback overhead dominates a small job. (`m·k·n` multiply-adds.)
28#[cfg(feature = "gpu-runtime")]
29const GPU_MIN_FLOPS: u64 = 1 << 20; // ~100³
30
31/// Which backend actually ran a dispatch (for observability and the correctness gate).
32#[derive(Debug, Clone, Copy, PartialEq, Eq)]
33pub enum RanOn {
34    Gpu,
35    Cpu,
36}
37
38static POLICY: OnceLock<ComputePolicy> = OnceLock::new();
39
40/// The shared compute policy, built once by probing this machine (the benchmark). The
41/// heavy probe runs on first call; thereafter `select` is O(1). Without `gpu-runtime`
42/// there is no GPU probe — the policy is CPU-only.
43pub fn shared_policy() -> &'static ComputePolicy {
44    POLICY.get_or_init(|| {
45        #[cfg(feature = "gpu-runtime")]
46        {
47            let registry = super::default_registry();
48            let panel = super::backend::KernelPanel::default();
49            let budget = PowerThermalBudget {
50                vram_budget_bytes: 4u64 << 30,
51                power_budget_mw: 45_000,
52                thermal_headroom_c: 20.0,
53            };
54            let host = HostCapabilities {
55                gpu_available: gpu_gemm::shared().is_some(),
56                vram_available: 2u64 << 30,
57                npu_available: crate::platform::accelerator_inventory::capture().has_detected_npu(),
58                cpu_threads: num_cpus::get() as u32,
59            };
60            ComputePolicy::probe(&registry, &panel, budget, host)
61        }
62        #[cfg(not(feature = "gpu-runtime"))]
63        {
64            ComputePolicy::cpu_only()
65        }
66    })
67}
68
69/// Multi-threaded CPU `C = A·B` (f32, row-major) — the always-present fallback.
70fn cpu_gemm_f32(_m: usize, k: usize, n: usize, a: &[f32], b: &[f32], c: &mut [f32]) {
71    use rayon::prelude::*;
72    c.par_chunks_mut(n).enumerate().for_each(|(i, row)| {
73        let a_row = &a[i * k..(i + 1) * k];
74        for (j, cell) in row.iter_mut().enumerate() {
75            let mut s = 0.0f32;
76            for l in 0..k {
77                s += a_row[l] * b[l * n + j];
78            }
79            *cell = s;
80        }
81    });
82}
83
84/// Accelerated `C = A·B` (f32). `a` is `m×k`, `b` is `k×n`, `c` is `m×n` (overwritten).
85/// With `gpu-runtime`, routes to the GPU when the measured matrix favours it for
86/// `DenseLinear`, the job clears `GPU_MIN_FLOPS`, and it fits in GPU buffers;
87/// otherwise the CPU path. Without `gpu-runtime` this is always the rayon CPU path
88/// and never reports [`RanOn::Gpu`]. On any GPU shortfall it falls back to CPU —
89/// never a hard fail.
90pub fn accelerated_gemm_f32(
91    m: usize,
92    k: usize,
93    n: usize,
94    a: &[f32],
95    b: &[f32],
96    c: &mut [f32],
97) -> RanOn {
98    debug_assert_eq!(a.len(), m * k);
99    debug_assert_eq!(b.len(), k * n);
100    debug_assert_eq!(c.len(), m * n);
101
102    #[cfg(feature = "gpu-runtime")]
103    {
104        let flops = (m as u64) * (k as u64) * (n as u64);
105        if flops >= GPU_MIN_FLOPS {
106            if let Some(ctx) = gpu_gemm::shared() {
107                if ctx.fits(m, k, n) {
108                    let plan = shared_policy().select(KernelClass::DenseLinear, (m * n * 4) as u64);
109                    if !plan.is_cpu() {
110                        if let Some(result) = ctx.gemm(m, k, n, a, b) {
111                            c.copy_from_slice(&result);
112                            return RanOn::Gpu;
113                        }
114                    }
115                }
116            }
117        }
118    }
119    cpu_gemm_f32(m, k, n, a, b, c);
120    RanOn::Cpu
121}
122
123#[cfg(test)]
124mod tests {
125    use super::*;
126
127    fn ref_gemm(m: usize, k: usize, n: usize, a: &[f32], b: &[f32]) -> Vec<f32> {
128        let mut c = vec![0.0f32; m * n];
129        for i in 0..m {
130            for j in 0..n {
131                let mut s = 0.0f32;
132                for l in 0..k {
133                    s += a[i * k + l] * b[l * n + j];
134                }
135                c[i * n + j] = s;
136            }
137        }
138        c
139    }
140
141    #[test]
142    fn small_job_runs_on_cpu_and_is_correct() {
143        let (m, k, n) = (4, 5, 3);
144        let a: Vec<f32> = (0..m * k).map(|i| i as f32 * 0.1).collect();
145        let b: Vec<f32> = (0..k * n).map(|i| i as f32 * 0.2 - 0.5).collect();
146        let mut c = vec![0.0f32; m * n];
147        let ran = accelerated_gemm_f32(m, k, n, &a, &b, &mut c);
148        assert_eq!(ran, RanOn::Cpu, "a tiny job must stay on CPU");
149        assert_eq!(c, ref_gemm(m, k, n, &a, &b));
150    }
151
152    #[test]
153    fn large_job_is_correct_on_whichever_backend_the_machine_chose() {
154        // 128³ clears the FLOP floor. Whether it runs on GPU or CPU depends on the
155        // measured matrix; either way the result must match the reference.
156        let (m, k, n) = (128, 128, 128);
157        let a: Vec<f32> = (0..m * k).map(|i| ((i % 17) as f32) * 0.05 - 0.3).collect();
158        let b: Vec<f32> = (0..k * n).map(|i| ((i % 11) as f32) * 0.07 - 0.2).collect();
159        let mut c = vec![0.0f32; m * n];
160        let ran = accelerated_gemm_f32(m, k, n, &a, &b, &mut c);
161        eprintln!("[accelerated_gemm_f32] 128³ ran on {ran:?}");
162        #[cfg(not(feature = "gpu-runtime"))]
163        assert_eq!(
164            ran,
165            RanOn::Cpu,
166            "without gpu-runtime the path is always CPU"
167        );
168        let reference = ref_gemm(m, k, n, &a, &b);
169        let max_err = c
170            .iter()
171            .zip(&reference)
172            .map(|(x, y)| (x - y).abs())
173            .fold(0.0f32, f32::max);
174        assert!(max_err < 1e-2, "max abs err {max_err} on {ran:?}");
175    }
176}