Skip to content

Latest commit

 

History

History
150 lines (99 loc) · 5.79 KB

README.rst

File metadata and controls

150 lines (99 loc) · 5.79 KB
Raw

https://raw.githubusercontent.com/lettucecfd/lettuce/master/.source/img/logo_lettuce_typo.png

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).

  • GPU-Accelerated Computation: Utilizes PyTorch for high performance and efficient GPU utilization.
  • Rapid Prototyping: Supports both 2D and 3D simulations for quick and reliable analysis.
  • Advanced Techniques: Integrates neural networks and automatic differentiation to enhance LBM.
  • Optimized Performance: Includes custom PyTorch extensions for native CUDA kernels.

Resources

Getting Started

To find some very simple examples of how to use lettuce, please have a look at the examples. These will guide you through lettuce's main features. Please ensure you have Jupyter installed to run the Jupyter notebooks.

The simplest example is:

lettuce/examples/00_simplest_TGV.py

Lines 6 to 21 in ef9830b

import torch
import lettuce as lt
flow = lt.TaylorGreenVortex(
lt.Context(dtype=torch.float64), # for running on cpu: device='cpu'
resolution=128,
reynolds_number=100,
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)
print("Performance in MLUPS:", mlups)

Installation

  • Install the anaconda or miniconda package manager from https://www.anaconda.org

  • Clone this repository from github and change to it:

    git clone https://github.com/lettucecfd/lettuce
cd lettuce

  • Update conda, create a new conda environment and activate it:

    conda update conda
conda create -n lettuce
conda activate lettuce

  • Follow the recommendations at https://pytorch.org/get-started/locally/ to install pytorch based on your GPU's CUDA version. You may need to install the nvidia toolkit. You may follow the instructions at https://developer.nvidia.com/cuda-downloads. You may need to check the compatibility of your NVIDIA driver with the desired CUDA version: https://docs.nvidia.com/deploy/cuda-compatibility/. To get your CUDA version, run:

    nvcc --version

  • For CUDA 12.1 (if supported by your GPU) use:

    conda install pytorch pytorch-cuda=12.1 -c pytorch -c nvidia

  • Install the remaining dependencies. _This will not include CUDA-support unless you installed pytorch-cuda!_:

    conda activate lettuce
conda install --file requirements.txt -c pytorch -c nvidia -c conda-forge

  • NOTE: Sometimes, the installation does not properly set the CUDA_HOME variable. In this case, you may install cudatoolkit and set CUDA_HOME to the package directory (it should containa /bin/nvcc/ subdirectory!).

  • If you want to only use lettuce, run the installation (from the lettuce base directory!). Ideally, use [PEP 517](https://peps.python.org/pep-0517/):

    pip install --use-pep517 .

  • If you are a developer, add the changeable-installation-flag (-e):

    pip install --use-pep517 -e .

  • Check out the convergence order, running on CPU:

    lettuce --no-cuda convergence

  • Run the test cases:

    pytest tests

  • 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

Citation

If you use Lettuce in your research, please cite the following paper:

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

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.