An interactive, real-time 2D acoustic wave simulator built in Rust for physics education.
- Screenshots
- Overview
- Features
- Getting Started
- Configuration
- Lab Experiments
- Controls
- Platform Support
- License
Rust Wave Simulation 2D is a high-performance, interactive 2D wave physics simulator. It solves the acoustic wave equation using the FDTD (Finite-Difference Time-Domain) method on a staggered grid, rendered in real time with an egui-based GUI.
The application is designed for physics education — from high school to university level — and provides interactive tools to explore phenomena such as diffraction, interference, the Doppler effect, standing waves, and Mach cones. It is available in both English and Polish.
- FDTD wave solver with staggered pressure/velocity grids
- CPML (Convolutional Perfectly Matched Layer) absorbing boundaries
- Moving medium / advection via semi-Lagrangian method — produces Doppler shifts and Mach cones
- Multiple wave sources: point sources and plane-wave sources
- Per-source control of frequency, amplitude, and phase
- User-drawn obstacles for diffraction and reflection experiments
- Adjustable wave speed and damping
- Real-time numerical stability warning when wavelength approaches grid spacing
- Real-time rendering of pressure, velocity, or energy fields
- Multiple colormaps (BlueRed, Greyscale, Viridis, …)
- Adjustable amplitude scaling
- Stroboscope mode — freezes the display at each source cycle for clear wave pattern inspection
- Zoom and pan
- Oscilloscope — plots waveform over time at the cursor position and estimates the dominant frequency
- Built-in lab experiment guides with theory, equations, and step-by-step procedures:
- Single Slit Diffraction
- Doppler Effect
- Standing Waves
- All guides available in English and Polish
- Preset system — save and load full simulation configurations (auto-scales to any grid size)
- Comprehensive in-app help covering all controls, physics formulas, and a full
config.jsonreference
- Parallel FDTD update loop using Rayon
- Sin/cos lookup table for ~100× speedup over
libm - Persistent pixel buffer (zero allocation per frame)
- Decoupled physics and rendering (physics runs at its own rate; rendering targets 60 Hz)
- Background thread monitors CPU and RAM; can auto-pause on resource limits
-
Rust (stable, 2024 edition)
-
On Linux (building from source only), the following development packages are required to compile the project. They are not pre-installed on most distributions and are not needed if you use a pre-built binary from the Releases page.
Debian / Ubuntu:
sudo apt-get install -y libxcb-render0-dev libxcb-shape0-dev \ libxcb-xfixes0-dev libxkbcommon-dev libssl-devFedora / RHEL / CentOS:
sudo dnf install -y libxcb-devel libxkbcommon-devel openssl-devel
Arch Linux:
sudo pacman -S --needed libxcb libxkbcommon openssl
-
On macOS and Windows, no extra system dependencies are needed.
# Clone the repository
git clone https://github.com/Ciwiruk/rust_wave_simulation_2d.git
cd rust_wave_simulation_2d
# Optimised release build
cargo build --releaseThe binary is placed at target/release/rust_wave_simulation_2d (or rust_wave_simulation_2d.exe on Windows).
cargo run --releaseOr execute the compiled binary directly:
./target/release/rust_wave_simulation_2dAn optional config.json file placed in the same directory as the executable customises the simulation at startup. All keys are optional; unset keys use their defaults.
Example config.json:
{
"grid_width": 800,
"grid_height": 600,
"wave_speed": 10.0,
"damping": 0.5,
"default_frequency": 2.0,
"colormap": "BlueRed",
"language": "English"
}The application supports 61 configuration keys in total. Refer to the in-app Help → Config Reference panel for the full list with descriptions and valid ranges.
- Place
.jsonpreset files in apresets/folder next to the executable to have them auto-loaded at startup. - Place
.jsoninstruction files in aninstructions/folder to add custom lab guides that appear in the Instructions panel.
The following guided experiments are included (English and Polish):
| Experiment | Description |
|---|---|
| Single Slit Diffraction | Observe Huygens' principle, measure diffraction minima, verify a·sin(θ) = nλ |
| Doppler Effect | Explore frequency shifts with a moving source or a flowing medium; visualise Mach cones at supersonic speeds |
| Standing Waves | Set up resonance between two sources or using a reflective boundary; identify nodes and antinodes |
Each guide includes theory, key equations, recommended parameters, and step-by-step measurement procedures.
| Action | Control |
|---|---|
| Place / remove source | Left-click on the simulation canvas |
| Draw obstacle | Right-click drag on canvas |
| Erase obstacle | Middle-click drag (or eraser tool in toolbar) |
| Pan | Click and drag with the pan tool active |
| Zoom | Scroll wheel |
| Pause / Resume | Space or the Pause button |
| Reset simulation | Reset button in toolbar |
| Open Help | Help panel in the sidebar |
All parameters (wave speed, frequency, amplitude, damping, medium velocity, colormap, …) are controlled via the sidebar panels. A complete reference is available in the in-app Help.
Pre-built binaries are produced by CI for all targets below:
| Platform | Architecture | Binary |
|---|---|---|
| Windows | x86-64 | rust_wave_simulation_2d-windows-x64.exe |
| Windows | ARM64 | rust_wave_simulation_2d-windows-arm64.exe |
| Linux | x86-64 | rust_wave_simulation_2d-linux-x64 |
| Linux | ARM64 | rust_wave_simulation_2d-linux-arm64 |
| macOS | x86-64 | rust_wave_simulation_2d-macos-x64.zip |
| macOS | ARM64 (Apple Silicon) | rust_wave_simulation_2d-macos-arm64.zip |
Download the latest binaries from the Releases page.
Copyright © 2025 Wiktor Słowik. All Rights Reserved.
The source code is proprietary and confidential. The compiled executable may be used for non-commercial educational purposes at academic institutions. See LICENSE for the full terms.