diff --git a/.gitignore b/.gitignore index 0aaf7ca..15873f3 100644 --- a/.gitignore +++ b/.gitignore @@ -143,4 +143,12 @@ src/drl_pinball/train/output/*/models/* !src/drl_pinball/train/calibrations/*/target.npy # CCD generated evidence/archive payloads remain external immutable data. src/CCD_analysis/evidence/* -src/CCD_analysis/archive/* +src/CCD_analysis/archive/ +src/archive/ + +# Local/runtime residue and generated publication working trees +.runtime/ +{output_dir}/ +src/drl_pinball/data/reproduction_flow_plots/ +src/drl_pinball/train/results/latest/tables/training_iterations.csv +src/drl_pinball/data/reproduction diff --git a/README.md b/README.md index dbf8175..b142061 100644 --- a/README.md +++ b/README.md @@ -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 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 讨论可复现性、证据合约和明确限定范围的改进。 diff --git a/docs/JFM_WYQ/SR_Draft.md b/docs/JFM_WYQ/SR_Draft.md deleted file mode 100644 index 4cfc5ee..0000000 --- a/docs/JFM_WYQ/SR_Draft.md +++ /dev/null @@ -1,452 +0,0 @@ -# Symbolic regression of learned flow-control policies - -## 1. Purpose, evidence hierarchy and scope - -The deep-reinforcement-learning (DRL) controllers used for hydrodynamic cloaking and illusion are effective, but their neural-network representation does not directly expose the control mechanism. Symbolic regression (SR) is therefore used as a post hoc policy-reduction method. The fitted expressions are empirical observation-to-action surrogates on states visited by PPO; they are not governing equations and are not identified directly from the Navier--Stokes equations. - -This distinction matters in closed loop. A formula can reproduce PPO actions on a recorded trajectory and still alter the state distribution after deployment, accumulate phase error, develop an action bias, or destabilize CFD. Consequently, offline regression metrics are used to discover variables and topologies, whereas finite closed-loop CFD and trajectory similarity decide whether a candidate is useful. Term deletion and coefficient scaling then assess which parts of a deployed candidate matter. - -The active software has three executable stages: - -1. `stage_1_infer.py` collects contract-audited PPO trajectories; -2. `stage_2_fit.py` performs symbolic discovery and fixed-topology coefficient refitting; -3. `stage_3_validate.py` deploys PPO, symbolic, constant, or uncontrolled policies in CFD. - -Within Stages 2--3, model selection has five phases: per-case discovery, within-objective joint discovery, topology freezing and coefficient refit, short and standard CFD screening, and term deletion/scaling. These phases are not additional software stages. - -The fitted article evidence is deliberately narrower than the complete flow-control project. It contains four periodic Kármán-street cloaking policies and three cylinder-wake illusion policies. Kármán and illusion are never pooled into one regression. The disturbance-free steady scene is used only for post-selection calibration of the Kármán law. Transient-vortex, erase, V5, and historical SINDy analyses are outside the fitted evidence considered here. - -Two evidence generations must remain separate: - -- the **2026-07-18 primary evidence** contains the seven training trajectories, symbolic discovery, fixed-topology refits, 40-step screening, 200-step validation, and term tests; -- the **2026-07-20 coefficient-frozen extension** contains steady calibration, per-case diagnostic refits, 400-step duration tests, CSV exports, and pointwise unseen-condition deployments. - -No extension condition participated in topology selection or coefficient estimation. - -## 2. Physical labels, state contract and action units - -### 2.1 Reynolds-number and target-size conventions - -The inlet speed is \(U_0=0.01\) in lattice units and the pinball-cylinder diameter is \(D=20\). The historical Kármán scene names use a code Reynolds label based on the reference length \(2D=40\): - -\[ -Re_D=\frac{U_0D}{\nu}=\frac{\texttt{re\_code}}{2}. -\] - -Thus `karman_re50`, `karman_re100`, `karman_re200`, and `karman_re400` denote \(\texttt{re\_code}=50,100,200,400\), corresponding to \(Re_D=25,50,100,200\). Both conventions must be stated whenever physical Reynolds numbers are compared. - -The illusion scene names `illusion_0.75L`, `illusion_1L`, and `illusion_1.5L` are legacy target-size labels. Despite the historical configuration field name `target_diameter`, its value times \(L=20\) is passed to `LegacyCelerisLab.add_cylinder` as the cylinder **radius**. The labels are retained for provenance, but they must not be described as target-cylinder diameters. - -The Kármán control sampling interval is 800 lattice steps. Illusion intervals are 400, 600, and 800 steps for the 0.75L, 1L, and 1.5L labels. With the convective scale \(D/U_0=2000\) lattice steps, - -\[ -\Delta t_c=\frac{\mathrm{sample\ interval}}{D/U_0}, -\] - -so the dimensionless control intervals are 0.4 for Kármán and 0.2, 0.3, and 0.4 for the three illusion scenes. - -### 2.2 Native ordering - -The canonical body and action order is - -\[ -(\mathrm{front},\mathrm{upper},\mathrm{lower}). -\] - -The six downstream sensor channels are ordered - -\[ -(u_U,v_U,u_C,v_C,u_L,v_L), -\] - -and the six force channels are - -\[ -(F_{x,F},F_{y,F},F_{x,U},F_{y,U},F_{x,L},F_{y,L}). -\] - -This order follows the audited LegacyCelerisLab object IDs and force slots. It is not inferred from force signs. The runtime order gate is rerun after CFD or kernel changes because a silent slot permutation would change the physical meaning of every fitted coefficient. - -### 2.3 PPO normalization and SR nondimensionalization - -Two different transformations must not be conflated. PPO receives a clipped normalized observation: forces are divided by `force_norm_fact`, sensor velocities are centred by `sens_deviation` and divided by `sens_norm_fact`, and the result is clipped to \([-1,1]\). Illusion appends the normalized two-component target-cylinder force. The article trajectories use frozen existing normalization rather than recomputing normalization on each rollout. - -SR does not fit these clipped PPO inputs. Recorded raw lattice data are converted to physical dimensionless features: - -\[ -\hat u=u/U_0,\qquad \hat v=v/U_0, -\] - -\[ -C_d=\frac{2F_x}{\rho U_0^2D},\qquad -C_l=\frac{2F_y}{\rho U_0^2D}, -\] - -with \(\rho=1\). The regression target is dimensionless cylinder surface velocity - -\[ -\boldsymbol{\alpha}_t -=\frac{\boldsymbol{\omega}_t}{U_0} -=(\alpha_{F,t},\alpha_{U,t},\alpha_{L,t})^{\mathsf T}. -\] - -A PPO-normalized command is decoded before fitting as - -\[ -\boldsymbol{\alpha} -=s_a\mathbf a_{\mathrm{norm}}+\mathbf b_a. -\] - -The Kármán action scale and bias are \(s_a=8\) and \((0,-4,4)\); the illusion values are \(s_a=4\) and \((0,-2,2)\). Stage 1 stores the normalized command, dimensionless \(\alpha\), and lattice \(\omega=U_0\alpha\), making unit conversion auditable. - -## 3. Article trajectories and causal dataset - -Seven new deterministic PPO trajectories were collected: - -\[ -\mathcal D_K=\{\texttt{re50},\texttt{re100},\texttt{re200},\texttt{re400}\}, -\] - -\[ -\mathcal D_I=\{0.75L,1L,1.5L\}. -\] - -Each trajectory contains 200 recorded post-action states. The causal contract is - -\[ -x_i\longmapsto\alpha_{i+1}, -\] - -named `causal_post_state_to_next_action`. At state \(x_i\), action-history features may use \(\alpha_i\) and \(\alpha_{i-1}\), but never a future action. The requirement for \(\alpha_{i+1}\) removes the final state and the two-row action-history warm-up removes indices 0 and 1, leaving state indices 2--198: 197 fitted rows per trajectory. - -Every trajectory is aligned and split independently before stacking. The discovery split is contiguous 60/20/20% train, validation, and blind data; temporal rows are not randomly shuffled and boundaries never cross trajectories. The blind block is not fitted during topology discovery. After a topology has been frozen, its numerical constants are refitted on all eligible aligned rows. Therefore, the blind block protects topology selection but is no longer an untouched holdout after final refitting; final scientific acceptance comes from closed-loop CFD. - -The PPO model was replayed on each stored causal state using the frozen observation normalization and decoder. All seven action sequences reproduced exactly. Historical and pre-contract trajectories remain available for diagnosis but are not pooled with the article dataset. - -## 4. Candidate variables and reflection symmetry - -### 4.1 Feature libraries - -The `raw_complete` representation contains twelve variables: six dimensionless sensor velocities and the drag/lift coefficients of the front, upper, and lower cylinders. - -The `symmetry` representation contains fourteen variables: - -\[ -(u_s,u_a,u_c,v_s,v_a,v_c, -C_{d,F},C_{d,\mathrm{rear},s},C_{d,\mathrm{rear},a},C_{d,\mathrm{tot}}, -C_{l,F},C_{l,\mathrm{rear},s},C_{l,\mathrm{rear},a},C_{l,\mathrm{tot}}). -\] - -The rear and sensor coordinates use half-sums and half-differences. For example, - -\[ -u_s=\frac{u_U+u_L}{2},\qquad -u_a=\frac{u_U-u_L}{2}, -\] - -\[ -C_{d,\mathrm{rear},s}=\frac{C_{d,U}+C_{d,L}}{2},\qquad -C_{d,\mathrm{rear},a}=\frac{C_{d,U}-C_{d,L}}{2}, -\] - -with identical conventions for \(v\) and lift. This factor of one half is part of the formula contract: omitting it would rescale the reported coefficients. - -Illusion discovery compares four controlled profiles: - -- `actual_only`: actual-state variables only; -- `target_only`: target \(C_d\) and \(C_l\) only; -- `actual_plus_target`: actual state plus target force coefficients; -- `actual_plus_error`: actual state plus \(C_{d,\mathrm{tot}}-C_{d,\mathrm{target}}\) and \(C_{l,\mathrm{tot}}-C_{l,\mathrm{target}}\). - -The article discovery does not add trigonometric phase coordinates or a manual bias column. PySR may still create numerical constants. Cross-correlation is never used to choose a feature lag. - -### 4.2 Complete reflection map - -Reflection \(G\) about the centreline exchanges upper and lower positions. Streamwise velocity is even, transverse velocity is odd, drag is even, and lift is odd. Thus upper/lower sensor and force slots are exchanged with the appropriate transverse/lift sign reversal. Front drag is even and front lift is odd. Target drag is even and target lift is odd. The same map is applied to any action history. - -The native action transforms as - -\[ -G_a(\alpha_F,\alpha_U,\alpha_L) -=(-\alpha_F,-\alpha_L,-\alpha_U). -\] - -Fit augmentation and deployment architecture are separate. G augmentation adds mirrored state-action rows during fitting. The final mapped-shared deployment imposes - -\[ -\operatorname{odd}[h](x)=\frac{h(x)-h(Gx)}{2}, -\] - -\[ -\alpha_F(x)=\operatorname{odd}[h_F](x),\qquad -\alpha_U(x)=h_R(x),\qquad -\alpha_L(x)=-h_R(Gx). -\] - -This is a physical inductive bias imposed on the symbolic controller. It does not establish exact PPO equivariance, and symmetrization may modify as well as simplify the PPO policy. Independent three-head fits are retained only as diagnostics of PPO structure. - -## 5. Discovery, refitting and safety - -### 5.1 PySR discovery - -The discovery grammar uses binary \(+\), \(-\), and multiplication, with `square` as the unary operator. Search is deterministic and serial, without batching. The full defaults are 30 populations, population size 33, tournament size 10, maximum expression size 15, constant complexity 2, and parsimony 0.01. The bounded article discovery configuration (`--smoke`) uses two populations, population size 16, tournament size 4, and maximum size 7. At least three deterministic seeds are run per case/profile. - -Only training blocks are fitted. Up to 25 retained Pareto candidates per head are evaluated on contiguous train, validation, and blind blocks using \(R^2\), MAE, RMSE, maximum error, complexity, and used variables. Static safety is a finite-value probe over sparse points spanning observed feature ranges; because no required output interval is supplied, it is not a global action-range guarantee. - -Topology selection is a manual, evidence-based scientific step. It considers recurrence across seeds and cases, held-out diagnostics, complexity, finite static evaluation, compatibility with mapped-shared deployment, and CFD viability. PySR score or \(R^2\) never automatically promotes a formula, and an average cannot hide failure in one required scene. - -### 5.2 Fixed-topology refit - -After selecting a recurring topology, every numerical literal is replaced by a separate optimization parameter while operators and feature occurrences remain fixed. Constants are optimized with `scipy.optimize.least_squares`. Residuals use square-root sample weights so each case has equal total mass and trajectories within a case also have equal mass. Mapped-shared refits retain G augmentation. The artifact records initial/refitted constants, optimizer status, aggregate/per-case/per-trajectory metrics, discovery-parent path and hash, dataset hashes, feature order, action units, alignment, and deployment semantics. - -Offline metrics describe PPO action imitation on PPO-visited states. They cannot be ranked directly against closed-loop DTW because symbolic deployment changes the state distribution. - -### 5.3 Formula and CFD safety - -Formula artifacts carry separate fitted/deployment expressions and hashes. Evaluation permits only declared features and a restricted function set, rejects unsupported syntax and variables, and performs a zero-state probe when Stage 3 loads a formula pair. Static finite probing is only a pre-screen. - -Closed-loop safety is decisive. The symbolic policy maintains separate online feature histories for \(x\) and \(Gx\), initialized from the scene policy action. Every action and raw CFD observation is checked for finiteness. A failure retains partial telemetry, failed-step information, hashes, and the exception instead of overwriting the run. Candidates first receive a 40-step screen, then a 200-step standard validation. The 2026-07-20 extension adds 400-step tests without changing coefficients. - -### 5.4 Legacy DTW metric - -The only article metric is `legacy_dtw_v1_abs_n_unclipped`, recorded under `legacy_reference_cycle_vs_last_recorded_cycle`. For Kármán, `conv_len=30`; for illusion, `conv_len=36`. Lag is selected from transverse sensor channel 1 by cross-correlating target samples `conv_len:2*conv_len` with the final controlled `conv_len` samples. The complete target sequence is circularly shifted by that lag. Absolute, normalized, unclipped DTW similarity - -\[ -S_j=1-\frac{d_{\mathrm{DTW}}(y^{\mathrm{target}}_j,y^{\mathrm{controlled}}_j)}{N} -\] - -is then computed independently for all six sensor channels, and the reported value is their arithmetic mean. One is ideal; the metric may be negative. Lag is a metric-alignment parameter, not a physical observation or actuation delay. The scalar score compares a reference cycle with the final recorded cycle; 400-step CSV convergence files are needed to inspect its evolution over duration. - -## 6. Attempt ledger and selection lessons - -Broad per-case searches showed heterogeneous Kármán formulas rather than a clean two-regime partition. Joint symmetry searches repeatedly selected front rear-drag asymmetry and a rear lift-plus-constant topology. For illusion, endpoint cases selected different variable families, motivating profile-controlled joint searches instead of a hand-reduced universal library. - -Two illusion front topologies remained plausible offline. Topology A combined \(C_{d,\mathrm{rear},a}\) and \(C_{l,F}\). Topology B used \(C_{d,\mathrm{rear},s}C_{l,F}-C_{l,\mathrm{tot}}\). Topology B completed 40 steps at 0.75L with similarity 0.958889 and lag 7, but both 1L and 1.5L failed with `FloatingPointError: raw observation contains non-finite values`. Its formula-pair hash is `93615f0809c76d722a9cd781e08b23e1167a2004957964807a3d661f5c98ee38`. It was rejected, and its failures were retained. This is the clearest demonstration that an offline Pareto candidate and even one successful scene cannot substitute for all-case closed-loop screening. - -Older pre-force-order formulas, round-one results, SINDy paths, V5 experiments, and archived Stage 4 figures remain historical or diagnostic. They are not alternative current entrypoints and their numbers are not imported into the article evidence. - -## 7. Kármán-street cloaking results - -### 7.1 Joint law and offline fit - -The selected fixed-topology law is - -\[ -\boxed{\alpha_F(x)=\operatorname{odd}\!\left[-0.381391\,C_{d,\mathrm{rear},a}\right]}, -\] - -\[ -\boxed{\alpha_U(x)=1.307782\,C_{l,\mathrm{rear},s}-3.431209,\qquad -\alpha_L(x)=-\alpha_U(Gx)}. -\] - -The formula-pair hash is `a678f2019e0da7a0e1263f0c911b377106a668a6716ba93d6efd78f58de0a3f1`; the front and rear deployment-expression hashes are `367b5b7e...d4650` and `75207940...60f7`. - -Aggregate offline metrics are: - -- front head: \(R^2=0.5699\), MAE 0.8872, RMSE 1.1876, maximum error 3.1129; -- rear shared head: \(R^2=0.4363\), MAE 1.6187, RMSE 2.0608, maximum error 5.6964. - -The per-case contrast is scientifically informative. Front \(R^2\) is 0.2488, 0.8671, 0.6100, and 0.8893 for the four code-Re labels. Rear \(R^2\) is -0.5315, 0.5666, 0.5483, and 0.2242. Re50 therefore has poor offline rear-action imitation but excellent closed-loop similarity, whereas Re400 has a strong front offline fit and the weakest standard closed-loop score. Offline action accuracy is not the control-performance ordering. - -### 7.2 Standard and duration validation - -The 200-step similarities at code labels Re50, Re100, Re200, and Re400 are 0.9543, 0.9427, 0.8560, and 0.7827. The shared law is strongest at lower/intermediate conditions and degrades at Re400; it is not a universal cross-Re law. - -At 400 steps, similarities are 0.952178, 0.944339, 0.863850, and 0.833365. Every telemetry channel remains finite. The Re400 limitation is therefore not delayed numerical blow-up over this tested horizon, although one 400-step realization cannot establish statistical robustness. - -### 7.3 Term deletion - -Forty-step deletion tests provide the following sequence over Re50/Re100/Re200/Re400: - -- delete front feedback: 0.939361 / 0.912182 / 0.881434 / 0.813289; -- remove rear lift feedback but retain the constant: 0.917126 / 0.869943 / 0.825250 / 0.789535; -- remove the rear constant but retain lift feedback: 0.839344 / 0.817735 / 0.708089 / 0.647401. - -Within this short ablation horizon, the supported ordering is - -\[ -\text{rear constant}>\text{rear lift feedback}>\text{tested front feedback}. -\] - -The persistent rear counter-rotation is therefore the dominant tested controller component. Its interpretation as downstream-deficit compensation is consistent with the expected gap-flow and momentum correction, but SR alone does not observe the spatial momentum field and does not prove causality. - -### 7.4 Per-case fixed-topology diagnostics - -Refitting the same topology separately gives \((a,b,c)\) in \(\alpha_F=-aC_{d,\mathrm{rear},a}\), \(\alpha_U=bC_{l,\mathrm{rear},s}-c\): - -- Re50: (0.5836, 0.2212, 3.5820), rear \(R^2=0.0221\); -- Re100: (0.3248, 1.3203, 4.1774), rear \(R^2=0.7131\); -- Re200: (0.5003, 1.6971, 3.4109), rear \(R^2=0.5788\); -- Re400: (0.2947, 1.0549, 2.5545), rear \(R^2=0.3285\). - -The coefficients vary non-monotonically and do not support a clean low/high-Re split. These fits are offline diagnostics and were not promoted as independent closed-loop controllers. - -### 7.5 Steady calibration - -A disturbance-free pinball independently calibrates the order of magnitude of the rear constant. A discrete constant counter-rotation sweep \(A=0,1,\ldots,6\), with rear commands \((-A,+A)\), gives similarities 0.631830, 0.723858, 0.857286, 0.955029, 0.976376, 0.987212, and 0.978674. Thus \(A=5\) is the best **sampled** value, not a continuously optimized value. - -The Kármán law in the same steady scene gives similarity 0.966494. Its final-cycle mean actions are -0.000563, -3.430589, and 3.431828 for front, upper, and lower, consistent with its analytical constant magnitude 3.431209. The fitted value is about 68.6% of the sampled \(5U_0\) optimum. This establishes scale consistency between the learned constant and useful steady compensation; it is not an equality between wake velocity deficit, momentum deficit, and cylinder surface speed. - -### 7.6 Pointwise unseen-Re extension - -Without coefficient retuning, 200-step deployments at code labels Re25, Re70, Re150, and Re300 give 0.988078, 0.954339, 0.907496, and 0.835758. Re70/Re150/Re300 are interpolation points within the fitted code-label range; Re25 is one low-Re extrapolation. The results show finite pointwise deployment at these sampled configurations only. There is no high-Re extrapolation above Re400, no continuous coefficient law, and no repeated-initial-condition uncertainty estimate. - -## 8. Illusion results - -### 8.1 Per-size discovery and selected law - -Broad discovery changes systematically across legacy target-size labels. At 0.75L, \(C_{d,\mathrm{rear},a}\) and \(C_{d,\mathrm{rear},s}\) appear 15 and 10 times across audited heads. The 1L searches are mixed/transitional, led by \(C_{d,F}\) (13) and \(C_{l,\mathrm{rear},s}\) (12). At 1.5L, \(C_{l,F}\) and \(C_{l,\mathrm{rear},s}\) appear 54 and 46 times, showing a lift-contrast-dominated endpoint. - -The stable joint numerical candidate is - -\[ -\boxed{\alpha_F(x)=\operatorname{odd}\!\left[-1.826604\,C_{d,\mathrm{rear},a}+2.064493\,C_{l,F}\right]}, -\] - -\[ -\boxed{\alpha_U(x)=1.254440\,C_{d,\mathrm{rear},a}-1.528074\,C_{l,F},\qquad -\alpha_L(x)=-\alpha_U(Gx)}. -\] - -Its formula-pair hash is `ae67ae5071065b7ee8412791ee1841011530746865528641beddb1a203c51b83`; front/rear expression hashes are `1df7c515...0487` and `485de2ca...b8e8`. - -### 8.2 Offline fit versus closed-loop performance - -Aggregate offline metrics are: - -- front head: \(R^2=0.4851\), MAE 1.3075, RMSE 1.9726, maximum error 6.6080; -- rear shared head: \(R^2=0.3598\), MAE 1.3347, RMSE 1.5823, maximum error 5.1284. - -Per-case front \(R^2\) is 0.5850, -1.7176, and 0.5054 for 0.75L, 1L, and 1.5L; rear \(R^2\) is -5.7162, -12.5115, and 0.5923. The negative values must be retained: the candidate is not a uniformly accurate PPO action surrogate. - -Nevertheless, 200-step closed-loop similarities are 0.8749, 0.9217, and 0.8306. At 400 steps they are 0.854379, 0.915609, and 0.833587, with finite telemetry. Closed-loop viability despite weak offline action fit again demonstrates that the deployed controller cannot be selected by \(R^2\) alone. - -### 8.3 Per-size fixed-topology diagnostics - -Separate refits produce: - -- 0.75L front: \(-0.2420C_{d,\mathrm{rear},a}-0.8373C_{l,F}\), \(R^2=0.8035\); rear: \(0.2486C_{d,\mathrm{rear},a}+0.0829C_{l,F}\), \(R^2=-5.4396\); -- 1L front: \(2.0438C_{d,\mathrm{rear},a}-2.2193C_{l,F}\), \(R^2=0.6060\); rear: \(0.1843C_{d,\mathrm{rear},a}-0.1588C_{l,F}\), \(R^2=-11.2480\); -- 1.5L front: \(-0.0441C_{d,\mathrm{rear},a}+2.1015C_{l,F}\), \(R^2=0.5421\); rear: \(1.5683C_{d,\mathrm{rear},a}-1.6011C_{l,F}\), \(R^2=0.5948\). - -The 1.5L front is nearly pure front-lift feedback and its rear coefficients are roughly an order of magnitude larger than the poorly identified smaller-target rear fits. Sign changes and very negative smaller-target rear \(R^2\) values prevent promotion of a clean two-group coefficient mechanism. These are diagnostics of the compromise made by a shared static topology. - -### 8.4 Deletion and non-uniqueness - -All four one-term deletion variants completed 40 steps. For 0.75L/1L/1.5L: - -- delete first front term: 0.939375 / 0.933481 / 0.885085; -- delete second front term: 0.960067 / 0.927035 / 0.836563; -- delete first rear term: 0.954488 / 0.936851 / 0.887603; -- delete second rear term: 0.954641 / 0.930454 / 0.850816. - -Thirty-seven preregistered coefficient-scaling shadow variants remained finite. The \(C_{l,F}\) terms dominate action-amplitude sensitivity, while \(C_{d,\mathrm{rear},a}\) is weaker and partly replaceable. Because all one-term deletions remain stable and differences are modest over 40 steps, the four-term expression is not unique and no individual term is established as universally necessary. - -Target and error variables were available but did not recur in the selected low-complexity static topology. This is negative evidence against claiming explicit target tracking; it is not proof that target information is physically irrelevant. Target phase may be aliased into PPO-visited forces, may require memory, or may enter differently across size regimes. - -### 8.5 Pointwise unseen-size extension - -Coefficient-frozen 200-step interpolation at 0.8L and 1.2L gives 0.884573 and 0.925530. Extrapolation at 0.5L, 0.6L, and 2L gives 0.784055, 0.821103, and 0.756880. Every sampled run completes, but degradation toward the extremes is clear. These are single pointwise realizations and do not define a universal target-size law. - -The defensible illusion conclusion is therefore narrower than for Kármán: a shared symmetric numerical controller exists over the tested family, with 1.5L a structurally different boundary regime, but the present static law does not identify a unique target-dependent mechanism. - -## 9. SR-to-OID/CCD handover - -SR identifies actuator-side observation-to-action structure. It does not identify where the corresponding flow correction is located. The handover to OID/CCD is therefore a ranked, falsifiable target list rather than a claim that the structures have already been found. - -For Kármán: - -1. **Rear steady counter-rotation, strongest evidence.** OID should search for a reflection-symmetric streamwise correction generated in the rear gap and retained at the sensor station. CCD should quantify the rear-pair relation to the mean/low-frequency downstream deficit mode. -2. **Symmetric rear lift feedback, moderate evidence.** Coefficients vary from 0.22 to 1.70, so the term is a condition-dependent modulation rather than a universal gain. Seek a rear-cylinder force-correlated source and lagged downstream descendant. -3. **Rear drag asymmetry in front action, weak evidence.** Test an antisymmetric near-front structure and expect weaker downstream canonical correlation. - -For illusion: - -1. **Front lift, moderate evidence.** Compare front-body source structures across target-size labels and test whether descendants change wavelength or phase. -2. **Rear drag asymmetry, weak-to-moderate evidence.** Search for antisymmetric rear-gap structures, explicitly contrasting 1.5L with smaller labels. -3. **Absence of explicit target/error terms, negative evidence.** Use lagged and phase-resolved analyses because static obs--act regression can alias memory or phase into force observations. - -For every element, actuator-to-source and source-to-downstream relations must be reported separately; upper/lower parity must be preserved; lag must be stated in \(D/U_0\); and spatial coincidence must not be promoted to causality without time-lagged evidence. Agreement between SR ranking and OID/CCD correlation is convergent evidence. Contradictions must be retained and used to revise the interpretation rather than forcing agreement. - -## 10. Limitations and claim discipline - -The analysis has the following explicit limitations. - -1. There is one 200-step PPO trajectory per fitted case. PySR seed recurrence is not recurrence over independent PPO or CFD trajectories. -2. Temporal rows are correlated; 197 rows are not 197 independent flow realizations. -3. The symbolic grammar, complexity bound, population settings, and finite seed count do not establish a global symbolic optimum. -4. Exact reflection symmetry is imposed, not discovered, and may modify the original PPO. -5. The selected laws are static and instantaneous. They cannot represent explicit memory, and failure to select target variables does not show memory or target information is unnecessary. -6. All eligible rows are reused after topology freezing, so final coefficient metrics are not a fully blind estimate. -7. The standard and extension runs report one deterministic realization per condition; no repeated-initial-phase or disturbance uncertainty interval is available. -8. The DTW result depends on the selected reference/final-cycle window and lag alignment, is not a full-field metric, and cannot prove mechanism identity. -9. Generalization is pointwise over sampled Reynolds labels and target sizes. Geometry perturbations, sensor noise, actuator mismatch, altered sampling, and other disturbances are untested. -10. No preregistered scalar DTW success threshold exists. Finiteness is a hard gate, while performance language is relative and case-specific. -11. There is no transient-vortex SR evidence in the current fitted package. -12. The steady sweep does not establish a momentum-balance equality or a continuous optimum. -13. OID/CCD causal structures are future/independent evidence, not present SR results. - -Accordingly, the evidence **establishes** a reproducible discovery-to-CFD workflow, the dominance of the rear constant within the tested Kármán law, secondary short-horizon value of rear lift feedback, a finite shared illusion numerical candidate, and the inadequacy of offline fit alone for controller selection. It **supports, with bounded scope**, a shared Kármán backbone over tested conditions and finite pointwise extension performance. It does **not establish** uniqueness, universality, explicit illusion target tracking, necessity of every illusion term, physical delay from DTW lag, or causal deficit compensation without field-level analysis. - -## 11. Reproducibility and evidence map - -### 11.1 Environments and resources - -Stage 1, policy replay, and Stage 3 use conda environment `pycuda_3_10`. PySR discovery and numerical refitting use `sr_env`. CFD runs are strictly serialized on physical GPU 2. With `CUDA_VISIBLE_DEVICES=2`, scripts use logical device 0; provenance records visibility and GPU identity. Run IDs are immutable and failure telemetry is retained. - -At the 2026-07-21 final-consolidation revision, the CPU contract suite is run from the repository root with: - -```bash -PYTHONPATH=src conda run -n sr_env python -m pytest \ - src/SR_analysis/tests tests/test_stage_3_validate.py -q -``` - -The expected result at the 2026-07-21 plotting-package revision is 88 passed tests. This count is revision-specific rather than a timeless scientific result. - -### 11.2 Primary and extension packages - -The primary evidence index is: - -```text -src/SR_analysis/results/runs/article-joint-sr-final-20260718/ - readable_summary.txt - evidence_manifest.json -``` - -The coefficient-frozen extension is indexed by: - -```text -src/SR_analysis/results/runs/article2-sr-elements-20260720/ -src/SR_analysis/results/runs/article2-steady-analysis-20260720/ -src/SR_analysis/results/runs/article2-percase-refit-summary-20260720/ -src/SR_analysis/results/runs/article2-generalization-summary-20260720/ -``` - -Standard-duration PPO/SR/target CSVs, including wide/long tables and DTW convergence, are under `article2-timeseries-csv-20260720/`. Four-hundred-step SR/target exports are under `article2-long-timeseries-csv-20260720/`. - -### 11.3 Stable identities - -The archived fitting Git SHA is `ca8ee5f238ee58eaaf48027ad026c35784f76d4d`. Kármán and illusion dataset hashes are respectively - -```text -dcbfdaaa48a61bd904bb540f3067760530bd69e88ce87d54110a79ecc54b79d6 -50c1d9f95bd72afc14e2d06a205bf4432672224ebf7daeb442ea6c517fbd9ab7 -``` - -Formula-pair hashes are - -```text -Karman: a678f2019e0da7a0e1263f0c911b377106a668a6716ba93d6efd78f58de0a3f1 -Illusion: ae67ae5071065b7ee8412791ee1841011530746865528641beddb1a203c51b83 -``` - -Formula JSON files carry exact commands, parent hashes, feature order, expression hashes, optimizer state, environment, and offline metrics. Validation JSON files carry formula/configuration hashes, metric details, GPU identity, telemetry hash, termination, and record hash. `scene_registry.json` is not the authority for current article evidence, and integrity auditing does not automatically promote a candidate. - -## 12. Final paper-level conclusion - -The Kármán analysis provides the strongest mechanism-oriented SR result. A persistent rear-pair counter-rotation is the dominant tested component; rear symmetric-lift feedback gives secondary short-horizon value; the tested front correction is weak. The constant has the same physical order as independently useful steady counter-rotation, which is consistent with a wake-deficit-compensation hypothesis. Spatial momentum correction and causality remain for OID/CCD, and reduced Re400 performance prevents a universal-law claim. - -The illusion analysis provides a stable shared symmetric numerical controller but not a unique target-tracking mechanism. Front-lift terms dominate action sensitivity, drag-asymmetry terms are partly replaceable, and 1.5L is a distinct boundary regime. Static target/error variables were not selected robustly, so further mechanism work should use controlled target-aware dynamic structures and independent field decomposition rather than broader unconstrained symbolic searches. - -The general methodological conclusion is that SR in closed-loop flow control should be treated as hypothesis generation plus deployment testing. Formula compactness and offline fit identify candidates; CFD stability, trajectory similarity, ablation, and independent flow-field evidence determine what can be interpreted physically. diff --git a/docs/OID_analysis_results.md b/docs/OID_analysis_results.md deleted file mode 100644 index 7a1afdc..0000000 --- a/docs/OID_analysis_results.md +++ /dev/null @@ -1,292 +0,0 @@ -# OID Analysis: Correction-Field Structure Diagnosis Results - -> Date: 2026-06-15 -> Project: DynamisLab -- Active hydrodynamic cloaking and illusion using DRL on a fluidic pinball. -> Analysis pipeline: OID (Observable-Inferred Decomposition) on correction fields (Delta-q_ctl). - ---- - -## Executive Summary - -Four key findings from the OID analysis pipeline: - -1. **Force-relevant and signature-relevant correction structures systematically separate** across control tasks. In steady cloak, they are highly related (cosine similarity = 0.763); in Karman cloak, nearly orthogonal (-0.034); in illusion, increasingly anti-correlated as target diameter grows (from -0.082 to -0.932). This is the most striking result of the analysis. - -2. **OID consistently and substantially outperforms POD** for predicting both force and future sensor signature. Across all periodic scenes, OID achieves R2 = 0.315-0.750 with 2 coordinates, while POD achieves R2 = -2.4 to 0.418. The success criterion ("m<=3 OID beats m<=3 POD") is satisfied for every scene. - -3. **The separation is robust.** POD rank sensitivity tests (r=6,8,10,12,16) confirm Karman and illusion 1.0L/1.5L are very stable. Karman's force-sig separation is insensitive to the choice of convective delay tau_c (overlap ranges 0.11-0.31 across 10 different delays). The one exception is illusion 0.75L, which shows rank sensitivity and needs more data. - -4. **OID coordinates are not control states.** Force-OID coordinates capture only 22.5% of action variance (vs 95.6% for raw sensor observations). This is expected and appropriate: OID identifies structures most relevant to forces and signatures, not to actions. Action-related coordinates require a separate causal-PCD analysis. - ---- - -## 1. OID: What It Is and Why - -### 1.1 The Problem with POD - -Standard POD (Proper Orthogonal Decomposition) ranks flow structures by their **fluctuation energy**. The highest-energy modes capture the most "energetic" features of the flow -- typically the von Karman vortex shedding pair. But the DRL controller's objective is not "maximize energy" or "minimize energy." It is to match a downstream sensor signature, which may involve flow structures that are not the most energetic. - -POD provides a useful unified coordinate system, but its ranking is by energy, not by task relevance. - -### 1.2 The OID Idea - -OID (Observable-Inferred Decomposition, Schlegel et al. 2012) is a generalization of POD that finds flow structures most correlated with a chosen **observable** of interest (e.g., total force, sensor error). The idea is: - -1. Start with a POD coordinate system (the unified basis) -2. Choose an observable Y (e.g., total lift force, delayed sensor error) -3. Compute the cross-covariance matrix between POD coefficients A and observable Y -4. Perform SVD on this cross-covariance: `C_AY = U @ Sigma @ V.T` -5. The columns of U define directions in POD space that best predict the observable - -The OID coordinates are: - -``` -z(t) = A(t) @ U -``` - -This is a simple rotation of the POD subspace. The singular values in Sigma tell us how much observable-relevant information each OID direction captures. The spatial modes are linear combinations of POD modes: - -``` -phi_k_OID(x,y) = sum_j U_{jk} * phi_j_POD(x,y) -``` - -### 1.3 The Correction-Field Preprocessing - -Before OID, we must separate what the controller actually changed from what the flow inherently does. For each scene we construct three fields: - -- **q_in**: Incident reference field (empty channel, or vortex street only) -- **q_blk**: Fixed pinball field (pinball present, zero rotation, natural shedding) -- **q_ctl**: Controlled pinball field (DRL policy active) - -The two derived difference fields are: - -- **Delta_q_blk = q_blk - q_in**: What the pinball's geometry does (passive blockage) -- **Delta_q_ctl = q_ctl - q_blk**: What the controller additionally does (active correction) - -OID operates on Delta_q_ctl (the active correction), NOT on the raw controlled field. This separation prevents mixing up "structures that were already there" (inherent shedding) with "structures the controller introduced." - -### 1.4 The OID Pipeline - -``` -Full field snapshots (500 steps) - | - v -Three-field decomposition: q_in, q_blk, q_ctl - | - v -Correction field: Delta_q_ctl = q_ctl - q_blk - | - v -POD on Delta_q_ctl -> coefficients A(t), modes phi(x,y) - (rank sensitivity: r=6,8,10,12,16) - | - v -Choose observable Y: - - Force-OID: Y = total force [Fx, Fy] - - Signature-OID: Y = delayed sensor error e_s(t + tau_c) - - Suppression-OID (steady only): Y = RMS fluctuation - | - v -Cross-covariance SVD: C_AY = (1/N) A^T Y = U Sigma V^T - | - v -OID coordinates: z(t) = A(t) @ U -OID modes: psi_k = sum_j U_{jk} * phi_j -``` - -### 1.5 Scene Setup - -| Scene | Inflow | Uncontrolled | Controlled | SI | Action bias | -|-------|--------|-------------|------------|----|-------------| -| Steady cloak | Parabolic (uniform) | Pinball natural shedding | Rear cylinders at constant +-5.1U0 | 800 | [0, -5.1, 5.1] | -| Karman cloak | Upstream vortex street | Pinball disrupts street | PPO periodic rotation (d1a3o12_re100) | 800 | [0, -4, 4] | -| Illusion 0.75L | Parabolic | Pinball natural shedding | PPO (d1a3o14_075L_2U_400S) | 400 | [0, -2, 2] | -| Illusion 1.0L | Parabolic | Pinball natural shedding | PPO (d1a3o14_1L_2U_600S) | 600 | [0, -2, 2] | -| Illusion 1.5L | Parabolic | Pinball natural shedding | PPO (d1a3o14_15L_2U) | 800 | [0, -2, 2] | - -System: 2D channel flow (1280x512 grid, 3 rotating cylinders, Re=100 code = Re_D=50 physical). -All models: PPO with Sin activation, SB3, 64x64 hidden layers. - ---- - -## 2. Core Result: Force-vs-Signature Systematic Separation - -### 2.1 The Monotonic Trend - -**Figure 1** (the flagship figure) shows the cosine similarity between force-OID mode 1 and signature-OID mode 1 across all five scenes: - -![Figure 1](src/OID_analysis/data/derived/figures/fig1_force_sig_overlap.png) -*File: `src/OID_analysis/data/derived/figures/fig1_force_sig_overlap.png`* - -**Panel (a)** shows the signed overlap. A cosine similarity of +1 means the two modes point in identical directions; 0 means orthogonal; -1 means opposite directions. - -**Panel (b)** shows the absolute overlap with three interpretation zones color-coded: green (same channel, |overlap| > 0.7), orange (partial separation, 0.3-0.7), red (orthogonal/separated, < 0.3). The gray arrow highlights the monotonic trend. - -The trend is remarkably clean: - -| Scene | Signed overlap | Separation level | -|-------|---------------|-----------------| -| Steady cloak | **+0.763** | Same channel | -| Karman cloak | **-0.034** | Nearly orthogonal | -| Illusion 0.75L | **-0.082** | Near-orthogonal | -| Illusion 1.0L | **-0.495** | Moderate separation | -| Illusion 1.5L | **-0.932** | Strongly opposite | - -**Physical interpretation**: The DRL controller does not engage the same flow structures for all tasks: - -- **Steady cloak**: The goal is to suppress natural shedding. Suppressing shedding IS suppressing force, so both objectives engage the same correction structures. -- **Karman cloak**: The goal is to let the incoming vortex street pass through undisturbed. The correction structures that preserve the street are orthogonal to those that would maximally alter the force. The controller must "stay out of the way" of natural force-generating modes. -- **Illusion**: The goal is to generate a target shedding pattern different from natural pinball shedding. Force-OID finds structures that modify the natural force, while signature-OID finds structures that generate the target frequency. These are increasingly different -- and eventually opposite -- as the target deviates further from the natural scale. - -This monotonic trend from +0.763 through -0.034 to -0.932 is the most compelling evidence that **force-relevant and signature-relevant correction structures are not the same, and their divergence quantifies task difficulty**. - ---- - -## 3. Robustness of the Core Result - -### 3.1 POD Rank Sensitivity - -**Figure 2** shows how the force-sig overlap changes when the POD truncation rank varies from 6 to 16: - -![Figure 2](src/OID_analysis/data/derived/figures/fig2_rank_sensitivity.png) -*File: `src/OID_analysis/data/derived/figures/fig2_rank_sensitivity.png`* - -Each subplot is one scene. The y-axis is force-sig overlap. Stability is measured by the standard deviation across ranks. - -| Scene | std | Stability | Verdict | -|-------|-----|-----------|---------| -| Steady cloak | 0.10 | Moderate | Sign consistent, magnitude varies | -| **Karman cloak** | **0.07** | **Stable** | **Always near zero** | -| Illusion 0.75L | 0.26 | **Unstable** | **Needs more data** | -| **Illusion 1.0L** | **0.03** | **Stable** | **Monotonic trend confirmed** | -| **Illusion 1.5L** | **0.02** | **Stable** | **Strongly separated across all ranks** | - -Three of five scenes are very stable. The exception (0.75L, std=0.26) is flagged for future investigation with longer time series. - -### 3.2 Karman tau_c Sensitivity - -For Karman cloak, the signature observable requires a convective delay tau_c (the time for flow structures to travel from pinball to downstream sensors). If tau_c is wrong, the signature-OID could be misaligned. - -**Figure 4** sweeps tau_c from 0 to 60 steps (the shedding period is approximately 30 steps): - -![Figure 4](src/OID_analysis/data/derived/figures/fig4_tauc_sensitivity.png) -*File: `src/OID_analysis/data/derived/figures/fig4_tauc_sensitivity.png`* - -**Top panel**: Force-sig overlap stays between 0.11 and 0.31 across ALL tau_c values. The overlap is always near the orthogonal threshold. **The Karman force-sig separation is not an artifact of a bad delay choice.** - -**Bottom panel**: Signature-OID R2 stays between 0.26-0.33 across all delays. Force-OID R2 is constant at 0.36 (since force has no delay). The signature prediction is modest but stable. - ---- - -## 4. OID vs POD: Quantitative Advantage - -### 4.1 Prediction Performance - -**Figure 3** compares OID and POD for both force prediction and signature prediction, using m=2 coordinates: - -![Figure 3](src/OID_analysis/data/derived/figures/fig3_oid_vs_pod_r2.png) -*File: `src/OID_analysis/data/derived/figures/fig3_oid_vs_pod_r2.png`* - -**Panel (a)**: Force prediction. OID (blue bars) strongly outperforms POD (red bars) in every scene. POD gives negative R2 for illusion 0.75L and 1.0L (meaning it is worse than predicting the mean), while OID gives positive R2. - -**Panel (b)**: Signature prediction. Sig-OID (green) outperforms POD (red) in every scene. The strongest effect is at 0.75L (OID R2=0.661 vs POD R2=-0.034). - -Master comparison table: - -| Scene | Task | OID R2 (m=2) | POD R2 (m=2) | OID wins? | -|-------|------|:-----------:|:-----------:|:---------:| -| Karman | Force | **0.750** | 0.418 | YES | -| Illusion 0.75L | Force | **0.435** | -2.426 | YES | -| Illusion 0.75L | Signature | **0.661** | -0.034 | YES | -| Illusion 1.0L | Force | **0.671** | -0.237 | YES | -| Illusion 1.0L | Signature | **0.586** | -0.160 | YES | -| Illusion 1.5L | Force | **0.640** | 0.264 | YES | -| Illusion 1.5L | Signature | **0.315** | 0.060 | YES | - -### 4.2 Correction-Field Dimensionality - -**Figure 5** confirms that correction fields are inherently low-dimensional: - -![Figure 5](src/OID_analysis/data/derived/figures/fig5_pod_energy.png) -*File: `src/OID_analysis/data/derived/figures/fig5_pod_energy.png`* - -All scenes capture 97.9-99.9% of correction-field fluctuation energy in just 5 POD modes. This justifies the "r=10" default truncation (safety margin) and confirms that the controller operates in a very low-dimensional correction space. - ---- - -## 5. Steady Cloak: Suppression Metrics - -**Figure 6** presents the physically meaningful metrics for steady cloak (replacing the inappropriate time-series R2): - -![Figure 6](src/OID_analysis/data/derived/figures/fig6_steady_metrics.png) -*File: `src/OID_analysis/data/derived/figures/fig6_steady_metrics.png`* - -| Metric | Value | Interpretation | -|--------|-------|---------------| -| Full-field RMS reduction | **99.43%** | Nearly complete fluctuation suppression | -| Recirculation area collapse | **38.55%** | The mean wake bubble shrinks significantly | -| Recirculation length change | **3.24%** | The bubble length barely changes | -| Fy (lift) RMS reduction | **83.29%** | Lift fluctuations strongly suppressed | - -The large area collapse with minimal length change is interesting: the controlled wake becomes **narrower** but not **shorter**. This suggests the control primarily suppresses lateral (y-direction) fluctuations rather than shortening the streamwise extent of the recirculation zone. - ---- - -## 6. OID and the Control Law - -### 6.1 White-Box Chain - -**Figure 7** answers: do OID coordinates capture the full control law? - -![Figure 7](src/OID_analysis/data/derived/figures/fig7_whitebox_summary.png) -*File: `src/OID_analysis/data/derived/figures/fig7_whitebox_summary.png`* - -| Model | Action R2 | Meaning | -|-------|:---------:|---------| -| obs -> act | **0.956** | PPO baseline: raw sensors predict actions | -| OID coord -> act | **0.225** | Force-OID coordinates capture 22.5% of action variance | -| OID+force -> act | **0.233** | Adding force doesn't help | - -This is NOT a failure. OID is designed to find structures relevant to **observables** (force, signature), not to **actions**. Force-OID coordinates are physics-interpretable coordinates (what correction structures affect force), not control-state coordinates (what the controller internally uses). An action-related coordinate would require a separate causal-PCD analysis using the action itself as the observable. - ---- - -## 7. Open Items and Caveats - -1. **Illusion 0.75L rank sensitivity** -- The force-sig overlap varies with POD rank (std=0.26). This needs investigation with a longer time series or phase-resampled data. - -2. **Karman future-signal R2** -- Signature-OID gives R2 near zero for Karman. This is under investigation. Possible causes: (a) the delayed error observable has artificially low variance due to target alignment; (b) tau_c needs scene-specific estimation using cross-correlation. - -3. **No mode-to-field mapping** -- OID spatial modes (psi_k) are computed but not yet visualized as flow field plots. This would answer: "where in the physical domain does the force-sig separation live?" (near-body vs downstream). CCD zone analysis already suggests the answer is zone-dependent. - -4. **PCD (whitened) did not outperform simple OID** -- The more complex whitened cross-correlation did not improve results. The simple cross-covariance SVD is sufficient for the current data quality. - -5. **No cross-validation** -- The current R2 values are from 70/30 split on a single rollout. Cross-validation across multiple independent rollouts would strengthen the results. - -6. **Data independence** -- All scenes use the same correction-field protocol (Delta-q_ctl = q_ctl - q_blk), ensuring fair cross-scene comparison. The illusion-position q_blk was collected separately from the cloak-position q_blk (geometry is different: front_x 19 vs 30, sensor_x 30 vs 40). - ---- - -## 8. Figures - -All figures in `src/OID_analysis/data/derived/figures/`: - -| Figure | File | Description | -|--------|------|-------------| -| 1 | `fig1_force_sig_overlap.png` | **Flagship**: Force-OID vs signature-OID overlap across all 5 scenes. Signed and absolute versions with monotonic trend. | -| 2 | `fig2_rank_sensitivity.png` | POD rank sensitivity (r=6,8,10,12,16) of force-sig overlap. 5 subplots, one per scene. | -| 3 | `fig3_oid_vs_pod_r2.png` | OID vs POD prediction R2. Left: force. Right: signature. All 4 periodic scenes. | -| 4 | `fig4_tauc_sensitivity.png` | Karman tau_c sensitivity. Top: overlap vs delay. Bottom: R2 vs delay. 10 delays tested. | -| 5 | `fig5_pod_energy.png` | Correction-field POD energy capture (5 modes, cumulative %). | -| 6 | `fig6_steady_metrics.png` | Steady cloak suppression metrics: RMS reduction, recirculation collapse, force reduction. | -| 7 | `fig7_whitebox_summary.png` | White-box chain: obs->act vs OID->act vs OID+force->act. Horizontal bar chart. | - ---- - -## 9. References - -- Sch12: Schlegel et al. "On least-order flow representations for aerodynamics and aeroacoustics." JFM 2012. -- Lyu23: Lyu et al. "Canonical correlation decomposition for data-driven analysis." -- Kan17b: Kantsios et al. "Body-connected near wake as primary force determinant." -- Che19, Che21b: Chen-Liu line on rotation first rewriting near-body source terms. -- Tad10: Tadmor et al. "Low-dimensional state for flow control." diff --git a/docs/figures/SR_analysis/fig1_illusion_comparison.png b/docs/figures/SR_analysis/fig1_illusion_comparison.png deleted file mode 100644 index ca8b283..0000000 Binary files a/docs/figures/SR_analysis/fig1_illusion_comparison.png and /dev/null differ diff --git a/docs/figures/SR_analysis/fig2_karman_ablation.png b/docs/figures/SR_analysis/fig2_karman_ablation.png deleted file mode 100644 index 15074bf..0000000 Binary files a/docs/figures/SR_analysis/fig2_karman_ablation.png and /dev/null differ diff --git a/docs/figures/SR_analysis/fig3_karman_generalization.png b/docs/figures/SR_analysis/fig3_karman_generalization.png deleted file mode 100644 index 9de1a1f..0000000 Binary files a/docs/figures/SR_analysis/fig3_karman_generalization.png and /dev/null differ diff --git a/docs/figures/SR_analysis/fig4_r2_vs_closedloop.png b/docs/figures/SR_analysis/fig4_r2_vs_closedloop.png deleted file mode 100644 index b2a6956..0000000 Binary files a/docs/figures/SR_analysis/fig4_r2_vs_closedloop.png and /dev/null differ diff --git a/docs/figures/SR_analysis/fig5_illusion_coefficients.png b/docs/figures/SR_analysis/fig5_illusion_coefficients.png deleted file mode 100644 index 23e088d..0000000 Binary files a/docs/figures/SR_analysis/fig5_illusion_coefficients.png and /dev/null differ diff --git a/docs/figures/SR_analysis/fig6_roadmap.png b/docs/figures/SR_analysis/fig6_roadmap.png deleted file mode 100644 index e0fe0e8..0000000 Binary files a/docs/figures/SR_analysis/fig6_roadmap.png and /dev/null differ diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..9a0b73a --- /dev/null +++ b/src/README.md @@ -0,0 +1,28 @@ +# `src/` index + +This directory contains the active analysis and rendering packages for DynamisLab. Read the package authority documents before using any result; `src/analysis_knowledge.md` records cross-project contracts, while `src/analysis_notes.md` records current gates and writing status. + +| Package | Current role | First documents | +|---|---|---| +| [`drl_pinball`](drl_pinball/) | Active V5 training/evaluation plus bounded Legacy reproduction and writing evidence | [`README`](drl_pinball/README.md), [`CLAIMS`](drl_pinball/CLAIMS.md), [`RESULTS`](drl_pinball/RESULTS.md) | +| [`SR_analysis`](SR_analysis/) | Bounded Legacy Kármán symbolic-regression evidence; Illusion SR is historical/negative | [`README`](SR_analysis/README.md), [`CLAIMS`](SR_analysis/CLAIMS.md), [`results/INDEX`](SR_analysis/results/INDEX.md) | +| [`CCD_analysis`](CCD_analysis/) | Closed, descriptive corrected Kármán CCD/POD comparison | [`README`](CCD_analysis/README.md), [`RESULTS_INDEX`](CCD_analysis/RESULTS_INDEX.md), [`CLAIMS`](CCD_analysis/CLAIMS.md) | +| [`OID_analysis`](OID_analysis/) | Claim-free CPU method core; old two-scene study is archived | [`README`](OID_analysis/README.md), [`SCIENTIFIC_RESET`](OID_analysis/SCIENTIFIC_RESET.md) | +| [`steady_pinball_theory`](steady_pinball_theory/) | Active NS-first steady-flow investigation with bounded evidence | [`README`](steady_pinball_theory/README.md), [`RESULTS`](steady_pinball_theory/RESULTS.md) | +| [`pv_plot`](pv_plot/) | Small ParaView/FFmpeg rendering utility | [`README`](pv_plot/README.md) | +| [`archive`](archive/) | Superseded repository-level reproduction material | package README/index files only; non-authoritative by default | + +## Solver boundary + +`CelerisLab/` is the modern GPU LBM submodule and is intentionally outside this repository closeout. `LegacyCelerisLab/` is tracked legacy solver source used by SR and historical reproduction. V5 and Legacy artifacts, normalization, action ordering, timing, and metrics must remain separate unless a document explicitly defines a migration comparison. + +## Evidence and storage + +- Compact manifests, tests, authority documents, and selected publication figures belong in Git. +- Large arrays, CFD outputs, generated plot trees, and external Optane mappings are local/external evidence and should be referenced by manifests or relocation notes rather than bulk-committed. +- `analysis_knowledge.md` is the durable cross-package contract ledger; package `README`, claims/results ledgers, and manifests are the numerical authorities. +- Working Memory is a retrieval aid, not a substitute for repository artifacts. + +## Reading rule + +For any claim, identify package, solver, case, role, realization/seed, time window, metric definition, artifact path or hash, and evidence status. If those fields are missing, treat the statement as navigation or historical context rather than authoritative science. diff --git a/src/analysis_knowledge.md b/src/analysis_knowledge.md index b1240cf..4a75e04 100644 --- a/src/analysis_knowledge.md +++ b/src/analysis_knowledge.md @@ -1,357 +1,211 @@ -# 主分析知识库 +# 跨项目科学与认识论知识库 -## 文档作用 +> 状态日期：2026-08-09。本文只保存可跨项目复用的科学合同、证据边界、工作假说、失败经验与开放问题；不安排任务，不以 `.cursor` 计划或 Memory 作为科学证据。数值与状态以各当前包的权威文档、可执行合同、不可变产物及清单为准。 -这份文档只负责保存当前主分析线里已经形成的**长期判断、边界条件、方法论经验和不该忘的坑**。 +## 1. 如何阅读本文 -它不安排执行顺序，也不写“下一步做什么”。凡是优先级、阶段、第一轮交付物，统一写在 `analysis_notes`。 +本文统一使用五类状态： -这里重点保留： +- **已确立合同（established contract）**：定义、坐标、单位、角色、比较量、对齐方式或证据准入规则；它规定“可以比较什么”，不等同于物理机制已证明。 +- **有界支持观察（bounded supported observation）**：在明确场景、窗口、分辨率、比较器和实现下由当前证据支持；不得外推为普适规律、因果或稳定性。 +- **工作假说（working hypothesis）**：与现有观察及文献相容、可组织后续检验，但尚未由本项目建立。 +- **撤回/历史（withdrawn/historical）**：保留以防重复犯错或丢失出处，但不得作为当前正面结论。 +- **开放问题（open question）**：现有证据不能回答，且不能用解释性语言填补。 -- 这一轮调研后已经比较稳的物理判断 -- 哪些文献对当前项目真的有用，分别用在什么层级 -- 哪些解释现在可以说，哪些不要说过头 -- 当前网格分辨率下，哪些分析是可信的，哪些不可信 +证据优先级通常为：源代码/冻结合同与机器可检验清单 → 不可变原始或派生产物 → 当前结果与 claim ledger → 读者图表和综述。后出的严格证据可以下调旧结论，而无需改写旧产物。计划、聊天记录和 Memory 只能帮助定位材料，不能升级科学主张。 -## 一、当前最重要的认识变化 +## 2. 已确立合同 -这一轮最大的变化，不是又多知道了几篇文献，而是**分析层级变了**。 +### 2.1 雷诺数、尺度与实现世代 -之前最容易滑向两个方向： +- **必须同时写清 `Re_code` 与 `Re_D`。** Legacy 命名中的长度基准为 `2D`，因此在现有 Legacy SR/Kármán合同中 + \[ + Re_D = Re_{code}/2. + \] + 例如 `karman_re100` 对应单圆柱直径定义的 `Re_D=50`，不能简称“Re=100”后与现代 `Re_D=50` 数据混合。 +- **Legacy 与 modern/V5 是两条证据链。** 即使名义网格、几何或 `U_0` 相同，壁面离散、动作单位、平滑、力/传感器累计与归一化、对象顺序、边界条件和 checkpoint 行为也可能不同。名义换算不构成数值奇偶性证明。 +- 坐标、数组存储、绘图方向、圆柱顺序和动作符号必须由当前源码/合同及壁面点速度 oracle 绑定。现代 Celeris 连续符号约定为 + \[ + (U_w,V_w)=(-\Omega r_y,\Omega r_x). + \] + “顺/逆时针”“上/下圆柱”标签不能越过显式对象 ID、中心坐标与壁面速度检查。 +- 跨包引用只能作为**情境三角验证**；不同 plant、边界条件、估计量或窗口的数值不能伪装成重复试验。 -- 要么把机制写成 `obs -> act -> force -> signature` -- 要么试图直接搬壁面涡量理论，做单圆柱边界层级别的解释 +### 2.2 三场分解与均值—动态分离 -现在更稳的理解是： +一般动态/差分分析先定义角色： + +- `q_in`：无 pinball 的入射/目标参考场； +- `q_blk`：固定 pinball 的被动阻挡场； +- `q_ctl`：受控 pinball 场。 + +并定义 \[ -\text{obs} \rightarrow \text{act} \rightarrow \text{near-body correction} \rightarrow \text{wake structure} \rightarrow \text{force / future signature} +\Delta q_{blk}=q_{blk}-q_{in},\qquad +\Delta q_{ctl}=q_{ctl}-q_{blk},\qquad +\Delta q_{tot}=q_{ctl}-q_{in}=\Delta q_{blk}+\Delta q_{ctl}. \] -也就是说： +解释权随定义冻结：`Δq_blk` 是几何/边界引入的被动差异，`Δq_ctl` 是相对于固定基线的控制附加差异，`Δq_tot` 是最终残差。三者不可互换；“控制抵消阻挡”至少需要在同一掩膜、单位、时间/相位和估计量上比较 `Δq_ctl` 与 `-Δq_blk`。 -- **force 依然重要，但更像近体区修正过程的低维投影，而不是唯一第一性机制** [Zhu15]。 -- **Chen Tao 线依然重要，但它提供的主要是因果方向，不是当前网格下可直接照搬的壁面分析模板** [Che19, Che21b, Ter21]。 -- **当前最可信、也最值得主打的层级，是 pinball 整体尺度的 correction field**，而不是单圆柱 wall-scale 细节。 - -## 二、Chen Tao 这条线对本项目到底有什么用 - -### 1. 有用的不是“旋转会改变表面量”这句常识 - -真正有用的是下面这条因果链： +均值和动态必须分开： \[ -\text{rotation} \rightarrow \text{surface condition change} \rightarrow \text{near-body vorticity organization} \rightarrow \text{shear-layer bias} \rightarrow \text{wake / force / signature} +q=\overline q+q',\qquad +\Delta q=\Delta\overline q+\Delta q'. \] -这条线的价值在于，它逼着解释停留在“近体区结构如何被改掉”这一层，而不是直接从动作跳到力，或者从动作跳到远场 wake。 +平均性能改善不能自动解释相位动态；相位共变也不能自动解释均值改善。常值控制贡献、反馈增量和波动结构应使用不同估计量并验证加法闭合。 -### 2. 最适合当前项目的 Chen–Liu 文献分工 +**steady 例外：** 当前 steady 主合同直接以 `q_ctl` 对匹配的无体 `q_in` 做全剖面性能评估；`q_blk` 是非排名参考。因此 steady 的主指标不是 `Δq_ctl=q_ctl-q_blk`，也不能因三场记号而把参考再减一次。历史半解析 scorer 的 double subtraction 正是此类合同错误。 -| 论文 | 在当前项目里的角色 | -|---|---| -| [Che19] | 最重要的桥梁。告诉我们表面压力、skin friction、boundary enstrophy flux 是耦合的，因此近体区源项不是空话。| -| [Che21b] | 提醒我们这些源项不是静态量，而有时空演化，并且和 separation / attachment 及近壁相干结构相关。| -| [Che24d] | 把 boundary vorticity flux 继续拆成 orbital rotation 与 spin，适合用来升级机理语言，但不是第一轮主证据。| -| [Che24e] | 提醒 Q-criterion 类量不要解释过满，边界上的 strain / enstrophy / Q 源项是不同层次。| -| [Che26] | 这是这一支到 JFM 的理论总论，更像上层统一框架，而不是 rotating-cylinder wake 的直接分析手册。| +### 2.3 对齐、比较与声明 -### 3. 当前项目里最该保留的 Chen 线结论 +- 时序、状态、动作、力、传感器和场必须按实际采样时钟与语义对齐；相邻步错位可产生漂亮但错误的公式或相关结构。 +- 周期场需绑定周期选择、相位原点、保留边界、bin 数和角色间配对规则。DTW 的循环位移是算法参数，不是物理响应延迟。 +- 任何数字旁应能恢复：场景、plant、`Re_code/Re_D`、窗口、掩膜/ROI、单位、比较器、样本/realization 数、状态标签和产物身份。 +- 预测/重构成功不等于重要性；相关不等于因果；空间先后不等于时间因果；单次 deterministic realization 不提供独立实现不确定度。 -- 旋转不是直接“指定一个目标 wake”，而是先改写近体区源项和剪切层出生条件。 -- 受力不是与涡量竞争的替代机制，而更像近体区涡量组织变化后的整体积分响应。 -- 若网格不支持壁面精细诊断，仍然可以保留“近体区源项先变、远场 observable 后变”这条因果顺序。 +## 3. 有界支持观察 -## 三、哪些部分现在不要硬做 +### 3.1 SR：当前只支持 Kármán/cloaking 正面结果 -当前 CFD 中单圆柱只占十多格，这是一个非常硬的边界条件。由此带来几个必须长期保留的判断： +- 当前 SR 科学范围是 **Legacy Kármán/cloaking only**；steady 只作幅值与结构显著性的情境校准。 +- 冻结 mapped-shared Kármán 稀疏律在命名的 Legacy `Re_code=50,100,200,400`、有限 200/400-step 部署中保持有限并取得已记录 DTW；这支持“可复现的稀疏闭环降阶控制器”，不支持全局符号最优、渐近稳定、普适 Reynolds 定律或统计鲁棒性。 +- 在已测试删除中，后圆柱持久反向旋转常数项最显著，后部升力反馈次之，前部反馈较弱。这里的“主导”只指父公式、指定窗口和已测试删除；不等于唯一充分、普遍必要或流动物理因果机制。 +- SR 是 `obs → act` 的白箱接口：它说明所选闭环公式依赖哪些可观测组合，不能独立完成 `act → flow → force/signature` 的机制证明。 -| 不应硬做的分析 | 原因 | -|---|---| -| 单圆柱边界层厚度与细节 | 分辨率不够 | -| 单圆柱精确分离点、附着点 | 数值可信度不足 | -| 壁面涡量通量逐点定量值 | 网格不足以支撑 | -| 以 wall-scale 量做主机制证据 | 容易把分辨率不支持的内容写过满 | +### 3.2 Illusion SR：负面/历史证据 -因此，对当前项目最稳的表述是： +- 旧的有限窗口 Illusion 公式与目标相似度保留为历史事实，但不是当前正面控制结论。 +- 所选静态公式虽在可用特征池中可访问 target/error，却没有显式选入它们；这不证明 PPO 不使用目标信息，只证明该静态 SR 公式没有显式表达它。 +- 标准化长窗口 Legacy `illusion_1L` 中，SR 与 physical zero 的 native/normalized DTW 实质相同，均值场和 phase-8 误差略差于 zero，动作趋近零。因此撤回 target tracking、相对 zero 的有效性、跨尺寸泛化、逐项必要性及机制主张。 +- Illusion 运行能力可为兼容性保留；“代码能跑”与“科学主张成立”是不同状态。 -- 可以引用 Chen–Liu 线来支持“壁面/近体区过程在前”； -- 但自己的主证据必须落在 **pinball-scale near-body correction** 上。 +### 3.3 corrected CCD：ROI 均值与 rank-3 描述共变 -## 四、为什么三场分解是当前最关键的方法论 +- 当前 corrected Kármán 权威使用 inclusive wake ROI `34<=x/D<=54, |y/D|<=5` 和四角色 solver-fluid mask 精确交集，共 80,200 点；速度已无量纲化，不得再次除以 `U0`。 +- ROI mean target error 为：zero `0.4694352273`、constant mean `0.1110140739`、DRL `0.0857787860`。zero→constant 与 constant→DRL 的改善严格加法闭合；这支持**均值控制贡献很大、反馈再提供较小增量**的观察。它不是 steady 后部动作机制的证明。 +- corrected CCD 使用 19 个 DRL 周期 × 10 phase bins，`N=190, Q=1, M=160400`，数值 rank 3。每个 DRL 周期/bin 相对一个 19-cycle constant ensemble phase template 独立居中并作差，角色周期不配对；无 POD、whitening 或 standardization。 +- 8-bin、12-bin 和 half-bin-10 的独立 retained-boundary 检查支持稳定的 rank-3 **子空间**；最不利 projector cosine 为 `0.9947903592`，最大相对奇异值变化 `0.0766020533`。单个 mode/action vector 只是该稳定子空间的一组 SVD 基表示。 +- 允许的最强表述是：**phase-coherent DRL-minus-constant-template 的 rank-3 描述性共变**。不支持 paired counterfactual、因果、机制、响应时间、独立实现不确定度、解释方差/场能量、CCD 优越性或相对 POD 优越性。 -这是这一轮最重要的方法收获。 +### 3.4 OID：无主张方法核心 -如果直接看控制场，很容易把三种影响混在一起： +- 当前 OID 包是 claim-free、CPU-only 方法核心：加权 snapshot POD、Schlegel LR/LE 线性映射与 generated-range 处理、符号不变的 mode/subspace 指标、exact/delayed pairing 和原子产物验证。 +- 当前没有 active scientific result、scene runner、GPU/plotting path 或 LR/LE action 结果。 +- 2026-07 两场景研究是 conditional archive：sensor 高 R² 部分来自 state 域内局部速度的 self-observation；force 未过 gate；action delayed association 未隔离策略反馈。因此不存在可比较的“sensor/force/action importance”排名。 +- `q_ctl-q_blk` 在 OID 语境中仍只是 paired closed-loop branch difference；预测或重构不能升级为重要性、机制、因果、控制器必要性、执行器 authority 或 controllability。 -- 入射来流本身的结构 -- pinball 作为障碍物的阻挡作用 -- 旋转控制额外施加的修正 +### 3.5 steady：直接剖面性能成立，整体状态为 BOUNDED -因此必须至少分成三类场： +- 当前 canonical steady 合同是 uniform-inlet/free-slip、`Re_D=50`、圆柱顺序 `(front,rear_y_plus,rear_y_minus)`，接受动作 `[0,+Omega,-Omega]`，`s=Omega R/U_inf>0`。按冻结壁面速度映射，这是 **base-bleed/gap-jet family**，不是 boat-tail。 +- 主排名指标是在 `x/D=10` 整个横截面上比较 `q_ctl` 与 `q_in` 的两分量 `E_inf_vector`；显式积分 `L2` 为次要诊断，其他站位为诊断，`q_blk` 不排名。 +- 在 `s={3.45,3.55,3.65}`，`E_inf_vector={0.0232525,0.0231671,0.0312490}`。D20 与 D30 在 `s=3.55` 的 `E_inf` 相对差约 `1.33%`；这支持当前离散设置下的稳态低残差性能与局部分辨率一致性。 +- 整体发布状态是 **BOUNDED**：未建立唯一最优、全局吸引、渐近/非线性/全局稳定、跨边界条件转移或 NS 闭合机制。D10 预期欠分辨；outlet/final-window/IC 检验缺失。 +- endpoint 数据支持“壁面方向—gap/outer shear—recirculation/force—downstream deficit”的有序空间共存/关联，但不是时间因果；旧 energy ledger、single switch 和 return norm 均不足以完成机制、分支切换或稳定性证明。 -- 入射参考场 \(q_{in}\) -- 固定 pinball 场 \(q_{blk}\) -- 控制 pinball 场 \(q_{ctl}\) +## 4. 工作假说 -然后定义两个差分场： +### 4.1 跨项目主链只能作为可检验假说 + +当前可用的组织框架是： \[ -\Delta q_{blk} = q_{blk} - q_{in} +\text{observation}\rightarrow\text{action}\rightarrow +\text{near-body correction}\rightarrow +\text{body-connected wake structures}\rightarrow +\text{force structures}\rightarrow +\text{future-signature structures}. \] -\[ -\Delta q_{ctl} = q_{ctl} - q_{blk} -\] +这条链**不是本项目已经建立的机制**。它的用途是区分中介对象和设计可证伪检验： -这里最关键的不是公式本身，而是它们对应的解释权。 +- SR 可约束 `observation → action`，但不证明后续物理链。 +- difference fields 可描述 `action` 后的附加场变化，但闭环分支差异不是 intervention。 +- 文献支持“旋转壁面先改变近体涡量生成/剪切层出生条件”和“body-connected wake 与瞬时力相关”的一般物理框架；它不证明本项目每个箭头。 +- CCD/OID 可以寻找与 observable 共变或可重构的结构，但需要独立对齐、干预和 held-out 证据才能谈方向或 authority。 -- \(\Delta q_{blk}\) 代表 **几何阻挡带来的被动破坏**。 -- \(\Delta q_{ctl}\) 代表 **旋转控制额外施加的主动修正**。 +### 4.2 force-relevant 与 signature-relevant 结构应先验分开 -一旦这两个量分开，很多原本混乱的问题会立刻清楚： +- **force structures** 指对瞬时/相位积分力投影强的近体或 body-connected 结构；其重要性取决于位置、符号及与 body-induced velocity 的耦合，而非仅总涡量或能量。 +- **signature structures** 指对下游未来传感器、ROI 或目标相似度有预测/重构关系的结构；它们可能经对流和非线性演化后才形成。 +- 两者可以重叠，但不得因同一控制器同时改善力与 signature 就假定为同一子空间。force-OID 与 signature-OID 的差异首先是待解释结果，不是算法失败；相同也仍需排除共享均值、相位和 self-observation。 -- cloak 不是“什么都不产生”，而是主动修正去抵消被动破坏； -- illusion 不是“pinball 变成了目标物体”，而是在自身基线 wake 上叠加 target-like correction。 +### 4.3 当前更可信的尺度是假设性的 pinball-scale correction -## 新增补充：wake-to-force 这条线为什么重要 +现有网格对整体场、ROI、横截面和 pinball-scale wake 可有用，但通常不足以支持单圆柱 wall-scale 的精确边界层厚度、分离/再附点或逐点 boundary-vorticity-flux 定量。因此“低维调制 pinball-scale correction structures”是合理工作假说；不能把它写成已证实机制。 -这一轮新增的第二条有效文献线，不是 another force formula，而是 **wake-to-force**。它真正补上的，是 `near-body correction -> force -> signature` 这一段的物理层次。[Noc99, Una97, Kan17b, Geh23, Gom16] +## 5. 撤回与历史边界 -这条线最值得保留的结论不是“用 wake 可以算出力”，而是以下三条： +- 撤回把 Illusion SR 写成 target-aware tracking、优于 physical zero、跨尺寸普适或机制解释。 +- 撤回把 CCD rank-3 共变写成响应模态、因果通道、解释能量、独立不确定度或方法优越性。 +- 撤回从 OID 的高 sensor R²、force/action 预测或重构推导 observable importance、必要性或 authority。 +- steady 的 prescribed-circulation blockage cancellation 因符号矛盾而 **FAIL**：理论所需 `g_opt=+6.147944`，接受 CFD 的描述拟合为 `g=-12.200554`。数学上的 rear-opposite inviscid dipole 性质仍成立，失败的是其作为当前 CFD 机制的识别。 +- steady composite semi-analytic 的 held-out PASS 已撤回：scorer double-subtracted reference，`q_VI` 不随 `omega/branch`，`q_wake` 未激活，speed/direction gates 也非独立预测。该产物只能说明一次失败拟合路径。 +- `[0,-Omega,+Omega]` 不是当前 accepted cloak branch；不同幅值 reverse endpoints 不能伪装成等幅因果对照。 +- 历史 phase-domain CCD、旧 OID 两场景结果、旧 Illusion 文章包、failed gates 和 negative controls 应保留，但不得越过当前包的 archive boundary 回升为 authority。 -### 1. 力与 wake 的关系分层成立 +## 6. 分辨率与文献的认识论边界 -较早的 control-volume / momentum 公式说明，只要控制体选得合理，近尾迹速度场本身就足以恢复瞬时力的主变化。[Una97, Noc99] 这至少证明： +### 6.1 分辨率决定可声明层级 -- force 不是脱离流场的黑箱量； -- 近尾迹与力之间确实存在可重复、可计算的映射。 +可以较稳地讨论：共同掩膜上的均值/相位场、ROI 或整剖面误差、pinball-scale correction、近尾迹宽度/强度、积分力及经验证的低维子空间稳定性。 -### 2. 真正最该关注的是 body-connected wake structure +通常不能据当前粗网格主张：逐点壁面涡量通量、精确分离点、单圆柱边界层细节、闭合压力/黏性动量或能量平衡。数值收敛只支持所测数值量，不会自动建立物理机制。 -minimum-domain impulse 理论的关键判断是：对瞬时力真正直接起作用的，不必是整个成熟 far wake，而是**仍与物体动态相连的 vortical zone**；已经 detached 的紧致尾涡，其净力贡献可以视为零。[Kan17b] +### 6.2 文献只能提供框架与可比边界 -这对当前 pinball 的帮助极大，因为它把“目标尾迹要几个 \(D\) 才形成”和“力的主决定层更靠前”区分开了。更稳的口径应当是： +- Chen–Liu/Tao 一线可支持 boundary vorticity/enstrophy/pressure/skin-friction 的一般耦合与“壁面/近体过程在前”的物理方向；不能替代本地 wall-resolved 证据。 +- control-volume、impulse 和 vortex-force 文献可支持 wake 与 force 的一般映射及 body-connected vortical zone 的概念；不能证明本项目识别出的 mode 就是 causal force structure。 +- Schlegel OID 与 Lyu CCD/PCD 提供 observable-conditioned 降阶与时延结构方法；方法定义不等于本地结果有效，更不等于因果。 +- rotating-cylinder 文献只可在核对 Re、几何、约束、坐标与壁面方向后做定性 framing。当前 accepted steady branch 与 base-bleed/gap-jet wall sense 相容；高 Re 阈值、drag optimum 和 URANS manifold 不可转移到 `Re_D=50`。 -- signature 的形成需要发展距离； -- force-relevant mechanism 更集中在 near-body / body-connected 区域。 +原则：**文献可以提高假说的物理可理解性，不能提高本地证据的等级。** -### 3. 同样的涡量，不同位置，对 force 的投影不同 +## 7. 跨项目耐久经验 -vortex force decomposition 进一步说明，力不是简单由“总涡量大小”决定，而取决于涡结构的位置、与 body-induced velocity 的耦合方式，以及它是 body-generated、shed 还是 external。[Geh23] +1. **合同先于分析。** 冻结对象顺序、坐标、动作单位/符号、`Re_code/Re_D`、plant、边界、时钟、归一化、目标和比较器；标签与记忆不能覆盖源码 oracle。 +2. **对齐是科学问题。** state→next-action、phase origin、retained boundary、角色配对和 snapshot 来源必须可审计；错一拍仍可能得到高 R² 或平滑 mode。 +3. **均值与动态分离。** 先验证 mean increment、phase decomposition 和 benefit additivity，再分别解释常值贡献与反馈波动。 +4. **association != causality。** correlation、OID/CCD、DTW、ordered spatial coexistence、公式变量选择和 deletion 都只在各自合同内回答有限问题。 +5. **闭环接受不能由离线拟合替代。** offline R²/重构可筛结构，控制器仍需 finite、same-protocol baseline、closed-loop 和失败保留。 +6. **no-clobber 是证据纪律。** 新结果写新 ID，staging 后原子发布；哈希、父产物和失败状态不可静默覆盖或“清理”。失败、rejected、partial 与 BOUNDED 都是证据。 +7. **不要修饰失败。** 不通过缩短 warm-up、降低 crossing gate、换归一化、改比较器或只对 target 不对 zero 来挽救结论。 +8. **Legacy 共享编译必须串行。** 多 GPU 不隔离共享生成的 PTX/config/`macros.h`；并行初始化可污染证据。采集应串行启动并保留角色级 provenance。 +9. **同 rollout 采传感器与场。** phase 选择后重新初始化/补采会改变涡相位，破坏对齐。 +10. **现代/Legacy 分证据链。** 只有显式 parity 测试通过后才能作受限映射；不能把现代 V5 steady/CCD 结果直接并入 Legacy SR 的接受链。 -对 pinball，最可迁移的不是照抄公式，而是保留这个判断： +## 8. 方法分工 -- 同一强度的局部涡量结构，若位置和耦合方式不同，对总 force 的贡献也会不同； -- 因此后续完全可以谈 **force-relevant structures**，而不是只谈 energetic structures。 +- **SR**：解释冻结闭环公式的 `obs → act` 接口；当前正面范围仅 Kármán，steady 为情境校准，Illusion 为历史负面。 +- **CCD**：当前只报告 corrected Kármán ROI mean 与 rank-3 phase-coherent descriptive co-variation；不承担因果或机制。 +- **OID**：当前为 claim-free 方法核心；未来可严格区分 force/signature observable，但当前无 active scientific result。 +- **steady**：回答接受 rear-only 恒定动作在独立 canonical steady plant 上是否形成低残差剖面；当前性能观察成立，机制与稳定性为 BOUNDED/未建立。 -## 新增补充：这条线如何改写当前主链 +四条线可相互约束语言和提出假说，但不能互相代替证据。 -wake-to-force 与 Chen 线结合后，当前最稳的主链不应再写成 +## 9. 开放问题 -\[ -\text{obs} \rightarrow \text{act} \rightarrow \text{force} \rightarrow \text{signature} -\] +- Kármán SR 的稀疏律在独立 realizations、更长窗口及更高 `Re_D` 下是否保持有限、有效与同一结构？ +- constant mean 占 Kármán ROI 改善的大部分，是否由后部持久旋转主导？需要 matched intervention，不能由 SR 删除或 steady 对应关系单独回答。 +- corrected CCD rank-3 子空间与 force-relevant、signature-relevant 或纯共享相位/均值结构分别有何关系？ +- 是否存在严格配对或随机化的 intervention 能把 policy response 与 commanded action 的作用分开？ +- steady accepted branch 的因果 NS 通道是什么？需要共同控制体闭合、重复 switch/return、有效稳定性指标及独立 held-out 预测。 +- free-slip `Re_D=50` 的 steady 性能能否转移到充分发展 `q_in`、静止 no-slip walls 和 rotating no-slip cylinders？当前没有证据。 +- wall-resolved 或经网格收敛的诊断是否支持 near-body vorticity/separation 假说？当前分辨率不能预支答案。 +- Legacy 与 modern 的动作、壁面速度、力/传感器语义及场统计能否建立可量化 parity？在完成前两条证据链保持分离。 -也不应写成过于粗糙的 +## 10. 紧凑权威阅读表 -\[ -\text{obs} \rightarrow \text{act} \rightarrow \text{wake} -\] +### 当前包内权威 -而应写成： +- SR 状态与边界：[SR `CLAIMS.md`](SR_analysis/CLAIMS.md)、[`HANDOFF.md`](SR_analysis/HANDOFF.md)、[`results/README.md`](SR_analysis/results/README.md)、[标准化复现图说明](drl_pinball/data/reproduction_plots_sr/README.md)。 +- CCD corrected authority：[CCD `README.md`](CCD_analysis/README.md)、[`FINAL_RESULTS.md`](CCD_analysis/FINAL_RESULTS.md)、[`EXECUTION_CHECKPOINT.json`](CCD_analysis/EXECUTION_CHECKPOINT.json)。 +- OID reset authority：[OID `README.md`](OID_analysis/README.md)、[`SCIENTIFIC_RESET.md`](OID_analysis/SCIENTIFIC_RESET.md)、[`PHYSICS_CONTRACT.md`](OID_analysis/PHYSICS_CONTRACT.md)、[`METHOD.md`](OID_analysis/METHOD.md)。 +- steady authority：[steady `README.md`](steady_pinball_theory/README.md)、[`RESULTS.md`](steady_pinball_theory/RESULTS.md)、[`DERIVATION.md`](steady_pinball_theory/DERIVATION.md)、[`LITERATURE.md`](steady_pinball_theory/LITERATURE.md)。 -\[ -\text{obs} \rightarrow \text{act} \rightarrow \text{near-body correction} \rightarrow \text{body-connected wake structure} \rightarrow \text{force} \rightarrow \text{future signature} -\] +### 文献框架入口 -其中： - -- Chen 线负责说明为什么 `act` 的第一作用层是近体区源项与涡量组织，而不是远场结果。[Che19, Che21b, Ter21] -- wake-to-force 线负责说明为什么 force 最好理解为 body-connected near-wake organization 的低维投影，而不是与涡量竞争的另一套机制。[Kan17b, Geh23, Gom16] -- OID/CCD 线负责把这条通道压缩成少数结构坐标，并区分 force-relevant 与 signature-relevant structures。[Sch12, Lyu23] - -## 五、对 cloak 与 illusion 的当前最稳表述 - -### cloak - -现在最稳的写法是： - -- fixed pinball 会在任务相关区域内产生一个 blockage wake； -- DRL 旋转产生的 correction field 会尽量抵消这部分 wake； -- 合力接近 0 不是全部机制，而是这种 wake cancellation 的积分表现。 - -因此，如果分析成立，应看到： - -\[ -\Delta q_{ctl} \approx -\Delta q_{blk} -\] - -至少在任务相关区域里呈现这种趋势。 - -### illusion - -现在最稳的写法是： - -- fixed pinball 先生成自身基线 wake； -- 控制不是把 wake 全部“消掉”，而是做一个 target-oriented correction； -- force matching 之所以有效，是因为它约束了整体节律与积分响应，但真正被操控的是 correction field。 - -如果分析成立，应看到： - -\[ -\Delta q_{ctl} -\] - -接近“目标物体相对 fixed pinball 的残差结构”。 - -## 六、force 在当前项目中的正确位置 - -这是最容易说错的地方之一。 - -### 现在可以说的 - -- force 是极重要的 observable。 -- force 对 DRL reward 有效，说明它确实和任务结构高度相关。 -- force 很可能是近体区修正场的低维、强相关投影，因此特别适合作为控制反馈量。 -- 更具体地说，当前最稳的理解不是“force 来自整个远场尾迹”，而是：force 更像 **body-connected near-wake organization** 的积分响应或低维投影。[Kan17b, Geh23, Gom16] - -### 现在不要说得太满的 - -- “控制机制本质上就是 force tracking” -- “只要合力为 0，就自然 cloak” -- “illusion 的本质就是匹配目标力” - -更稳的说法是： - -- force 是 near-body correction 的一个重要投影； -- 它之所以有用，是因为它和 task-relevant structures 强相关； -- 但真正被操纵的，仍然更像是 correction field 而不是一个单独积分量。 - -## 七、OID / CCD / PCD 在当前主线中的正确位置 - -这条线现在不应再被理解成“对原始全流场做更高级模态分解”。 - -更稳的理解是： - -- 原始全流场里混着入射结构、阻挡结构和控制结构； -- 真正需要找的是 **control-induced correction structures**； -- 因此 OID / CCD / PCD 最好作用在 \(\Delta q_{ctl}\) 或其低维系数上。 - -### 当前最有价值的任务 - -| 方法 | 现在最值得做的事 | -|---|---| -| correction-field POD | 看控制修正主要落在哪几个低维方向上 | -| force-OID | 找最影响 force 的 correction structures | -| signature-OID | 找最影响 future signature 的 correction structures | -| PCD / CCD | 在显式时延下区分 source / descendant correction modes [Lyu23] | - -这里需要新增一条长期保留的解释纪律：**force-OID** 与 **signature-OID** 不应先验合并。更稳的工作假设是： - -- controller 首先调制一小组 force-relevant near-wake structures； -- 这些结构经过若干个 \(D\) 的对流与相互作用后，才演化为 signature-relevant downstream structures。[Kan17b, Sch12, Lyu23] - -因此，如果后续真的看到 force-OID 与 signature-OID 差异明显，这首先应被视为潜在机制结果，而不是算法失败。只有在 POD rank、时延、标准化和数据量都排查完后，才适合讨论该差异是否可信。 - -### 这条线最关键的判断 - -若少数 correction modes 就能： - -- 解释大部分 force 变化 -- 预测 future signature 的改善 -- 在 cloak 与 illusion 间提供可比较结构 - -则说明“控制调用的是少数 pinball-scale correction structures”这一主张成立。 - -## 八、SR / SINDy 的正确角色 - -这条线现在最容易被高估，也最容易被低估。 - -### 它不该单独承担的事 - -- 不应让 `obs -> act` 一条线独自承担全部物理解释。 -- 不应把高拟合度自动当成“机制已明”。 - -### 它现在真正该承担的事 - -- 作为 `obs -> act` 的白箱接口； -- 给出控制律依赖哪些低维量的证据； -- 最终和 correction field 及 OID/CCD 拼起来，形成闭环解释。 - -因此最合理的三段拼法是： - -\[ -\text{SR/SINDy}: \text{obs} \rightarrow \text{act} -\] - -\[ -\text{difference-field analysis}: \text{act} \rightarrow \Delta q_{ctl} -\] - -\[ -\text{wake-to-force / Chen}: \Delta q_{ctl} \rightarrow \text{body-connected wake structure} \rightarrow \text{force} -\] - -\[ -\text{OID/CCD}: \text{force-related structure} \rightarrow \text{future signature} -\] - -这也意味着，当前阶段不应要求 SINDy/SR 一条线独自把全部物理机制说完。更稳的节奏是：先让 SINDy/SR 找到共享骨架与可闭环公式，再等 CCD/OID 与 wake-to-force 这边把结构中介对象做扎实之后，回头精简和改写白箱公式。 - -## 九、这一轮最值得长期保留的方法论经验 - -### 经验 1 - -**不要直接在原始控制场上谈“机制”。** - -先拆出： - -- 来流本身是什么 -- 几何阻挡本身做了什么 -- 控制额外改了什么 - -否则很容易把“本来就有的结构”误当成“控制生成的结构”。 - -### 经验 2 - -**当前问题的自然尺度不是单圆柱 wall-scale，而是 pinball-scale correction-scale。** - -这意味着： - -- 可以放弃一些不可信的细节分析； -- 但反而更容易得到跨场景稳定的主结论。 - -### 经验 3 - -**Chen 线最该保留的是因果顺序，不是细节模板。** - -它告诉我们： - -- 近体区在前，远场 observable 在后； -- 受力是近体区组织变化后的结果； -- 这就足以为 correction field 主线提供物理正当性。 - -### 经验 4 - -**Lyu / Schlegel 这条线最适合用来识别“控制额外改出来的任务相关结构”。** - -不是所有 energetic 结构都重要； -真正重要的是 observable-relevant correction structures。[Sch12, Lyu23] - -## 十、当前最值得长期保留的两句话 - -\[ -\boxed{\text{当前项目最有价值的主张，不是“DRL 学会了某个力学量”，而是“DRL 学会了对 pinball 近体区修正场的低维调制”。}} -\] - -同时必须保留另一句： - -\[ -\boxed{\text{Chen Tao 线提供的是正确的因果方向，而不是当前网格下可直接照搬的壁面分析模板。}} -\] - -这两句话一起保留，最能防止后续再次滑回两个极端： - -- 把全部机制压扁成 force tracking； -- 把分辨率并不支持的壁面细节写得过满。 +优先使用各包的 source-to-claim ledger，而不是从本文二手升级主张：steady 的 [`LITERATURE.md`](steady_pinball_theory/LITERATURE.md) 记录 potential/viscous interface、rotating-cylinder 与 wake/stability 文献边界；OID 的 [`METHOD.md`](OID_analysis/METHOD.md) 记录 Schlegel LR/LE 数学；CCD 当前方法边界由 [CCD `README.md`](CCD_analysis/README.md) 给出。历史 Lyu/旧 CCD 材料仅作出处追踪，不是 current result authority。 diff --git a/src/analysis_notes.md b/src/analysis_notes.md index 040d1ca..c80108f 100644 --- a/src/analysis_notes.md +++ b/src/analysis_notes.md @@ -1,1220 +1,225 @@ -## 课题背景与当前目标 +# DynamisLab 项目状态、开放问题与写作路线 -当前工作的核心不是再证明 pinball 可以被控制，而是解释 **机器学习控制究竟通过哪些流动结构通道改写尾迹**。项目对象是 2D 槽道中的 fluidic pinball：三个等径圆柱按等边三角形排布、各自可独立旋转；控制器利用 **各圆柱受力** 与 **下游三点速度观测** 进行闭环控制，在典型的二维脱涡雷诺数范围内实现 hydrodynamic stealth、illusion 和 wake erasure。已有数值结果已经证明这几类目标可以实现，且部分 stealth 与 illusion case 已完成实验验证。 +> 状态日期：2026-08-09。本文取代旧的广义分析任务书，只负责项目状态、问题门禁、历史计划索引和写作准备；概念框架见 [`analysis_knowledge.md`](analysis_knowledge.md)，不在此重复。 -当前真正的瓶颈不是“控制是否有效”，而是如何把以下链条写清楚：控制器看到了什么，动作首先改变了哪些受力或近尾迹结构，这些结构又怎样传播到下游并决定最终的 signature。换言之，文章和后处理最缺的是 +## 1. 权威层级（先读） -\[ -\text{obs} \rightarrow \text{act} \rightarrow \text{flow structure} \rightarrow \text{signature} -\] +发生冲突时依次服从： -而不仅是 `obs -> act` 或“控制前后流场长得不一样”。因此，这份任务书的目标是把已有能力组织成一条可重复的后处理链：从 `obs`、`act`、force、全流场和局部体力 probing 出发，解释控制如何改变低维结构、均值尾迹和下游 signature。对圆柱尾迹与受控 wake，最稳的分析框架是把 **控制代价**、**mean–fluctuation 重组**、**observable-related structure** 和 **localized forcing 诊断** 接起来，而不是单看 DTW 或单看全场误差 [Ber06, Tad10, Man15, Sch12, Lyu23, Jin21]。 +1. **当前用户明确决定与冻结合同**：范围、符号、比较量和禁止项。 +2. **可验证的当前证据**：immutable artifact、manifest/hash、数组、明确 metric/window/comparator/realization，以及 fail-closed loader。 +3. **当前 package authority**：数学合同、结果账本、checkpoint、代码与测试；包内另有顺序时服从包内顺序。 +4. **仓库级导航文档**：只汇总，不覆盖包内证据。 +5. **archive、历史计划与 Nowledge Memory**：用于恢复意图和教训，**是 context，不是 evidence**，不能升级 claim 或覆盖后来的 artifact。 -## 新人首先需要知道的系统设定 +论文数字必须能反查 artifact、metric、窗口、比较对象、场景和 realization 数。测试通过只证明实现满足测试合同，不自动证明物理命题。 -### 研究对象 +## 2. 2026-08-09 状态总览 -| 项目 | 内容 | 备注 | -|---|---|---| -| 几何对象 | fluidic pinball | 三个等径圆柱，前一后二，中心构成等边三角形 | -| 流动类型 | 2D 槽道不可压缩流 | 当前主线为抛物面来流，也有上游扰动来流工况 | -| 典型雷诺数 | 约 `Re_D ~ O(10^2)` | 目前分析重点可按 `Re≈100` 附近理解，但文稿中必须始终写清具体口径 | -| 执行器 | 三圆柱独立旋转 | 每个圆柱一个控制输入 | -| 观测 | 圆柱受力 + 下游三点速度 | 三个传感器各含 `u,v` 两分量 | -| 控制目标 | stealth / illusion / erasure | 本质上都是 downstream wake signature shaping | -| 评价方式 | 目标时序匹配 + 力学量辅助 | 当前主指标是 DTW，也保留 force / spectrum / field error | +标签：**ACTIVE** 当前推进；**BOUNDED** 可写但边界严格；**HISTORICAL** 仅追溯；**OPEN** 证据不足。 -### 为什么选 pinball +### 2.1 DRL / CFD 与复现 -pinball 不是随意挑的玩具系统，而是一个兼具复杂性和可分析性的规范化平台。它同时具有： +- **ACTIVE（工程）**：现代 V5 训练/评估入口见 [`drl_pinball/train/`](drl_pinball/train/README.md) 与 [`drl_pinball/eval/`](drl_pinball/eval/README.md)。 +- **BOUNDED（能力）**：历史 PPO 展示 Kármán cloaking 与 Illusion 控制能力；数值仍绑定 solver 世代、模型、normalizer、目标和窗口。 +- **必须分开**：**Illusion PPO capability** 是控制能力；**Illusion SR** 是解释/替代路线，后者关闭不否定前者。 +- **HISTORICAL**：靠 sensor/force 缩放、旧 norm 搬运或近似新环境直接宣称 Legacy→V5 等价的路线已失败。原生 Legacy 入口见 [`drl_pinball/legacy_test/`](drl_pinball/legacy_test/README.md)，旧路线见 [`archive/reproduce/`](archive/reproduce/README.md)。 +- **OPEN**：V5 与 Legacy 不可混池；剩余复现须按各自原生合同逐 gate 验收，training-best、视觉相似均不能替代独立 replay。 -- 多输入多输出闭环控制结构 -- 近尾迹强非线性与多时间尺度 -- 可清楚分辨的几何分工：前圆柱、上下后圆柱 -- 已有较成熟的低维建模与模态分析背景 [Den18b, Den20, Den21, Li22b] +### 2.2 SR -因此它既足够复杂，能承载机器学习控制；又足够“干净”，适合追问控制到底在调什么结构。 +Authority：[`SR_analysis/README.md`](SR_analysis/README.md) → [`SR_analysis/results/README.md`](SR_analysis/results/README.md) → [`SR_analysis/PIPELINE.md`](SR_analysis/PIPELINE.md) → [`SR_analysis/HISTORY_AND_LESSONS.md`](SR_analysis/HISTORY_AND_LESSONS.md) → [`SR_analysis/HANDOFF.md`](SR_analysis/HANDOFF.md)。 -### 当前课题和传统主动流控的区别 +- **ACTIVE / BOUNDED**：科学主线只剩 Kármán/cloaking。在已测试映射共享律和删除窗口内，persistent rear counter-rotation 是主导 tested element，rear-lift feedback 次要，tested front feedback 较弱；精确反射对称性是部署施加的，不证明 PPO training equivariance。 +- **BOUNDED contextual**：steady sweep 只校准 Kármán rear constant 量级，不是拟合目标，也不证明动量平衡或因果机制。 +- **HISTORICAL / CLOSED**：Illusion Stage 1–3、target/harmonics 和 provenance 能力保留；但公式遗漏 target/error，长窗标准化 Legacy 采集动作衰减至近物理零，相对 physical-zero 无有意义收益。旧 200/400-step 结果不得支持 target tracking、跨尺寸泛化、项必要性或机制。 +- **OPEN**：跨 Re 普适性、独立 realization uncertainty、唯一/全局最优符号律、因果结构和动量等式均未建立。 -当前目标不是传统 AFC 中常见的单一 drag reduction 或 force tracking，而是 **让下游观测到的时空 signature 变成指定目标**。因此，真正的控制对象不是某个积分量，而是下游可感知流场。对当前项目，更准确的说法是： +### 2.3 corrected CCD -- stealth：让 pinball 的 downstream signature 接近“没有 pinball”或目标背景流 -- illusion：让 pinball 的 downstream signature 接近另一个目标物体或目标流场 -- erasure：强调抹去原有 wake signature，可视为 stealth 的一个极端形式 +Authority：[`CCD_analysis/README.md`](CCD_analysis/README.md)、[`CCD_analysis/FINAL_RESULTS.md`](CCD_analysis/FINAL_RESULTS.md)、[`CCD_analysis/EXECUTION_CHECKPOINT.json`](CCD_analysis/EXECUTION_CHECKPOINT.json)。 -这也是为什么单纯按全场能量排序的 POD 不够，后续必须围绕 observable 去定义低维结构坐标。 +- **BOUNDED（均值）**：inclusive wake ROI `34 <= x/D <= 54, |y/D| <= 5` 上，mean target errors 为 zero `0.4694352273`、constant mean `0.1110140739`、DRL `0.0857787860`；constant mean 贡献 zero→DRL mean-error reduction 的约 `93.4%`。 +- **BOUNDED（描述）**：cycle-template CCD 为 `N=190, Q=1, M=160400`、rank 3；最差 rank-3 projector cosine `0.9947903592`，最大相对 singular-value shift `7.66%`。只支持 phase-coherent DRL-minus-constant-template **co-variation**。 +- **非主张**：没有 paired counterfactual、因果、机制、response time、独立 uncertainty、explained variance、field energy 或 CCD/POD superiority。 +- **ACTIVE / IN PROGRESS**：模态涡量、phase harmonic、对称性、空间定位、streamwise shift、action-coordinate diagnostics 与同 residual/weight/rank POD 对照在进行。 +- **OPEN**：validated review-fix sibling 的 canonical alias 仍待决定；旧 unsuffixed artifacts 保留且 superseded，不破坏性替换。 -### 当前控制与学习路线 +### 2.4 OID -| 模块 | 当前状态 | 用途 | -|---|---|---| -| DRL 闭环控制 | 已完成多类 case | 证明 stealth / illusion / erasure 可实现 | -| DANTE 树搜索 | 已用于替代或补充 DRL 探索 | 加速寻找有效策略 | -| SINDy / SR | 已用于分析 `act-obs` 关系 | 提升策略可解释性 | -| 实验验证 | 部分 stealth 与 illusion 已完成 | 支撑数值结果不是纯仿真特例 | -| 后处理分析 | 正在补强 | 目标是把控制与结构机制连起来 | +Authority：[`OID_analysis/README.md`](OID_analysis/README.md)。 -当前最缺的不是再给出一个更高分的控制器，而是把黑箱策略推进成： +- **ACTIVE（方法）**：仅 claim-free、CPU-only 的 weighted POD、Schlegel LR/LE maps、generated-range handling、延迟配对、subspace metrics 和 atomic validation。 +- **HISTORICAL / CONDITIONAL**：July two-scene study 已归档；sensor 高 R² 部分是 state-domain 内局部速度自观测，force 未过 gate，无 active LR/LE action result。 +- **OPEN**：当前**没有 active scientific result**，也没有 scene runner、GPU、plotting、audit 或 redo route。新工作须先冻结 estimand、独立 observable 和反循环性 gate。 -\[ -\text{obs} \rightarrow z \rightarrow \text{act} -\] +### 2.5 steady pinball theory -并进一步说明这个低维状态 \(z\) 对应哪些 flow structures、force channels 和 downstream signatures。 +Authority：[`steady_pinball_theory/DERIVATION.md`](steady_pinball_theory/DERIVATION.md) → code/tests → [`steady_pinball_theory/RESULTS.md`](steady_pinball_theory/RESULTS.md) → [`steady_pinball_theory/LITERATURE.md`](steady_pinball_theory/LITERATURE.md) → [`steady_pinball_theory/README.md`](steady_pinball_theory/README.md)。 -### 这份任务书要回答的核心问题 +冻结合同： -后续所有分析，最终都服务于下面几个问题： +- action：`[0,+Omega,-Omega]`，`Omega>0`。 +- body order：`(front, rear_y_plus, rear_y_minus)`；不得再用旧符号或仅凭 upper/lower 猜旋向。 +- primary metric：`x/D=10` 完整截面两分量 `E_inf_vector(q_ctl,q_in)`；同时报告 `E_inf_x/E_inf_y`。其他站位与 explicit integral `L2` 是诊断，`q_blk` 非排名。 -1. 控制器到底在调哪些流动结构，而不是仅仅输出了什么动作 -2. 这些结构首先体现在哪些量上：受力、均值尾迹、剪切层、回流区还是主模态 -3. stealth 与 illusion 是在利用同一条结构通道，还是两类不同机制 -4. 简化后的白箱控制律是否作用于少数低维结构态，而不是直接“记住”高维流场 -5. CCD / OID / 相关分解是否能比普通 POD 更准确地识别这些与任务相关的结构 +状态： -## 这一轮调研后新增的关键判断 +- **BOUNDED publication**：2026-08-09 immutable article package 已发布；accepted `s={3.45,3.55,3.65}` 的 `E_inf_vector={0.0232525,0.0231671,0.0312490}`，只支持 free-slip、`Re_D=50`、有限配置下 steady rear-only 低亏损结果。 +- **FAILED / HISTORICAL**：prescribed-circulation blockage cancellation 因符号矛盾失败；composite semi-analytic held-out PASS 因 metric double subtraction 与非独立 holdout 等被撤回。势流是外场/不可穿透参考和反例，不是 rotating-wall no-slip closure。 +- **OPEN**：同一控制体 NS closure、统计/干预 causality、branch/asymptotic/global stability、no-slip transfer 均未建立；endpoint association、torque/power 与有限时程只能按 artifact 的 BOUNDED 标签使用。 -这一轮最重要的变化，不是又多知道了几篇壁面涡量论文，而是**分析层级要下调到当前网格真正能承受的尺度**。 -虽然 Chen Tao 这条线给出了很好的因果方向：旋转先改写壁面/近壁源项，再改写剪切层、受力和尾迹 [Che19, Che21b, Ter21, Zhu15]，但当前 pinball CFD 里单圆柱只占十多格，单圆柱边界层、精确分离点、壁面涡量通量点值都不可信。因此，这条线对本项目最重要的用途不是照着做 wall-resolved diagnosis，而是帮助把机制顺序写对： +## 3. 当前开放问题与精确下一门禁 -\[ -\text{rotation} \rightarrow \text{near-body correction} \rightarrow \text{wake structure} \rightarrow \text{force / signature} -\] +### Gate A — CCD 解释扩展（当前唯一活跃科学分析） -这意味着对当前项目，更稳的表述应当是： +1. 对 corrected `N=190` residual 完成 vorticity、phase-harmonic、symmetry、localization、shift、action-coordinate diagnostics。 +2. 对完全相同 residual、mask、quadrature、centering 和 rank=3 完成 weighted POD baseline。 +3. 预注册判读：若 CCD/POD 子空间近同，只写“CCD 为共同 residual subspace 添加动作坐标”；若不同，也只写 observable-selected candidate structure。 +4. 生成单一 no-clobber diagnostics artifact，fresh-process reload；完成一次独立 science/code/claim review。 +5. 随后停止并讨论是否进入 SR/最小 CFD；不得为正结果追加 CFD。Canonical alias 另行决定。 -- `force` 仍然很重要，但更像近体区修正过程的低维、强相关投影，而不是唯一第一性原因 -- 当前最可信的主分析对象不是单圆柱壁面量，而是 **pinball 整体尺度的 near-body correction field** -- OID / CCD / PCD 最好优先作用在“控制额外改出来的那部分结构”上，而不是直接拿原始全流场做全部解释 +### Gate B — steady 收尾 -这并不否定原来 `obs -> z -> act -> force/power -> wake structure -> signature` 的主链，而是要求在 `act` 与 `force/wake` 之间再补上一层更贴近当前数值分辨率的中介： +1. 冻结 BOUNDED article report 与 claim matrix；所有文字使用正确 action、body order、`x/D=10 E_inf_vector`。 +2. archived NS ledger/switch/return 不得写成 closure、causality 或 stability。 +3. 若重开 NS closure，先满足同一控制体、pressure/viscous boundary terms、storage 和 near-wall error convergence；缺项即停在 partial ledger。 +4. 因果/稳定性需预注册 intervention、独立 realizations 或合格 basin/order parameter；单 realization 不升级。 +5. no-slip transfer 是新问题：fully developed no-body `q_in`、stationary no-slip walls、rotating-cylinder no-slip、同一直接 profile metric；不继承 free-slip optimum。 -\[ -\text{obs} \rightarrow \text{act} \rightarrow \text{near-body correction} \rightarrow \text{force/wake} \rightarrow \text{signature} -\] +### Gate C — SR 与 manuscript 同步 -后面几项任务里的新增内容，基本都围绕这一层展开。 -## 为什么后处理主线必须引入 observable-related decomposition +1. 不再增加 Kármán formula search；先冻结 active/archive claim ledger 和数字 provenance。 +2. **待同步文件：[`../docs/JFM_WYQ/SR_Draft.md`](../docs/JFM_WYQ/SR_Draft.md)**。本轮不编辑。后续须删除/降级 active Illusion SR result、shared stable Illusion controller、跨尺寸正面结论等旧叙事；保留 Illusion PPO capability，并写明 Illusion SR 长窗相对 physical-zero 的负结果。 +3. Kármán 仅写 policy surrogate 与指定 scene/window/realization 的 closed-loop evidence；steady 只作 contextual calibration。 +4. manuscript evidence-parity review：每个数字绑定 artifact、metric、duration/window、comparator、realization；V5 不导入 Legacy SR chain。 -当前项目的 reward 和成功判据，本质上都围绕传感器时序和目标 signature 展开。也就是说，真正需要解释的是 **哪些流场结构最影响 observable**，而不是哪些结构能量最大。POD 提供统一坐标系，但它按能量排序；CCD 则更适合回答“与某个 observable 最相关的结构是什么”，并且可以显式纳入时间延迟 [Lyu23]。这正好契合当前项目中最关键但最难的一步：把当前流场结构与未来下游 signature 联系起来。 +### Gate D — DRL/reproduction 与 OID -因此，后续最值得建立的主链条不是停在 `obs -> act`，而是 +1. 复现只按原生 V5 或原生 Legacy 合同；每 gate 失败即停，不批量生成矩阵。 +2. Illusion PPO 若作为新论文证据，须建立独立于 closed SR 的 current replay/target/zero 链。 +3. OID 保持 claim-free；只有明确 estimand、非自观测 observable、strict split/alignment 和 failure criteria 后才立项。 -\[ -\text{obs} \rightarrow z \rightarrow \text{act} \rightarrow \text{force/power} \rightarrow \text{wake structure} \rightarrow \text{signature} -\] +## 4. 当前可写 claims / nonclaims -其中 \(z\) 不是抽象潜变量，而是由公共 POD、observable-related coordinates、回流区几何量和必要的频域量共同构成的低维状态 [Sch12, Lyu23, Li22b]。 +### 可写（必须带范围） -当前数值能力足以支撑一套分层分析：实时获得三个圆柱的独立转速与受力、下游一排三个传感器的速度时序、完整 2D 流场快照，以及在一个或多个小圆形区域内施加局部体力。这意味着可以把主线明确写成 +- Legacy Kármán SR 在已测试公式、场景与删除窗口内，将 persistent rear counter-rotation 排为主导 tested element；rear-lift feedback 次要，tested front feedback 较弱。 +- corrected Kármán ROI mean decomposition 表明 constant mean 完成约 `93.4%` 的 zero→DRL mean-error reduction；dynamic residual 的 rank-3 CCD subspace 在已执行检查下稳定。 +- CCD 结论是 descriptive co-variation；物理解读与同对象 POD comparison 仍在进行。 +- steady free-slip `Re_D=50` 在 `[0,+Omega,-Omega]`、`(front,rear_y_plus,rear_y_minus)` 下有 BOUNDED low-deficit endpoints，主指标为 `x/D=10 E_inf_vector(q_ctl,q_in)`。 +- Illusion PPO/DRL 有历史控制能力；Illusion SR 是另一条已关闭解释路线。 +- OID 只有 claim-free method core，无 active scientific result。 -\[ -\text{obs} \rightarrow z \rightarrow \text{act} \rightarrow \text{force/power} \rightarrow \text{wake structure} \rightarrow \text{signature} -\] +### 不可写 / 尚未建立 -其中 \(z\) 不是抽象潜变量，而是由公共 POD、observable-related coordinates、回流区几何量和必要的频域量共同构成的低维状态 [Sch12, Li22b, Tad10]。 +- SR 给出 Navier–Stokes 方程、唯一/普适 law、跨分布泛化、完整 term necessity 或 causal mechanism。 +- Illusion SR 已实现 target tracking、优于 physical zero、跨尺寸泛化或 target/error necessity。 +- CCD 证明 mechanism、response time、CCD>POD、paired counterfactual、独立 uncertainty 或 causality。 +- steady 已闭合 NS conservation、证明因果或 basin/global/asymptotic stability，或可直接迁移 no-slip。 +- potential-circulation cancellation 解释 accepted steady cloak；该 identification 已失败。 +- OID 高 reconstruction/prediction 证明 importance、controller necessity 或 control authority。 -## 系统设定与统一记号 +## 5. 写作准备路线 -采用以下统一记号，后续所有脚本、文件名和数据结构都按这一套执行。 +1. **冻结证据账本**：按 package authority 形成 claim matrix，分类 proved mathematical、numerical observation、contextual、historical/negative、open。 +2. **完成 CCD Gate A**：先判断 dynamic residual 能否形成诚实短结果；若 CCD≈POD，主动收缩叙事。 +3. **同步 SR draft**：仅在另行授权后编辑 `docs/JFM_WYQ/SR_Draft.md`；先修 Illusion scope，再核 Kármán 数字与限定词。 +4. **组织主线**：DRL capability → SR tested-term ranking → corrected CCD mean/dynamic separation → steady rear-only BOUNDED prototype。四条证据职责不同，不共用纵轴、不互换因果含义。 +5. **limitations before mechanism**：先写 no-slip、independent realization、NS closure、causality、stability 缺口。 +6. **最终 preflight**：核对 paths/hashes、metric/window/comparator、action/body order、Re 口径、Legacy/V5 边界、caption claim。 -| 量 | 记号 | 说明 | -|---|---|---| -| 采样索引 | `n=0,1,2,...` | 每隔若干 CFD 步采一次样，同时更新一次控制 | -| 物理时间 | \(t_n\) | 与采样点一一对应 | -| 三圆柱转速 | \(\Omega_i(t_n)\), `i=1,2,3` | 控制输入 | -| 三圆柱受力与力矩 | \(F_{x,i},F_{y,i},M_{z,i}\) | 实时可得 | -| 三个传感器速度 | \(s(t_n)\in\mathbb{R}^6\) | 每个传感器含 \(u,v\) 两分量 | -| 目标传感器时序 | \(s_{tar}(t_n)\) | 用于 DTW 与相似度 | -| 流场 | \(u(x,y,t_n),v(x,y,t_n)\) | 全域 2D 快照 | -| 局部体力 | \(\mathbf f_p(x,y,t)\) | 只允许作用在一个或多个圆形区域 | -雷诺数口径也必须固定写法： +## 6. Authority-first 历史计划索引 -- \(Re_D\)：以 pinball 单个圆柱直径为特征长度 -- \(Re\)：以两倍直径的标准扰流圆柱尺度为特征长度 +以下计划用于发现历史意图和耐久教训，**不是证据或当前进度 authority**。每条给出当前应读位置。 -所有图题、case 标签、数据目录和表格都必须显式写明使用哪一个口径，不能混写。 +### 6.1 SR 谱系 -## 数据输出与目录结构 +- `/home/frank14f/.cursor/plans/可信sr全流程重建_ac521468.plan.md` + **意图**：从 order/alignment/PPO parity 到 closed-loop CFD 重建可信链。**耐久教训**：先保护 immutable assets；R² 不晋升 controller；失败 telemetry 保留。**状态**：被后续 joint/final/closeout 收束。**当前 authority**：[`SR_analysis/PIPELINE.md`](SR_analysis/PIPELINE.md)、[`SR_analysis/HISTORY_AND_LESSONS.md`](SR_analysis/HISTORY_AND_LESSONS.md)。 +- `/home/frank14f/.cursor/plans/joint_sr_article_flow_4d153f90.plan.md` + **意图**：per-case discovery、同目标 joint fit、DTW 与 term ablation。**教训**：Kármán/Illusion 不混池；部署 symmetry 与 PPO equivariance 分开；offline Pareto 不等于部署。**状态**：HISTORICAL；Illusion positive promotion 被 long-window zero control 推翻。**当前 authority**：[`SR_analysis/README.md`](SR_analysis/README.md)、[`SR_analysis/results/README.md`](SR_analysis/results/README.md)。 +- `/home/frank14f/.cursor/plans/sr_final_consolidation_846e9c84.plan.md` + **意图**：清理实现并把 SR draft 建成当时 paper source。**教训**：formula/metric/provenance 单一实现；manuscript numbers 必须 evidence parity。**状态**：当时完成，Illusion 章节已 superseded。**当前 authority**：[`SR_analysis/HANDOFF.md`](SR_analysis/HANDOFF.md)；draft 待 Gate C。 +- `/home/frank14f/.cursor/plans/sr项目收尾整理_56371fda.plan.md` + **意图**：收束 Kármán-only，保留 Illusion runtime 并关闭其 SR science。**教训**：capability 与 scientific result 分离；不为可读性破坏 hash-bound paths。**状态**：最近 scope 背景。**当前 authority**：[`SR_analysis/README.md`](SR_analysis/README.md)、[`SR_analysis/HANDOFF.md`](SR_analysis/HANDOFF.md)。 -为了避免后期反复重跑，建议所有 case 都一次性导出下列数据。 +### 6.2 CCD 谱系 -| 数据组 | 变量 | 最低格式 | -|---|---|---| -| 流场 | `U[n, iy, ix]`, `V[n, iy, ix]` | float32 或 float64 | -| 压力可选 | `P[n, iy, ix]` | 若存储允许则保留 | -| 力与力矩 | `Fx[n,3]`, `Fy[n,3]`, `Mz[n,3]` | 每个圆柱一列 | -| 控制量 | `Omega[n,3]` | 与受力严格同步 | -| 观测量 | `Obs[n,6]`, `Obs_tar[n,6]` | 顺序固定 | -| case 元数据 | `meta.json` | Re 口径、来流类型、目标类型、采样步长 | -| probing 元数据 | `probe.json` | 圆区中心、半径、方向、频率、幅值、起止时间 | +- `/home/frank14f/.cursor/plans/rigorous_ccd_refinement_75d9896e.plan.md` + **意图**：重审 correction field、CCD–POD 与 minimal CFD。**教训**：同 index 不等于 paired state；CCD 不优于 POD 应停止；机制句降级。**状态**：被 reset/corrected core supersede。**当前 authority**：[`CCD_analysis/README.md`](CCD_analysis/README.md) 及 archive boundary。 +- `/home/frank14f/.cursor/plans/ccd_three-part_reset_15f14717.plan.md` + **意图**：隔离 archive，冻结 exact-time acquisition/direct-dq/original CCD。**教训**：estimand、mask、weights、action lineage、centering 显式；Q=1 不等于因果。**状态**：早期 real-case route 被 corrected cycle-template authority 取代。**当前 authority**：[`CCD_analysis/README.md`](CCD_analysis/README.md)、[`CCD_analysis/EXECUTION_CHECKPOINT.json`](CCD_analysis/EXECUTION_CHECKPOINT.json)。 +- `/home/frank14f/.cursor/plans/ccd_模态物理解读_39a32ff3.plan.md` + **意图**：corrected residual mode diagnostics 与 same-object rank-3 POD。**教训**：phase harmonic 不是连续 physical frequency；稳定对象是 subspace，不必是 individual basis vector。**状态**：**IN PROGRESS**。**当前 authority destination**：完成后写入 [`CCD_analysis/FINAL_RESULTS.md`](CCD_analysis/FINAL_RESULTS.md) 和 checkpoint；此前不预写结论。 -建议统一目录： +### 6.3 steady 谱系 -- `case_xxx/raw/`：原始同步数据 -- `case_xxx/derived/`：均值场、RMS、涡量、回流区、谱、POD 系数等中间量 -- `case_xxx/fig/`：标准图 -- `case_xxx/report/`：统计表与摘要 +- `/home/frank14f/.cursor/plans/steady-cloak-jfm-roadmap_9c27caab.plan.md` + **意图**：从零冻结 sign、direct-`q_in` objective、CFD/theory。**教训**：action 由 body ID/wall-point oracle 决定；primary metric 是 `x/D=10 E_inf_vector`。**状态**：historical reset，后续部分 claims 被降级。**当前 authority**：[`steady_pinball_theory/DERIVATION.md`](steady_pinball_theory/DERIVATION.md)、[`steady_pinball_theory/RESULTS.md`](steady_pinball_theory/RESULTS.md)。 +- `/home/frank14f/.cursor/plans/rigorous_steady-cloak_mechanism_48a85f33.plan.md` + **意图**：检验 rear-opposite circulation/dipole cancellation。**教训**：mathematical outer property 不等于 wall-speed closure；负结果保留。**状态**：physical identification **FAIL**，不得复活。**当前 authority**：`RESULTS.md` failed/withdrawn 与 `DERIVATION.md` proof boundary。 +- `/home/frank14f/.cursor/plans/steady理论收尾_7e4c9476.plan.md` + **意图**：NS-first 收尾、units/torque contract、transient 与 article package。**教训**：partial ledger 不叫 closure；单 realization 不叫 causality；return norm 不等于 basin stability。**状态**：publication BOUNDED。**当前 authority**：[`steady_pinball_theory/README.md`](steady_pinball_theory/README.md)、[`steady_pinball_theory/RESULTS.md`](steady_pinball_theory/RESULTS.md)。 -## 时间对齐与窗口原则 +### 6.4 reproduction 谱系 -控制效应不会立刻在传感器上体现，而是存在明显对流时延。当前设定里，控制通常需要大约 \(L_x/U\) 的传播时间才能在下游传感器上稳定体现；同时每个脱涡周期只有约 10–20 个采样点。因此所有分析都必须把 **时延** 和 **窗口长度** 当成一级问题，而不是事后修正 [Jin21, Jin19b]。 +- `/home/frank14f/.cursor/plans/reproduce_inference_plan_a46a088e.plan.md` + **意图**：用 scaling/legacy norm 在新 Celeris 复现 Legacy policy。**教训**：API conversion 不证明 dynamics equivalence；order、initialization、EMA/FIFO、target、solver build 都是 contract。**状态**：HISTORICAL / superseded。**当前 authority**：[`archive/reproduce/`](archive/reproduce/README.md)。 +- `/home/frank14f/.cursor/plans/clean_reproduction_reset_a644c5fa.plan.md` + **意图**：删除错误旁路，分别以 V5 train contract 与 Legacy 原环境建 thin evaluator。**教训**：retained native baseline 验收；controlled-vs-target 与 fresh-vs-historical 不同；gate failure 即停。**状态**：current governance context，不代表 matrix 完成。**当前 authority**：[`drl_pinball/eval/README.md`](drl_pinball/eval/README.md)、[`drl_pinball/legacy_test/README.md`](drl_pinball/legacy_test/README.md)。 -定义采样间隔为 \(\Delta t_s\)，主脱涡周期为 \(T_{shed}\)，则每周期样本数约为 +### 6.5 literature / manuscript 谱系 -\[ -N_T = \frac{T_{shed}}{\Delta t_s} \approx 10\text{--}20 -\] +- `/home/frank14f/.cursor/plans/sr_final_consolidation_846e9c84.plan.md` + **意图**：完整 SR manuscript、reproducibility appendix、claim review。**教训**：写作晚于 evidence parity；authority 改变须同步 manuscript。**状态**：method framework 有用，Illusion narrative superseded。**当前 authority**：[`SR_analysis/HANDOFF.md`](SR_analysis/HANDOFF.md)；待同步 [`../docs/JFM_WYQ/SR_Draft.md`](../docs/JFM_WYQ/SR_Draft.md)。 +- `/home/frank14f/.cursor/plans/steady-cloak-jfm-roadmap_9c27caab.plan.md` 与 `/home/frank14f/.cursor/plans/steady理论收尾_7e4c9476.plan.md` + **意图**：source-to-equation ledger、proof、numerical results、figures 组成 JFM-ready chain。**教训**：primary literature 支撑 equations/comparison boundary，不替代 project evidence；publication 可以是 BOUNDED。**状态**：historical routes。**当前 authority**：[`steady_pinball_theory/LITERATURE.md`](steady_pinball_theory/LITERATURE.md)、[`steady_pinball_theory/RESULTS.md`](steady_pinball_theory/RESULTS.md)。 +- `/home/frank14f/.cursor/plans/项目总文档收尾_4b6a93bc.plan.md` + **意图**：重建 repo entry、knowledge、status roadmap、compatibility ledger。**教训**：导航/知识/任务/兼容文档分工；plans/Memory 只作 context。**状态**：本文件是 analysis-notes 交付，plan 本身不成为 authority。**当前 authority**：本文件与 [`analysis_knowledge.md`](analysis_knowledge.md)。 -定义控制到传感器的对流时延近似为 -\[ -\tau_c \approx \frac{L_x}{U_{conv}} -\] +## 7. 项目级失败方法与停止规则 -实际代码中不应只用固定 \(U_{in}\)，而应在 pinball 下游到传感器之间取一个代表性的局部平均对流速度 \(U_{conv}\)。随后定义对应的采样滞后步数 +### 已失败或撤回 -\[ -N_c = \mathrm{round}\left(\frac{\tau_c}{\Delta t_s}\right) -\] +- 用漂亮 field plot、frequency proximity、DTW lag 或 high R² 直接推断 mechanism/causality。 +- 把同 trajectory 的 windows、phase offsets、r1/r2/r3 当 independent realizations。 +- 把 raw full-field POD/CCD/OID reconstruction 当 task importance 或 control authority。 +- 无 paired counterfactual 时把同 phase/index difference 称 intervention effect。 +- 把 constant mean 与 dynamic residual 混成一个 modal conclusion。 +- 通过 Legacy→V5 sensor scaling、norm 搬运或 object labels 宣称 solver equivalence。 +- 用 short-window Illusion SR positives 覆盖 long-window physical-zero negative control。 +- 把 potential circulation 当 rotating no-slip closure，或以 good fit 掩盖 sign contradiction。 +- 把 incomplete control-volume ledger 称 NS/energy closure；把 single switch/return 称 causality/stability。 +- 为修复 claim 新增 parallel pipeline、自动 alias 或覆盖 old artifacts。 -所有 `act -> obs`、`force -> obs`、probing 响应和窗口化 DTW 计算，默认都要至少测试三种滞后： +### 全项目停止规则 -- `0` -- `N_c` -- `N_c \pm 0.25 N_T` +1. **contract failure 即停**：body/action/order、units、clock、mask、parent/hash、metric/window 任一不清楚，不运行下游。 +2. **unfair comparison 即停**：无同条件 baseline/physical zero、相同 residual/rank/weight 或 preregistered comparator，不作 superiority claim。 +3. **insufficient data 即降级**：single realization、correlated rows、缺 pressure/near-wall resolution 或 independent observable 时，只报 bounded description。 +4. **negative result 即收束**：CCD≈POD、SR≈zero、potential sign wrong 或 closure 不收敛时缩叙事，不追加 search 寻找正结果。 +5. **CFD 必须解除 blocker**：每次新 CFD 只回答一个明确、可证伪且影响文章结论的问题；失败两次或 schema/solver 根本异常即停。 +6. **no-clobber**：successful、failed、partial、superseded artifacts 均不覆盖；新结论用 sibling + authority ledger 晋升。 +7. **一次复核循环**：每阶段最多一次 independent review 和一次 remediation/re-review；仍有 high-severity finding 就阻断并交用户。 +8. **writing 不领先 evidence**：package authority/evidence parity 未冻结前不更新 manuscript conclusions；plans、Memory、archive 不填补证据空缺。 + +## 8. 最短阅读顺序 -这样可以判断最佳对齐是否真接近物理对流时延。 +1. 本文件：状态、gates、historical index。 +2. [`analysis_knowledge.md`](analysis_knowledge.md)：跨项目概念与认识论边界。 +3. [`SR_analysis/README.md`](SR_analysis/README.md)、[`CCD_analysis/README.md`](CCD_analysis/README.md)、[`steady_pinball_theory/README.md`](steady_pinball_theory/README.md)、[`OID_analysis/README.md`](OID_analysis/README.md)：package entries。 +4. 对应 results/checkpoint/manifest：决定可写 numbers/status。 +5. `.cursor/plans` 与 Nowledge Memory：只恢复 history/rationale，不作 evidence。 + + +## 2026-08-09 closeout -## 任务 1 - -## 基础后处理 - -第一批结果必须先把均值、脉动、功率和回流区做扎实。这一层风险最低，但几乎一定能给出物理信息。 - -### 1.1 均值场与脉动场 - -对每个 case，在去掉初始过渡后，计算时间均值场 - -\[ -\bar u(x,y)=\frac{1}{N}\sum_{n=1}^{N} u(x,y,t_n),\qquad -\bar v(x,y)=\frac{1}{N}\sum_{n=1}^{N} v(x,y,t_n) -\] - -定义脉动场 - -\[ -u'(x,y,t_n)=u(x,y,t_n)-\bar u(x,y),\qquad -v'(x,y,t_n)=v(x,y,t_n)-\bar v(x,y) -\] - -以及 RMS 图 - -\[ -\mathrm{RMS}_u(x,y)=\sqrt{\frac{1}{N}\sum_{n=1}^{N} u'(x,y,t_n)^2} -\] - -\[ -\mathrm{RMS}_v(x,y)=\sqrt{\frac{1}{N}\sum_{n=1}^{N} v'(x,y,t_n)^2} -\] - -同时建议输出均值涡量与瞬时涡量： - -\[ -\omega(x,y,t)=\frac{\partial v}{\partial x}-\frac{\partial u}{\partial y} -\] - -### 1.2 回流区几何量 - -由均值流定义回流区边界为 \(\bar u=0\) 等值线。提取： - -- 回流区长度 \(L_r\) -- 回流区面积 \(A_r\) -- 上下半区面积差 -- 尾迹中心线偏移 - -圆柱尾迹的受控变化往往先表现为均值流重构，再改变脉动的增长与饱和，因此这些量应视为主指标，而不是附属图 [Tad10, Man15, Kha24c]。 - -### 1.3 力、力矩与控制功率 - -对每个圆柱定义瞬时控制功率 - -\[ -P_{c,i}(t_n)=M_{z,i}(t_n)\,\Omega_i(t_n) -\] - -总控制功率 - -\[ -P_c(t_n)=\sum_{i=1}^{3} P_{c,i}(t_n) -\] - -对每个 case 输出： - -- \(P_{c,i}(t)\) 与 \(P_c(t)\) 时间序列 -- 平均功率 \(\overline{P_c}\) -- 功率 RMS -- 功率谱 -- 三个圆柱功率占比 - -旋转控制的功率核算必须和气动收益分开记账，否则很容易得到“结果有效但代价模糊”的控制解释 [Ber06]。 - -### 1.4 传感器误差与相似度 - -定义瞬时传感器误差向量 - -\[ -e_s(t_n)=s(t_n)-s_{tar}(t_n) -\] - -定义点态误差范数 - -\[ -E_s(t_n)=\lVert e_s(t_n)\rVert_2 -\] - -DTW 仍保留为最终任务指标，但建议补两个更轻量的窗口量： - -- 窗口化欧氏误差均值 -- 窗口化相关系数或相位滞后 - -因为 DTW 适合最终评分，不适合作为所有中间分析唯一指标。 - -### 1.5 新增：三场分解与 correction field - -这是这一轮调研后最值得优先加入的分析层。目的不是替代前面的基础后处理，而是把“pinball 自身阻挡的影响”和“旋转控制额外施加的影响”分开。 - -对每个主分析工况，至少准备三类同步场： - -| 记号 | 含义 | -|---|---| -| \(q_{in}(x,t)\) | 入射参考场：没有 pinball，只有背景来流或上游扰动 | -| \(q_{blk}(x,t)\) | 固定 pinball 场：pinball 在场内，但不旋转 | -| \(q_{ctl}(x,t)\) | 控制 pinball 场：pinball 按 DRL 策略旋转 | - -这里的 \(q\) 可以是速度场、涡量场、压力场，或其低维投影。 - -随后定义两个差分场： - -\[ -\Delta q_{blk} = q_{blk} - q_{in} -\] - -表示 **pinball 几何阻挡本身** 对流场造成的扰动；再定义： - -\[ -\Delta q_{ctl} = q_{ctl} - q_{blk} -\] - -表示 **在 pinball 已经存在的前提下，旋转控制额外施加的修正**。 - -这一步对 cloak 与 illusion 都特别关键。 - -- 对 cloak，更合理的任务表述不是“合力为零”，而是：控制产生的 correction field 尽量抵消 blockage wake，因此在任务相关区域里倾向于看到 - -\[ -\Delta q_{ctl} \approx -\Delta q_{blk} -\] - -- 对 illusion，更合理的任务表述不是“pinball 直接变成目标物体”，而是：控制在 fixed-pinball 的基线 wake 上叠加一个 target-like correction。若目标物体在相同来流下的场记为 \(q_{tar}\)，则理想上应比较 - -\[ -\Delta q_{ctl} -\] - -与 - -\[ -q_{tar} - q_{blk} -\] - -之间的接近程度。 - -第一轮不必追求精细壁面量，只需先在 pinball 整体尺度上回答： - -- pinball 本来会把流场改成什么样 -- 控制又额外把它改成什么样 -- 这部分额外修正是否具有稳定结构，并继续传到 force 与 signature - -推荐至少分三个区域看这些差分场： - -- pinball 紧邻区 -- 近尾迹形成区 -- 下游传感器区 - -并优先用粗粒化指标，而不是单点壁面量。例如： - -- 正负涡量面积或积分 -- 上下半区涡量不平衡 -- 回流区长度与面积变化 -- 近尾迹中心线偏移 -- 分区能量 / enstrophy 差分 - -这一步若能跑通，后面的 OID、CCD 和 SR 才有一个真正清楚的中介对象可接。 - -### 1.6 新增：wake-to-force 视角下的 near-wake 层级 - -这一轮需要补上的，不只是“控制额外改了什么流场”，还包括：**这些改动里哪些部分最直接投影到 force，哪些部分再继续发展成 downstream signature**。wake-to-force 文献给出的最重要启发，不是又多了一套算力公式，而是指出应把“与物体仍动态相连的近尾迹结构”与“已经成熟脱落的 far wake”分开看。[Noc99, Kan17b, Geh23] - -这会把主链条进一步细化为： - -\[ -\text{obs} \rightarrow \text{act} \rightarrow \Delta q_{ctl} \rightarrow \text{body-connected wake structure} \rightarrow \text{force} \rightarrow \text{future signature} -\] - -对当前 pinball，这条补充很重要，因为它正好化解一个表面矛盾： - -- **目标 signature** 的形成确实需要若干个 \(D\) 的对流、融合和发展； -- 但**瞬时力与控制直接作用的主结构层**未必需要延伸到整个成熟 far wake，而更可能集中在 pinball 后方有限的 body-connected 区域。[Kan17b] - -因此，第一轮分析时不宜把“离 pinball 很近的结构不可能像 target”误写成“近尾迹对机制不重要”。更稳的表述应当是： - -- 近尾迹负责 force-relevant structure； -- 更下游的发展区负责 signature formation； -- 两者应区分但不能割裂。[Kan17b, Sch12, Lyu23] - -在执行层面上，这意味着至少应把后处理区域分成三层： - -| 区域 | 主要问题 | 更适合接哪条线 | -|---|---|---| -| pinball 紧邻区 | 旋转先改了什么近体区修正 | Chen 线 / correction field [Che19] | -| body-connected near wake | 哪些结构最先投影到 force | wake-to-force / force-OID / force-CCD [Noc99, Kan17b, Geh23, Sch12] | -| downstream sensor zone | 哪些结构最终决定 future signature | signature-OID / CCD / delay-aware 相关分解 [Sch12, Lyu23] | - -## 任务 2 - -## 公共 POD 与低维状态 - -POD 的用途不是直接给最终机制下结论，而是建立统一坐标系，让不同 case 的结构变化可比较 [Den18b, Den20, Tai17]。 - -### 2.1 公共 POD - -把 uncontrolled、stealth、illusion、target，以及必要的 disturbed inflow case 的快照拼在一起，构造状态向量 - -\[ -q(t_n)= -\begin{bmatrix} - u(x_1,y_1,t_n),\ldots,u(x_M,y_M,t_n), - v(x_1,y_1,t_n),\ldots,v(x_M,y_M,t_n) -\end{bmatrix}^{\top} -\] - -对去均值后的矩阵做 SVD： - -\[ -Q = U \Sigma V^{\top} -\] - -得到空间模态 \(\phi_k\) 与时间系数 \(a_k(t_n)\)。 - -### 2.2 必须输出的 POD 结果 - -| 输出 | 说明 | 用途 | -|---|---|---| -| 前 6 阶模态 | 空间结构图 | 看主导 shedding pair、shift-like mode | -| 模态能量占比 | 条形图 | 看各 case 能量重分配 | -| 主系数时间序列 | \(a_1,a_2,a_3,a_4\) | 看周期、相位和稳定态 | -| 主系数相图 | 如 \((a_1,a_2)\) | 看 attractor 与状态迁移 | - -### 2.3 主系数与观测/动作/力的关联 - -至少计算下列相关量： - -\[ -\mathrm{corr}(a_k,\Omega_i),\qquad -\mathrm{corr}(a_k,F_{x,i}),\qquad -\mathrm{corr}(a_k,F_{y,i}),\qquad -\mathrm{corr}(a_k,E_s) -\] - -同时做滞后版本： - -\[ -\mathrm{corr}(a_k(t),\Omega_i(t-\tau)),\qquad -\mathrm{corr}(a_k(t),E_s(t+\tau)) -\] - -如果 stealth 与 illusion 主要作用于同一对主模态，则说明它们可能是同一结构通道的不同目标化使用；如果作用对象不同，则可支持“机制并不相同”的判断。 - -## 任务 3 - -## observable-related decomposition - -你的控制目标仍然是 downstream signature shaping，但这一轮之后，OID 这条线不应再被理解成“对原始全流场做更高级模态分解”。更稳的做法是：**先把流场分成入射场、阻挡场和控制额外修正场，再在 correction field 上做 observable-related decomposition。** 也就是说，OID / PCD / CCD 的默认主对象应优先变成 - -\[ -\Delta q_{ctl} = q_{ctl} - q_{blk} -\] - -而不是直接拿 \(q_{ctl}\) 做解释。 - -同时，cloak 和 illusion 虽然都属于 signature shaping，但它们面对的原始流场和要完成的修正任务并不相同： - -- **steady cloak**：均匀来流下，pinball 自身会自激 shedding；控制后要把下游重新推回稳定均匀态。 -- **Karman cloak**：上游本来就有涡街；pinball 不控制时把它扰乱；控制后要恢复原来涡街的频率与形状。 -- **illusion**：均匀来流下，pinball 不控制时有 natural shedding；控制后要把这个 shedding 改写成目标圆柱的 shedding。 - -因此，这一部分不能再把 steady cloak、Karman cloak 和 illusion 当成同一种 OID 问题来处理。 - -### 3.1 为什么 POD 不够 - -POD 的排序标准是流场能量最大，而不是任务相关性最大 [Den18b, Tai17]。但对当前问题，真正关心的不是“哪个结构最强”，而是： - -- steady cloak 中，哪个 correction structure 最能压低 natural shedding、恢复均值尾迹 -- Karman cloak 中，哪个 correction structure 最能抵消 pinball 对 incoming street 的破坏 -- illusion 中，哪个 correction structure 最能把 natural pinball shedding 改写成 target shedding -- 哪个 structure 最影响总 force 或各圆柱 torque -- 哪个 structure 最决定 future signature - -因此必须比较三类坐标： - -- **POD 坐标**：最 energetic 的结构 -- **OID-style 坐标**：最影响 observable 的结构 [Sch12] -- **PCD-style 坐标**：与 observable 最相关、且可显式处理时延的结构 [Lyu23] - -如果后两者与 POD 前几阶不同，反而说明控制不是简单压主模态，而是在调少数 task-relevant correction structures。 - -### 3.2 前置数据准备 - -这一轮之后，OID 的前置数据不应只有公共 POD，还必须先有三场分解： - -- \(q_{in}\)：入射参考场 -- \(q_{blk}\)：固定 pinball 场 -- \(q_{ctl}\)：控制 pinball 场 - -然后定义： - -\[ -\Delta q_{blk} = q_{blk} - q_{in} -\] - -\[ -\Delta q_{ctl} = q_{ctl} - q_{blk} -\] - -其中： - -- \(\Delta q_{blk}\) 代表 pinball 几何阻挡本身带来的被动扰动 -- \(\Delta q_{ctl}\) 代表旋转控制额外施加的主动修正 - -随后在 correction field 上做公共 POD。保留前 \(r\) 阶系数，建议先从 \(r=6,8,10\) 做最小 rank sensitivity，再根据数据长度扩到 \(r=12,16\)。定义 POD 系数向量： - -\[ -a(t_n)=\begin{bmatrix}a_1(t_n),\ldots,a_r(t_n)\end{bmatrix}^{\top} -\] - -对每个系数做标准化： - -\[ -\tilde a_k(t)=\frac{a_k(t)-\mu_{a_k}}{\sigma_{a_k}} -\] - -组成标准化矩阵 \(\tilde A\in\mathbb{R}^{N\times r}\)。observable 也全部做标准化，避免不同量纲主导分解。 - -### 3.3 三类场景下的 observable 设计 - -OID 现在不能只机械地区分 force observable 和 sensor observable，还要按场景定主问题。 - -#### A. steady cloak - -steady cloak 的第一问题不是“未来周期性 signature 匹配”，而是： - -- 压低自然 shedding -- 恢复均值尾迹 -- 收缩回流区 -- 让下游重新接近均匀稳定态 - -因此更适合的 observable 是： - -- 总 force / total torque -- control power -- fluctuation amplitude 或局部 RMS -- mean-wake 指标，如 \(L_r\)、\(A_r\)、尾迹中心线偏移 -- 下游相对于均匀稳态的误差 - -steady cloak 第一轮不必强行套入 periodic future-signature 模板。 - -#### B. Karman cloak - -Karman cloak 的第一问题是： - -- pinball 破坏了 incoming vortex street 的什么结构 -- 控制又额外施加了什么 correction 去恢复该 street -- 哪些结构最决定 future signature 的相位、频率和形状恢复 - -这里最自然的 observable 是： - -\[ -y_F(t)=\begin{bmatrix} -\sum_i F_{x,i}(t),\sum_i F_{y,i}(t),\sum_i M_{z,i}(t) -\end{bmatrix}^{\top} -\] - -以及 future-signature observable： - -\[ -p_{sig}(t)=\begin{bmatrix} -e_s(t+\tau_c), e_s(t+\tau_c+\tau), e_s(t+\tau_c+2\tau) -\end{bmatrix}^{\top} -\] - -其中 \(\tau_c\) 取控制到传感器的对流时延，\(\tau\) 建议先取约四分之一脱涡周期。 - -#### C. illusion - -illusion 的第一问题不是 suppress wake，而是 retune wake： - -- natural pinball shedding 如何被改写成 target shedding -- 哪些结构主要改频 -- 哪些结构主要改空间形态 -- 这些结构与 force 的关系是同一条通道，还是先近尾迹调制、后下游重组 - -这里同样优先保留： - -\[ -y_F(t)=\begin{bmatrix} -\sum_i F_{x,i}(t),\sum_i F_{y,i}(t),\sum_i M_{z,i}(t) -\end{bmatrix}^{\top} -\] - -以及 future-signature observable： - -\[ -p_{sig}(t)=\begin{bmatrix} -e_s(t+\tau_c), e_s(t+\tau_c+\tau), e_s(t+\tau_c+2\tau) -\end{bmatrix}^{\top} -\] - -必要时再补与目标 shedding 直接相关的低维指标，如主频偏差、phase error 或 envelope 差异。 - -### 3.4 从零开始的 OID-style 实现 - -严格按原始 OID 理论实现会比较重，对 coder 最稳的第一版仍然是 **cross-covariance OID-style decomposition**。但这一步默认应先作用在 correction-field POD 系数上，而不是 raw full-field POD 系数上。 - -给定标准化 correction-field POD 系数 \(\tilde A\in\mathbb{R}^{N\times r}\) 和标准化 observable 矩阵 \(\tilde Y\in\mathbb{R}^{N\times m}\)，先计算交叉协方差： - -\[ -C_{AY}=\frac{1}{N}\tilde A^{\top}\tilde Y -\] - -对 \(C_{AY}\) 做奇异值分解： - -\[ -C_{AY}=U\Sigma V^{\top} -\] - -则： - -- \(U\) 的列向量给出 POD 子空间里与 observable 最相关的方向 -- 奇异值 \(\sigma_k\) 给出相关强度排序 -- 定义 observable-related 坐标 - -\[ -z^{OID}(t)=U^{\top}\tilde a(t) -\] - -- 对应空间模态可由 POD 模态线性组合得到 - -\[ -\psi_k^{OID}(x,y)=\sum_{j=1}^{r} U_{jk}\,\phi_j(x,y) -\] - -这一步的物理解释要写准：\(\psi_k^{OID}\) 不是最 energetic 的结构，而是最能改变当前选定 observable 的 **correction structure**。 - -#### OID-style 的主分支 - -1. **force-OID**：令 \(Y=y_F\) -2. **signature-OID**：令 \(Y=e_s\) 或 \(Y=p_{sig}\) -3. **steady-suppression OID**：steady cloak 下令 \(Y\) 取 fluctuation / mean-wake restoration 指标 - -这样回答的问题会更直接： - -- 哪些 correction structures 最影响 force -- 哪些 correction structures 最影响 future signature -- 哪些 correction structures 最能压低 natural shedding 并恢复稳定尾迹 - -### 3.5 从零开始的 PCD-style 实现 - -对当前问题，PCD 最值得用于处理 **时延 + 多变量 sensor + 噪声**。特别是 Karman cloak 与 illusion，它们都比 steady cloak 更依赖 future signature 的显式对齐。对 coder，推荐做一个 **delay-aware correlation decomposition**，本质上是对标准化 POD 系数和延迟 observable 做 whitening 后的 SVD。 - -先取标准化系数 \(\tilde A\) 和某个延迟 observable 矩阵 \(\tilde P\)；例如 \(\tilde P=\tilde P_{sig}\) 或 \(\tilde P_{causal}\)。 - -定义协方差矩阵： - -\[ -C_{AA}=\frac{1}{N}\tilde A^{\top}\tilde A, -\qquad -C_{PP}=\frac{1}{N}\tilde P^{\top}\tilde P, -\qquad -C_{AP}=\frac{1}{N}\tilde A^{\top}\tilde P -\] - -构造 whitening 后的相关矩阵： - -\[ -K=C_{AA}^{-1/2} C_{AP} C_{PP}^{-1/2} -\] - -对 \(K\) 做 SVD： - -\[ -K=U\Sigma V^{\top} -\] - -定义 PCD-style 坐标： - -\[ -z^{PCD}(t)=U^{\top} C_{AA}^{-1/2}\tilde a(t) -\] - -对应空间模态仍由 POD 模态线性组合得到： - -\[ -\psi_k^{PCD}(x,y)=\sum_{j=1}^{r} W_{jk}\,\phi_j(x,y) -\] - -其中 \(W=C_{AA}^{-1/2}U\)。 - -这一步比 OID-style 更适合 periodic signature 问题，因为： - -- 可以自然纳入多时刻 observable -- 可以把当前 correction structure 与未来 signature 对齐 -- 对不同 observable 分量量纲和噪声更稳 [Lyu23] - -### 3.6 推荐的两套 PCD-style 版本 - -#### A. causal-PCD - -输入用 \(p_{causal}(t)\)。用途是： - -- 找到与当前控制输入最相关的结构态 -- 后续进入 `obs -> z -> act` - -#### B. signature-PCD - -输入用 \(p_{sig}(t)\)。用途是： - -- Karman cloak：找到哪些 correction structures 最决定 incoming street 的重建 -- illusion：找到哪些 correction structures 最决定 target shedding 的重建 -- 建立 `structure -> future signature` 链条 - -### 3.7 force-OID 与 signature-OID 的分工口径 - -这一轮之后，OID/CCD 这条线里必须长期保留一个区分：**force-relevant structures** 与 **signature-relevant structures** 不应先验地视为同一组 [Sch12, Kan17b, Lyu23]。 - -更稳的工作假设是： - -- controller 首先调制一小组与 force 强相关的 near-body / body-connected correction structures； -- 这些结构在若干个 \(D\) 的对流与相互作用后，再组织成与 downstream signature 强相关的 descendant structures。 - -因此，若后续分析发现 force-OID 与 signature-OID 不同，这不应被第一时间解释为算法失败；它很可能正是最有价值的机制结果。 - -### 3.8 该怎么判断 OID/PCD 比 POD 更有用 - -不能只看模态图好不好看，要用预测能力比较，并且要按场景选择评价对象。 - -#### 对比 1 - -用前 \(m\) 个 POD 坐标预测 observable，与用前 \(m\) 个 OID/PCD 坐标预测 observable 比较。 - -例如对 periodic cases： - -\[ -\hat e_s(t+\tau_c)=B z_{1:m}(t) -\] - -对 steady cloak，则可改用： - -- fluctuation suppression metric -- mean-wake restoration metric -- recirculation geometry metric - -#### 对比 2 - -用前 \(m\) 个坐标拟合动作： - -\[ -\hat \Omega_i(t)=b_i^{\top} z_{1:m}(t) -\] - -比较 POD 与 OID/PCD 的误差和稀疏度。 - -#### 对比 3 - -比较不同坐标与任务指标的相关强度： - -\[ -\mathrm{corr}(z_k,E_s),\qquad \mathrm{corr}(z_k,\Omega_i),\qquad \mathrm{corr}(z_k,y_F) -\] - -steady cloak 还应补看： - -\[ -\mathrm{corr}(z_k,L_r),\qquad \mathrm{corr}(z_k,A_r),\qquad \mathrm{corr}(z_k,\text{RMS metric}) -\] - -### 3.9 coder 的实现顺序 - -1. 先做三场分解，得到 \(q_{in}, q_{blk}, q_{ctl}\) -2. 构造 \(\Delta q_{blk}\) 与 \(\Delta q_{ctl}\) -3. 先做 correction-field POD，而不是直接做 raw-field POD -4. 标准化 \(a(t)\) 和 observable -5. 先做 force-OID -6. steady cloak 再做 suppression / mean-wake OID -7. Karman cloak 与 illusion 再做 signature-OID 或 signature-PCD -8. 输出前 3 到 5 个坐标和对应空间模态 -9. 比较这些坐标与 `act`、`force`、`future sensor error` 或 steady restoration 指标的关系 -10. 最后再决定是否追更严格的 paper-level exact OID/PCD 公式 - -### 3.10 输出要求 - -| 输出 | 说明 | 用途 | -|---|---|---| -| correction-field POD vs OID/PCD 模态对比 | 同一基底下比较 | 看最强 correction structure 与最相关 correction structure 是否不同 | -| \(z_k(t)\) 时间序列 | 各种坐标时序 | 看控制在调哪些 correction freedom | -| \(z_k\) 与 `act` 的回归图 | 含滞后版本 | 看白箱控制依赖何种结构态 | -| \(z_k\) 与 future signature 的关系 | 用 \(p_{sig}\) | 看哪些结构最决定周期性 cloak / illusion 成败 | -| \(z_k\) 与 suppression / recirculation 指标的关系 | steady cloak | 看哪些结构最决定稳态恢复 | -| 预测性能表 | POD / OID / PCD 三种坐标对比 | 证明 observable-related 分解有价值 | - -## 任务 4 - -## 白箱控制链的两级拟合 - -既然 stealth 下 `obs -> act` 已经可能较简单，就不要只停在这一条。应同时比较下列三类模型： - -\[ -\text{Model A:}\quad \Omega = f(s) -\] - -\[ -\text{Model B:}\quad z = g(s),\qquad \Omega = h(z) -\] - -\[ -\text{Model C:}\quad z = g(s,F),\qquad \Omega = h(z) -\] - -其中 \(f,g,h\) 可用线性回归、稀疏回归、SINDy 或简单符号回归。关键不是追求最高精度，而是比较： - -- 哪个模型最简单 -- 哪个模型最稳 -- 哪个模型更能解释结构态 - -### 4.1 单 case 白箱链 - -对单个 case，优先比较四种输入： - -- 原始 sensor：`s(t)` -- sensor + force：`[s(t), y_F(t)]` -- POD 坐标：`a(t)` -- OID/PCD 坐标：`z(t)` - -对每个圆柱拟合： - -\[ -\Omega_i(t)=h_i(\chi(t)) -\] - -其中 \(\chi\) 依次取上面四类输入，并比较精度与稀疏度。 - -### 4.2 针对涡街隐身的跨 Re 统一方程 - -对于上游圆柱涡街来流的 stealth 工况，建议单独做一条 **多 Reynolds 数统一方程** 路线。目标不是每个 case 单独给一个公式，而是检验是否存在一个共享骨架，在不同 \(Re_D\) 下只靠一个上下文参数就能内插 [Bru16, Loi17]。 - -这里最建议使用的上下文变量不是 \(Re\) 本身，而是 - -\[ -\mu = \frac{1}{Re_D} -\] - -或等价的无量纲黏性参数 \(\nu/(U_{ref}D)\)。原因是 Navier–Stokes 方程的黏性项本身就是按 \(1/Re\) 缩放，物理上比直接用 \(Re\) 更自然。 - -### 4.3 统一方程前的数据标准化 - -跨 Re 拟合前，必须先把不同 case 归一到同一坐标和时间标度，否则统一方程很容易被周期差和幅值差破坏。 - -建议统一做三步： - -1. **统一低维坐标** - - 所有 Re 的 vortex-street stealth case 用同一个公共 POD / OID / PCD 基底 - - 这样所有 case 的 \(z_k\) 都在同一个坐标系里 - -2. **统一时间标度** - - 用目标涡街的主频 \(f_{tar}\) 或脱涡周期 \(T_{tar}\) 归一化时间 - - 或者把每个周期重采样到相同点数，例如每周期 16 点 - -3. **统一幅值标度** - - sensor、force、\(z\) 坐标都做标准化 - - 推荐按各自 target case 的 RMS 做归一化，而不是按全局最大值 - -### 4.4 统一方程的候选形式 - -最稳的做法不是让每个 Re 拟合完全独立的式子，而是先固定一个共享特征库，再联合稀疏识别。 - -建议候选特征库先只包含低阶项： - -\[ -\Theta(t)=\Big[ -1,\mu, -z_1,\ldots,z_m, -y_{F,1},\ldots,y_{F,p}, -z_1^2,\ldots,z_m^2, -\mu z_1,\ldots,\mu z_m, -z_i z_j -\Big] -\] - -若考虑时延，则加入少量延迟项： - -\[ -z_k(t-\tau),\qquad y_{F,j}(t-\tau) -\] - -统一控制律写成 - -\[ -\Omega_i(t)=\beta_i^{\top}\Theta(t) -\] - -更具体一点，可写成 - -\[ -\Omega_i(t)=c_{i0}+c_{i\mu}\mu+\sum_{k=1}^{m}(c_{ik}+d_{ik}\mu)z_k(t) -+\sum_{j=1}^{p} b_{ij} y_{F,j}(t) -+\sum_{k\le l} q_{ikl} z_k(t)z_l(t) -\] - -这意味着： - -- 所有 Re 共用同一组 active terms -- 黏性影响主要通过 \(\mu\) 和 \(\mu z_k\) 来调节系数 - -### 4.5 联合拟合方式 - -把所有 Re case 的样本按行堆叠成一个大矩阵： - -\[ -\Omega_i^{all}=\Theta^{all}\beta_i -\] - -然后做联合稀疏回归。推荐顺序： - -1. 先普通 LASSO / sequential threshold least squares -2. 再做 group sparsity，让三个圆柱或多个 Re 共用项结构 -3. 最后再尝试符号回归做更漂亮的闭式表达式 - -实际目标不是一开始求最美公式，而是先验证： - -- 是否存在共享支持集 -- 是否只需一个 \(\mu\) 就能把多个 Re 串起来 - -### 4.6 必须做的验证 - -统一方程最关键的是验证“真内插”而不是只在训练点硬记住。必须至少做两类测试。 - -#### A. leave-one-Re-out - -例如用三个 Re 训练，留一个 Re 测试，看统一方程是否还能保持合理误差。 - -#### B. pairwise interpolation - -例如只用低 Re 和高 Re 训练，测试中间 Re。若中间 Re 也能拟合，说明 \(\mu\) 的连续插值是有意义的。 - -### 4.7 成功与失败的判据 - -统一方程成功，不等于误差最低，而是满足： - -- active term 数量明显少于逐 case 单独拟合后项数总和 -- leave-one-Re-out 误差没有灾难性变差 -- 主要 active terms 在不同 Re 下仍是同一批 -- 系数随 \(\mu\) 的变化平滑、可解释 - -如果做不到，则不要强行保留“一个总公式”的说法，而应退一步写成： - -- **统一骨架 + Re 依赖系数** - -或者： - -- **低 Re 与高 Re 两个分段方程** - -### 4.8 推荐的统一拟合版本顺序 - -1. 先做单 case 的 `obs -> act` -2. 再做单 case 的 `z -> act` -3. 再做多 Re 的 `z, y_F, \mu -> act` -4. 最后再尝试 raw `obs, \mu -> act` - -如果 `z, y_F, \mu -> act` 比 raw `obs, \mu -> act` 更简单、更稳，就能非常有力地说明： - -- 不同 Re 的控制不是完全不同的策略 -- 而是在同一低维结构反馈骨架上，受黏性参数 \(\mu\) 调制 - -### 判据 - -| 判据 | 说明 | -|---|---| -| 拟合误差 | `RMSE`, `MAE`, `R^2` | -| 稀疏度 | 非零项数 | -| 稳定性 | 不同 case 或不同时间窗是否保结构 | -| 内插性 | leave-one-Re-out 是否成立 | -| 物理性 | 是否能对应少数结构态 | - -如果出现 `obs -> act` 复杂、但 `obs -> z -> act` 简单的情况，这会是很强的物理论据 [Loi17, Bru16, Li22b]。 - -## 任务 5 - -## 能量分析的三层实现 - -### 5.1 第一层 - -最小功率 bookkeeping - -这是必须完成的最低层。 - -输出： - -- 每个圆柱 \(P_{c,i}(t)\) -- 总功率 \(P_c(t)\) -- 平均功率、RMS、谱 -- 功率与 DTW 改善的关系 - -建议再加两个效率指标： - -\[ -\eta_{DTW} = \frac{\Delta \mathrm{Sim}}{\overline{P_c}+\epsilon} -\] - -\[ -\eta_{force} = \frac{\Delta F_{rms}}{\overline{P_c}+\epsilon} -\] - -其中 \(\epsilon\) 为防止分母为零的小量。 - -### 5.2 第二层 - -mean–fluctuation 动能 - -定义平均动能 - -\[ -K_m = \int_{\Omega} \frac{1}{2}(\bar u^2+\bar v^2)\,d\Omega -\] - -定义脉动动能 - -\[ -K_f = \int_{\Omega} \frac{1}{2}\overline{u'^2+v'^2}\,d\Omega -\] - -若数据质量允许，定义黏性耗散近似 - -\[ -\varepsilon_f \approx \nu \int_{\Omega} \overline{\nabla \mathbf u' : \nabla \mathbf u'}\,d\Omega -\] - -\[ -\varepsilon_m \approx \nu \int_{\Omega} \nabla \bar{\mathbf u} : \nabla \bar{\mathbf u}\,d\Omega -\] - -这层的关键判断是： - -- stealth 是否主要降低 \(K_f\) -- illusion 是否在不显著降低 \(K_f\) 的情况下重组结构 -- disturbed inflow 是否主要增加 \(\varepsilon_f\) 或功率波动 - -### 5.3 第三层 - -coherent transfer 与频带耦合 - -这一层是可选增强。建议先做轻量版，再决定是否上 BMD [Sch20]。 - -轻量版顺序： - -1. 传感器和主模态系数 FFT -2. 探针信号 bispectrum -3. 主频、二倍频、均值分量之间的相干与相位 - -若这些结果明确显示二次耦合，再考虑 full BMD。对当前数据，直接上 BMD 不是第一优先级。 - -## 任务 6 - -## 回流区与通量分析 - -受控 wake 很多时候可以通过回流区通量平衡来解释，而不仅是“能量变小了” [Kha24c]。 - -### 6.1 回流区边界 - -用均值流的 \(\bar u=0\) 等值线作为 recirculation region interface。 - -### 6.2 通量量 - -对边界曲线 \(\Gamma_r\) 上的单位法向量 \(\mathbf n\)，定义法向通量 - -\[ -\Phi_r = \int_{\Gamma_r} \bar{\mathbf u}\cdot \mathbf n\, ds -\] - -在数值上，对外流与内流分别积分： - -\[ -\Phi^{+} = \int_{\Gamma_r} \max(\bar{\mathbf u}\cdot\mathbf n,0)\, ds -\] - -\[ -\Phi^{-} = \int_{\Gamma_r} \min(\bar{\mathbf u}\cdot\mathbf n,0)\, ds -\] - -同时可在上下 shear layer 位置定义辅助界面，统计各自通量。目标不是做 3D bluff-body 那样完整的体积分，而是先比较： - -- stealth 是否让上下通量更平衡 -- illusion 是否让回流区形态和通量分布向 target 靠拢 -- 某些控制是否通过延后 shear-layer roll-up 改变 bubble 长度 - -## 任务 7 - -## circular body-force probing - -局部体力 probing 的目标不是替代 pinball 旋转，而是做 **结构敏感性和因果诊断**。已有圆柱尾迹的灵敏度、adjoint、wavemaker 和 localized resolvent 结果表明：局部 forcing 的空间位置、方向和频率本身就能提供很强的结构信息 [Gia07, Mar08b, Jin19b, Jin21, Ske22]。 - -### 7.1 圆形 forcing 的统一定义 - -对第 \(m\) 个圆形区域，中心为 \((x_m,y_m)\)，半径为 \(R_m\)。定义空间窗函数 - -\[ -\phi_m(x,y)= -\begin{cases} -\frac{1}{2}\left[1+\cos\left(\pi r_m/R_m\right)\right], & r_m \le R_m \\ -0, & r_m > R_m -\end{cases} -\] - -其中 \(r_m = \sqrt{(x-x_m)^2+(y-y_m)^2}\)。 - -则局部体力写为 - -\[ -\mathbf f_p(x,y,t)=A\,\phi_m(x,y)\,g(t)\,\mathbf e_d -\] - -其中 \(\mathbf e_d\in\{\mathbf e_x,\mathbf e_y\}\)。 - -### 7.2 第一轮 probing 类型 - -只做两类： - -1. 脉冲 forcing - -\[ -g(t)=\mathbb{1}_{[t_0,t_0+\Delta T]}(t) -\] - -2. 单频谐波 forcing - -\[ -g(t)=\sin(2\pi f t) -\] - -第一轮频率只扫： - -- 主脱涡频率 \(f_s\) -- 目标频率 \(f_{tar}\) -- \(2f_s\) -- \(2f_{tar}\) - -### 7.3 候选圆区 - -第一轮不做全场遍历，先选最有物理意义的 5 类区域： - -| 区域 | 位置建议 | 目的 | -|---|---|---| -| 前圆柱后缘近尾迹 | front cylinder 后方 | 看主剪切层起始敏感性 | -| 两后圆柱之间 | pinball 中央空隙 | 看 central jet / 对称性通道 | -| 上剪切层起始处 | 上后圆柱外侧 | 看反对称结构 | -| 下剪切层起始处 | 下后圆柱外侧 | 看反对称结构 | -| pinball 后方主尾迹核心 | 三圆柱后方短距离 | 看回流区与大尺度 roll-up | - -### 7.4 probing 输出 - -每次 probing 必须输出： - -| 输出 | 指标 | -|---|---| -| 传感器响应 | \(\max_t \lVert \Delta s(t) \rVert\)、窗口化 DTW 变化 | -| 受力响应 | 总 lift、drag、各圆柱 torque 峰值变化 | -| 结构态响应 | 主 POD/OID 系数峰值与恢复时间 | -| 做功 | \(P_f(t)=\int_{\Omega} \mathbf u\cdot\mathbf f_p\,d\Omega\) | -| 频域响应 | 传感器与主模态的谱峰变化 | - -定义累计 forcing 做功 - -\[ -W_f = \int_{t_0}^{t_1} P_f(t)\,dt -\] - -再定义响应效率 - -\[ -\eta_s = \frac{\max_t \lVert \Delta s(t) \rVert}{W_f+\epsilon} -\] - -\[ -\eta_z = \frac{\max_t \lvert \Delta z_k(t) \rvert}{W_f+\epsilon} -\] - -最终产出应包括： - -- 区域–方向 敏感性热图 -- 区域–频率 响应图 -- 若干代表区域的时序响应图 - -## 任务 8 - -## 图组与最终交付物 - -建议按下面顺序生成标准图，先做低风险主图，再做增强图。 - -| 顺序 | 图 | 内容 | -|---|---|---| -| 1 | mean + RMS 图 | uncontrolled / stealth / illusion / target 对比 | -| 2 | 回流区图 | \(\bar u=0\) 边界、长度、面积、对称性 | -| 3 | force / torque / power 图 | 三圆柱局部分工与总功率 | -| 4 | POD 图 | 公共基底、模态能量、系数相图 | -| 5 | observable-related 图 | OID/PCD 模态和 \(z(t)\) | -| 6 | 白箱链图 | `obs -> act` vs `obs -> z -> act` | -| 7 | probing 热图 | 区域–方向–频率 敏感性 | -| 8 | 频带耦合图 | FFT / bispectrum / 必要时 BMD | - -## coder 的执行顺序 - -最稳妥的实现顺序如下。 - -1. 做统一数据读取与同步校验 -2. 生成 mean、RMS、vorticity、force、power 的基础结果 -3. 提取回流区边界与几何统计 -4. 做公共 POD 和主系数关联图 -5. 构造 observable，做 OID/PCD 或相关替代方案 -6. 先补做三场分解：`q_in`, `q_blk`, `q_ctl`，并明确 `Δq_blk` 与 `Δq_ctl` -7. 在 correction field 上检查 cloak 是否呈现 wake cancellation、illusion 是否呈现 target-oriented correction -8. 比较 `obs -> act` 与 `obs -> z -> act` -9. 实现最小版能量分析：\(P_c\)、\(K_m\)、\(K_f\)、必要时 \(\varepsilon_f\) -10. 实现圆形体力 probing 的脉冲与谐波扫描 -11. 最后视结果决定是否进入 bispectrum / BMD - -## 直接判断成功与否的标准 - -如果后处理结果支持以下判断，则整套方案算成功： - -- stealth 主要通过压低与传感器误差最相关的结构并重构均值尾迹实现 [Sch12, Lyu23, Tad10] -- illusion 不是简单降能，而是保留或重组目标相关结构与频带 [Jin20, Sch20] -- 三圆柱在力、力矩和功率上存在可识别分工 [Ber06, Den20] -- 控制对白箱化后，简单律主要作用于少数低维结构态，而不是直接依赖全场 [Loi17, Bru16, Li22b] -- 若三场分解成立，则控制主要体现为对 pinball-scale correction field 的低维调制，而不是简单的单一力学量跟踪 -- body-force probing 能识别出少数高敏感区域，并与真实控制下的主要结构变化相呼应 [Gia07, Mar08b, Jin21] -- force 最好被解释为 body-connected near-wake organization 的低维投影，而不是与涡量竞争的另一套机制 [Kan17b, Geh23, Sch12] -- force-relevant structures 与 signature-relevant structures 若被区分出来，应视为加强主线的结果，而不是分析失败 [Sch12, Lyu23] - -这套任务书的重点不是让所有高阶分析都必须成功，而是保证第一轮就能产出一组稳的、可解释的、能直接服务论文主线的结果。 \ No newline at end of file +- The repository-wide source index is `src/README.md`; use package READMEs and claim/result ledgers as authority. +- DRL pinball writing package was published in commit `86157c6`; its clean training CSV excludes the ambiguous Re60 TensorBoard stream fail-closed. +- Corrected Kármán CCD is closed as descriptive evidence; it does not support causal, stability, or mechanism claims. +- SR active scope is Kármán/cloaking only; Illusion SR remains historical/negative. OID remains a claim-free method core. +- `CelerisLab/` is excluded from this closeout; large external/generated data remains local and is governed by manifests and relocation notes. diff --git a/src/understanding_notes.md b/src/understanding_notes.md index 728d462..448f8b8 100644 --- a/src/understanding_notes.md +++ b/src/understanding_notes.md @@ -1,399 +1,250 @@ -# DynamisLab Understanding Notes +# LegacyCelerisLab → CelerisLab V5 兼容与迁移账本 -## 1. 网格尺寸 (Grid Dimensions) +- 文档版本：`v5.0.0-ledger.2026-08-09` +- 状态日期：2026-08-09 +- 适用范围：Legacy 场景复现、Legacy 策略跨求解器迁移差距研究、原生 CelerisLab V5 训练/评估 +- 文档性质：工程兼容账本，不是科学结论、论文证据或当前开放路线图 -### 旧版配置 -- `config_cuda.json`: X_1U=128, Y_1U=32, Z_1U=1 -- `config_flowfield.json`: field_dim_in_U=[10, 16, 1] -- 实际网格 = [128×10, 32×16, 1×1] = **[1280, 512, 1]** +> 本账本记录“什么必须保持、什么已经验证、什么不能等同”。Legacy 数值结果的最终权威是固定版本的 Legacy 原始求解器、原始环境和绑定 artifact；迁移代码与本账本只能解释兼容关系，不能替代原求解器证据。 -### 新版配置 -- `config_lbm_pinball.json`: nx=1280, ny=512 → **完全相同** +## 1. 三条工作通道必须分开 -所以网格尺寸没有变化。L0=20 是基尺度，但网格的 U 单位 = (128, 32) 是为了对齐 CUDA SM 数。 +### L1 — Legacy 原始求解器复现 ---- +目的：在 `LegacyCelerisLab` 上重放历史场景、策略、归一化、控制区间和 reset 语义。 -## 2. Re 数定义 +- 使用原始 Legacy 动力学、对象顺序、动作插槽、观测布局、SI、FIFO、EMA 和冻结 norm。 +- 当前统一入口及证据边界见 [Legacy reproduction README](drl_pinball/legacy_test/README.md)。 +- 这是历史 Legacy 数值行为的首要权威；若迁移实现、旧笔记或文件名与直接 Legacy 运行冲突，以绑定源码/配置/artifact 的 Legacy 运行结果为准。 +- SR 的当前科学范围和角色限制由各自包内文档决定；本账本不把历史 Illusion 或混合输出升级为当前正面科学证据。 -**关键：** 用户使用了两种 Re 定义： +### L2 — 归档 Legacy 策略在现代求解器上的迁移差距研究 -| 符号 | 长度尺度 | 公式 | 默认值 | -|------|---------|------|--------| -| `Re_D` | 单个圆柱直径 D=20 | U0·D/ν | 0.01×20/0.004 = **50** | -| `Re` (代码中写) | 2×D = 40 | U0·(2D)/ν | 0.01×40/0.004 = **100** | +目的：把冻结 Legacy PPO 和匹配 normalizer 接到现代 `Simulation`，量化 solver/API/geometry/schema 差距。 -- Confirmation report 中的 `Re_D = 50` 对应代码中的 Re100 -- 代码内写 re100 系列模型 → 实际物理 Re_D=50 -- 上游扰流圆柱直径 = L0×1 = 20 → Re=U0×20/ν=50 (单直径) +- 这是 compatibility experiment，不是“Legacy 已在 V5 等价复现”。 +- 必须显式使用 `legacy-policy-v1`、Legacy sensor 单位转换、匹配的 norm/VecNormalize 和 provenance。 +- 两套 LBM 实现的尾迹动力学可系统性不同；高 DTW 或动作相关性不证明 plant 等价。 +- 归档经验与已知差距见 [REPRODUCE_KNOWLEDGE](archive/reproduce/REPRODUCE_KNOWLEDGE.md)，但其中任何旧结论仍须服从当前源码和本账本的日期/版本规则。 ---- +### L3 — 原生现代 V5 训练与评估 -## 3. 旧 API vs 新 API 关键差异 +目的：在现代 2000×600 CelerisLab contract 下校准、训练、保存和评估原生策略。 -### 3.1 力的物理含义 +- 训练入口、artifact 集和 resume 边界见 [V5 training README](drl_pinball/train/README.md)。 +- canonical case registry、冻结 VecNormalize、确定性 360 步评估和复现 gate 见 [V5 evaluation README](drl_pinball/eval/README.md)。 +- 原生 V5 使用当前 calibration/native sensor units；不得为了“像 Legacy”而隐式乘 `SENSOR_CC`。 +- 保留的历史模型/结果不自动证明已按当前 native-v2 contract 完整重训。 -**旧 API (`FlowField.run(N, action)`)：** -``` -obs[:] = 0 -for step in range(N): - memset(obs_gpu, 0) # 每步清零 obs_gpu - step_kernel(...) # 每步 force 通过 atomicAdd 累加进 obs_gpu - obs += obs_gpu (H2D copy) # 每步读取到 host -obs /= N # 除以步数 = 每步平均力 -``` -→ 旧 `obs` = **每步平均力** +## 2. Legacy 不变量账本 -**新 API (`sim.run(N)` / `sim.stepper.step(N, ...)`)：** -``` -# stepper 内部不会清零 obs -# 需要用户手动清零 -sim.bodies.zero_force_segment_async(stream) # 清零力/扭矩段 -sim.stepper.step(N, ..., stream) -sim.read_force(id) → 累积 N 步后的值 -``` -→ 新 `sim.read_force()` = **N 步累积力**（需除以 N 得到每步平均） +### 2.1 `Re_code` 与 `Re_D` -**对应关系：** -- 旧 `obs` = 新 `sim.read_force(id)` ÷ N -- 旧 `obs[i]` 的 index 顺序 = 传感器在前 + 力在后 -- 新 API 分别用 `read_force(id)` 和 `read_sensor(id)` 分开读取 +Legacy 模型名和环境里的 `reXX` 通常是以 `2D` 为长度尺度的代码标签： -### 3.2 传感器的物理含义 - -**旧 API：** -- Sensor 值通过 atomicAdd 累加，跟力一样每步清零、host 累积、除以步数 -- 所以旧 `obs` 中的 sensor = **每步平均速度** - -**新 API：** -- SensorKernel 用 atomicAdd 累加 `ux, uy` 到 `obs_gpu` 的 sensor 段 -- `read_sensor(id, normalize=True)` 除以 `sensor_cell_counts[body_id]` （该 sensor 覆盖的格子数） -- **但没有除以步数！** - -```python -# 新 API 读取 sensor： -# read_sensor(id) = (sum_{steps} sum_{cells} ux) / cell_count -# 要得到每步平均 = read_sensor(id) / N +```text +Re_code = U0 · (2D) / ν +Re_D = U0 · D / ν = Re_code / 2 ``` -**所以旧 → 新转换：** -```python -# 旧环境： -# flow_field.run(SAMPLE_INTERVAL, action) -# obs = flow_field.obs # 已经是每步平均 +以 `U0=0.01, D=L0=20, ν=0.004` 为例：`Re_code=100`，但单圆柱直径定义为 `Re_D=50`。因此 `d1a3o12_re100` 不能写成“Re_D=100”。任何跨目录比较必须同时记录 `Re_code`、`Re_D`、`U0`、`D` 和 `ν`，不能只抄文件名。 -# 新环境等效： -# sim.bodies.zero_force_segment_async(stream) -# sim.bodies.zero_sensor_segment_async(stream) -# sim.run(SAMPLE_INTERVAL) # 或 stepper.step(SAMPLE_INTERVAL) -# fx_per_step = sim.read_force(id)[0] / SAMPLE_INTERVAL -# fy_per_step = sim.read_force(id)[1] / SAMPLE_INTERVAL -# ux_per_step = sim.read_sensor(id)[0] / SAMPLE_INTERVAL -# uy_per_step = sim.read_sensor(id)[1] / SAMPLE_INTERVAL +### 2.2 场景用途与历史参数 + +- **Steady cloak**：均匀来流中的开环/上下游稳态隐身基线；`SI=800`，`CONV_LEN=30`，scale `8`，bias `[0,-5.1,+5.1]`。 +- **Karman cloak**：上游扰流圆柱产生涡街，控制 pinball 使下游传感器接近“有扰流圆柱、无 pinball”的目标；`SI=800`，`CONV_LEN=30`，scale `8`，bias `[0,-4,+4]`。 +- **Erase**：历史目标是把扰流尾迹向干净入口流状态“抹除”；`SI=600`，`CONV_LEN=36`，scale `8`，bias `[0,-8,+8]`。其滚动受控力历史/目标映射特殊，只有具备完整场景证据的入口才能声称支持。 +- **Illusion**：均匀来流中控制 pinball，使下游信号模仿指定半径目标圆柱；scale `8`，bias `[0,-2,+2]`，`CONV_LEN=36`。历史 `0.75L/1L/1.5L` 的 SI 分别为 `400/600/800`。 +- **Vortex Lamb/Taylor**：在保存的背景场上注入瞬态 Lamb dipole 或 Taylor vortex 后控制；`SI=800`，`CONV_LEN=30`，scale `4`，bias `[0,-4,+4]`，历史控制长度 150 区间。 +- **Reduced observation**：Karman 任务的 12→9→5→3→2 维观测消融，不是新的物理场景。 + +所有 bias/scale 先形成 Legacy 切向表面速度： + +```text +surface_vel = (normalized_action × scale + bias) × U0 ``` -### 3.3 Obs 布局对比 +Illusion 的历史 FIFO 初始化可使用 `[0,-1,+1]×U0`，而策略映射 bias 为 `[0,-2,+2]×U0`；不能把两者合并。具体 artifact 的 scene config 高于通用默认值。 -**旧 API obs 数组（以 cloak env 为例，7 个 objects）:** -``` -obs[0:6] = sensor0_ux, sensor0_uy, sensor1_ux, sensor1_uy, sensor2_ux, sensor2_uy -obs[6:12] = cylinder0_fx, cylinder0_fy, cylinder1_fx, cylinder1_fy, cylinder2_fx, cylinder2_fy -obs[12:14] = dist_cylinder_fx, dist_cylinder_fy (扰流圆柱) -``` -objects 添加顺序：传感器 → 圆柱体。obs 是先 sensor 段（6个值），后 cylinder 段（每个 cyL 2 个值）。 +### 2.3 对象、动作、body 与观测顺序 -**新 API：** -- `sim.read_force(body_id)` → `[fx, fy]` 按 body_id 读取 -- `sim.read_sensor(body_id)` → `[ux, uy]` 按 body_id 读取 -- `sim.read_torque(body_id)` → `[tz]` 按 body_id 读取 +顺序是策略 contract，不是展示偏好。canonical 控制体顺序为：`front, upper(+y), lower(-y)`。 -### 3.4 Checkpoint/恢复 +**Karman（7 objects）** -**旧 API：** -```python -flow_field.get_ddf() # host ← gpu -flow_field.save_ddf() # 保存到 host 内存 -flow_field.restore_ddf() # host 内存恢复 -flow_field.apply_ddf() # host → gpu +```text +添加/body 顺序：dist_cyl(0), sensor_upper(1), sensor_center(2), sensor_lower(3), + front(4), upper(5), lower(6) +Legacy raw obs： [dist_fx, dist_fy, 6 sensor channels, 6 controlled-force channels] +策略 raw slice：obs[2:14] +策略归一化顺序：[front/upper/lower forces(6), sensors upper/center/lower(6)] +动作槽：action[0:3] → body 4/5/6 → front/upper/lower ``` -**新 API：** -```python -sim.snapshot() # 内存快照 -sim.restore() # 恢复 -# 或 -sim.save_checkpoint(path) # HDF5 文件 -sim.load_checkpoint(path) # 从文件恢复 +**Illusion/Vortex（6 objects）** + +```text +添加/body 顺序：sensor_upper(0), sensor_center(1), sensor_lower(2), + front(3), upper(4), lower(5) +Legacy raw obs： [6 sensor channels, 6 controlled-force channels] +策略归一化顺序：[front/upper/lower forces(6), sensors upper/center/lower(6)] +Illusion 14D：上述 12D 后追加 target_cd, target_cl +动作槽：action[0:3] → body 3/4/5 → front/upper/lower ``` -### 3.5 动作施加方式 +旧 `FlowField.run()` 接收按 object slot 打包的数组；sensor slot 不等于策略动作。迁移时必须用 impulse/order test 证明策略 action 0/1/2 实际驱动 front/upper/lower，不能根据变量名猜测。 -**旧 API：** -```python -# 全部 action 打包成一个数组，按 object 顺序排列 -action_array = np.zeros(n_objects, dtype=DATA_TYPE) -action_array[4:7] = ... # 圆柱体的 omega 值 -flow_field.run(N, action_array) -# 内部有指数平滑：action_pinned = (1-weight)*action_pinned + weight*action_target +### 2.4 Legacy telemetry、norm、FIFO、EMA 与 reset + +Legacy 控制区间内，force 和 sensor 对每个 lattice step 累加，公开 interval observation 再按步数平均。关键差别是 Legacy sensor 保留 footprint 内的 cell sum，不做现代 API 的面积平均。 + +历史 norm 公式： + +```text +force_norm_fact = 6 × max(abs(controlled forces)) +sens_deviation[i] = mean(sensor_i) +sens_norm_fact[i] = 5 × max(abs(sensor_i - sens_deviation[i])) ``` -**新 API：** -```python -sim.set_body(body_id, omega=value) # 每个圆柱体单独设置 -sim.run(N) -# 没有内置动作平滑（通过 ActionSmoother 可以实现） +完整初始化/reset contract： + +1. 稳定背景/场景，在定义的边界保存 DDF 状态。 +2. 以零动作采集 `FIFO_LEN=150` 个控制区间并计算诊断 norm。 +3. 恢复保存状态；按场景 FIFO init action 采集保存 FIFO。 +4. 历史策略推理使用训练时冻结 norm；重新计算 norm 只用于诊断和 reset FIFO，不能替换冻结 norm。 +5. `FlowField.run()` 内部动作 EMA 为 `pinned = 0.9*pinned + 0.1*target`。当前 Legacy reproduction adapter 在每个公开 interval 前将 host action seed 清零，以复现 pre-persistence driver contract，同时保留 interval 内 EMA；不得再叠加第二个外部 EMA。 +6. reset 必须同时恢复 DDF、保存 FIFO、策略可见初始 observation（当前 reproduction contract 为精确零）以及场景规定的动作/时钟状态。 + +若研究需要可重复的中途分支，而非普通 episode reset，仅保存一个 DDF 不够。Legacy 的 `full_state_checkpoint()`/`restore_full_state()` 会绑定双 ping-pong DDF、action、last effective action、raw/boundary observation 和 solver clocks；证据入口见 [Legacy driver](../LegacyCelerisLab/driver.py)。 + +### 2.5 `uni_test.ipynb` 的历史角色 + +`uni_test.ipynb` 曾是连续视频/演示编排器：加载模型和 DummyEnv，录制 steady、Karman、Illusion、Lamb/Taylor 目标，采集各场景 norm/FIFO，恢复 DDF，确定性推理，动作渐入/淡出，保存 Tecplot 场并合成视频。 + +它的价值是保存历史执行顺序和场景切换知识；它不是现代 V5 的 canonical 训练入口、评估 manifest 或科学权威。现代 V5 应使用 train/eval README 所声明的入口与 artifact contract。 + +### 2.6 Illusion “2U” 更正与 SI 差异 + +`2U` 表示 `S_DIM=14` 中额外的两个目标力维度 `target_cd,target_cl`，**不表示入口速度是 2×U0**。这些模型仍使用 `U0=0.01`： + +- `..._075L_2U_400S`：`SI=400` +- `..._1L_2U_600S`：`SI=600` +- `..._15L_2U`：无 S 后缀，历史默认 `SI=800` + +现代 V5 registry 的 SI 不相同：当前 `ill_075L=1100`，`ill_1L/ill_15L/ill_2L=1200`。因此现代 native Illusion 与 Legacy Illusion 即使 case 名相似，也不是相同 interval contract。 + +## 3. 当前 CelerisLab V5 contract + +### 3.1 telemetry：已纠正的当前语义 + +`Simulation.run(steps, zero_obs=True)` 默认在该批次前清零 force/torque/sensor 累积区并重置内部累计步数；`zero_obs=False` 可跨多次 run 累积。完成下载并同步后： + +- `read_force(id, normalize=True)`：GPU 累积力除以自上次清零以来累计的 lattice steps，返回**每步平均力**。 +- `read_sensor(id, normalize=True)`：先除 sensor footprint cell count，再除累计 lattice steps，返回**每步、面积平均速度**。 +- 所以使用默认 `normalize=True` 时，**禁止再除以 `SAMPLE_INTERVAL/SI`**；再次除法会引入错误的 `1/SI`。 +- 为构造 Legacy-equivalent sensor，可在几何和 cell-count 已验证时使用 `legacy_sensor ≈ modern_sensor × sensor_cell_count`；历史半径 5 footprint 曾验证为 78 cells，不能把 `78` 当作任意几何/版本常数。 + +`normalize=False` 的当前源码意图是：force 返回未做时间归一化的 GPU 累积和；sensor 仍会做面积归一化，但不做时间归一化。**迁移研究不得仅凭该描述推断跨版本 raw 等价**：每个目标 commit/config/GPU 路径都应通过 `raw == normalized × accumulated_steps`（sensor 在相同 area convention 下）及清零/跨-run 累积测试显式验证。特别是低层 `bodies.read_*`、自定义 `zero_obs`、异步下载路径不能默认继承高层调用时序。 + +当前实现与测试证据： + +- [ObjectManager telemetry implementation](../CelerisLab/src/CelerisLab/body/manager.py) +- [Unified observation integration tests](../CelerisLab/tests/integration/test_unified_obs.py) +- [CelerisLab public API](../CelerisLab/README.md) + +### 3.2 动作单位：表面速度与角速度 + +Legacy action 是圆柱表面切向速度，现代 `set_body(id, omega=...)` 是角速度。两者都采用 lower-origin、y-up 坐标： + +```text +Legacy: Uw = -surface_vel × ry/R, Vw = surface_vel × rx/R +Modern: Uw = -omega × ry, Vw = omega × rx +因此：omega = surface_vel/R ``` -### 3.6 数值错误检测 +正 `omega` 为逆时针；该方程对照下**不需要额外负号**。完整映射为： -**旧 API：** -```python -flow_field.has_numeric_error() -flow_field.last_error_flag +```text +omega = ((action_norm × scale + bias) × U0) / R ``` -**新 API：** -需要手动实现检查。 +例如 `R=10, U0=0.01` 时，Karman bias `[0,-4,+4]` 映射为 `[0,-0.004,+0.004]`。任何出现 `omega = -surface_vel/R` 的迁移实现都必须先用 wall-point velocity 和直接 solver test 重新证明，不能沿用旧的符号猜测。 ---- +### 3.3 原生 V5 calibration、policy 与 eval -## 4. 五种场景详解 +高层 contract 如下，细节以 [training README](drl_pinball/train/README.md) 和 [evaluation README](drl_pinball/eval/README.md) 为准： -### 4.1 Karman Cloak (模型名: d1a3o12_re系列) +- 训练 target 是匹配的 `calibration.json + target.npy`；Illusion 还需要匹配 harmonics，JSON 单独存在不构成完整 target。 +- 物理层先使用 CelerisLab area/time telemetry；环境再应用 `FORCE_SCALE/SENS_SCALE`；SB3 `VecNormalize` 是第三层在线 running statistics。 +- `native-v2` 不插入 Legacy `SENSOR_CC`；`legacy-policy-v1` 仅用于冻结历史模型的兼容加载。 +- best policy 必须与同一 best-selection 点的 best normalizer 配对。独立 eval 对 artifact 文件名有显式、fail-closed 的 case 规则。 +- eval 冻结 `VecNormalize(training=False, norm_reward=False)`，策略确定性运行 360 步，以后 180 步计分；GPU replay 不承诺 bitwise 一致。 +- resume 仅是 policy + matching normalizer continuation，不是 optimizer、RNG、CFD、wrapper 和 trajectory 的精确进程重放。 -**目标：** 上游 2D 扰流圆柱产生涡街，控制 pinball 使下游传感器信号跟无 pinball 时一致 +## 4. 已验证等价与已知不等价 -**几何布局：** -``` -上游扰流圆柱：x=10*L0, y=中心, r=L0 (=200, 240, 20) -Pinball前： x=30*L0, y=中心, r=L0/2 (=600, 240, 10) -Pinball下： x=31.3*L0, y=中心-0.75*L0, r=L0/2 (=626, 225, 10) -Pinball上： x=31.3*L0, y=中心+0.75*L0, r=L0/2 (=626, 255, 10) -Sensor上： x=40*L0, y=中心+2*L0, r=L0/4 (=800, 280, 5) -Sensor中： x=40*L0, y=中心, r=L0/4 (=800, 240, 5) -Sensor下： x=40*L0, y=中心-2*L0, r=L0/4 (=800, 200, 5) -``` +### 4.1 已验证或可机械证明的局部等价 -**目标信号:** 只有上游扰流圆柱（无 pinball）时，sensor 的时间序列 -**观测:** `forces[6]+sens[6]` = 6 个 force 值 + 6 个 sensor 值 = 12 维 -**动作缩放:** `action×8U₀ + [0, -4U₀, 4U₀]` (=0,0 代表 -4,4 的偏置动作) -**Reward:** `min(0.3×exp(-|Cd×20|) + 0.4×exp(-|Cl×80|) + 0.3×exp(-10×|sim-1|), 1.0)` -**SAMPLE_INTERVAL:** 800 -**CONV_LEN:** 30 -**检查点流程:** -1. 初始化只有扰流圆柱+3传感器的环境 → 运行稳定 → 记录150步目标信号 -2. 添加 pinball → 稳定 → 保存 DDF(无控制状态) -3. 用零动作运行 150 步 → 记录 obs 到 fifo → 计算 norm -4. 用预设动作(-4,4)运行 150 步 → 记录 obs → 保存 save_states -5. reset=恢复DDF + 恢复fifo +- `Re_D = Re_code/2`：在相同 `U0,D,ν` 定义下成立。 +- 当前 modern `normalize=True` force 与 Legacy interval force 都具有“每 lattice step 平均”层次；数值本身仍可能因 solver/geometry 不同而不等价。 +- Legacy/modern 旋转壁面方程给出 `omega=surface_vel/R`，同号、正值逆时针。 +- 固定 footprint 下，Legacy sensor cell-sum/step 与 modern area/time average 的单位桥为乘实际 cell count；半径 5 的历史配置曾测得 78。 +- canonical 控制顺序是 front/upper/lower，且 Karman body IDs 4/5/6、Illusion body IDs 3/4/5 已有 order tests。 +- modern in-memory `snapshot/restore` 当前覆盖场、solver step、body state/control、action 和 telemetry；body topology 必须不变。 -### 4.2 Erase (模型名: d1a3o12_250729_250326_erase系列) +### 4.2 已知非等价 -**目标：** 跟 Karman Cloak 场景基本一致，但目标是让下游流场恢复到"入口流状态"（干净来流），即抹除扰流圆柱尾迹 +- Legacy 与 modern 是不同 LBM 实现；迁移策略下的尾迹、力方差、相位和闭环轨迹不保证相同。 +- Legacy 常用 1280×512 网格；native V5 是 2000×600。Karman/Illusion 的绝对位置、中心线（现代 `y=299.5`）、入口/壁面/出口配置也可能改变。 +- Legacy sensor 是 cell-sum/step；modern sensor 是 area-average/step。 +- Legacy action 输入是 surface velocity；modern action输入是 angular velocity。 +- Legacy interval EMA/host-action seed contract 与 modern 用户态 smoother 不天然相同。 +- Legacy Illusion SI `400/600/800` 与当前 native V5 `1100/1200/1200/1200` 不同。 +- Legacy frozen norm 与 native calibration/VecNormalize 不是同一个统计对象。 +- 同名 target size 仍可能有半径/直径命名陷阱：现代 `target_diam` 历史上实际作为 `radius = target_diam×L0` 传入。 +- DDF snapshot 相等不代表完整 RL 状态相等；FIFO、外部 EMA、reward EMA、target phase、current step、VecNormalize、policy/optimizer/RNG 都可能在求解器外。 -**关键区别：** -- 目标信号 = 入口均匀流的均值（基本为零方差） -- Reward 主要看传感器与均值的偏差 -- **这是未完全实现的部分** -- 动作缩放: `×8U₀ + [0, -8U₀, 8U₀]` +## 5. checkpoint 与 full-state 要求 -### 4.3 Illusion (模型名: d1a3o14_250525_imit系列) +按用途分级保存，禁止把较低级别称为“精确恢复”： -**目标：** 上游干净来流，控制 pinball 使其下游流场跟指定直径的单个圆柱一致 +1. **场恢复**：双 DDF/ping-pong 状态、flags、solver step 与完全匹配的 config/precision/topology。 +2. **环境 reset**：场恢复 + body action/control + telemetry accumulator + FIFO/save_states + action smoother + reward EMA + target phase/current step。 +3. **策略推理复现**：环境 reset + policy + 同点 normalizer + calibration/target/harmonics + case registry/provenance + deterministic flags。 +4. **训练精确续跑**：再加 optimizer、scheduler、所有 RNG、rollout buffer、wrapper/process state；当前 V5 README 明确不承诺这一层。 -**几何差异：** -- 没有上游扰流圆柱 -- 目标圆柱位置不同（x=20*L0 或 x=31*L0，取决于场景） -- Sensor 位置可能调整（x=30*L0 而不是 40×L0，为了贴近目标圆柱等效距离） -- 目标信号通过 harmonics 分析（FFT 提取频域特征）进行重构 +modern `snapshot/restore` 适合内存内环境 reset，但外部 Python 状态仍须由 env 同步保存。HDF5 `save_checkpoint/load_checkpoint` 当前保存 DDF、temp、flags、step、config metadata 和 object states；在把它称为完整 RL/full-state checkpoint 前，必须额外证明 action buffer、telemetry accumulator、FIFO/EMA/normalizer 等均被恢复。 -**观测:** 12 维 (forces) + 2 维 (target_cd, target_cl) = 14 维 -**Reward:** `min(0.3×exp(-|(Cd-Cd_target)×10|) + 0.3×exp(-|(Cl-Cl_target)×10|) + 0.4×exp(-10×|sim-1|), 1.0)` -- 力的比较是和目标圆柱的谐波重构值比较 +## 6. 几何、版本与证据 caveat -**IMPORTANT CORRECTION (2026-06-12):** "2U" in model name means S_DIM=14 (2 extra target force dimensions), NOT 2x velocity. ALL models train with u0=0.01. SAMPLE_INTERVAL varies by diameter: -- 0.75L: `..._075L_2U_400S` → S=400 -- 1.0L: `..._1L_2U_600S` → S=600 -- 1.5L: `..._15L_2U` → no S suffix = default S=800 -- nu=0.004 for all (no Vis suffix = default) — confirmed via sweep +- 每次运行记录：git commit、solver version、CUDA/GPU、config SHA256、geometry/body ledger、object IDs、`U0/ν/L0/R`、`Re_code/Re_D`、SI、cell count、动作公式、obs 切片、normalizer/target/model hashes。 +- grid size 相同只说明数组尺寸相同，不证明几何、边界条件、碰撞模型、streaming、DDF shifting、精度或动力学相同。 +- body center/radius、upper/lower 符号和动作数组必须在运行前打印；文件名、图例和记忆不能覆盖直接 source equation 或 reversal CFD。 +- `SENSOR_CC=78` 只对已验证 footprint 成立；几何、离散化或版本改变后重测。 +- `normalize=False`、异步路径和 checkpoint compatibility 均按目标 commit 重新验证，不能由旧 API 文档外推。 -### 4.4 Vortex (模型名: vortex_lamb / vortex_taylor) +推荐的测试/证据路径： -**目标：** 在初始流场中加入涡量（Lamb dipole 或 Taylor vortex），控制 pinball 使下游信号跟无 pinball 时一致 +- Legacy contract 与 reset/order：[`drl_pinball/legacy_test/tests/`](drl_pinball/legacy_test/tests/) +- SR Legacy order/Re/SI：[`SR_analysis/tests/test_legacy_contracts.py`](SR_analysis/tests/test_legacy_contracts.py) +- modern telemetry：[`../CelerisLab/tests/integration/test_unified_obs.py`](../CelerisLab/tests/integration/test_unified_obs.py) +- modern body sync：[`../CelerisLab/tests/integration/test_body_sync_e2e.py`](../CelerisLab/tests/integration/test_body_sync_e2e.py) +- native normalization schema：[`drl_pinball/train/tests/test_normalization_schema.py`](drl_pinball/train/tests/test_normalization_schema.py) +- eval compatibility：[`../tests/test_drl_pinball_infer_train.py`](../tests/test_drl_pinball_infer_train.py) +- Legacy→modern 归档比较器：[`drl_pinball/eval/archive/compare_legacy_v5.py`](drl_pinball/eval/archive/compare_legacy_v5.py) -**关键特征：** -- 要正确使用 `add_vortex` 进行初始化 -- Dipole (Lamb) 强度较大 (0.5*U0)，Monopole (Taylor) 强度较小 (0.03*U0) -- Vortex 在保存 DDF 之后添加，随流场演化 -- 有 `MAX_STEPS=150` 的终止条件（因为是 transient 事件） -- 动作缩放: `×4U₀ + [0, -4U₀, 4U₀]` -- Reward: `min(0.2×exp(-|Cd×20|) + 0.3×exp(-|Cl×80|) + 0.5×exp(-10×|sim-1|), 1.0)` +## 7. 最后验证与来源权威规则 -### 4.5 Reduced Obs (模型名: d1a3o12_250421系列) +发生冲突时按以下顺序裁决，并记录裁决日期： -**目标：** 同 Karman Cloak，但逐步减少观测维度 -**观测:** 从 12 → 9 → 5 → 3 → 2 递减，观察模型是否能适应 +1. 目标 commit 上的直接 kernel/source equation 与最小可重复 runtime test。 +2. 与该 commit/config/artifact hash 绑定的集成测试和生成 provenance。 +3. scene registry、训练/评估 README 与设计决策文档。 +4. 本账本和归档迁移报告。 +5. notebook、文件名、图例、口头记忆。 ---- +“最后验证”必须说明验证了哪个 commit、哪个 config、哪个 GPU 路径和哪一种 normalize/reset 调用；只写日期不够。未验证项应 fail closed，不得用看似合理的转换自动补全。 -## 5. Norm 采集过程（关键！） +## 8. 历史重写提案状态 -**所有旧环境共有的模式：** - -```python -# 环境初始化最后阶段： - -# Step 1: 用零动作运行 FIFO_LEN 步，记录 obs -for i in range(FIFO_LEN): - flow_field.run(SAMPLE_INTERVAL, zero_action) - fifo_states.append(flow_field.obs[sensor_select]) - -# Step 2: 从 fifo 计算 norm -temp_states = np.array(fifo_states) -force_norm_fact = 6 * max(|forces|) # 力归一化因子 -for i in range(6): - sens_deviation[i] = mean(sensor[i]) # 均值 - sens_norm_fact[i] = 5 * max(|sensor[i] - mean|) # 波动范围×5 - -# Step 3: 恢复 DDF，用预设动作运行 FIFO_LEN 步 -flow_field.apply_ddf() -for i in range(FIFO_LEN): - flow_field.run(SAMPLE_INTERVAL, init_action) - fifo_states.append(...) -save_states = fifo_states.copy() -``` - -这个 norm 值是**模型训练时就固化**的，**推理时也必须使用完全相同的值**。旧版环境在初始化时自动计算，新环境需要为每个场景预计算和存储这些 norm 值。 - ---- - -## 6. uni_test.ipynb 流程解析 (最重要参考) - -这个 notebook 是一个连续的、视频式展示，包含以下序列： - -### Phase 0: 初始化和元数据采集 -1. 加载所有模型 -2. 创建 DummyEnv 用于加载模型（只是一个匹配 obs/action space 的空壳） -3. 设置 CUDA context，创建 `FlowField` -4. 设置 `meta_*` 对象存储 norm 值 - -### Phase 1: 目标信号录制 -1. **Steady 目标**：3 sensors × 150步 → 记录时序均值（干净来流） -2. **Dipole (Lamb)** 目标：restore DDF → add_vortex Lamb → 150步 → 记录 -3. **Monopole (Taylor)** 目标：restore DDF → add_vortex Taylor → 150步 → 记录 -4. **Illusion 目标**（1.0L 圆柱）：新 FlowField → 单圆柱 x=31*L0, r=1*L0 → 3 sensors → 150步 × 800 采样 → 记录 8 维 obs + harmonics 分析 -5. **Illusion 目标**（0.75L 圆柱）：类似，SAMPLE_INTERVAL=400 -6. **Illusion 目标**（1.5L 圆柱）：类似，SAMPLE_INTERVAL=800 -7. **Karman 目标信号**：pinball 恢复 + 扰流圆柱 → 3 sensors → 150步 × 800 采样 → 记录 sensor+force obs - -### Phase 2: Pinball + Norm 采集 -- 创建 pinball → 运行到稳定 → save DDF -- 零动作 150步 → 计算 norm -- 预设动作 150步 → 记录 save_states - -### Phase 3: Norm 采集（各个场景） -- 跟 Phase 2 类似，但针对各个特定场景恢复 DDF 后分别采集 norm - -### Phase 4: 推理运行（控制演示序列） -1. **No Control (nc)** 基线：加载 pinball DDF → 零动作 100步 × 1000采样 → 保存场 -2. **Steady Cloaking**: 从 nc 继续 → 逐步切换到 cloak 动作（75步渐入+保持） -3. **Dipole Cloaking**: restore DDF → add Lamb vortex → 用 cloak_lamb 模型推理 → 25步渐入/25步淡出 → 保存场 -4. **Monopole Cloaking**: restore DDF → add Taylor vortex → 用 cloak_taylor 模型推理 → 类似渐入淡出 -5. **Illusion (1L)**: restore DDF → 用 illusion_1L 模型推理 → 10步渐入 → 200步保持 -6. **Illusion (0.75L)**: 类似 -7. **Illusion (1.5L)**: 类似 -8. **Karman NC + Cloak**: restore Karman场景DDF → 200步无控制 → 切换到 cloak_re100 模型推理 -9. **Frame 合成 → ffmpeg 视频** - -关键点： -- **场景间过渡**通过 `restore/apply DDF` 实现 -- **动作渐入/淡出**用 `linear interpolation in action space` -- 场数据存在 `.dat` 文件（Tecplot格式），用 `save_field()` 保存 -- 所有推理都用 `deterministic=True` - ---- - -## 7. 旧 API 动作数组的索引规则 - -旧 `FlowField.run()` 的 `action_target` 数组按 object 添加顺序排列： - -``` -| Sensors 的 action slot | Cylinders 的 action slot | -| sensor0, sensor1, ... | cylinder0, cylinder1, ... | -``` - -每个 object 的 action slot 有 3×DIM 个值（DIM=2 时=6），但 LBM 中 sensor 只用第一个值（实际上被忽略），cylinder 用最后一个值（omega）。 - -``` -action[0] = sensor0 (ignored) -action[1] = sensor0 (ignored) -action[2] = sensor0 (ignored) -action[3] = sensor1 (ignored) -action[4] = sensor1 (ignored) ← 对于 cloak env，这里放 cylinder0 的 omega -action[5] = sensor1 (ignored) -action[6] = cylinder0 omega (disturbance cylinder for cloak) -action[7] = cylinder1 omega (front pinball) ← 注意！对象索引顺序取决于添加顺序 -``` - -实际各环境设置 action 的方式： -```python -# cloak env (7 objects: 3 sensors + 1 dist_cyl + 3 pinball): -temp = np.zeros(7, dtype=DATA_TYPE) -temp[4:7] = (action*8 + [0,-4,4]) * U0 # action[4]=front omega, [5]=bottom, [6]=top - -# erase env: -temp[4:7] = (action*8 + [0,-8,8]) * U0 - -# imit env (6 objects: 3 sensors + 3 pinball): -temp[3:6] = (action*8 + [0,-2,2]) * U0 - -# vortex env: -temp[3:6] = (action*4 + [0,-4,4]) * U0 -``` - -注意 `temp[4:7]` 是从 index 4 开始取 3 个值。这是因为添加顺序是： -1. sensor0 (id=0) -2. sensor1 (id=1) -3. sensor2 (id=2) -4. dist_cylinder (id=3) — 旧 env 里添加上游扰流圆柱后固定为 0 -5. pinball_front (id=4) -6. pinball_bottom (id=5) -7. pinball_top (id=6) - ---- - -## 8. 重写注意事项 - -### 8.1 力和传感器的归一化 -因为新 API 返回的是 N 步累积值（需要除以步数），所以 norm 的物理含义需要重新标定。 - -### 8.2 动作缩放关系 -旧环境动作缩放矩阵（从归一化 [-1,1] action 到物理 U0 倍数的 omega）： - -| 场景 | 公式 (θ=action) | 物理范围 | -|------|----------------|---------| -| Cloak | `action×8 + [0,-4,4]` | front: [-8,8], bottom:[-12,4], top:[-4,12] | -| Erase | `action×8 + [0,-8,8]` | front: [-8,8], bottom:[-16,0], top:[0,16] | -| Illusion | `action×8 + [0,-2,2]` | front: [-8,8], bottom:[-10,6], top:[-6,10] | -| Vortex | `action×4 + [0,-4,4]` | front: [-4,4], bottom:[-8,0], top:[0,8] | - -然后乘以 U0=0.01 得到实际的晶格 omega 值。 - -### 8.3 边界条件 -旧配置是 parabolic inlet + no-slip walls（因为 legacy solver 不支持 free-slip） -新 pinball 配置是 parabolic inlet + **bounce_back** walls（即 no-slip，跟旧版一致） -注意新配置 `config_lbm_pinball.json` 的 `y_wall_bc` 是 `bounce_back`，验证配置 `run_kan99b` 是 `free_slip`，要统一。 - -### 8.4 重写策略 -1. **base_env.py**: 封装共享逻辑（Simulation 创建、几何布局、checkpoint 管理、norm 存储、DTW 工具） -2. **每个场景继承 base_env**: 只覆盖 reward、目标信号、动作缩放 -3. **train/*.py**: 跟旧版一致的 PPO 训练循环（Sin 激活、SB3 PPO、TensorBoard） -4. **eval/*.py**: 推理脚本，对应 uni_test 功能，用配置文件驱动场景序列 -5. **configs/**: 存储每个场景的 norm 值、几何参数、采样参数 -6. **models/**: 从旧版复制训练好的 .zip 模型（在新 API 推理中使用） - -### 8.5 与旧环境的数值一致性验证方法 -新环境在完全实现后，必须用旧训练好的模型在新 env 上跑推理，对比： -- 传感器时序信号（旧 `obs` vs 新 `read_sensor/SAMPLE_INTERVAL`） -- 力信号（旧 `obs` vs 新 `read_force/SAMPLE_INTERVAL`） -- 场数据（旧 `save_field` vs 新 `get_macroscopic`） +旧版“未来重写 base_env、逐场景继承、复制模型、再做等价验证”的提案已于 V5 train/eval 与 compatibility lanes 建立后作为**已完成的历史设计阶段**关闭。它不是当前开放 roadmap，也不授权继续把 Legacy 迁移结果包装成原生 V5 科学结果。后续变更应分别进入 L1、L2 或 L3，并遵守各 lane 的证据边界。