clearwater-rs — Shallow-Water Wave & Refractive Caustic Simulation in Pure Rust
clearwater-rs is a real-time shallow-water fluid dynamics and optical caustics engine written in safe Rust. It solves the 2D Saint-Venant shallow-water equations with semi-Lagrangian advection and traces surface normals via Snell's law to render interactive ripples, wakes, and underwater light caustics.
$ cargo add clearwater-rs
Architected for Speed & Reliability
Engineered from the ground up in memory-safe Rust with zero unnecessary dependencies.
Jerry Tessendorf 2D FFT Waves
Phillips and JONSWAP-style directional wave dispersion relations with shallow water tanh factor, choppy horizontal displacement vectors, and normal mapping.
Evan Wallace Refracted Caustics
Direct photon density accumulation on the seabed with flux conservation and multi-wavelength chromatic dispersion producing vibrant spectral fringing.
Interactive 2D Wave Grid
Localized 256x256 dynamic simulation grid tracking user droplets, disturbances, and ripples with smooth boundary dampening.
Marc Olano LEAN Mapping
Slope covariance matrix computation and Beckmann microfacet variance widening to prevent aliasing and sparkle flicker on distant wave horizons.
Pure Rust & Cross-Platform
Eliminates proprietary C++ dependencies, running seamlessly across Apple Silicon, Linux, and Windows with multi-threaded CPU and WGPU support.
Game Engine Integrations
Easily integrates into Bevy, Godot (via GDExtension or FFI), or standalone graphics pipelines.
Get Started in Seconds
Install via Cargo and run immediately on macOS, Linux, or Windows.
# Clone and run the Clearwater interactive demo
git clone https://github.com/bhubbard/clearwater-rs
cd clearwater-rs
# Run the live ocean wave and caustic simulation
cargo run --release --example ocean_demo
# Run comprehensive test suite
cargo testEngine Architecture
Streamlined execution pipeline with deterministic memory isolation and zero runtime overhead.
┌───────────────────────────────────────────────────────────┐
│ Interactive Disturbances / Droplets │
└─────────────────────────────┬─────────────────────────────┘
│
┌─────────────────────────────▼─────────────────────────────┐
│ 2D Wave Equation Grid + Discrete Laplacian │
└─────────────────────────────┬─────────────────────────────┘
│ Height & Gradient Map
┌─────────────────────────────▼─────────────────────────────┐
│ Jerry Tessendorf 2D FFT Wave Spectrum (Phillips) │
└─────────────────────────────┬─────────────────────────────┘
│ Choppy Displacements
┌─────────────────────────────▼─────────────────────────────┐
│ Evan Wallace Caustics Accumulation (RGB Dispersion) │
│ + Marc Olano LEAN Mapping Anti-Aliasing Filter │
└───────────────────────────────────────────────────────────┘