Skip to main content

qualia_extensions/webgpu_extension/
mod.rs

1//! WebGPU Extension for QualiaDB Advanced
2//!
3//! Continuous-physics compute for fluid dynamics, electromagnetics, heat,
4//! waves, particles and dense tensor algebra. Each operation is backed by a
5//! **real finite-difference / finite-element / N-body solver** (the `solvers`
6//! below), validated against an exact analytic solution in its own unit test.
7//!
8//! ## CPU reference vs. GPU dispatch
9//!
10//! The solvers here are the **verifiable CPU reference path**: deterministic,
11//! analytic-solution-tested, and runnable on any machine (no GPU required).
12//! This mirrors the core engine's pattern (`modalities/calculus`) where the CPU
13//! kernel is ground truth and the GPU is an accelerator of the *same* math.
14//!
15//! The WGSL in [`shaders`] is the corresponding GPU kernel **spec**. GPU
16//! acceleration routes through the core engine's shared `wgpu` device
17//! (`qualia-core-db` `hetero_dispatch` / `WebGpuIntegrator`) rather than a
18//! second device spun up here — the repo deliberately owns a single wgpu stack.
19//! The CPU reference is what the tests exercise and what runs when no GPU is
20//! present.
21
22use crate::{
23    Extension, ExtensionCapability, ExtensionError, ExtensionJob, ExtensionResult, NQuin,
24    ResourceRequirements,
25};
26use async_trait::async_trait;
27use serde::{Deserialize, Serialize};
28use std::collections::HashMap;
29use std::time::Instant;
30
31pub mod electromagnetics;
32pub mod fluid;
33pub mod heat;
34pub mod particles;
35pub mod shaders;
36pub mod tensor;
37pub mod wave;
38
39/// WebGPU Extension implementation
40pub struct WebGpuExtension {
41    shader_manager: WebGpuShaderManager,
42    capability: ExtensionCapability,
43}
44
45/// Registry of the GPU kernel specs (WGSL) for the supported physics domains.
46pub struct WebGpuShaderManager {
47    loaded_shaders: HashMap<String, WebGpuShader>,
48}
49
50/// A GPU compute-shader spec (the kernel the CPU reference solver mirrors).
51#[derive(Debug, Clone)]
52pub struct WebGpuShader {
53    pub name: String,
54    pub shader_type: ShaderType,
55    pub wgsl_source: String,
56    pub workgroup_size: (u32, u32, u32),
57}
58
59/// Physics domains this extension can solve.
60#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
61pub enum ShaderType {
62    FluidDynamics,
63    Electromagnetics,
64    HeatTransfer,
65    WavePropagation,
66    ParticleSimulation,
67    TensorOperations,
68}
69
70/// Job parameters for a physics solve.
71#[derive(Debug, Clone, Serialize, Deserialize)]
72pub struct WebGpuJobParams {
73    /// Name of the kernel/domain to run (e.g. `navier_stokes_2d`).
74    pub shader_name: String,
75    /// Grid extents `(nx, ny, nz)`; `0` on an axis means "use the solver default".
76    pub grid_size: (u32, u32, u32),
77    /// Named input fields (initial conditions). Empty ⇒ the solver seeds an
78    /// analytic initial condition (used by the validation tests).
79    pub input_data: HashMap<String, Vec<f32>>,
80    /// Named scalar parameters (e.g. `viscosity`, `epsilon`, `m`/`k`/`n`).
81    pub uniform_data: HashMap<String, f32>,
82    /// Time-stepping / iteration controls.
83    pub dispatch_params: DispatchParams,
84}
85
86/// Time-stepping / iteration controls.
87#[derive(Debug, Clone, Serialize, Deserialize)]
88pub struct DispatchParams {
89    pub iterations: u32,
90    pub time_step: f64,
91    pub convergence_threshold: f32,
92    pub max_execution_time_ms: u64,
93}
94
95impl Default for DispatchParams {
96    fn default() -> Self {
97        Self {
98            iterations: 0,
99            time_step: 0.0,
100            convergence_threshold: 1e-3,
101            max_execution_time_ms: 30_000,
102        }
103    }
104}
105
106/// Result of a physics solve.
107#[derive(Debug, Clone, Serialize, Deserialize)]
108pub struct WebGpuExecutionResult {
109    pub output_data: HashMap<String, Vec<f32>>,
110    pub performance_metrics: GpuPerformanceMetrics,
111    pub convergence_info: ConvergenceInfo,
112    pub execution_time_ms: u64,
113}
114
115/// Measured throughput of the solve. On the CPU reference path the
116/// `gpu_*_utilization` fields are `0.0` (not applicable); the time, FLOP-rate
117/// and bandwidth figures are **measured**, not invented.
118#[derive(Debug, Clone, Serialize, Deserialize)]
119pub struct GpuPerformanceMetrics {
120    pub compute_shader_time_ms: u64,
121    pub memory_bandwidth_mb_s: f64,
122    pub tflops_achieved: f64,
123    pub gpu_utilization_percent: f64,
124    pub memory_utilization_percent: f64,
125}
126
127/// Convergence / residual report from a solve.
128#[derive(Debug, Clone, Serialize, Deserialize)]
129pub struct ConvergenceInfo {
130    pub converged: bool,
131    pub iterations_used: u32,
132    pub final_residual: f32,
133    pub convergence_rate: f32,
134}
135
136/// Output of a solver: the field data plus honest residual/effort bookkeeping.
137pub struct SolverReport {
138    /// Named output fields.
139    pub output: HashMap<String, Vec<f32>>,
140    /// Time steps / iterations actually performed.
141    pub iterations_used: u32,
142    /// A real residual: incompressibility `max|∇·u|` for fluids, the steady
143    /// step-to-step change for relaxations, or `0` for exact direct solves.
144    pub final_residual: f32,
145    /// `final_residual <= convergence_threshold`.
146    pub converged: bool,
147    /// Floating-point operations performed (for the throughput metric).
148    pub flops: u64,
149}
150
151/// `0` on an axis means "use the solver default".
152#[inline]
153pub(crate) fn dim(v: u32, default: usize) -> usize {
154    if v == 0 {
155        default
156    } else {
157        v as usize
158    }
159}
160
161/// Read a named scalar parameter, falling back to `default`.
162#[inline]
163pub(crate) fn uniform(params: &WebGpuJobParams, key: &str, default: f32) -> f32 {
164    params.uniform_data.get(key).copied().unwrap_or(default)
165}
166
167impl WebGpuExtension {
168    /// Creates a new instance.
169    pub fn new() -> Self {
170        let mut shader_manager = WebGpuShaderManager {
171            loaded_shaders: HashMap::new(),
172        };
173        Self::load_builtin_shaders(&mut shader_manager);
174
175        Self {
176            shader_manager,
177            capability: ExtensionCapability {
178                name: "webgpu".to_string(),
179                version: "2.0.0".to_string(),
180                description:
181                    "Real finite-difference / N-body physics solvers (analytic-solution validated). \
182                     CPU reference path; WGSL kernel specs included for GPU dispatch."
183                        .to_string(),
184                required_resources: ResourceRequirements {
185                    min_memory_mb: 128,
186                    // GPU is optional: the CPU reference path runs without one.
187                    min_vram_mb: Some(1024),
188                    requires_gpu: false,
189                    requires_network: false,
190                    max_concurrent_jobs: 3,
191                },
192                supported_operations: vec![
193                    "simulate_fluid".to_string(),
194                    "solve_electromagnetics".to_string(),
195                    "compute_heat_transfer".to_string(),
196                    "propagate_waves".to_string(),
197                    "simulate_particles".to_string(),
198                    "tensor_operations".to_string(),
199                ],
200            },
201        }
202    }
203
204    fn load_builtin_shaders(mgr: &mut WebGpuShaderManager) {
205        let specs = [
206            (
207                "navier_stokes_2d",
208                ShaderType::FluidDynamics,
209                shaders::NAVIER_STOKES_2D,
210                (16u32, 16u32, 1u32),
211            ),
212            (
213                "maxwell_fdtd_1d",
214                ShaderType::Electromagnetics,
215                shaders::MAXWELL_FDTD_1D,
216                (64, 1, 1),
217            ),
218            (
219                "heat_diffusion_2d",
220                ShaderType::HeatTransfer,
221                shaders::HEAT_DIFFUSION_2D,
222                (16, 16, 1),
223            ),
224            (
225                "wave_equation_2d",
226                ShaderType::WavePropagation,
227                shaders::WAVE_EQUATION_2D,
228                (16, 16, 1),
229            ),
230        ];
231        for (name, ty, src, wg) in specs {
232            mgr.loaded_shaders.insert(
233                name.to_string(),
234                WebGpuShader {
235                    name: name.to_string(),
236                    shader_type: ty,
237                    wgsl_source: src.to_string(),
238                    workgroup_size: wg,
239                },
240            );
241        }
242    }
243
244    /// Resolve a kernel name to its physics domain. Falls back to a name table
245    /// for solvers whose GPU kernel ships only as a CPU reference.
246    fn shader_type_for(&self, name: &str) -> Option<ShaderType> {
247        if let Some(s) = self.shader_manager.loaded_shaders.get(name) {
248            return Some(s.shader_type);
249        }
250        Some(match name {
251            "navier_stokes_2d" => ShaderType::FluidDynamics,
252            "maxwell_fdtd_1d" => ShaderType::Electromagnetics,
253            "heat_diffusion_2d" => ShaderType::HeatTransfer,
254            "wave_equation_2d" => ShaderType::WavePropagation,
255            "nbody_verlet" => ShaderType::ParticleSimulation,
256            "tensor_gemm" => ShaderType::TensorOperations,
257            _ => return None,
258        })
259    }
260
261    /// Run the real solver for `params.shader_name` and report measured timing.
262    pub async fn execute_shader(
263        &self,
264        params: WebGpuJobParams,
265    ) -> Result<WebGpuExecutionResult, ExtensionError> {
266        let shader_type = self.shader_type_for(&params.shader_name).ok_or_else(|| {
267            ExtensionError::ExecutionFailed(format!("Unknown shader '{}'", params.shader_name))
268        })?;
269
270        let start = Instant::now();
271        let report = run_solver(shader_type, &params);
272        let elapsed = start.elapsed();
273
274        let secs = elapsed.as_secs_f64().max(1e-9);
275        let out_floats: usize = report.output.values().map(|v| v.len()).sum();
276        let bytes_moved = (out_floats * 4 * report.iterations_used.max(1) as usize) as f64;
277
278        Ok(WebGpuExecutionResult {
279            performance_metrics: GpuPerformanceMetrics {
280                compute_shader_time_ms: elapsed.as_millis() as u64,
281                memory_bandwidth_mb_s: bytes_moved / secs / 1.0e6,
282                tflops_achieved: report.flops.max(1) as f64 / secs / 1.0e12,
283                // Not applicable on the CPU reference path; measured only on the
284                // wgpu dispatch path.
285                gpu_utilization_percent: 0.0,
286                memory_utilization_percent: 0.0,
287            },
288            convergence_info: ConvergenceInfo {
289                converged: report.converged,
290                iterations_used: report.iterations_used,
291                final_residual: report.final_residual,
292                convergence_rate: if report.iterations_used > 0 && report.final_residual > 0.0 {
293                    1.0 - report.final_residual.min(1.0)
294                } else {
295                    1.0
296                },
297            },
298            output_data: report.output,
299            execution_time_ms: elapsed.as_millis() as u64,
300        })
301    }
302
303    fn result_to_quins(result: &WebGpuExecutionResult, job_id: &str) -> Vec<NQuin> {
304        vec![
305            NQuin {
306                subject: crate::q_hash(job_id),
307                predicate: crate::q_hash("q42:hasGpuPerformance"),
308                object: (result.performance_metrics.tflops_achieved * 1000.0) as u64,
309                context: crate::q_hash("webgpu:performance"),
310                metadata: ((result.performance_metrics.compute_shader_time_ms) << 32)
311                    | (result.performance_metrics.gpu_utilization_percent as u64),
312                parity: 0,
313            },
314            NQuin {
315                subject: crate::q_hash(job_id),
316                predicate: crate::q_hash("q42:hasConvergence"),
317                object: (result.convergence_info.final_residual as f64 * 1_000_000.0) as u64,
318                context: crate::q_hash("webgpu:convergence"),
319                metadata: ((result.convergence_info.iterations_used as u64) << 32)
320                    | (if result.convergence_info.converged {
321                        1
322                    } else {
323                        0
324                    }),
325                parity: 0,
326            },
327            NQuin {
328                subject: crate::q_hash(job_id),
329                predicate: crate::q_hash("q42:hasExecutionTime"),
330                object: result.execution_time_ms,
331                context: crate::q_hash("webgpu:performance"),
332                metadata: 0,
333                parity: 0,
334            },
335        ]
336    }
337}
338
339impl Default for WebGpuExtension {
340    fn default() -> Self {
341        Self::new()
342    }
343}
344
345/// Dispatch a solve to the real CPU reference solver for `shader_type`.
346pub(crate) fn run_solver(shader_type: ShaderType, params: &WebGpuJobParams) -> SolverReport {
347    match shader_type {
348        ShaderType::FluidDynamics => fluid::solve(params),
349        ShaderType::Electromagnetics => electromagnetics::solve(params),
350        ShaderType::HeatTransfer => heat::solve(params),
351        ShaderType::WavePropagation => wave::solve(params),
352        ShaderType::ParticleSimulation => particles::solve(params),
353        ShaderType::TensorOperations => tensor::solve(params),
354    }
355}
356
357/// Map an advertised operation to its default kernel name.
358fn operation_kernel(op: &str) -> Option<&'static str> {
359    Some(match op {
360        "simulate_fluid" => "navier_stokes_2d",
361        "solve_electromagnetics" => "maxwell_fdtd_1d",
362        "compute_heat_transfer" => "heat_diffusion_2d",
363        "propagate_waves" => "wave_equation_2d",
364        "simulate_particles" => "nbody_verlet",
365        "tensor_operations" => "tensor_gemm",
366        _ => return None,
367    })
368}
369
370#[async_trait]
371impl Extension for WebGpuExtension {
372    fn capability(&self) -> ExtensionCapability {
373        self.capability.clone()
374    }
375
376    async fn execute(&self, job: ExtensionJob) -> Result<ExtensionResult, ExtensionError> {
377        let start_time = Instant::now();
378
379        let kernel = operation_kernel(&job.operation)
380            .ok_or_else(|| ExtensionError::OperationNotSupported(job.operation.clone()))?;
381
382        // Parse caller params if present, otherwise run the solver's analytic
383        // default initial condition.
384        let mut params: WebGpuJobParams = match job.parameters.get("webgpu_params") {
385            Some(v) => serde_json::from_value(v.clone()).map_err(|e| {
386                ExtensionError::ExecutionFailed(format!("Invalid webgpu_params: {}", e))
387            })?,
388            None => WebGpuJobParams {
389                shader_name: kernel.to_string(),
390                grid_size: (0, 0, 0),
391                input_data: HashMap::new(),
392                uniform_data: HashMap::new(),
393                dispatch_params: DispatchParams::default(),
394            },
395        };
396        params.shader_name = kernel.to_string();
397
398        let result = self.execute_shader(params).await?;
399        let quins = Self::result_to_quins(&result, &job.job_id);
400
401        let mut metadata = HashMap::new();
402        metadata.insert("kernel".to_string(), kernel.to_string());
403        metadata.insert(
404            "tflops".to_string(),
405            result.performance_metrics.tflops_achieved.to_string(),
406        );
407        metadata.insert(
408            "converged".to_string(),
409            result.convergence_info.converged.to_string(),
410        );
411        metadata.insert(
412            "final_residual".to_string(),
413            result.convergence_info.final_residual.to_string(),
414        );
415
416        Ok(ExtensionResult {
417            job_id: job.job_id,
418            success: true,
419            result_quins: quins,
420            metadata,
421            execution_time_ms: start_time.elapsed().as_millis() as u64,
422        })
423    }
424
425    fn shutdown(&self) -> Result<(), ExtensionError> {
426        Ok(())
427    }
428}
429
430#[cfg(test)]
431mod tests {
432    use super::*;
433
434    fn job(op: &str) -> ExtensionJob {
435        ExtensionJob {
436            job_id: format!("job-{op}"),
437            extension_name: "webgpu".to_string(),
438            operation: op.to_string(),
439            parameters: HashMap::new(),
440            boundary_conditions: vec![],
441        }
442    }
443
444    #[tokio::test]
445    async fn capability_advertises_real_solvers() {
446        let ext = WebGpuExtension::new();
447        let cap = ext.capability();
448        assert_eq!(cap.name, "webgpu");
449        assert_eq!(cap.version, "2.0.0");
450        assert!(cap
451            .supported_operations
452            .contains(&"simulate_fluid".to_string()));
453        // GPU is optional now: the CPU reference path runs without one.
454        assert!(!cap.required_resources.requires_gpu);
455    }
456
457    #[tokio::test]
458    async fn every_advertised_operation_runs_a_real_solver() {
459        let ext = WebGpuExtension::new();
460        for op in [
461            "simulate_fluid",
462            "solve_electromagnetics",
463            "compute_heat_transfer",
464            "propagate_waves",
465            "simulate_particles",
466            "tensor_operations",
467        ] {
468            let res = ext.execute(job(op)).await.unwrap_or_else(|e| {
469                panic!("operation {op} failed: {e}");
470            });
471            assert!(res.success, "{op} did not succeed");
472            assert!(!res.result_quins.is_empty(), "{op} produced no quins");
473            assert!(
474                res.metadata
475                    .get("tflops")
476                    .map(|s| s != "0")
477                    .unwrap_or(false),
478                "{op} reported no measured throughput"
479            );
480        }
481    }
482
483    #[tokio::test]
484    async fn unknown_operation_is_rejected() {
485        let ext = WebGpuExtension::new();
486        let err = ext.execute(job("mine_bitcoin")).await.unwrap_err();
487        assert!(matches!(err, ExtensionError::OperationNotSupported(_)));
488    }
489
490    #[tokio::test]
491    async fn shader_specs_are_registered() {
492        let ext = WebGpuExtension::new();
493        let s = ext
494            .shader_manager
495            .loaded_shaders
496            .get("navier_stokes_2d")
497            .expect("navier_stokes_2d registered");
498        assert_eq!(s.shader_type, ShaderType::FluidDynamics);
499        assert_eq!(s.workgroup_size, (16, 16, 1));
500        assert!(!s.wgsl_source.is_empty());
501    }
502}