cuLBM

GPU-accelerated library for 2D Lattice-Boltzmann Method in Python

Features

• (Weakly) compressible D2Q9 discretization of the Navier-Stokes equations (without external forces)
• Runs on NVIDIA GPUs
• Different boundary conditions:
  • wall;
  • inlet, outlet pressure boundary conditions (based on Zou, He 1997);
  • slip;
  • periodic;
  • moving wall with velocity boundary condition (Zou, He 1997);
• Types of obstacles:
  • ellipses (or circles);
  • rectangles;
• Turbulence models:
  • Smagorinsky
• Surface-normal detection

Tests and benchmarks

• Poiseuille flow
• Potential flow around a cylinder
• Lid-driven cavity (comparison with openFOAM simulation)

Installation

Prerequisites

cuLBM is a simple library that uses CUDA kernels written in Python with Cupy and Numba to perform fluid dynamics simulations using the Lattice-Boltzmann method. To run cuLBM it is required that your environment has a recent Nvidia GPU with a CUDA toolkit. For futher information, refer to the Cupy installation here.

Note: for Cupy and Numba to correctly locate your CUDA installation you may have to set the environment variables CUDA_HOME and CUDA_PATH in your .bashrc or .bash_profile as follows (substitute with the path to the CUDA installation on your system, and replace version number as necessary):

export CUDA_HOME=/path/to/cuda/12.0 # numba
export CUDA_PATH=/path/to/cuda/12.0 # cupy

Installation steps

1. Create a conda environment:

   • Download miniforge and follow instructions at https://github.com/conda-forge/miniforge/#download
   • Create an environment called e.g. `cuLBM': conda create --name cuLBM python=3.14
   • Install pip conda install pip

2. Activate the environment (if not already activated):

   conda activate cuLBM
   

3. Clone the directory from GitHub and install the required packages:

   git clone git@github.com:LorenzoLMP/cuLBM.git
   cd cuLBM
   pip install -r requirements.txt
   

4. Add the directory of the cloned repository to your PYTHONPATH, e.g., in the .bash_profile:

   export PYTHONPATH=$PYTHONPATH:/path/to/cuLBM
   

5. Open a new shell (you may have to source the .bash_profile as well: source ~/.bash_profile). Check that the installation worked and that you can import cuLBM:

   python -c "import cuLBM"
   python -c "import cupy"
   python -c "from numba import cuda"
   

   If no error message appeared, you are good to go!