Lettuce is a Computational Fluid Dynamics framework based on the lattice Boltzmann method (LBM).
- GPU-Accelerated Computation: Utilizes PyTorch for high performance and efficient GPU utilization.
- Rapid Prototyping: Supports both 2D and 3D simulations for quick and reliable analysis.
- Advanced Techniques: Integrates neural networks and automatic differentiation to enhance LBM.
- Optimized Performance: Includes custom PyTorch extensions for native CUDA kernels.
To find some very simple examples of how to use lettuce, please have a look at the examples. These will guide you through lettuce's main features. Please ensure you have Jupyter installed to run the Jupyter notebooks.
Install the uv package manager from https://docs.astral.sh/uv/
Clone this repository from github and change to it:
git clone https://github.com/lettucecfd/lettuce cd lettuce
Create a new virtual environment and activate it:
uv venv source .venv/bin/activate
The pyproject.toml file currently requires at least CUDA 12.4 (we successfully tested CUDA 12.4, 12.6, 12.8 and 13.0). If your GPU does not support this version, you may need to downgrade it. Please note that we cannot guarantee the maintenance for older CUDA versions.
Run the install command, depending on your needs (run one of the three options below):
use lettuce (no development) with GPU support:
uv pip install .
use lettuce (no development) with CPU only or specific older CUDA versions (if you do not have access to a GPU or an older GPU) use (cpu, cu124, cu126):
uv pip install ".[cpu]"
use and develop lettuce (code changes take effect in program execution): use the changeable-installation-flag (-e):
uv pip install -e .
Check out the convergence order, running on CPU:
lettuce --no-cuda convergence
For running a CUDA-driven LBM simulation on one GPU omit the --no-cuda. If CUDA is not found, make sure that CUDA-capable GPU drivers are installed and compatible with the installed cudatoolkit (check cuda version number).
Check out the performance, running on GPU:
lettuce benchmark
Run the test cases:
pytest tests
If you use Lettuce in your research, please cite the following paper:
@inproceedings{bedrunka2021lettuce,
title={Lettuce: PyTorch-Based Lattice Boltzmann Framework},
author={Bedrunka, Mario Christopher and Wilde, Dominik and Kliemank, Martin and Reith, Dirk and Foysi, Holger and Kr{\"a}mer, Andreas},
booktitle={High Performance Computing: ISC High Performance Digital 2021 International Workshops, Frankfurt am Main, Germany, June 24--July 2, 2021, Revised Selected Papers},
pages={40},
organization={Springer Nature}
}
We use the following third-party packages:
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.
- Free software: MIT license, as found in the LICENSE file.