1use 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
39pub struct WebGpuExtension {
41 shader_manager: WebGpuShaderManager,
42 capability: ExtensionCapability,
43}
44
45pub struct WebGpuShaderManager {
47 loaded_shaders: HashMap<String, WebGpuShader>,
48}
49
50#[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#[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#[derive(Debug, Clone, Serialize, Deserialize)]
72pub struct WebGpuJobParams {
73 pub shader_name: String,
75 pub grid_size: (u32, u32, u32),
77 pub input_data: HashMap<String, Vec<f32>>,
80 pub uniform_data: HashMap<String, f32>,
82 pub dispatch_params: DispatchParams,
84}
85
86#[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#[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#[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#[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
136pub struct SolverReport {
138 pub output: HashMap<String, Vec<f32>>,
140 pub iterations_used: u32,
142 pub final_residual: f32,
145 pub converged: bool,
147 pub flops: u64,
149}
150
151#[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#[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 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 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 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 pub async fn execute_shader(
263 &self,
264 params: WebGpuJobParams,
265 ) -> Result<WebGpuExecutionResult, ExtensionError> {
266 let shader_type = self.shader_type_for(¶ms.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, ¶ms);
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 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
345pub(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
357fn 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 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 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}