Repository navigation
lettuce 0.3.0 is the first release since 0.2.3 (January 2023) and the first one published on PyPI. It contains a substantial rework of the core and is not backwards compatible with 0.2.x.
Installation
lettuce is now available on PyPI under the distribution name lettucecfd (the name lettuce is taken by an unrelated project). The import name and the command line tool are unchanged.
pip install lettucecfd
uv add lettucecfd
import lettuce as ltPython 3.12 or newer is required. For CUDA builds of PyTorch, see the installation section of the README.
Breaking changes
The core was rebuilt around a native CUDA code generator (#173, #279). Code written for 0.2.x needs to be adapted:
Latticewas replaced byContext, which holds device and dtype. The stencil is passed to the flow instead.- Streaming is part of the
Simulation;StandardStreamingno longer exists. - No component takes a
latticeargument anymore: collision models and boundaries are constructed from their own parameters (e.g. a mask), observables take theflow. Simulation.step(num_steps)becamesimulation(num_steps).TaylorGreenVortex2D/TaylorGreenVortex3Dwere merged intoTaylorGreenVortex.- The package layout changed: implementations live under
lettuce.extandlettuce.util. Import public classes from the top level (lt.BGKCollision) rather than from submodules. - Flows apply their boundaries via
post_boundary(#284).
0.2.3
lattice = Lattice(D2Q9, "cuda:0", torch.float32)
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)0.3.0
flow = lt.TaylorGreenVortex(lt.Context(device="cuda", dtype=torch.float32),
resolution=256, reynolds_number=10, mach_number=0.05, stencil=lt.D2Q9)
simulation = lt.Simulation(flow=flow,
collision=lt.BGKCollision(tau=flow.units.relaxation_parameter_lu),
reporter=[])
mlups = simulation(num_steps=1000)New features
- Native CUDA backend with code generation for stream-and-collide (#173, #279)
PartiallySaturatedBCboundary condition (#244)LambOseenVortex2Dflow (#258)ProgressReporter(#283),NaNReporterandHighMaReporter(#248)- Example project for flow around a cylinder with efficient halfway and interpolated bounce-back boundaries (#287)
- Package extras
cpu,cu124,cu126,cu128andcu130to select the PyTorch build
Fixes
HDF5Reportersilently stored float64 simulations in single precision- Corrected unit converter definition of the Taylor–Green vortex (#267)
- PyTorch indexing and deprecation warnings (#290)
- Porous medium example (#261)
Packaging and documentation
- Version is derived from git tags (setuptools-scm);
lettuce --versionreports it correctly - Complete package metadata and PEP 639 license information
- Rewritten API reference and usage page on Read the Docs; documentation builds without warnings
- New contributing guide (
CONTRIBUTING.md) - Removed unused dependencies (
vtk),pytestmoved to the dev group - Releases are published to PyPI automatically via trusted publishing
Citation
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},
pages={40},
organization={Springer Nature}
}Full changelog: 0.2.3...0.3.0