Skip to content

0.3.0

Latest

Choose a tag to compare

@McBs McBs released this 06 Oct 09:03
· 1 commit to master since this release
9ad0997

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 lt

Python 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:

  • Lattice was replaced by Context, which holds device and dtype. The stencil is passed to the flow instead.
  • Streaming is part of the Simulation; StandardStreaming no longer exists.
  • No component takes a lattice argument anymore: collision models and boundaries are constructed from their own parameters (e.g. a mask), observables take the flow.
  • Simulation.step(num_steps) became simulation(num_steps).
  • TaylorGreenVortex2D / TaylorGreenVortex3D were merged into TaylorGreenVortex.
  • The package layout changed: implementations live under lettuce.ext and lettuce.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)
  • PartiallySaturatedBC boundary condition (#244)
  • LambOseenVortex2D flow (#258)
  • ProgressReporter (#283), NaNReporter and HighMaReporter (#248)
  • Example project for flow around a cylinder with efficient halfway and interpolated bounce-back boundaries (#287)
  • Package extras cpu, cu124, cu126, cu128 and cu130 to select the PyTorch build

Fixes

  • HDF5Reporter silently 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 --version reports 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), pytest moved 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