DynamisLab/README.md

# DynamisLab

**Machine Learning meets Numerical Simulation**

DynamisLab 是一个面向机器学习与数值模拟交叉研究的框架，当前主线是二维 fluidic pinball（三圆柱）主动流动控制：以 GPU 加速 Lattice Boltzmann Method（LBM）求解流场，用 PPO 等策略驱动圆柱旋转，并用 Symbolic Regression（SR）、Corrected Cross-Covariance Decomposition（CCD）、Observable Identification（OID）和稳态理论分析审查控制规律与证据边界。

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

## 当前状态（2026-08-09）

- **活跃（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/`。

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

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，不承载活跃科学结论。

## 五分钟阅读顺序

先看 [`src/README.md`](src/README.md) 获取源码包总索引，再按项目进入权威文档。

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。

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

## 包与目录地图

- [`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 https://github.com/frank14f/DynamisLab.git
cd DynamisLab
git submodule update --init --recursive

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 .
```

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

## 真实 quickstart

现代 V5 Kármán target calibration 与单次训练（完整参数见 [`train/README`](src/drl_pinball/train/README.md)）：

```bash
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
```

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

```bash
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
```

CPU-only 稳态分析/测试示例（更多命令及 bounded 条件见 [`steady_pinball_theory/README`](src/steady_pinball_theory/README.md)）：

```bash
PYTHONPATH="$PWD/src" conda run -n pinball_math \
  python -m pytest -q src/steady_pinball_theory/tests/test_core.py
```

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

## 2026 年 2–8 月演进

- **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；根文档改为状态与证据入口。

## Archive 与 provenance 规则

- 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 分库存放、分开引用。

## 科学写作边界

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

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

写作时应并列给出 observation、interpretation 和 mechanism 的层级，并明确 solver、场景、基线、时长、样本数和状态。论文草稿、计划和 acknowledgements 不得反向升级本地证据。

## Citation、License 与致谢

若使用本仓库，请引用实际采用的代码版本/commit、对应 artifact/manifest 和底层 solver；建议的软件引用为：

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

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

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