chore(repo): close out project indexes and evidence boundaries

Add a canonical src package index, synchronize cross-project status and root navigation, and ignore local generated/runtime payloads while preserving the documented solver and evidence boundaries. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-09 22:32:55 +08:00
parent 86157c6f31
commit 140eea4d25
14 changed files with 638 additions and 2789 deletions
@@ -2,277 +2,149 @@

 **Machine Learning meets Numerical Simulation**

-DynamisLab is a research framework for combining machine learning techniques with numerical simulations. Built on top of [CelerisLab](https://github.com/frank14f/CelerisLab), it provides standardized environments and training pipelines for various ML + CFD/Physics projects.
+DynamisLab 是一个面向机器学习与数值模拟交叉研究的框架，当前主线是二维 fluidic pinball（三圆柱）主动流动控制：以 GPU 加速 Lattice Boltzmann Method（LBM）求解流场，用 PPO 等策略驱动圆柱旋转，并用 Symbolic Regression（SR）、Corrected Cross-Covariance Decomposition（CCD）、Observable Identification（OID）和稳态理论分析审查控制规律与证据边界。

-## Current Projects
+项目关注的科学问题是：有限的力/速度观测和三个旋转执行器，能否使下游流动接近无扰动基准（Kármán cloaking/stealth）或指定目标流动（Illusion），以及可复现证据究竟支持到“性能、控制结构、统计共变、稳态关联或机制”的哪一层。仓库不是一个已经证明普适机理的成品库；它同时保存可执行代码、当前受限结论、失败结果和历史路线。

-### 🎯 FlowStealth
+## 当前状态（2026-08-09）

-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/`
+- **活跃（active）**：现代 CelerisLab V5 的 `drl_pinball` 训练/评估工作流与保留的 compact policy bundles；Legacy Kármán SR 的受限结论；corrected Kármán CCD 的描述性 phase-coherent co-variation 结果；稳态 pinball 的 NS-first 后续验证路线。
+- **受限（bounded）**：稳态端点、有限时域瞬态和 article publication 已形成可审计证据，但机制、因果性及渐近/全局稳定性未建立；现代 V5 发布可复现训练接口和部分保留模型，不表示所有 case/seed 已按当前代码完整重训并验证；Legacy 标准化 SR 图包仍是 partial Kármán package。
+- **历史/负结果（historical/negative）**：Illusion SR 已失败并关闭为科学解释路线；OID 的 2026-07 双场景研究降级为条件性历史材料；早期 reproduce、CCD/OID 分支和被替代实现均保留在各级 `archive/`。

-## Features
+必须区分两个不同命题：**Illusion PPO 是仓库仍支持的训练与确定性评估能力**，包括现代 `train_illusion.py`、目标及 harmonics 合约；**Illusion SR 则不是有效科学结果**。长窗口 Legacy 标准化采集显示保留的 SR 动作衰减到接近 physical zero，未显示相对 zero 的有意义收益，因此不得把旧的 200/400-step target similarity 写成 Illusion SR efficacy、target tracking 或跨尺寸泛化。

- 🌊 **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
+Kármán CCD 只支持 DRL 相对 constant-control phase template 的描述性共变及稳定 rank-3 subspace；它不是配对反事实、因果效应、响应时间、机制、explained variance，也不证明 CCD 优于 POD。稳态结果同样尚未闭合 Navier–Stokes 机制链；potential-circulation cancellation 已失败，有限时域关联不得升级为因果性或全局稳定性。OID 当前是 claim-free CPU method core，不承载活跃科学结论。

-## 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
-```
+先看 [`src/README.md`](src/README.md) 获取源码包总索引，再按项目进入权威文档。

-## Installation
+1. 本页：项目范围、状态和证据规则。
+2. [`src/drl_pinball/train/README.md`](src/drl_pinball/train/README.md)：现代 V5 校准、训练与保留产物。
+3. [`src/drl_pinball/eval/README.md`](src/drl_pinball/eval/README.md)：canonical V5 确定性评估及 fail-closed 合约。
+4. [`src/SR_analysis/README.md`](src/SR_analysis/README.md)：Legacy Kármán SR 主张、Illusion SR 负结果和不可变证据链。
+5. [`src/CCD_analysis/README.md`](src/CCD_analysis/README.md)：corrected Kármán CCD 当前唯一结果权威。
+6. [`src/steady_pinball_theory/README.md`](src/steady_pinball_theory/README.md) 与 [`src/OID_analysis/README.md`](src/OID_analysis/README.md)：稳态受限路线与 OID scientific reset。

-### Prerequisites
+继续复现实验前，再读对应 package 的 pipeline、contract、results、handoff 和 archive index；不要只依据旧图、文件名或历史 README 作结论。

- Python 3.8+
- NVIDIA GPU with CUDA support
- CUDA Toolkit 11.0+
+## 包与目录地图

-### Step 1: Clone the repository
+- [`src/drl_pinball/`](src/drl_pinball/) — 主运行包。`train/` 是现代 2000×600 CelerisLab V5 校准/训练；`eval/` 是 V5 评估；`legacy_test/` 在 LegacyCelerisLab 上执行统一的历史角色采集；`legacy_env/`、`legacy_train/` 和局部 `archive/` 服务于兼容与溯源。状态：**active + bounded + historical**。
+- [`src/SR_analysis/`](src/SR_analysis/) — 在冻结 PPO 轨迹上发现、拟合并于 Legacy CFD 闭环验证符号控制器。当前只保留 Kármán/cloaking 为 **active but bounded**；Illusion SR 是 **historical/negative**，steady 仅作幅值校准背景。
+- [`src/CCD_analysis/`](src/CCD_analysis/) — corrected `karman_re100` ROI mean 与 cycle-template CCD 的精简权威入口。状态：**completed descriptive/bounded**；旧 temporal/phase 与 pre-reset 树为 **superseded historical**。
+- [`src/OID_analysis/`](src/OID_analysis/) — weighted snapshot POD、Schlegel LR/LE maps、配对和原子 artifact 校验。状态：**active method core, no active science claim**；2026-07 两场景研究为条件性历史材料。
+- [`src/steady_pinball_theory/`](src/steady_pinball_theory/) — rear-symmetric steady rotation 的分析、finite-Re 数值证据与 NS-first 验证。状态：**active investigation, bounded evidence**；尚无完成的稳态机制证明。
+- [`src/pv_plot/`](src/pv_plot/) — ParaView/FFmpeg 轻量 PNG/MP4 渲染接口，不是独立服务或 pip 项目。状态：**active utility**。
+- [`src/archive/`](src/archive/) — 被替代的现代 solver reproduction Track B 等仓库级历史材料；各 package 自己的 `archive/` 也属于其 provenance chain。状态：**historical, non-authoritative unless an active document explicitly cites it**。
+- [`CelerisLab/`](CelerisLab/) — Git submodule，现代 GPU LBM solver。Legacy solver 及其证据依赖按各 package 文档和本地环境解析；不要把两个 solver 的结果静默合并。
+
+## 两条 solver 证据链
+
+**LegacyCelerisLab** 是 SR article chain、标准化 Legacy acquisition 以及 corrected CCD 输入所依赖的历史 plant。其冻结模型、normalization、动作顺序、EMA、边界条件、采样时钟和 immutable manifests 共同定义证据；可从 [`src/drl_pinball/legacy_test/README.md`](src/drl_pinball/legacy_test/README.md) 进入。
+
+**现代 CelerisLab V5** 是当前 `drl_pinball/train` 与 `drl_pinball/eval` 的 2000×600 工作流，使用新的 Simulation API、calibration/target bundle 和 registry。仓库保留了可推理的 compact bundles 与评估基线，但这不等于当前实现已经完成全矩阵重训，也不允许用 V5 replay 自动替代 Legacy article evidence。
+
+两条链的网格、边界实现、动作换算、force/sensor normalization、policy bundle 和指标版本必须分别报告。跨 solver 比较只能作为明确标注的 migration/reproduction 研究，不能混池统计或互相补证。
+
+## 证据权威层级
+
+由高到低采用以下顺序；若 package README 指定了更严格的内部顺序，以它为准：
+
+1. **不可变原始/派生 artifact**：成功、失败或 partial run 的 manifest、SHA-256、parent identity、原始 telemetry/field 和完整 metric contract。
+2. **可执行代码与测试**：能够重算或 fail closed 的 loader、analysis、runner 和 contract tests。
+3. **当前 package 权威文档**：active README、RESULTS/claim ledger、METHOD/PIPELINE、checkpoint；后写且明确 supersede 的文档优先。
+4. **仓库根 README**：负责导航和跨包边界，不替代 package 数值权威。
+5. **历史文档、计划、旧图和 archive narrative**：只说明当时意图或演进，不证明 run 完成，也不覆盖后续负结果。
+6. **Working Memory/对话摘要**：仅作检索线索，不能替代仓库 artifact。
+
+任何数字若不能解析到 scene、solver、role、realization、window、metric definition、artifact path/hash 和 evidence status，就不应写成权威结论。失败、拒绝、未完成和 partial 记录也是证据，不得覆盖或“清理”掉。
+
+## 环境与安装
+
+基础包声明 Python `>=3.8`，但当前 GPU 工作流以 Linux、NVIDIA GPU、CUDA 和 Python 3.10 的 `pycuda_3_10` conda 环境为准。分析任务通常在 CPU-only `pinball_math` 环境运行；具体依赖和命令以相应 package README 为准。ParaView 自带 Python 不能混入 conda Python 的 `PYTHONPATH`。

 ```bash
-git clone --recurse-submodules <your-repo-url> DynamisLab
+git clone --recurse-submodules https://github.com/frank14f/DynamisLab.git
 cd DynamisLab
-```
+git submodule update --init --recursive

-> **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
+conda create -n pycuda_3_10 python=3.10 -y
+conda activate pycuda_3_10
+pip install pycuda
+pip install -e CelerisLab
 pip install -e .
 ```

-## Quick Start
+`requirements.txt`/`pyproject.toml` 提供 NumPy、SciPy、PyTorch、Gymnasium、Stable-Baselines3、绘图和开发工具的基础声明。GPU CFD 应串行初始化；尤其 Legacy 编译会改写共享 kernel/config 文件，不要因使用不同 GPU 就并发编译不同 case。

-### Training a PPO Agent
+## 真实 quickstart

-Train a Proximal Policy Optimization agent for flow control:
+现代 V5 Kármán target calibration 与单次训练（完整参数见 [`train/README`](src/drl_pinball/train/README.md)）：

 ```bash
-python scripts/train_ppo.py \
-    --run-name my_first_run \
-    --device-id 0 \
-    --total-timesteps 100 \
-    --n-steps 3600 \
-    --activation sin
+cd src/drl_pinball/train
+conda run --no-capture-output -n pycuda_3_10 python -u calibrate.py \
+  --case kar_re100 --device-id 0 --si 800 \
+  --config ../../../configs/config_lbm_karman_2000x600.json \
+  --out-dir calibrations/kar_re100
+
+conda run --no-capture-output -n pycuda_3_10 python -u train_karman.py \
+  --case-name kar_re100 --device-id 0 --seed 42 \
+  --config ../../../configs/config_lbm_karman_2000x600.json \
+  --calibration calibrations/kar_re100/calibration.json \
+  --total-episodes 500 --symmetry-prob 0
 ```

-**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
+Illusion PPO 使用同一 calibration contract、`train_illusion.py` 和 `ill_*` case；这表示能力存在，不表示 Illusion SR 成功。V5 retained policy 评估：

 ```bash
-tensorboard --logdir tensorboard/
+bash src/drl_pinball/eval/run_all.sh --case kar_re100 --seed 45
+python3 src/drl_pinball/eval/infer_train.py --validate-all --output-root /tmp/v5-eval
 ```

-Then open http://localhost:6006 in your browser.
-
-### Using the Environment Programmatically
-
-```python
-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:
-
-```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
+CPU-only 稳态分析/测试示例（更多命令及 bounded 条件见 [`steady_pinball_theory/README`](src/steady_pinball_theory/README.md)）：

 ```bash
-python scripts/train_ppo.py \
-    --resume models/my_run_best.zip \
-    --run-name my_run_continued
+PYTHONPATH="$PWD/src" conda run -n pinball_math \
+  python -m pytest -q src/steady_pinball_theory/tests/test_core.py
 ```

-### Custom Hyperparameters
+绘图接口见 [`src/pv_plot/README.md`](src/pv_plot/README.md)；Legacy SR acquisition 和 CCD 不适合作为首次 GPU quickstart，应先读其 immutable-input、serial execution 与 provenance 合约。

-```bash
-python scripts/train_ppo.py \
-    --learning-rate 0.0003 \
-    --gamma 0.99 \
-    --batch-size 512 \
-    --n-steps 7200
-```
+## 2026 年 2–8 月演进

-### Multi-GPU Setup
+- **2 月**：仓库建立，形成 “Machine Learning + numerical simulation” 的广义框架和 fluidic pinball 主问题。
+- **6 月**：集中整理早期 SR/SINDy、CCD correction-field 与 OID/POD/LR-LE 分析；同时暴露 alignment、FIFO、ROI 和证据组织问题，开始从“有图/有分数”转向 contract-first。
+- **7 月上旬**：建立参数化现代 V5 Kármán/Illusion 训练、跨 Re/尺寸路线和 solver reproduction；修正 inlet/action/order 等兼容问题。
+- **7 月中下旬**：冻结 Legacy SR Stage 1→2→3 article chain，加入 dual-clock CCD、OID 和轻量 `pv_plot`；闭环、hash、no-clobber 与失败保留成为基本要求。
+- **8 月初**：OID scientific reset 撤回 importance/causality 读法；现代 V5 training release 冻结 compact bundles；steady theory 转向 NS-first；CCD 重做为 corrected ROI mean/cycle-template 权威。
+- **8 月 8–9 日**：统一 Legacy 长窗口角色采集并完成项目收尾。Kármán SR 保持受限活跃；Illusion SR 因接近 physical-zero 的长窗口结果关闭；steady article publication 保持 BOUNDED；根文档改为状态与证据入口。

-```bash
-# CFD simulation on GPU 0, PyTorch training on GPU 1
-python scripts/train_ppo.py \
-    --device-id 0 \
-    --cuda-device 1
-```
+## Archive 与 provenance 规则

-## Environment Details
+- run/artifact 一经发布即 immutable、no-clobber；新尝试使用新 ID，不覆盖成功、失败或 partial 目录。
+- 移动/重命名前先核对 parent path、hash、manifest、symlink、外部 Optane mapping 和下游消费者。可读性不能破坏 identity。
+- Git 中没有 bulk payload 不代表证据不存在；外部 archive 必须由 inventory/hash 和 package relocation 文档绑定。仅有本地文件也不等于已经 Git-preserved。
+- `archive/` 默认不执行、不导入、不作为当前结论；只有 active authority 明确引用时，才按其限定用途使用。
+- derived plot/report 不自动成为 acceptance evidence；必须回溯其完整输入和生成合约。
+- Legacy 与 V5 的 artifact、normalization、target、metric 和 solver version 分库存放、分开引用。

-### CFDFlowControlEnv
+## 科学写作边界

-The main environment for active flow control around a cylinder.
+可以写：指定 solver、case、窗口和 comparator 下的性能；Kármán SR 在已测试 deletion window 内的 term ranking；corrected CCD 的 phase-coherent descriptive co-variation；稳态端点/有限时域的审计结果；OID 数学工具的实现与验证。

-**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
+不能写：普适 Reynolds/尺寸规律、全局最优或唯一 SR 方程、PPO 本身具有等变性、CCD/DTW lag 给出因果机制或物理延迟、稳态旋转已经闭合动量/能量机制、单 realization 给出不确定性、现代全矩阵已完整重训、OID predictive R² 等价于 importance/control authority，或 Illusion SR 已实现 tracking/generalization。

-**Action Space:**
- Dimensionality: `n_control_cylinders`
- Default: 3 (three controllable cylinders)
- Range: [-1, 1] (scaled internally to physical velocities)
+写作时应并列给出 observation、interpretation 和 mechanism 的层级，并明确 solver、场景、基线、时长、样本数和状态。论文草稿、计划和 acknowledgements 不得反向升级本地证据。

-**Reward:**
- Drag reduction: `-cd × 0.1`
- Lift minimization: `-|cl| × 0.05`
- Flow similarity: `-similarity_distance × 0.5`
- Total reward is sum of components
+## Citation、License 与致谢

-**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
-
-```bash
-pytest tests/
-```
-
-## Citation
-
-If you use DynamisLab in your research, please cite:
+若使用本仓库，请引用实际采用的代码版本/commit、对应 artifact/manifest 和底层 solver；建议的软件引用为：

 ```bibtex
-@software{dynamis2026,
+@software{dynamislab2026,
  author = {Frank14f},
  title = {DynamisLab: Machine Learning for Computational Fluid Dynamics},
  year = {2026},
@@ -280,31 +152,6 @@ If you use DynamisLab in your research, please cite:
 }
 ```

-Also cite CelerisLab:
+同时按实际使用情况引用 [CelerisLab](https://github.com/frank14f/CelerisLab)、Stable-Baselines3、Gymnasium、NumPy/SciPy、PyTorch、ParaView 以及各分析方法的原始论文。代码以 [MIT License](LICENSE) 发布；外部论文、模型、数据和 solver artifact 可能有各自的引用与再分发要求。

-```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.
+感谢 CelerisLab 提供 GPU-accelerated LBM 基础，Stable-Baselines3 与 Gymnasium 提供强化学习接口，PyTorch、NumPy/SciPy、Matplotlib 和 ParaView 支撑训练、分析与可视化。欢迎通过 issue 或 pull request 讨论可复现性、证据合约和明确限定范围的改进。