2026-04-17 21:50:38 +08:00

6.0 KiB

Raw Blame History

CelerisLab

GPU-Accelerated Lattice Boltzmann Method (LBM) CFD Solver

CelerisLab is a high-performance computational fluid dynamics (CFD) solver based on the Lattice Boltzmann Method, leveraging NVIDIA CUDA for GPU acceleration. It provides a Python interface for easy integration into scientific workflows while maintaining high computational efficiency through CUDA kernels.

Features

GPU Acceleration: CUDA-based kernels for high-performance simulations
D2Q9 / D3Q19 Lattice: 2D and 3D lattice implementations
Multiple Collision Models: SRT, TRT, and MRT operators; Smagorinsky LES subgrid model
Dual Streaming Paths: Standard double-buffer pull and memory-efficient esoteric-pull (EsoPull)
Immersed Boundary Method (IBM): Support for complex geometries (cylinders, arbitrary shapes)
Flexible Boundary Conditions: NEQ-extrapolation pressure outlet, parabolic/uniform velocity inlet, half-way bounce-back walls
Layered Configuration: Compile-time parameters organized into Global / Method / Case / Debug tiers
High-Re Validated: Tested up to Re=5000 (2D cylinder); MRT+LES and SRT+LES stable; TRT+LES stable with tuned Lambda and WMAX
Python API: High-level Simulation class for scripting and RL integration

Installation

Prerequisites

Python 3.8 or higher
NVIDIA GPU with CUDA Compute Capability 6.0 or higher
CUDA Toolkit 11.0 or higher
NVIDIA drivers

Install from source

git clone <repository_url>
cd CelerisLab
pip install -e .  # Installs from src/ directory

Dependencies

pycuda>=2020.1: CUDA Python bindings
numpy>=1.19.0: Numerical computing
scipy>=1.5.0: Scientific computing (special functions for vortex initialization)

Quick Start

from CelerisLab import Simulation

sim = Simulation("configs/config_lbm.json")
sim.add_cylinder(center=(50, 50), radius=10)
sim.initialize()

for step in range(10000):
    sim.run(1)

macro = sim.get_macroscopic()  # {"rho": ..., "ux": ..., "uy": ...}
sim.close()

Or as a context manager:

with Simulation("configs/config_lbm.json") as sim:
    sim.add_cylinder(center=(96, 64), radius=12)
    sim.initialize()
    sim.run(5000)
    data = sim.get_macroscopic()

Configuration

`configs/config_lbm.json`

{
  "dim": 2,
  "nq": 9,
  "nx": 384,
  "ny": 192,
  "nz": 1,
  "viscosity": 0.0005,
  "velocity": 0.04,
  "rho": 1.0,
  "collision": "MRT",
  "streaming": "double_buffer",
  "les_enabled": true,
  "les_cs": 0.16,
  "trt_magic_param": 0.001,
  "omega_max": 1.90,
  "inlet_profile": "parabolic",
  "outlet_mode": "neq_extrap",
  "compute_capability": "auto",
  "threads_per_block": 256
}

Parameter tiers

Tier	Headers	Examples
Global/Grid	`config_grid.h`	DIM, NQ, NX, NY, NZ
Global/Physics	`config_physics.h`	VIS, RHO, U0, flag constants
Method	`config_method.h`	COLLISION_MODEL, USE_LES, TRT_MAGIC_PARAM, OMEGA_COLLISION_MAX
Case	`config_objects.h`	N_OBJS

Headers are auto-generated by the compiler from LBMConfig; do not edit manually.

API Reference

`Simulation`

sim = Simulation(lbm_config_path=None, body_config_path=None, device_id=0)
sim.add_cylinder(center, radius) -> int
sim.add_sensor(center, radius)  -> int
sim.initialize()
sim.run(steps)
sim.step(n=1)
sim.get_macroscopic() -> {"rho": ndarray, "ux": ndarray, "uy": ndarray}
sim.get_ddf()    -> ndarray
sim.get_flags()  -> ndarray
sim.update_runtime_params(omega=..., u_inlet=...)
sim.snapshot() / sim.restore()
sim.close()

Vortex initialization

from CelerisLab.lbm.initializers import add_vortex

# Superimpose a Lamb–Oseen vortex on an existing LBMField
add_vortex(sim.field, center=(50, 50), radius=10.0, strength=1.0, vortex_type="lamb")

Collision & LES Recommendations

Use case	Recommended config
Low Re (≤ 500)	SRT or TRT, LES off
Medium Re (500–2000)	MRT or SRT+LES
High Re (2000–5000)	MRT+LES (most robust); SRT+LES; TRT+LES with `omega_max=1.90`, `trt_magic_param=0.001`

Project Layout

src/CelerisLab/
  simulation.py          High-level API
  config.py              LBMConfig / BodyConfig dataclasses
  cuda/
    compiler_v2.py       Config header generation + nvcc + PTX load
    context.py           CUDA context lifecycle
  lbm/
    field.py             GPU memory management
    stepper.py           Time-step driver
    initializers.py      Vortex superposition
    kernels/
      kernel_v2.cu       Kernel entry (thin wrapper)
      config/            Auto-generated config headers
      core/              Descriptors, layout, flags, params
      operators/         Collision, LES, forcing
      boundary/          Inlet, outlet, wall, curved, IBM
      streaming/         Double-buffer & esopull
      step/              Step orchestration
  body/
    objects.py           SimObject / Cylinder / Sensor
    manager.py           ObjectManager + GPU sync
  common/
    preprocess.py        Geometry utilities
tests/
  test_stability_matrix.py    13-case stability matrix (Re × collision × LES × streaming)
  test_high_re_validation.py  High-Re directed validation (Re5000, 2D/3D, parameter sweep)
output/
  CelerisLab_stage1_architecture.md   Architecture specification (v3)
  refactor_brief_stage1.md            Refactoring brief
  high_re_audit_round1.md             8-round audit log
legacy/                               Superseded code (FlowField, compiler v1, macros.h)

Performance

Tested on Tesla V100-SXM2-16GB (CUDA 12.4):

Config	Grid	MLUPS
Re100 MRT noLES	384×192	~4200
Re100 EsoPull SRT	384×192	~3900
Re3000 MRT+LES	384×192	~4360

Citation

If you use CelerisLab in your research, please cite:

@software{celerislab2026,
  author = {Frank14f},
  title = {CelerisLab: GPU-Accelerated Lattice Boltzmann Method Solver},
  year = {2026},
  url = {https://github.com/frank14f/CelerisLab}
}

License

MIT License — see LICENSE file for details.

6.0 KiB Raw Blame History Unescape Escape