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 获取源码包总索引，再按项目进入权威文档。

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

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

包与目录地图

• src/drl_pinball/ — 主运行包。train/ 是现代 2000×600 CelerisLab V5 校准/训练；eval/ 是 V5 评估；legacy_test/ 在 LegacyCelerisLab 上执行统一的历史角色采集；legacy_env/、legacy_train/ 和局部 archive/ 服务于兼容与溯源。状态：active + bounded + historical。
• src/SR_analysis/ — 在冻结 PPO 轨迹上发现、拟合并于 Legacy CFD 闭环验证符号控制器。当前只保留 Kármán/cloaking 为 active but bounded；Illusion SR 是 historical/negative，steady 仅作幅值校准背景。
• src/CCD_analysis/ — corrected karman_re100 ROI mean 与 cycle-template CCD 的精简权威入口。状态：completed descriptive/bounded；旧 temporal/phase 与 pre-reset 树为 superseded historical。
• src/OID_analysis/ — weighted snapshot POD、Schlegel LR/LE maps、配对和原子 artifact 校验。状态：active method core, no active science claim；2026-07 两场景研究为条件性历史材料。
• src/steady_pinball_theory/ — rear-symmetric steady rotation 的分析、finite-Re 数值证据与 NS-first 验证。状态：active investigation, bounded evidence；尚无完成的稳态机制证明。
• src/pv_plot/ — ParaView/FFmpeg 轻量 PNG/MP4 渲染接口，不是独立服务或 pip 项目。状态：active utility。
• src/archive/ — 被替代的现代 solver reproduction Track B 等仓库级历史材料；各 package 自己的 archive/ 也属于其 provenance chain。状态：historical, non-authoritative unless an active document explicitly cites it。
• 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 进入。

现代 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。

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）：

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 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）：

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；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；建议的软件引用为：

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

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

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