DynamisLab/src/SR_analysis/sr_legacy_pipeline_bf1c2e74.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
SR Legacy Pipeline	冻结当前 legacy 证据后，修复并版本化 Kármán 与 Illusion 的 Stage 1–3 数据、特征、公式和闭环契约；第一轮只在四个 Kármán 训练 Re 与 Illusion 0.75L/1L 上完成端到端复现并暂停复核。DTW 闭环是公式选择的最终判据，离线指标仅用于排查时序错位、共线性和部署不一致。	id content status snapshot-baseline 创建 SR 专用 Git 快照并记录 ignored 数据、模型和环境资产清单 pending id content status freeze-contracts 统一 legacy 场景、layout、无量纲化、G 映射和 DTW 契约 pending id content status repair-stage1 修复并版本化 Kármán/Illusion Stage 1 数据与因果时序 pending id content status unify-features 实现 Stage 2/3 共用的 stateful 特征和导数计算 pending id content status repair-stage2 实现可复现的 joint front/rear PySR 拟合与公式 schema pending id content status repair-stage3 实现公式/G 部署、versioned DTW 与完整 validation provenance pending id content status run-round1 在指定 Conda 环境和 GPU 2 完成第一轮 legacy Stage 1–3 复跑 pending id content status review-candidates 审计历史与 candidate 结果并暂停等待 canonical 晋升决定 pending	false

SR Legacy 端到端完善计划

范围与原则

• 主体系冻结为 legacy；V5、erase、unseen-Re、Vortex、1.5L、论文绘图均不进入第一轮验收。
• CFD、PPO 推理与闭环统一使用 pycuda_3_10 和 GPU 2；PySR/SINDy 使用 sr_env。
• 所有新数据、公式和 validation 先写入带 run_id 的 staging 目录，不覆盖现有 data/ 与 results/ canonical 文件。
• 离线拟合的 (R^2)、MAE 等只作为数据/模型诊断；公式取舍以 legacy DTW 闭环结果为最终标准。legacy DTW 固定为独立版本，不混用 V5 的 target-amplitude normalization。
• observation、action、force 均使用实际物理无量纲量；明确 legacy action 是圆柱表面切向速度，统一定义 (\alpha=u_{wall}/U_0)。
• G 映射作为结构约束：front 为 odd channel，upper/lower 交换并反号；新公式必须记录 rear shared-head 的 anchor 和镜像构造。

flowchart LR
    snapshot["Git快照与资产清单"] --> contracts["冻结数据和物理契约"]
    contracts --> infer["Stage1 PPO推理"]
    infer --> fit["Stage2 PySR拟合"]
    fit --> deploy["Stage3 CFD闭环"]
    deploy --> review["结果审计与人工复核"]
    review -->|"通过后"| promote["晋升canonical"]
    review -->|"不通过"| diagnose["时序或公式诊断"]

第一阶段：冻结当前状态与建立可回滚基线

• 按用户选择先创建一个专用 Git 快照提交；提交前按 Git 协议核对完整 status、diff 和近期提交，只纳入当前 SR 工作及明确相关文件，不混入其他模块的无关改动。
• 记录当前 commit、工作树状态、Conda/Python/PySR/Julia/CUDA/GPU 信息，以及 legacy 模型最终解析路径。
• 为 ignored 的 NPZ 和 PPO 模型生成只读资产清单：路径、大小、SHA-256、NPZ keys/shape/dtype。Git 快照本身不能恢复 ignored 数据，因此第一轮脚本必须禁止覆盖这些文件；资产清单用于检测意外变化。
• 将现有 scene_registry.json、results/README.md、formula 和 validation 标记为 historical_frozen，不立即判断 0.978/0.970 与 0.982/0.958 哪组为最终 canonical。

第二阶段：冻结跨 Stage 的唯一契约

场景与数据契约

• 在 configs.py 集中定义 Kármán/Illusion 的：几何、目标位置、Re_code 与 Re_D、SI、(dt_c=SI/(D/U_0)=SI/2000)、动作 decoder、FIFO 初始动作、sensor/force/action layout、target slices。
• 保持 legacy 物理定义与数值：Re_code=2Re_D；论文输出可以转换成 Re_D，文件名和模型名继续保留 code Re。
• 明确 Illusion target 契约为 [target_fx,target_fy, six_sensor_channels]，传感器比较使用 [:,2:8]，策略目标力使用 [:,0:2]。
• 先核对真实 native body order，不直接交换历史 NPZ 列；新数据写显式 layout metadata，内部统一使用 front/upper/lower，旧 top/bottom 名称通过兼容映射读取。

物理特征与 G 映射

• 收敛 feature_builder.py 与 g_operator.py 的重复实现，使所有 Stage 调用同一个 G 和无量纲化入口。
• 增加 G(G(x))=x、target drag even/target lift odd、rear shared-head equivariance 测试。
• 缺失 required feature 时默认报错，禁止再由 build_feature_matrix 静默补零；仅历史兼容读取可显式选择零填充。

legacy DTW

• 在 cfd_interface.py 中固定 scene-specific metric：legacy_dtw_v1_abs_n_unclipped，明确 lag channel、target slice、window、无幅值归一化、无 clipping。
• 文档明确 legacy 与 V5 DTW 不直接混用；第一轮不改变历史算法。

第三阶段：修复 Stage 1 并隔离运行产物

• 修改 stage_1_infer.py 使路径不依赖 cwd，配置 dry-run 能在不启动 CUDA 时完成模型、target、norm 和输出路径检查。
• 修复 Illusion 的目标位置配置、target force 索引和 controlled.npz 中 target_forces 缺失；首步 observation、target harmonic phase 与已验证 legacy 测试保持一致。
• 明确数据采集时序并写入 metadata：哪个 observation 是 action 执行前或执行后、target phase index、action command index。先以旧推理循环和 legacy test 为事实依据，不凭数组同名假设对齐。
• 新 NPZ 同时保存 schema/version、layout、SI、(dt_c)、normalization source、model hash 和 alignment；保留旧 key alias 只用于兼容。
• Stage 1 只写 data/runs/<run_id>/...；没有显式 promotion 时拒绝覆盖历史数据。

第四阶段：让离线与在线特征严格一致

• 建立 stateful feature state，统一保存 previous observation、previous target force、previous actions 和 (dt_c)。
• 在真实 legacy 数据上比较两种主要 alignment：当前同行 (X_t\to a_t) 与按控制循环推导的 (X_t\to a_{t+1})。这一步是契约审计，不用较高 (R^2) 自动决定正确性；最终采用与 PPO 决策时刻一致的因果定义。
• 对同一 trajectory 验证：Stage 2 批量计算与 Stage 3 逐步计算的每个 required feature 数值一致；包含 du_a_dt、dCl_tot_dt、dCd_err_dt 和 action derivative。
• 将 alignment、导数定义和丢弃的初始样本数写入 formula metadata，避免未来再次产生“拟合公式与部署公式语义不同”。

第五阶段：修复 Stage 2 的双头拟合与公式记录

• 修改 stage_2_fit.py，使 per-scene 和 joint 都生成：
  • front head；
  • rear shared head；另一个 rear action 由 Stage 3 通过 G 构造。
• 统一 formula JSON schema，兼容读取旧 feature_names/feature_keys 与 best_sympy，新写出至少包含：training scenes、feature order/definitions、fitted expression、deployment expression、role/anchor、G version、data hashes、alignment、(dt_c)、PySR seed/operators/complexity、in-sample diagnostics。
• 固定 PySR seed并提供极短 smoke 参数；候选公式写入 results/runs/<run_id>/formulas/，不覆盖现有 formula。
• 对 Kármán 同时保留：
  • fitted expression；
  • 人工物理审计后的 deployment expression，例如删除部署时恒零/共线产生的 daB_dt 项。 二者必须分别带 hash，禁止用一个公式的 DTW 给另一个公式背书。
• SINDy/STLSQ 第一轮只作为内部筛选诊断：检查 feature 共线、lag 与支持稳定性，不作为闭环候选的自动裁决，也不写成正文核心方法。

第六阶段：修复 Stage 3 的真实部署

• 修改 stage_3_validate.py，使用统一 formula loader：有 symbolic expression 时直接编译，只有明确 linear schema 时才读取 coefficient；禁止缺 coefficient 时默认为全零。
• 使用与 Stage 2 完全相同的 stateful feature builder 和 (dt_c)，并按 formula metadata 构造 front 与 G-mirrored rear actions。
• Kármán和 Illusion 共享部署核心，只在 target-force/reference 和环境 builder 上分支。
• validation 文件按 scene、mode、formula hash 和 SI 独立命名，异常必须返回非零；不再让 PPO、SR、uncontrolled 或不同 SI 相互覆盖。
• 每个结果记录：formula/data/model hash、Git SHA、环境、scene config、metric version、n_steps、full/tail DTW、per-channel DTW、action range、NaN/Inf、termination reason 和原始 telemetry 路径。

第七阶段：分层运行与第一轮验收

无 GPU 与短 smoke

• 先运行 config/NPZ/formula schema、G、DTW fixture、batch-vs-step feature equivalence 测试。
• 在 sr_env 中用 Kármán Re100 小样本、极少 iterations 验证 PySR/Julia 启动、front/rear 双输出和 Stage 3 可读性。
• 在 pycuda_3_10 中确认 GPU 2 可用，再做 Kármán Re100 与 Illusion 1L 的最短 wiring smoke；短跑只检查 finite/actions/schema，不用 DTW 判断控制效果。

完整第一轮

按以下顺序运行，单场失败即停止批量扩展：

1. Kármán Re100 Stage 1→2→3；
2. Illusion 1L Stage 1→2→3；
3. Kármán code Re 50/100/200/400 joint fit 与闭环；
4. Illusion 0.75L+1L joint fit 与各自闭环。

验收条件：

• Stage 1 数据、Stage 2 formula 和 Stage 3 telemetry 均有完整 provenance；
• required features 无静默零填充，批量/在线特征一致，G 测试通过；
• 每个 formula 实际部署 expression 与 validation 中的 hash 一致；
• CFD 无 NaN/Inf 或动作异常；
• legacy DTW 可与历史结果并列比较。若结果改变，不以“必须复现旧数字”强行通过，而是通过 telemetry 定位是 target 修复、alignment 修复、导数修复还是公式变化造成；
• 第一轮结束后只生成审计报告和 candidate registry，不自动修改 canonical scene_registry.json。到此暂停，请用户复核后再决定晋升或继续机制分析。

后续阶段：第一轮复核后再启动

机制与公式项价值

• Kármán：uncontrolled、constant rear、front-only、full fitted law、reduced deployment law，比较总 DTW、ux/uy、drag/lift、控制功率。
• Illusion：target-force feedforward-only、feedback-only、error-only、phase hybrid、front-only、rear-only；重点检验当前 joint front 化简为 target_Cd + phase term 后是否只是周期轨道上的等价表示。
• 做受限 lag cross-correlation、coherence/cross-spectrum、delay embedding 和 target/observed quadrature phase；候选仍由 CFD DTW 裁决。
• 检查 Illusion PPO 与公式的完整 G-equivariance，特别是 target_Cd 为 even 而 front action 应为 odd 的结构冲突。

泛化与扩展

• 流程稳定后再补 unseen-Re；随后恢复 Kármán law 到 Lamb/Taylor 的专用 Vortex validator。
• 重采 1.5L trajectory，分析高频/phase-state 边界；不把 lagged-action 平凡解标为 canonical。
• 最后再引入 V5 数据、生成论文图、同步 README/registry/报告和写作。

文档与长期维护

• 更新 README.md、PIPELINE.md 与 Stage 文档，使命令、环境、GPU、schema 和实际代码一致。
• scene_registry 只索引 artifact ID/path/hash/run ID；formula 和 validation JSON 各自保存原始数值。README 与后续图表从 registry 自动生成，避免手工重复 0.978/0.970 等数字。
• 在 SR 根目录最终保存这份长期计划，并在每轮完成后更新状态、风险和下一验收点。