DCTS/docs/design.md

DCTS 物理计算与流程设计 (Physics Pipeline Design)

本文档阐述 DCTS 核心物理计算引擎的设计原理、TLUSTY/SYNSPEC 计算链（冷启动 / 种子步进）， 以及基于策略链（Strategy Chain）的回退机制与种子匹配算法。 阶段独立配置（enabled / policy / strategies）的完整设计见 task_engine_decoupling_design.md。

---

1. 物理计算链原理

TLUSTY 通过完全线性化 (Complete Linearization) 方法求解恒星大气结构的 NLTE（非局部热力学平衡）统计平衡方程与辐射转移方程。由于线性化的收敛半径有限，若初始猜想（初猜）偏离真解较远，迭代极易发生数值发散。

DCTS 把单点计算拆分为 TLUSTY 大气结构求解 + SYNSPEC 光谱合成两个独立阶段（各自有 enabled 开关）。TLUSTY 阶段内再按执行策略选用不同收敛链：

冷启动链 (ColdRun，default_cold_chain)：

flowchart LR
    Stage1["1. LTE 灰大气\n(lte / tlusty)\n解析灰色初猜"] --> Stage2["2. NLTE 连续谱\n(nc / tlusty)\n收敛电离平衡"]
    Stage2 --> Stage3["3. NLTE 完整谱线\n(nl / tlusty)\n包含线跃迁求解"]
    Stage3 --> Stage4["4. 合成光谱\n(synspec)\n输出 .spec / .cont"]

种子步进链 (SeedStep，default_seed_chain)：直接以近邻已收敛大气为热启动起点，跳过 lte 灰大气阶段：

flowchart LR
    Seed1["1. NLTE 连续谱热启动\n(seed_nc / tlusty)\n以种子 .7 作 fort.8 初猜"] --> Seed2["2. NLTE 完整谱线\n(nl / tlusty)\n精化收敛"]
    Seed2 --> Seed3["3. 合成光谱\n(synspec)"]

各阶段物理配置与功能明细

阶段配置见 common::runner::default_cold_chain / default_seed_chain（StageConfig）：

阶段	执行程序	物理含义	关键参数	迭代上限
1. LTE 灰大气 (lte)	tlusty.exe	解析灰色不透明度求解温度结构，无需种子，提供合理起点。	lte=T, ltgray=T, niter=0, ilvlin=0	0 次（生成初始结构）
2. NLTE 连续谱 (nc)	tlusty.exe	切换到 NLTE，忽略束缚-束缚线跃迁（ilvlin=0），收敛基础电离平衡。	lte=F, ltgray=F, ilvlin=0, niter=10	10 次
3. NLTE 完整谱线 (nl)	tlusty.exe	引入全部线跃迁（ilvlin=100），求解包含非平衡辐射场的大气结构；要求收敛（require_converged=true）。	lte=F, ltgray=F, ilvlin=100, niter=100	100 次
3'. 种子热启动 (seed_nc)	tlusty.exe	以近邻收敛大气 .7 为 fort.8 初猜做 NLTE 连续谱收敛（跳过低温度灰大气阶段）。	lte=F, ltgray=F, ilvlin=0, niter=20, ichang=0	20 次
4. 合成光谱 (synspec)	synspec.exe	基于收敛大气结构（.7），计算高分辨率合成光谱。	波长窗/展宽/截断由 synspec: 数值参数配置	—

阶段标签由 workflow 配置保证唯一（lte/nc/nl/seed_nc），各阶段输入卡/日志/大气/收敛诊断 以 <name>.<label>.<后缀> 快照落盘归档（见 tlusty_result_artifacts.md）。

---

2. 冷启动链 vs 种子步进链（策略链机制）

在极端高有效温度、极低氦丰度或强金属线空白区，从 LTE 灰大气直接启动的冷启动链容易发散。DCTS 通过 策略链 (Strategy Chain) 机制处理：工作流可配置 tlusty_strategies（如 ["cold_run", "seed_step"]），调度器按顺序派发，失败时弹出链首、以剩余链回退重试（见 task_engine_decoupling_design.md §4.2）。

flowchart TD
    Start([开始计算指定网格点]) --> Resolve[调度器解析策略链\nresolve_dispatchable_chain]
    Resolve --> Exec[执行链首策略]
    Exec --> Check{nl 阶段物理收敛?}
    Check -- "是 (Success)" --> RunSyn[运行 Synspec 生成光谱] --> Save[结果入库 & 汇报成功]
    Check -- "否 (失败)" --> Pop[服务端弹出链首策略\ntrigger_strategy_fallback]
    Pop --> Rest{剩余链非空?}
    Rest -- "是，下一顺位 seed_step" --> FindSeed[查全局种子池找近邻收敛 .7 种子]
    FindSeed --> HasSeed{找到合规种子?}
    HasSeed -- "是" --> Inject[注入 seed_point_name\n重置 pending 再派发] --> Exec
    HasSeed -- "否" --> Hold[保持 pending 待种子出现后自愈\n（seed_step 顺位暂存链尾）]
    Rest -- "否（链耗尽）" --> Fail[标记任务彻底失败]

要点：

1. 派发门控：链首为 seed_step 时必须能查到近邻种子才可派发；无种子则暂存该顺位到链尾、继续解析下一项（保证终止性，重复 seed_step 不陷入死循环）。初始派发与失败回退共用 resolve_dispatchable_chain。
2. 种子注入：seed_step 派发时服务端在 tasks 行写入 seed_point_name，节点凭此下载种子大气（GET /api/seed/<name>），TLUSTY 以种子 .7 作为 fort.8 热启动输入，跳过灰大气阶段直接跑 seed_nc -> nl。
3. 回退语义：仅 failed 状态且状态实际迁移时触发（2026-08-02 修复，杜绝重复失败报告触发多余 seed_step）；回退保留派发时的策略链快照，不修改原 policy。

---

3. 种子匹配算法 (Seed Finding)

种子池是全局共享的物理资源池（seeds 表 + 内存缓存 + 索引，跨工作流共享）。收敛且大气干净（无 NaN）的结果上报时，.7 大气原子写入 seeds_dir/<name>/<name>.7 并入库。

3.1 exact_family 桶索引

(teff/5000, logg×100, loghe×100) 量化成 SeedBucketKey，插入时写入 floor/floor+1 的 8 个笛卡尔积桶，查询时查 8 桶 → O(1)~O(小) 缩候选集，桶内再精算距离（量化只缩候选、不影响正确性）。

3.2 有向 CNO 距离（非对称，核心创新）

exact_family 判定（同物理族，仅 CNO 不同）：Δteff<5000 && Δlogg<0.01 && Δloghe<0.01。候选按有向 CNO 距离排序：

delta = target − cand（对 logc / logn / logo 各分量）
delta > 0（目标更富，坏方向）→ 惩罚 4.0 × delta
delta < 0（目标更贫，好方向）→ 惩罚 1.0 × |delta|

数据标定依据：对历史 1191 个真实 seed_step 配对的成败统计——贫金属方向（种子更富、目标往贫走）成功率 42–54%，富金属方向仅 3–11%（he=-4 时 54% vs 3%，差 18 倍）。物理解释：从高金属收敛解减少金属是稳定微扰；反过来增加金属时，新增紫外谱线辐射驱动会破坏已建立的辐射平衡 → 发散出现 NaN。

3.3 全局距离（跨 teff）

exact_family 未命中时退化到全量扫描，候选需 d ≤ 3.0：

d = Δteff/5000 + Δlogg×2 + Δloghe×0.5 + Δcno×0.1

权重物理意义：Teff 主导黑体势（÷5000 归一）；logg 破坏静力学压强平衡最烈（×2）；loghe 次之（×0.5）；CNO 影响紫外谱线辐射驱动，方向性已由有向距离表达（×0.1）。

---

4. 节点端执行与现场处理

1. 种子获取：seed_step 任务凭 seed_point_name 下载种子 .7，落 .seed_cache/（LRU 上限 8），再复制私有副本进 slot 沙盒作为 fort.8。
2. 沙盒生命周期：任务算完 → 上报成功（或失败，尽力而为）→ 白名单归档（result_dir/<name>/，永久保留）→ 清理沙盒；节点重启时也会清理残留的 task_* 沙盒（2026-08-02 修复：避免强杀遗留工作目录写满磁盘）。归档白名单与 TLUSTY fort 单元语义详见 tlusty_result_artifacts.md。
3. 节点无感知：节点只执行 strategies[0] + 注入的 seed_point_name，对回退过程完全无感知，调度与计算解耦。