PyBurgers v2.0
Announcing PyBurgers v2.0
I’m excited to announce the release of PyBurgers v2.0. PyBurgers implements direct numerical simulation (DNS) and large-eddy simulation (LES) for studying Burgers turbulence, inspired by the procedures described in Basu (2009).
The version represents a complete rewrite of my 1D Stochastic Burgers Equation solver. This release delivers dramatic performance improvements, a modernized codebase, and new features for studying Burgers turbulence with DNS and LES. It provides a robust playground for students and educators to learn about numerical methods, how to write subgrid-scale (SGS) models, and to study the statistics of turbulence.
Why the Rewrite?
The original PyBurgers served its purpose as an educational tool, but performance limitations made it a pain for longer or more frequent simulations. It was slower than the original Matlab script that inspired PyBurgers. Version 2.0 addresses this head-on with a rewrite focused on speed and maintainability.
Performance That Speaks for Itself
The headline number: up to 65x faster than v1.0.
| Version | DNS (8192 pts) | LES (512 pts) |
|---|---|---|
| Matlab | ~35 min | ~16 min |
| v1.0 | ~43 min | ~23 min |
| v2.0 | ~40 sec | ~7 sec |
Benchmarked on M3 Max MacBook Pro with default namelist (200s simulation)
What used to take the better part of an hour now completes in under a minute. This opens up new possibilities for ensemble runs, sensitivity analyses, and prototyping of SGS models.
What Changed Under the Hood
Architectural changes:
- Real FFT operations — Switching from complex to real FFTs immediately cuts computation roughly in half for real-valued fields. - FFTW wisdom caching — FFT plans are expensive to compute. PyBurgers now saves optimized plans to disk and reuses them across runs, eliminating startup overhead.
- Efficient buffer management — Reduced memory allocations during time integration by reusing pre-allocated arrays.
- Spectral workspace — A centralized workspace bundles all spectral utilities, eliminating redundant FFT plan creation across the solver.
New Features
Four SGS Models
LES users now have access to a suite of SGS models:
- Constant-coefficient Smagorinsky
- Dynamic Smagorinsky
- Dynamic Wong-Lilly
- Deardorff 1.5-order TKE
Models are selected via the namelist with a simple integer flag, and adding new models follows a clean factory pattern.
Hyperviscosity
A new hyperviscosity option addresses spectral blocking at high-frequency wavenumbers, which can sometimes happen with the applied forcing methodology in pseudo-spectral codes.
Schema-Validated Configuration
The JSON namelist now includes comprehensive validation that catches configuration errors before the simulation starts.
Unit testing
PyBurgers now has Pytest-based tests for derivatives, FBM, filtering, SGS models, and integration.
Modern Python Throughout
PyBurgers v2.0 requires Python 3.10+ and embraces modern Python practices:
- Type hints throughout the codebase
- Abstract base class design for DNS/LES solvers
- Dataclass-based configuration management
- Clean separation of concerns across modules
Getting Started
Clone and install
git clone https://github.com/jeremygibbs/pyburgers.git
cd pyburgers
pip install -e .
Run a simulation
python burgers.py -m dns -o dns.nc
python burgers.py -m les -o les.nc
Visualize output
python scripts/plot_velocity.py dns.nc les.nc
python scripts/plot_spectra.py dns.nc les.nc
python scripts/plot_tke.py.py dns.nc les.nc
Requirements
- Python ≥ 3.10
- NumPy ≥ 2.1
- pyFFTW ≥ 0.15
- netCDF4 ≥ 1.7
Documentation
Full documentation, including changes, namelist options, and API reference is available at: https://docs.gibbs.science/pyburgers
Feedback
Feedback, bug reports, and contributions are welcome on https://github.com/jeremygibbs/pyburgers
