WaveSim3D - 3D Acoustic Wave Simulation

A comprehensive 3D acoustic wave simulation with realistic physics, binaural audio, and GPU acceleration.

Features

Realistic 3D Physics

• Temperature-dependent speed of sound: Uses accurate formula c = 331.3 * sqrt(1 + T/273.15) with humidity correction
• Frequency-dependent absorption: Implements ISO 9613-1 atmospheric absorption model
• Multiple propagation media:
  • Air: Temperature and humidity-dependent properties
  • Water: Bilaniuk-Wong speed of sound formula
  • Metal: Steel and aluminum with proper material properties

3D Wave Simulation

• FDTD (Finite-Difference Time-Domain) wave equation solver
• 7-point stencil Laplacian for accurate 3D propagation
• CFL stability automatically maintained: dt ≤ dx / (c * sqrt(3))
• Absorbing boundary conditions to minimize reflections
• Support for obstacles, reflectors, and custom geometries

Audio System

• Multiple source types:
  • Impulse (click/clap)
  • Continuous tone (sine wave)
  • Chirp (frequency sweep)
  • White/pink noise
  • Gaussian pulse
  • WAV file playback
• 3D positioned sources with real-time movement
• Binaural microphone with virtual head:
  • Realistic ear spacing (~17cm)
  • ITD (Interaural Time Difference) calculation
  • ILD (Interaural Level Difference) modeling
• WAV file I/O for recording and playback

GPU Acceleration

• Two computation methods:
  • Stencil: Traditional GPU stencil computation with shared memory tiling
  • Actor: Novel cell-as-actor paradigm with message-based halo exchange and HLC
• CUDA backend for NVIDIA GPUs
• CPU fallback with Rayon parallelization
• Volumetric ray marching for real-time 3D pressure field visualization

3D Visualization

• wgpu-based rendering (Vulkan, Metal, DX12)
• Interactive camera with orbit, pan, and zoom controls
• Slice visualization: XY, XZ, and YZ plane cuts
• Color mapping: Blue-White-Red pressure visualization
• Source and listener markers

Quick Start

# Run with CPU backend
cargo run -p ringkernel-wavesim3d --bin wavesim3d --features cpu

# Run with CUDA acceleration (requires NVIDIA GPU)
cargo run -p ringkernel-wavesim3d --bin wavesim3d --features cuda

Controls

Usage Example

use ringkernel_wavesim3d::simulation::{
    SimulationConfig, SimulationEngine, Environment, Position3D
};
use ringkernel_wavesim3d::audio::{AudioSystem, AudioSource, VirtualHead};

// Create simulation with custom environment
let config = SimulationConfig {
    width: 64,
    height: 32,
    depth: 64,
    cell_size: 0.1,  // 10cm cells
    environment: Environment {
        temperature_c: 20.0,
        humidity_percent: 50.0,
        medium: Medium::Air,
        ..Default::default()
    },
    prefer_gpu: true,
    computation_method: ComputationMethod::Stencil, // or ComputationMethod::Actor
    ..Default::default()
};

let mut engine = config.build();

// Add audio source
let mut audio = AudioSystem::new(Default::default());
let source = AudioSource::tone(
    0,
    Position3D::new(3.2, 1.6, 3.2),  // Source position
    440.0,  // Frequency (Hz)
    1.0,    // Amplitude
);
audio.add_source(source);

// Set up binaural microphone
let head = VirtualHead::new(Position3D::new(3.2, 1.6, 5.0));
audio.init_microphone(head, engine.grid.params.time_step);

// Run simulation steps
for _ in 0..1000 {
    engine.step();
    if let Some(mic) = &mut audio.microphone {
        mic.capture(&engine.grid);
    }
}

// Get binaural audio
if let Some(mic) = &audio.microphone {
    let (left, right) = mic.get_samples(1024);
    // Process or save stereo audio...
}

Physics Model

Wave Equation

The simulation solves the 3D acoustic wave equation:

∂²p/∂t² = c² ∇²p - α ∂p/∂t

Where:

• p is pressure
• c is speed of sound
• ∇² is the 3D Laplacian
• α is damping coefficient

FDTD Discretization

Using a 7-point stencil for the 3D Laplacian:

∇²p ≈ (p_W + p_E + p_S + p_N + p_D + p_U - 6p) / Δx²

Time stepping:

p_new = 2p - p_prev + c²Δt²∇²p

Atmospheric Absorption (ISO 9613-1)

Frequency-dependent absorption in air:

• Oxygen relaxation (dominant ~10 kHz)
• Nitrogen relaxation (dominant ~100 Hz)
• Classical absorption (molecular viscosity)

Configuration Options

Environment

Environment {
    temperature_c: 20.0,      // Temperature in Celsius
    humidity_percent: 50.0,   // Relative humidity
    pressure_pa: 101325.0,    // Atmospheric pressure (Pa)
    medium: Medium::Air,      // Air, Water, or Metal
}

Grid Size

• Recommended: 64x32x64 for real-time visualization
• Maximum frequency: f_max ≈ c / (10 * cell_size)
• For 10cm cells in air: ~343 Hz accurate simulation

Binaural Audio

• Default ear spacing: 17cm (average human)
• Sample rate: 44.1 kHz
• ITD range: ±0.6ms (full lateralization)

Benchmarks

Feature Flags

Dependencies

• wgpu: Cross-platform graphics
• winit: Window management
• egui: GUI controls
• glam: 3D math
• hound: WAV file I/O
• rayon: CPU parallelization
• cudarc: CUDA bindings (optional)

Related Crates

• ringkernel-wavesim: 2D wave simulation
• ringkernel-cuda-codegen: CUDA kernel generation

License

Same license as the parent RingKernel project.