je-santos / 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).

It provides

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

Resources

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

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:

• A First Example
• Decaying Turbulence

Installation

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

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

Credits

We use the following third-party packages:

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

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

License

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