.. image:: https://raw.githubusercontent.com/lettucecfd/lettuce/master/.source/img/logo_lettuce_typo.png
.. image:: https://github.com/lettucecfd/lettuce/actions/workflows/CI.yml/badge.svg :target: https://github.com/lettucecfd/lettuce/actions/workflows/CI.yml :alt: CI Status
.. image:: https://readthedocs.org/projects/lettucecfd/badge/?version=latest :target: https://lettucecfd.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3757641.svg :target: https://doi.org/10.5281/zenodo.3757641
Lettuce is a Computational Fluid Dynamics framework based on the lattice Boltzmann method (LBM).
Documentation
_Paper
| Preprint
| Slides
| Video
| Code
_.. _Paper: https://www.springerprofessional.de/en/lettuce-pytorch-based-lattice-boltzmann-framework/19862378 .. _Documentation: https://lettuceboltzmann.readthedocs.io .. _Preprint: https://arxiv.org/pdf/2106.12929.pdf .. _Slides: https://drive.google.com/file/d/1jyJFKgmRBTXhPvTfrwFs292S4MC3Fqh8/view .. _Video: https://www.youtube.com/watch?v=7nVCuuZDCYA .. _Code: https://github.com/lettucecfd/lettuce-paper
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. The simplest example is:
Please ensure you have Jupyter installed to run the Jupyter notebooks.
.. _examples: https://github.com/lettucecfd/lettuce/tree/master/examples
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::
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
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}
}
We use the following third-party packages:
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage
project template.
.. Cookiecutter: https://github.com/audreyr/cookiecutter
.. audreyr/cookiecutter-pypackage
: https://github.com/audreyr/cookiecutter-pypackage
.. _pytorch: https://github.com/pytorch/pytorch .. _numpy: https://github.com/numpy/numpy .. _pytest: https://github.com/pytest-dev/pytest .. _click: https://github.com/pallets/click .. _matplotlib: https://github.com/matplotlib/matplotlib .. _versioneer: https://github.com/python-versioneer/python-versioneer .. _pyevtk: https://github.com/pyscience-projects/pyevtk .. _h5py: https://github.com/h5py/h5py .. _mmh3: https://github.com/hajimes/mmh3
.. _LICENSE: https://github.com/lettucecfd/lettuce/blob/master/LICENSE