Welcome to lettuce’s documentation!¶

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 - Paper | Preprint | Slides | Video | Code

When using lettuce please cite:

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

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:

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:

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

License¶

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

Installation¶

From sources¶

The sources for lettuce can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/lettucecfd/lettuce

Or download the tarball:

$ curl  -OL https://github.com/lettucecfd/lettuce/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

Usage¶

To use lettuce in a project:

import lettuce

API¶

Simulation¶

Lattice Boltzmann Solver

class lettuce.simulation.Simulation(flow, lattice, collision, streaming)[source]

Bases: object

High-level API for simulations.

reporters¶

A list of reporters. Their call functions are invoked after every simulation step (and before the first one).

Type:	list

initialize(max_num_steps=500, tol_pressure=0.001)[source]

Iterative initialization to get moments consistent with the initial velocity.

Using the initialization does not better TGV convergence. Maybe use a better scheme?

initialize_f_neq()[source]: Initialize the distribution function values. The f^(1) contributions are approximated by finite differences. See Krüger et al. (2017).

initialize_pressure(max_num_steps=100000, tol_pressure=1e-06)[source]: Reinitialize equilibrium distributions with pressure obtained by a Jacobi solver. Note that this method has to be called before initialize_f_neq.

load_checkpoint(filename)[source]: Load f as np.array using pickle module.

save_checkpoint(filename)[source]: Write f as np.array using pickle module.

step(num_steps)[source]: Take num_steps stream-and-collision steps and return performance in MLUPS.

Lattices¶

Stencils and Lattices.

A Stencil, like the D1Q3 class, provides particle velocities (e), weights (w), and speeds of sound. Velocities and weights are stored as numpy arrays.

In contrast, the Lattice lives on the Device (usually a GPU) and its vectors are stored as torch tensors. Its stencil is still accessible trough Lattice.stencil.

class lettuce.lattices.Lattice(stencil, device, dtype=torch.float32)[source]

Bases: object

D

Q

classmethod convert_to_numpy(tensor)[source]

convert_to_tensor(array)[source]

einsum(equation, fields, **kwargs)[source]: Einstein summation on local fields.

entropy(f)[source]: entropy according to the H-theorem

incompressible_energy(f)[source]: incompressible kinetic energy

j(f)[source]: momentum

mv(m, v)[source]: matrix-vector multiplication

pseudo_entropy_global(f)[source]: pseudo_entropy derived by a Taylor expansion around the weights

pseudo_entropy_local(f)[source]: pseudo_entropy derived by a Taylor expansion around the local equilibrium

rho(f)[source]: density

shear_tensor(f)[source]: computes the shear tensor of a given f in the sense Pi_{lpha eta} = f_i * e_{i lpha} * e_{i eta}

u(f, rho=None, acceleration=None)[source]: velocity; the acceleration is used to compute the correct velocity in the presence of a forcing scheme.

Stencils¶

class lettuce.stencils.Stencil[source]

Bases: object

classmethod D()[source]

classmethod Q()[source]

class lettuce.stencils.D1Q3[source]