Initial commit: CelerisLab v0.2.0 with src layout
This commit is contained in:
Frank14f
@@ -0,0 +1,224 @@
|
||||
# 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 Lattice**: 2D nine-velocity lattice implementation
|
||||
- **MRT Collision Model**: Multiple-Relaxation-Time collision operator for improved stability
|
||||
- **Immersed Boundary Method (IBM)**: Support for complex geometries (cylinders, arbitrary shapes)
|
||||
- **Flexible Boundary Conditions**: Periodic, velocity inlet, pressure outlet
|
||||
- **Real-time Sensors**: Monitor flow properties at specific locations during simulation
|
||||
- **Vortex Initialization**: Built-in support for Lamb, Oseen, and Taylor vortices
|
||||
- **Dynamic Compilation**: Runtime CUDA kernel compilation with configurable parameters
|
||||
|
||||
## 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
|
||||
|
||||
### Basic Flow Simulation
|
||||
|
||||
```python
|
||||
from CelerisLab import FlowField, utils
|
||||
|
||||
# Load configurations
|
||||
config_cuda = utils.load_cuda_config() # Uses default or CELERISLAB_CONFIG_DIR
|
||||
config_field = utils.load_flow_field_config()
|
||||
|
||||
# Initialize flow field
|
||||
flow = FlowField(
|
||||
config_cuda=config_cuda,
|
||||
config_field=config_field,
|
||||
device_id=0
|
||||
)
|
||||
|
||||
# Add a cylinder obstacle
|
||||
flow.add_cylinder(
|
||||
center=(50, 50, 0),
|
||||
radius=10,
|
||||
velocity=(0, 0, 0),
|
||||
use_IBM=True
|
||||
)
|
||||
|
||||
# Add sensors to monitor flow
|
||||
flow.add_sensor(position=(70, 50, 0))
|
||||
|
||||
# Run simulation
|
||||
for step in range(10000):
|
||||
flow.run(1)
|
||||
|
||||
# Read sensor data every 100 steps
|
||||
if step % 100 == 0:
|
||||
sensor_data = flow.read_sensor()
|
||||
print(f"Step {step}: Velocity = {sensor_data[0]}")
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
CelerisLab searches for configuration files in the following order:
|
||||
|
||||
1. **Explicit path**: Passed to `load_*_config(config_path)`
|
||||
2. **Environment variable**: `CELERISLAB_CONFIG_DIR` environment variable
|
||||
3. **Current directory**: `./configs/` in current working directory
|
||||
4. **Package default**: Bundled `CelerisLab/configs/` directory
|
||||
|
||||
#### Configuration Files
|
||||
|
||||
**config_cuda.json**: CUDA execution parameters
|
||||
```json
|
||||
{
|
||||
"multi_gpu": false,
|
||||
"gpu_connection": "NVLINK",
|
||||
"required_cuda_capability": "6.0",
|
||||
"threads_per_block": 256,
|
||||
"X_1U": 16,
|
||||
"Y_1U": 16,
|
||||
"Z_1U": 1
|
||||
}
|
||||
```
|
||||
|
||||
**config_flowfield.json**: Flow physics parameters
|
||||
```json
|
||||
{
|
||||
"data_type": "FP32",
|
||||
"dimensionality": 2,
|
||||
"lattice": 9,
|
||||
"field_dim_in_U": [100, 100, 1],
|
||||
"viscosity": 0.01,
|
||||
"velocity": 0.1,
|
||||
"boundary_conditions": {
|
||||
"x": ["periodic", "periodic"],
|
||||
"y": ["periodic", "periodic"],
|
||||
"z": ["periodic", "periodic"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### FlowField Class
|
||||
|
||||
Main interface for running LBM simulations.
|
||||
|
||||
#### Constructor
|
||||
```python
|
||||
FlowField(config_cuda, config_field, device_id=0)
|
||||
```
|
||||
|
||||
#### Methods
|
||||
|
||||
- `add_cylinder(center, radius, velocity, use_IBM=False)`: Add cylindrical obstacle
|
||||
- `add_sensor(position)`: Add flow monitoring sensor
|
||||
- `add_vortex(center, circulation, core_radius, vortex_type='Lamb')`: Initialize vortex
|
||||
- `run(n_steps)`: Execute simulation steps
|
||||
- `read_sensor()`: Read current sensor values
|
||||
- `get_ddf()`: Get distribution function data
|
||||
- `apply_ddf(ddf)`: Set distribution function data
|
||||
|
||||
### Utility Functions
|
||||
|
||||
- `load_cuda_config(config_path=None)`: Load CUDA configuration
|
||||
- `load_flow_field_config(config_path=None)`: Load flow field configuration
|
||||
- `check_cuda_device_availability(device_id=0)`: Verify CUDA device
|
||||
- `get_device_info(device_id=0)`: Query GPU properties
|
||||
- `estimate_memory_consumption(config_field, num_objects, num_sensors)`: Calculate memory usage
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Custom Geometry with IBM
|
||||
|
||||
```python
|
||||
# IBM enables smooth treatment of curved boundaries
|
||||
flow.add_cylinder(
|
||||
center=(grid_x//2, grid_y//2, 0),
|
||||
radius=20,
|
||||
velocity=(0.0, 0.0, 0.0),
|
||||
use_IBM=True # Enables immersed boundary method
|
||||
)
|
||||
```
|
||||
|
||||
### Multiple Sensors
|
||||
|
||||
```python
|
||||
# Add sensors in a line downstream of obstacle
|
||||
for i in range(5):
|
||||
flow.add_sensor(position=(100 + i*10, 50, 0))
|
||||
|
||||
# Read all sensors at once
|
||||
sensor_data = flow.read_sensor() # Returns array of shape (n_sensors, 3)
|
||||
```
|
||||
|
||||
### Vortex Initialization
|
||||
|
||||
```python
|
||||
# Initialize Lamb-Oseen vortex
|
||||
flow.add_vortex(
|
||||
center=(50, 50, 0),
|
||||
circulation=1.0,
|
||||
core_radius=10.0,
|
||||
vortex_type='Lamb'
|
||||
)
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
- `CELERISLAB_CONFIG_DIR`: Directory containing configuration JSON files
|
||||
- `OMP_NUM_THREADS`: OpenMP thread count (recommend setting to 1 for GPU workflows)
|
||||
- `MKL_NUM_THREADS`: Intel MKL thread count (recommend setting to 1)
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. **Grid Size**: Choose dimensions that are multiples of `unit_dimensions` in config_cuda.json
|
||||
2. **Thread Block Size**: 256 threads/block works well for most GPUs
|
||||
3. **Memory**: Estimate memory with `utils.estimate_memory_consumption()` before large runs
|
||||
4. **Single-threaded Python**: Set `OMP_NUM_THREADS=1` to avoid CPU interference with GPU
|
||||
|
||||
## 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
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit issues and pull requests.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- Built with PyCUDA by Andreas Klöckner
|
||||
- Inspired by the palabos C++ LBM library
|
||||
Reference in New Issue
Block a user