DynamisLab

Machine Learning meets Numerical Simulation

DynamisLab is a research framework for combining machine learning techniques with numerical simulations. Built on top of CelerisLab, it provides standardized environments and training pipelines for various ML + CFD/Physics projects.

Current Projects

🎯 FlowStealth

Deep Reinforcement Learning for Active Flow Control, focusing on:

• Flow Stealth: Drag reduction and flow signature minimization
• Flow Illusion: Manipulating flow patterns for deception and control
• Methods: DRL (PPO) + CFD (Lattice Boltzmann Method)
• Location: src/flow_stealth/

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: Organized by research projects
• 📦 Standard Structure: Follows Python packaging best practices

Project Structure

DynamisLab/
├── src/                            # Source code (organized by project)
│   └── flow_stealth/               # FlowStealth: DRL + CFD Active Control
│       ├── __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 for FlowStealth
├── configs/                        # Configuration files
│   ├── config_cuda.json            # CUDA settings
│   ├── config_flowfield.json       # Flow field parameters
│   └── config_gym.json             # Environment settings
├── CelerisLab/                     # CelerisLab submodule (GPU-accelerated CFD)
├── 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 flow_stealth.environments import CFDFlowControlEnv
from flow_stealth.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
• Organize projects under src/ (e.g., src/flow_stealth/)
• Keep training scripts in scripts/
• Use config.py for all path and configuration management

Adding a New Project

1. Create new project directory in src/ (e.g., src/my_new_project/)
2. Add __init__.py, config.py, and project-specific modules
3. Create environments in src/my_new_project/environments/
4. Create corresponding training scripts in scripts/

Adding a New Environment to FlowStealth

1. Create new environment class in src/flow_stealth/environments/
2. Inherit from gym.Env
3. Register in src/flow_stealth/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.