First commit

2026-02-20 11:57:01 +08:00
commit 15c6de7243
17 changed files with 2451 additions and 0 deletions
@@ -0,0 +1,291 @@
+# 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](https://github.com/frank14f/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
+
+```bash
+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)
+
+```bash
+cd CelerisLab
+pip install -e .
+cd ..
+```
+
+#### Option B: Install from pip (if published)
+
+```bash
+pip install CelerisLab
+```
+
+### Step 3: Install DynamisLab dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### Step 4: Install DynamisLab in development mode
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+### Training a PPO Agent
+
+Train a Proximal Policy Optimization agent for flow control:
+
+```bash
+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
+
+```bash
+tensorboard --logdir tensorboard/
+```
+
+Then open http://localhost:6006 in your browser.
+
+### Using the Environment Programmatically
+
+```python
+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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "threads_per_block": 256,
+  "unit_dimensions": [16, 16, 1],
+  ...
+}
+```
+
+## Advanced Usage
+
+### Resume Training
+
+```bash
+python scripts/train_ppo.py \
+    --resume models/my_run_best.zip \
+    --run-name my_run_continued
+```
+
+### Custom Hyperparameters
+
+```bash
+python scripts/train_ppo.py \
+    --learning-rate 0.0003 \
+    --gamma 0.99 \
+    --batch-size 512 \
+    --n-steps 7200
+```
+
+### Multi-GPU Setup
+
+```bash
+# 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
+
+```bash
+pytest tests/
+```
+
+## Citation
+
+If you use DynamisLab in your research, please cite:
+
+```bibtex
+@software{dynamis2026,
+  author = {Frank14f},
+  title = {DynamisLab: Machine Learning for Computational Fluid Dynamics},
+  year = {2026},
+  url = {https://github.com/frank14f/DynamisLab}
+}
+```
+
+Also cite CelerisLab:
+
+```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
+
+## Acknowledgments
+
+- Built on [CelerisLab](https://github.com/frank14f/CelerisLab) CFD solver
+- Uses [Stable-Baselines3](https://github.com/DLR-RM/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.