qualia_core_db/platform/compute_bridge/mod.rs
1//! Compute bridge — the engine's one shared "which hardware runs this kernel"
2//! surface (HARDWARE_BACKEND_AUTOSELECT_PLAN.md; CLAUDE.md §13).
3//!
4//! Every accelerable STEM function classifies itself into a [`KernelClass`], and at
5//! its call site asks [`ComputePolicy::select`] for a [`Plan`] — which backend
6//! (over the **open** [`BackendRegistry`]), which precision, how to tile, how to move
7//! data — then runs it. No module hardcodes a device; they all defer to the
8//! **measured** per-class capability matrix. CPU is always present and never fails.
9//!
10//! Layers (each its own submodule, plan §11):
11//! - [`kernel_class`] — the fixed kernel-shape taxonomy routed per class.
12//! - [`backend`] — the open `ProbeableBackend` registry (the expansion point: a new
13//! accelerator is one `register()`, never an edit to the decision tree).
14//! - [`mod@reference`] — correct CPU microkernels: the always-present path AND the
15//! correctness reference a GPU/NPU/vendor kernel must match before it may default.
16//! - [`matrix`] — the per-class capability matrix + the built-in CPU/wgpu backends.
17//! - [`policy`] — `ComputePolicy::select` → `Plan` (wraps `hetero_dispatch`).
18//!
19//! Native only (it reuses the native wgpu probe + `rayon` CPU path). A WASM/browser
20//! build registers a narrower set (WebGPU-or-CPU); that target-conditional registry
21//! is a follow-on (plan §4b).
22#![cfg(not(target_arch = "wasm32"))]
23
24pub mod backend;
25pub mod execute;
26#[cfg(feature = "gpu-runtime")]
27pub mod gpu_gemm;
28pub mod kernel_class;
29pub mod matrix;
30pub mod policy;
31pub mod reference;
32
33pub use backend::{BackendId, BackendRegistry, DispatchError, KernelPanel, ProbeableBackend};
34pub use execute::{accelerated_gemm_f32, shared_policy, RanOn};
35#[cfg(feature = "gpu-runtime")]
36pub use gpu_gemm::WgpuGemm;
37pub use kernel_class::KernelClass;
38#[cfg(feature = "gpu-runtime")]
39pub use matrix::WgpuBackend;
40pub use matrix::{probe_class_matrix, ClassMatrix, CpuBackend};
41pub use policy::{ComputePolicy, Plan};
42
43/// The default backend registry: the always-present native CPU path plus the
44/// portable wgpu path. Expansion backends (`cuda`, `rocm`, `oneapi`, NPU runtimes)
45/// register here behind their Cargo features — one `register()` each, no change to
46/// ranking or `select`.
47pub fn default_registry() -> BackendRegistry {
48 let mut reg = BackendRegistry::new();
49 reg.register(Box::new(CpuBackend));
50 #[cfg(feature = "gpu-runtime")]
51 reg.register(Box::new(WgpuBackend));
52 // #[cfg(feature = "cuda")] reg.register(Box::new(CudaBackend)); // plan P7
53 // #[cfg(feature = "npu-directml")] reg.register(Box::new(...)); // plan P6
54 reg
55}
56
57#[cfg(test)]
58mod tests {
59 use super::*;
60
61 #[test]
62 fn default_registry_has_cpu_and_wgpu() {
63 let reg = default_registry();
64 let ids: Vec<_> = reg.iter().map(|b| b.id()).collect();
65 assert!(ids.contains(&BackendId::CPU));
66 #[cfg(feature = "gpu-runtime")]
67 assert!(ids.contains(&BackendId::WGPU));
68 // CPU is always available even when headless.
69 assert!(reg
70 .iter()
71 .any(|b| b.id() == BackendId::CPU && b.available()));
72 }
73}