lettucecfd / lettuce

Computational Fluid Dynamics based on PyTorch and the Lattice Boltzmann Method

GPU-accelerated Lattice Boltzmann Simulations in Python

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.

Resources

• Documentation
• Presentation at CFDML2021 - Paper | Preprint | Slides | Video | Code

Getting Started

The following Python code will run a two-dimensional Taylor-Green vortex on a GPU:

import torch
import lettuce as lt

lattice = lt.Lattice(lt.D2Q9, device='cuda', dtype=torch.float64, use_native=False)  # for running on cpu: device='cpu'
flow = lt.TaylorGreenVortex2D(resolution=128, reynolds_number=100, mach_number=0.05, lattice=lattice)
collision = lt.BGKCollision(lattice, tau=flow.units.relaxation_parameter_lu)
streaming = lt.StandardStreaming(lattice)
simulation = lt.Simulation(flow=flow, lattice=lattice, collision=collision, streaming=streaming)
mlups = simulation.step(num_steps=1000)
print("Performance in MLUPS:", mlups)

More advanced examples are available as jupyter notebooks.

Please ensure you have Jupyter installed to run these notebooks.

Installation

• Install the anaconda package manager from www.anaconda.org

• Create a new conda environment and install PyTorch:

  conda create -n lettuce -c pytorch -c nvidia pytorch pytorch-cuda=12.1

• Activate the conda environment:

  conda activate lettuce

• Install all requirements:

  conda install -c conda-forge -c anaconda matplotlib pytest click pyevtk h5py mmh3

• Clone this repository from github
• Change into the cloned directory

• Run the install script:

  python setup.py install

• Run the test cases:

  python setup.py test

• 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 drivers are installed and compatible with the installed cudatoolkit (see conda install command above).

• Check out the performance, running on GPU:

  lettuce benchmark

Citation

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}
}

Credits

We use the following third-party packages:

• pytorch
• numpy
• pytest
• click
• matplotlib
• versioneer
• pyevtk
• h5py
• mmh3

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

License

• Free software: MIT license, as found in the LICENSE file.