CelerisLab/README.md

# 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

```bash
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

```python
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:

```python
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`

```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`

```python
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

```python
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:

```bibtex
@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.