Awesome Open Source
Awesome Open Source CI Status Documentation Status

GPU-accelerated Lattice Boltzmann Simulations in Python

Lettuce is a Computational Fluid Dynamics framework based on the lattice Boltzmann method (LBM).

It provides

  • GPU-accelerated computation based on PyTorch
  • Rapid Prototyping in 2D and 3D
  • Usage of neural networks and automatic differentiation within LBM


When using lettuce please cite:

  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},
  organization={Springer Nature}

Getting Started

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

import torch
from lettuce import BGKCollision, StandardStreaming, Lattice, D2Q9, TaylorGreenVortex2D, Simulation

device = "cuda:0"   # for running on cpu: device = "cpu"
dtype = torch.float32

lattice = Lattice(D2Q9, device, dtype)
flow = TaylorGreenVortex2D(resolution=256, reynolds_number=10, mach_number=0.05, lattice=lattice)
collision = BGKCollision(lattice, tau=flow.units.relaxation_parameter_lu)
streaming = StandardStreaming(lattice)
simulation = 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:


  • Install the anaconda package manager from

  • Create a new conda environment and install all dependencies:

    conda create -n lettuce -c pytorch -c conda-forge\
         "pytorch>=1.2" matplotlib pytest click cudatoolkit "pyevtk>=1.2"
  • Activate the conda environment:

    conda activate lettuce
  • Clone this repository from github

  • Change into the cloned directory

  • Run the install script:

    python install
  • Run the test cases:

    python 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


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.
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Python (837,392
Machine Learning (38,590
Pytorch (21,659
Torch (2,062
Physics Simulation (616
Cfd (310
Lattice Boltzmann (51