DynamisLab

Machine Learning for Computational Fluid Dynamics

DynamisLab is a research framework for applying reinforcement learning and machine learning techniques to computational fluid dynamics problems. Built on top of CelerisLab, it provides standardized environments and training pipelines for active flow control tasks.

Features

• 🌊 CFD Environments: Gymnasium-compatible environments for flow control
• 🤖 RL Integration: Ready-to-use with Stable-Baselines3 and other RL libraries
• 🚀 GPU Acceleration: Leverages CelerisLab's CUDA-accelerated LBM solver
• 📊 Experiment Tracking: Built-in TensorBoard integration
• 🔧 Modular Design: Clean separation of environments, configs, and training scripts
• 📦 Standard Structure: Follows Python packaging best practices (src layout)

Project Structure

DynamisLabNew/
├── src/                            # Source code (src layout)
│   ├── __init__.py
│   ├── config.py                   # Configuration management
│   └── environments/               # Gymnasium environments
│       ├── __init__.py
│       └── cfd_env.py              # CFD flow control environment
├── scripts/                        # Training and evaluation scripts
│   └── train_ppo.py                # PPO training script
├── configs/                        # Configuration files
│   ├── config_cuda.json            # CUDA settings
│   ├── config_flowfield.json       # Flow field parameters
│   └── config_gym.json             # Environment settings
├── models/                         # Trained model checkpoints (gitignored)
├── output/                         # Training data and results (gitignored)
├── tensorboard/                    # TensorBoard logs (gitignored)
├── docs/                           # Documentation
├── requirements.txt                # Python dependencies
├── pyproject.toml                  # Package configuration
└── README.md                       # This file

Installation

Prerequisites

• Python 3.8+
• NVIDIA GPU with CUDA support
• CUDA Toolkit 11.0+

Step 1: Clone the repository

git clone --recurse-submodules <your-repo-url> DynamisLab
cd DynamisLab

Note

: If CelerisLab is a submodule, use --recurse-submodules to clone it automatically.

Step 2: Install CelerisLab

Option A: Install from submodule (recommended for development)

cd CelerisLab
pip install -e .
cd ..

Option B: Install from pip (if published)

pip install CelerisLab

Step 3: Install DynamisLab dependencies

pip install -r requirements.txt

Step 4: Install DynamisLab in development mode

pip install -e .

Quick Start

Training a PPO Agent

Train a Proximal Policy Optimization agent for flow control:

python scripts/train_ppo.py \
    --run-name my_first_run \
    --device-id 0 \
    --total-timesteps 100 \
    --n-steps 3600 \
    --activation sin

Arguments:

• --run-name: Name for this training run (used for saving models and logs)
• --device-id: CUDA device ID for CFD simulation
• --cuda-device: CUDA device ID for PyTorch training (can be different from --device-id)
• --total-timesteps: Number of training iterations
• --n-steps: Environment steps per training iteration
• --activation: Activation function (sin, tanh, or relu)

Monitoring Training

tensorboard --logdir tensorboard/

Then open http://localhost:6006 in your browser.

Using the Environment Programmatically

from environments import CFDFlowControlEnv
from config import load_celeris_configs

# Load configurations
config_cuda, config_field = load_celeris_configs()

# Create environment
env = CFDFlowControlEnv(
    device_id=0,
    config_cuda=config_cuda,
    config_field=config_field,
)

# Run episode
obs, info = env.reset()
for step in range(500):
    action = env.action_space.sample()  # Random action
    obs, reward, terminated, truncated, info = env.step(action)
    
    if terminated or truncated:
        break

env.close()

Configuration

CFD Configuration

Edit configs/config_flowfield.json to change flow parameters:

{
  "viscosity": 0.01,          # Fluid viscosity
  "velocity": 0.1,            # Inlet velocity
  "field_dim_in_U": [400, 200, 1],  # Grid dimensions
  ...
}

CUDA Configuration

Edit configs/config_cuda.json for GPU settings:

{
  "threads_per_block": 256,
  "unit_dimensions": [16, 16, 1],
  ...
}

Advanced Usage

Resume Training

python scripts/train_ppo.py \
    --resume models/my_run_best.zip \
    --run-name my_run_continued

Custom Hyperparameters

python scripts/train_ppo.py \
    --learning-rate 0.0003 \
    --gamma 0.99 \
    --batch-size 512 \
    --n-steps 7200

Multi-GPU Setup

# CFD simulation on GPU 0, PyTorch training on GPU 1
python scripts/train_ppo.py \
    --device-id 0 \
    --cuda-device 1

Environment Details

CFDFlowControlEnv

The main environment for active flow control around a cylinder.

Observation Space:

• Dimensionality: n_sensors × 2 × 2 (velocity components, current + derivative)
• Default: 12 dimensions (3 sensors × 2 velocities × 2)
• Normalized to zero mean and unit variance

Action Space:

• Dimensionality: n_control_cylinders
• Default: 3 (three controllable cylinders)
• Range: [-1, 1] (scaled internally to physical velocities)

Reward:

• Drag reduction: -cd × 0.1
• Lift minimization: -|cl| × 0.05
• Flow similarity: -similarity_distance × 0.5
• Total reward is sum of components

Episode:

• Max steps: 500 (configurable)
• Simulation runs at 800 LBM steps per environment step

Development

Project Guidelines

• Follow PEP 8 style guide
• Use type hints for function signatures
• Document classes and functions with docstrings
• Keep environments in src/dynamis/environments/
• Keep training scripts in scripts/
• Use config.py for all path and configuration management

Adding a New Environment

1. Create new environment class in src/dynamis/environments/
2. Inherit from gym.Env
3. Register in src/dynamis/environments/__init__.py
4. Create corresponding training script in scripts/

Running Tests

pytest tests/

Citation

If you use DynamisLab in your research, please cite:

@software{dynamis2026,
  author = {Frank14f},
  title = {DynamisLab: Machine Learning for Computational Fluid Dynamics},
  year = {2026},
  url = {https://github.com/frank14f/DynamisLab}
}

Also cite CelerisLab:

@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

Acknowledgments

• Built on CelerisLab CFD solver
• Uses Stable-Baselines3 for RL
• Gymnasium API for standardized environments

Contributing

Contributions are welcome! Please open an issue or pull request.

Contact

For questions or issues, please open a GitHub issue or contact Frank14f.