@buley/hexgrid-3d 1.1.2 → 3.0.1

package/src/algorithms/FluidSimulationWebNN.ts

@@ -0,0 +1,141 @@
+/**
+ * WebNN implementation of Fluid Simulation.
+ * Attempts to map the Stable Fluids algorithm to a neural network graph
+ * for NPU acceleration.
+ */
+
+import { Vector3 } from '../math/Vector3';
+import { WebNNContext } from '../webnn/WebNNContext';
+import type { FluidConfig3D } from './FluidSimulation3D';
+
+// Extended WebNN types for GraphBuilder
+declare global {
+  interface MLGraphBuilder {
+    input(name: string, descriptor: MLOperandDescriptor): MLOperand;
+    constant(descriptor: MLOperandDescriptor, buffer: ArrayBufferView): MLOperand;
+    add(a: MLOperand, b: MLOperand): MLOperand;
+    sub(a: MLOperand, b: MLOperand): MLOperand;
+    mul(a: MLOperand, b: MLOperand): MLOperand;
+    div(a: MLOperand, b: MLOperand): MLOperand;
+    clamp(x: MLOperand, options?: { minValue?: number; maxValue?: number }): MLOperand;
+    build(outputs: Record<string, MLOperand>): Promise<MLGraph>;
+  }
+
+  interface MLOperandDescriptor {
+    dataType: 'float32' | 'float16' | 'int32' | 'uint32';
+    dimensions: number[];
+  }
+
+  interface MLOperand {
+    // Opaque handle
+  }
+
+  interface Window {
+    MLGraphBuilder: {
+      new (context: MLContext): MLGraphBuilder;
+    };
+  }
+}
+
+export class FluidSimulationWebNN {
+  private width: number;
+  private height: number;
+  private depth: number;
+  private size: number;
+  
+  private density: Float32Array;
+  private velocityX: Float32Array;
+  private velocityY: Float32Array;
+  private velocityZ: Float32Array;
+
+  private context: WebNNContext;
+  private graph: MLGraph | null = null;
+  private builder: MLGraphBuilder | null = null;
+
+  constructor(config: FluidConfig3D) {
+    this.width = Math.round(config.width);
+    this.height = Math.round(config.height);
+    this.depth = Math.round(config.depth);
+    this.size = this.width * this.height * this.depth;
+
+    this.density = new Float32Array(this.size);
+    this.velocityX = new Float32Array(this.size);
+    this.velocityY = new Float32Array(this.size);
+    this.velocityZ = new Float32Array(this.size);
+
+    this.context = WebNNContext.getInstance();
+  }
+
+  async initialize(): Promise<boolean> {
+    const success = await this.context.initialize('npu');
+    if (!success) return false;
+
+    const mlContext = this.context.getContext();
+    if (mlContext && typeof window !== 'undefined' && window.MLGraphBuilder) {
+        this.builder = new window.MLGraphBuilder(mlContext);
+        await this.buildGraph();
+        return true;
+    }
+    return false;
+  }
+
+  private async buildGraph() {
+      if (!this.builder) return;
+      
+      // NOTE: WebNN 1.0 does not natively support the iterative loops required for
+      // discrete projection methods (Stabilized Fluids) efficiently within a single graph execution.
+      // 
+      // Current Implementation Strategy:
+      // 1. Build a "Diffusion Block" graph that performs one step of density diffusion.
+      // 2. We will execute this graph multiple times from the `step` loop if supported.
+      
+      const desc: MLOperandDescriptor = { dataType: 'float32', dimensions: [1, this.depth, this.height, this.width] };
+      const densityInput = this.builder.input('density', desc);
+      const decayConst = this.builder.constant({dataType: 'float32', dimensions: [1]}, new Float32Array([0.99]));
+      
+      // Basic Decay operation as placeholder for full PDE solver
+      const output = this.builder.mul(densityInput, decayConst);
+      
+      this.graph = await this.builder.build({ 'densityOut': output });
+  }
+
+  async step(dt: number) {
+      if (!this.graph || !this.context.getContext()) {
+          // Fallback or no-op
+          return;
+      }
+      
+      // Execute the graph
+      // Needs to bind inputs/outputs
+      // This is highly experimental logic as WebNN API/Browser support is in flux.
+      try {
+           // Mock execution for now until we have a real environment to test against
+           // In a real implementation: 
+           // this.context.getContext()!.compute(this.graph, inputs, outputs);
+      } catch (e) {
+          console.error("WebNN compute failed", e);
+      }
+  }
+  
+  // Public API compatibility with StableFluids3D
+  addDensity(x: number, y: number, z: number, amount: number, radius: number) {
+      // CPU implementation for interaction
+      // ... same as CPU ...
+  }
+  
+  addForce(pos: Vector3, force: Vector3, radius: number) {
+      // ... same as CPU ...
+  }
+  
+  getDensityAt(pos: Vector3): number {
+      return 0; // Readback from GPU/NPU required
+  }
+  
+  getVelocityAt(pos: Vector3): Vector3 {
+      return new Vector3(0,0,0);
+  }
+  
+  clear() {
+      this.density.fill(0);
+  }
+}

package/src/components/HexGrid.tsx

@@ -1,18 +1,61 @@
-import type { CSSProperties, RefObject } from 'react';
-import React from 'react';
-import type {
-  Photo as PhotoType,
-  HexGridProps as HexGridPropsType,
-  HexGridFeatureFlags,
-} from '../types';
 
-export type Photo = PhotoType;
+import React, { useEffect, useRef, useState } from 'react';
+import { FluidEngineFactory, FluidEngine } from '../algorithms/FluidEngineFactory';
+import { HexGridProps } from '../types';
 
-// Re-export the proper HexGridProps from types.ts
-export type { HexGridProps } from '../types';
+export function HexGrid(props: HexGridProps): React.JSX.Element {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const [engine, setEngine] = useState<FluidEngine | null>(null);
+  const [error, setError] = useState<string | null>(null);
 
-export function HexGrid(_props: HexGridPropsType): React.JSX.Element | null {
-  return null;
+  useEffect(() => {
+    // Initialize Fluid Engine
+    const initEngine = async () => {
+      try {
+        const fluidEngine = await FluidEngineFactory.create({
+          width: 64,
+          height: 64,
+          depth: 64,
+          viscosity: 0.0001,
+          diffusion: 0.00001
+        });
+        setEngine(fluidEngine);
+      } catch (err: unknown) {
+        console.error("Failed to init fluid engine", err);
+        setError(err instanceof Error ? err.message : String(err));
+      }
+    };
+
+    initEngine();
+
+    return () => {
+       // Cleanup if engine has cleanup method
+       if (engine && 'clear' in engine) {
+           engine.clear();
+       }
+    };
+  }, []);
+
+  if (error) {
+      return <div className="text-red-500">Error initializing simulation: {error}</div>;
+  }
+
+  return (
+    <div className="hexgrid-container" style={{ width: '100%', height: '100%', position: 'relative' }}>
+        {/* Visualization Canvas */}
+        <canvas 
+            ref={canvasRef} 
+            width={800} 
+            height={600}
+            style={{ width: '100%', height: '100%' }}
+        />
+        
+        {/* Status Overlay */}
+        <div style={{ position: 'absolute', top: 10, left: 10, background: 'rgba(0,0,0,0.5)', color: 'white', padding: '5px', pointerEvents: 'none' }}>
+            Engine: {engine ? engine.constructor.name : 'Initializing...'}
+        </div>
+    </div>
+  );
 }
 
 export default HexGrid;

package/src/types/wgsl.d.ts

@@ -0,0 +1,4 @@
+declare module '*.wgsl' {
+  const content: string;
+  export default content;
+}

package/src/webgpu/WebGPUContext.ts

@@ -0,0 +1,71 @@
+/**
+ * WebGPU Context Manager
+ * Handles the creation and management of the WebGPU Device and Adapter.
+ */
+
+export class WebGPUContext {
+  private static instance: WebGPUContext;
+  private adapter: GPUAdapter | null = null;
+  private device: GPUDevice | null = null;
+  private isSupported: boolean = false;
+
+  private constructor() {}
+
+  static getInstance(): WebGPUContext {
+    if (!WebGPUContext.instance) {
+      WebGPUContext.instance = new WebGPUContext();
+    }
+    return WebGPUContext.instance;
+  }
+
+  /**
+   * Initialize WebGPU context.
+   */
+  async initialize(): Promise<boolean> {
+    if (typeof navigator === 'undefined' || !navigator.gpu) {
+      console.warn('WebGPU is not supported in this environment.');
+      this.isSupported = false;
+      return false;
+    }
+
+    try {
+      this.adapter = await navigator.gpu.requestAdapter({
+        powerPreference: 'high-performance'
+      });
+
+      if (!this.adapter) {
+        console.warn('No WebGPU adapter found.');
+        this.isSupported = false;
+        return false;
+      }
+
+      this.device = await this.adapter.requestDevice();
+      
+      this.device.lost.then((info) => {
+        console.error(`WebGPU device lost: ${info.message}`);
+        this.device = null;
+        this.isSupported = false;
+      });
+
+      this.isSupported = true;
+      console.log('WebGPU initialized successfully.');
+      return true;
+    } catch (e) {
+      console.error('Failed to initialize WebGPU:', e);
+      this.isSupported = false;
+      return false;
+    }
+  }
+
+  getDevice(): GPUDevice | null {
+    return this.device;
+  }
+
+  getAdapter(): GPUAdapter | null {
+    return this.adapter;
+  }
+
+  isAvailable(): boolean {
+    return this.isSupported && this.device !== null;
+  }
+}

package/src/webgpu/shaders/fluid_sim.wgsl

@@ -0,0 +1,140 @@
+// fluid_sim.wgsl
+// 3D Fluid Simulation Compute Shaders
+
+struct FluidUniforms {
+  dt: f32,
+  width: f32,
+  height: f32,
+  depth: f32,
+  decay: f32,
+};
+
+@group(0) @binding(0) var<uniform> uniforms: FluidUniforms;
+
+// Bindings for Double-Buffering (Read -> Write)
+// Group 1: Velocity / Density
+@group(1) @binding(0) var field_in: texture_3d<f32>;
+@group(1) @binding(1) var field_out: texture_storage_3d<rgba16float, write>;
+
+// Sampler for linear interpolation
+@group(1) @binding(2) var field_sampler: sampler;
+
+// ----------------------------------------------------------------------------
+// ADVECTION
+// Moves quantities along the velocity field
+// ----------------------------------------------------------------------------
+@group(2) @binding(0) var velocity_field: texture_3d<f32>;
+
+@compute @workgroup_size(8, 8, 8)
+fn advect(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let dims = vec3<f32>(uniforms.width, uniforms.height, uniforms.depth);
+  let coords = vec3<f32>(global_id);
+
+  if (any(coords >= dims)) { return; }
+
+  // 1. Sample velocity at current position
+  // Note: textureSampleLevel requires normalized coordinates [0, 1]
+  let uvw = (coords + 0.5) / dims;
+  let vel = textureSampleLevel(velocity_field, field_sampler, uvw, 0.0).xyz;
+
+  // 2. Trace back in time
+  let dt = uniforms.dt;
+  // Scale velocity back to grid units?
+  // Uniforms velocity tends to be in grid-units per second.
+  // Backtrace coordinate:
+  let back_pos = coords - vel * dt;
+
+  // 3. Sample field at previous position
+  let back_uvw = (back_pos + 0.5) / dims;
+  let new_val = textureSampleLevel(field_in, field_sampler, back_uvw, 0.0);
+
+  // 4. Apply decay
+  let decayed = new_val * uniforms.decay;
+
+  textureStore(field_out, global_id, decayed);
+}
+
+// ----------------------------------------------------------------------------
+// DIFFUSION (Jacobi Iteration)
+// ----------------------------------------------------------------------------
+// x_new = (x_old + alpha * neighbor_sum) * inverse_beta
+struct JacobiUniforms {
+  alpha: f32,
+  rBeta: f32,
+};
+@group(3) @binding(0) var<uniform> jacobi: JacobiUniforms;
+@group(3) @binding(1) var b_field: texture_3d<f32>; // The 'b' vector in Ax=b (usually previous state or inputs)
+@group(3) @binding(2) var x_field: texture_3d<f32>; // The 'x' vector (current guess)
+
+@compute @workgroup_size(8, 8, 8)
+fn diffuse(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let dims = vec3<i32>(uniforms.width, uniforms.height, uniforms.depth);
+  let pos = vec3<i32>(global_id);
+  
+  if (any(pos >= dims)) { return; }
+
+  // Neighbors
+  let left   = textureLoad(x_field, pos + vec3<i32>(-1, 0, 0), 0);
+  let right  = textureLoad(x_field, pos + vec3<i32>(1, 0, 0), 0);
+  let down   = textureLoad(x_field, pos + vec3<i32>(0, -1, 0), 0);
+  let up     = textureLoad(x_field, pos + vec3<i32>(0, 1, 0), 0);
+  let back   = textureLoad(x_field, pos + vec3<i32>(0, 0, -1), 0);
+  let front  = textureLoad(x_field, pos + vec3<i32>(0, 0, 1), 0);
+
+  let bC = textureLoad(b_field, pos, 0);
+
+  // Jacobi step
+  let result = (left + right + down + up + back + front) * jacobi.alpha + bC;
+  let next_val = result * jacobi.rBeta;
+
+  textureStore(field_out, global_id, next_val);
+}
+
+// ----------------------------------------------------------------------------
+// DIVERGENCE
+// ----------------------------------------------------------------------------
+@compute @workgroup_size(8, 8, 8)
+fn divergence(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let dims = vec3<i32>(uniforms.width, uniforms.height, uniforms.depth);
+  let pos = vec3<i32>(global_id);
+
+  if (any(pos >= dims)) { return; }
+
+  let left   = textureLoad(field_in, pos + vec3<i32>(-1, 0, 0), 0).x;
+  let right  = textureLoad(field_in, pos + vec3<i32>(1, 0, 0), 0).x;
+  let down   = textureLoad(field_in, pos + vec3<i32>(0, -1, 0), 0).y;
+  let up     = textureLoad(field_in, pos + vec3<i32>(0, 1, 0), 0).y;
+  let back   = textureLoad(field_in, pos + vec3<i32>(0, 0, -1), 0).z;
+  let front  = textureLoad(field_in, pos + vec3<i32>(0, 0, 1), 0).z;
+
+  let div = 0.5 * ((right - left) + (up - down) + (front - back));
+
+  textureStore(field_out, global_id, vec4<f32>(div, 0.0, 0.0, 1.0));
+}
+
+// ----------------------------------------------------------------------------
+// GRADIENT SUBTRACTION
+// u_new = u_old - gradient(p)
+// ----------------------------------------------------------------------------
+@group(4) @binding(0) var pressure_field: texture_3d<f32>;
+
+@compute @workgroup_size(8, 8, 8)
+fn subtract_gradient(@builtin(global_invocation_id) global_id: vec3<u32>) {
+  let dims = vec3<i32>(uniforms.width, uniforms.height, uniforms.depth);
+  let pos = vec3<i32>(global_id);
+
+  if (any(pos >= dims)) { return; }
+
+  let pLeft   = textureLoad(pressure_field, pos + vec3<i32>(-1, 0, 0), 0).x;
+  let pRight  = textureLoad(pressure_field, pos + vec3<i32>(1, 0, 0), 0).x;
+  let pDown   = textureLoad(pressure_field, pos + vec3<i32>(0, -1, 0), 0).x;
+  let pUp     = textureLoad(pressure_field, pos + vec3<i32>(0, 1, 0), 0).x;
+  let pBack   = textureLoad(pressure_field, pos + vec3<i32>(0, 0, -1), 0).x;
+  let pFront  = textureLoad(pressure_field, pos + vec3<i32>(0, 0, 1), 0).x;
+
+  let old_vel = textureLoad(field_in, pos, 0).xyz;
+  let grad = vec3<f32>(pRight - pLeft, pUp - pDown, pFront - pBack) * 0.5;
+  let new_vel = old_vel - grad;
+
+  textureStore(field_out, global_id, vec4<f32>(new_vel, 1.0));
+}

package/src/webnn/WebNNContext.ts

@@ -0,0 +1,99 @@
+/**
+ * WebNN Context Manager
+ * Handles the creation and management of the WebNN MLContext.
+ * Prioritizes NPU -> GPU -> CPU.
+ */
+
+export type WebNNDeviceType = 'cpu' | 'gpu' | 'npu';
+
+export class WebNNContext {
+  private static instance: WebNNContext;
+  private context: MLContext | null = null;
+  private deviceType: WebNNDeviceType = 'cpu';
+  private isSupported: boolean = false;
+
+  private constructor() {}
+
+  static getInstance(): WebNNContext {
+    if (!WebNNContext.instance) {
+      WebNNContext.instance = new WebNNContext();
+    }
+    return WebNNContext.instance;
+  }
+
+  /**
+   * Initialize WebNN context with preferred device type.
+   */
+  async initialize(preference: WebNNDeviceType = 'npu'): Promise<boolean> {
+    if (typeof navigator === 'undefined' || !navigator.ml) {
+      console.warn('WebNN is not supported in this environment.');
+      this.isSupported = false;
+      return false;
+    }
+
+    try {
+      // Try preferred device first
+      this.context = await navigator.ml.createContext({ deviceType: preference });
+      this.deviceType = preference;
+      this.isSupported = true;
+      console.log(`WebNN initialized successfully on ${preference}`);
+      return true;
+    } catch (e) {
+      console.warn(`Failed to initialize WebNN on ${preference}, trying fallback chain...`, e);
+      
+      // Fallback chain: NPU -> GPU -> CPU
+      const chain: WebNNDeviceType[] = ['npu', 'gpu', 'cpu'];
+      const startIndex = chain.indexOf(preference) + 1;
+
+      for (let i = startIndex; i < chain.length; i++) {
+        const fallback = chain[i];
+        try {
+          this.context = await navigator.ml.createContext({ deviceType: fallback });
+          this.deviceType = fallback;
+          this.isSupported = true;
+          console.log(`WebNN initialized successfully on fallback ${fallback}`);
+          return true;
+        } catch (err) {
+            console.warn(`Failed to initialize WebNN on fallback ${fallback}`, err);
+        }
+      }
+    }
+
+    this.isSupported = false;
+    return false;
+  }
+
+  getContext(): MLContext | null {
+    return this.context;
+  }
+
+  getDeviceType(): WebNNDeviceType {
+    return this.deviceType;
+  }
+
+  isAvailable(): boolean {
+    return this.isSupported && this.context !== null;
+  }
+}
+
+// Type definitions for WebNN (since it might not be in standard lib yet)
+declare global {
+  interface Navigator {
+    ml: {
+      createContext(options?: { deviceType?: string }): Promise<MLContext>;
+    };
+  }
+
+  interface MLContext {
+    // Placeholder for MLContext methods
+    compute(graph: MLGraph, inputs: Record<string, ArrayBufferView>, outputs: Record<string, ArrayBufferView>): Promise<MLComputeResult>;
+  }
+
+  interface MLGraph {
+      // Opaque
+  }
+
+  interface MLComputeResult {
+      // Opaque
+  }
+}

package/tsconfig.json

@@ -18,8 +18,9 @@
     "baseUrl": ".",
     "paths": {
       "@/*": ["src/*"]
-    }
+    },
+    "types": ["@webgpu/types"]
   },
-  "include": ["src"],
+  "include": ["src", "src/**/*.wgsl"],
   "exclude": ["node_modules", "dist", "tests"]
 }