Skip to main content

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}