DCTS/docs/tlusty_result_artifacts.md

TLUSTY 结果产物分析：Node 归档白名单与 fort 单元快照

本文档记录对 TLUSTY/SYNSPEC 源码的单元号（fort.N）语义分析，以及据此确定的 Node 端结果归档（result_dir）白名单与 TLUSTY b 因子/出射谱快照的设计依据。 源码路径：TLUSTY 位于 /home/fmq/program/SpectraRust/tlusty/（tlusty208.f）， SYNSPEC 位于 /home/fmq/program/SpectraRust/synspec/（synspec54.f）。 归档逻辑实现于 crates/node/src/executor.rs、crates/common/src/runner.rs、 crates/common/src/result_filter.rs。

1. 背景与问题

Node 每个任务算完后，把沙盒 work_dir/task_<id>/<name>/ 内的产物拷贝到持久归档 result_dir/<name>/。归档采用白名单策略（is_result_worthy），只保留有语义价值 的产物，丢弃 Tlusty/Synspec 运行时的中间工作单元（旧版 catch-all 会把它们一并搬进 归档，每个模型浪费约 2MB / 4.8MB）。

需要回答的核心问题：

1. 当前归档到底保留了哪些文件？
2. TLUSTY 的 fort.12（b 因子）、fort.14（出射谱）、fort.69（计时日志）是否有 保存价值？—— 需以 TLUSTY 源码为准。
3. TLUSTY 出射谱（fort.14）与 SYNSPEC 输出的 .spec 有什么区别，是否冗余？

2. Node 结果归档机制（现状）

• 归档路径：result_dir/<name>/（result_dir 由 node 配置指定，默认为 data/result/）。
• 触发时机：上报成功后（上报失败也归档，用于排错），随后清理沙盒。
• 原子写入：先拷为 .result.tmp.<uuid> 再 rename，防止半截文件。
• 无 LRU 上限：所有已算网格点产物永久保留（2026-08-02 撤销此前 200 目录上限）。
• 白名单判定：common::result_filter::is_result_worthy(fname, model_name)。

2.1 保留的文件（白名单）

model_name 为网格点权威名，如 t20000_g5.0_he-2_c-4_n-4_o-4。

裸名保留（不以 model_name 为前缀，有独立语义）：

文件	语义
conv.json	收敛摘要
fort.8	SYNSPEC 输入大气
fort.55	SYNSPEC 控制卡

科学核心 <name>.<后缀>：

后缀	来源	语义
.7	TLUSTY/SYNSPEC	最终大气
.spec	SYNSPEC fort.7	合成光谱（高分辨率）
.cont	SYNSPEC fort.17	连续谱
.iden	SYNSPEC fort.12	谱线证认表
.log	SYNSPEC	SYNSPEC 日志
.bfac	TLUSTY fort.12 快照	最终模型 b 因子（非 LTE 偏离因子）
.emflux	TLUSTY fort.14 快照	最终模型出射谱（波长 Å + Fλ）

阶段快照 <name>.<label>.<后缀>（label ∈ lte/nc/nl/seed_nc）：

• .5（输入卡）、.6（输出日志）、.err（错误日志）、.nst（控制卡）、.7（该阶段大气）

收敛诊断 <name>.<label>_chmax*.9：唯一保留的 .9 形态（裸 <name>.<label>.9 与 _chmax*.9 内容重复，runner 源头已停止写出）。

2.2 丢弃的内容

• 所有 Tlusty 中间工作单元：fort.1/2/3/10/11/13/14/18/22/42/44/50/57/69/82/95
• fort.84（NATOMS 崩溃缓存）、.tmp 残留
• 符号链接（data、fort.19 等共享 runtime 资源）、子目录
• 不以 <name>. 开头且不在裸名列表的文件、未知后缀/未知阶段标签
• fort.12 / fort.17：被 runner 消费（见 §4.1）后删除

3. TLUSTY fort 单元语义（源码分析）

TLUSTY 每次运行到达最终迭代（LFIN=.TRUE.）时，经 OUTPRI（tlusty208.f:14156，调用点 :3889）一次性写出多个单元。各单元语义与行号：

单元	内容	源码位置	判定
fort.12	b 因子（非 LTE 偏离因子表）：头 2I5 + 每深度 TEMP/ELEC/DENS/BFAC，格式 701/702/703	:14344	科学价值高，需快照
fort.13	出射辐射场（FREQ, FLUX=H(ν), FH=Eddington 因子），格式 602	:14185	与 fort.14 同源，未快照
fort.14	出射谱（波长 Å + Fλ），格式 614 F15.3,1pe15.3	:14188	科学价值高，需快照
fort.17	每深度布居数 POPUL（格式 503）	:14124	SYNSPEC 覆盖后转存 .cont
fort.20	b 因子 BFAC（另一分支）	:14119	未保留
fort.22	绝对 b 因子 BFAB	:14346	未保留
fort.69	迭代计时日志：TIMING 子程序写 IP/MOD/TIME/DT/ROUT（FORMAL SOLUTION / LINEARIZATION），格式 600	:29937	纯性能诊断，丢弃

注意：OUTPRI 仅在最终迭代调用，故每个单元内保存的是最后一次迭代的最终值。 收敛链上最后一次 TLUSTY 运行即最终模型。

4. SYNSPEC 对 unit 12/14 的覆盖与丢失风险

4.1 单元号复用导致覆盖

TLUSTY 与 SYNSPEC 同目录串行执行，且两个程序复用相同的单元号：

单元	TLUSTY 写	SYNSPEC 写
12	b 因子	谱线证认表（synspec54.f:9719，格式 603）
14	出射谱	谱线数据（synspec54.f:9852，格式 601）

由于 TLUSTY 先跑、SYNSPEC 后跑，SYNSPEC 会把 fort.12/fort.14 覆盖。现有 runner 流程：

1. TLUSTY 写 b 因子 + 出射谱 → 被 SYNSPEC 覆盖
2. SYNSPEC 写 fort.7（谱）、fort.17（连续谱）、fort.12（谱线证认表）
3. runner 将 fort.7→.spec、fort.17→.cont、fort.12→.iden，随后删除 fort.12/fort.17

结论：归档里的 .iden 保存的是 SYNSPEC 的谱线证认表（覆盖后的 fort.12）， TLUSTY 的 b 因子与出射谱在覆盖前无任何快照，会被静默丢失 —— 这是真实的数据损失点。

4.2 快照决策

• fort.69：纯计时日志，不保存（无科学内容）。
• fort.12（b 因子）与 fort.14（出射谱）：需快照。

5. 实现：快照 b 因子 + 出射谱

5.1 快照命名与白名单

源文件	快照名	白名单后缀
fort.12	<name>.bfac	bfac（加入 SCIENCE_SUFFIXES）
fort.14	<name>.emflux	emflux（加入 SCIENCE_SUFFIXES）

5.2 插入点

runner::run_model_with_timeout：收敛链循环结束后、SYNSPEC 启动前调用 snapshot_tlusty_outputs(&model_dir, name)。此时 fort.12/14 是最后一次 TLUSTY 运行 （最终模型）的产物，且尚未被 SYNSPEC 覆盖。仅 SYNSPEC 场景（tlusty 未运行）下 fort.12/14 不存在，函数按文件存在性静默跳过。

5.3 变更文件

• crates/common/src/runner.rs：新增 snapshot_tlusty_outputs() + 调用 + 2 个测试
• crates/common/src/result_filter.rs：SCIENCE_SUFFIXES 加 bfac/emflux + 文档 + 测试
• crates/node/src/executor.rs：归档文档、test_save_result_artifacts 同步 + 修正 fort.13 注释（原误标为"NLTE 跃迁频率网格"，实为出射辐射场 FREQ/FLUX/FH）

6. TLUSTY 出射谱（fort.14）vs SYNSPEC .spec

两者转换公式完全相同、物理量一致，差异在网格密度、线不透明度处理、覆盖范围与用途。

6.1 相同点

• 公式一字不差：Fλ = H(ν) × ν² / c
  • TLUSTY（:14188）：FLAM=FLUX(IJP)*FREQ(IJP)*FREQ(IJP)/2.997925E18
  • SYNSPEC（:3365）：FLAM=FLUX(IJ)*FREQ(IJ)*FREQ(IJ)*CAS，CAS=1./2.997925D18
• FLUX 都是表面出射 Eddington 通量 H(ν)（erg/cm²/s/sterad/Hz，OUTPRI 注释明确 "precisely the second moment H(freq) at the surface"）。
• 同一波长点的连续谱水平应当一致。

6.2 差异点

维度	TLUSTY fort.14	SYNSPEC .spec
网格密度	模型自身频率网格（NFREQ 个点，数百~数千，非均匀）	以每条谱线为中心的细网格（FR0=FREQ0(IL0)，SPACE/CUTOFF/DOPSTD 采样线轮廓，密度高几个量级）
线不透明度	模型求解时的粗/近似线处理（不透明度采样/ODF/超能级），只体现最强线	完整线表（fort.19）逐细频点重解辐射转移，得到分辨开的真实线轮廓
波长覆盖	整个模型宽带频率范围	仅 fort.55 指定窗口（dcts 默认 1400–1410 Å）
FLUX 来源	模型迭代过程的自洽辐射场解（顺带用于通量守恒检查 TOTF）	用已收敛大气在细网格重新解 RT
用途/下游	模型副带品，快速看谱/校验	科学产品，注释明说 "serves as input to ROTINS"（转动/仪器展宽卷积），用于与观测对比

6.3 实际含义

两者是同一物理量（表面 Fλ）在不同分辨率和线处理下的版本，非两种东西。叠画时 连续谱重合，.spec 显示被分辨开的精细谱线轮廓，fort.14 中弱线基本不可见。归档同时 保留二者不构成冗余：.emflux 代表模型自身辐射场（宽带、粗，可独立校验），.spec 代表最终高分辨率合成谱（窄窗、细，与观测对比的产品）。

7. 完整归档文件清单（快照实施后）

result_dir/<name>/
├── conv.json
├── fort.8                 # SYNSPEC 输入大气（裸名保留）
├── fort.55                # SYNSPEC 控制卡（裸名保留）
├── <name>.7               # 最终大气
├── <name>.spec            # SYNSPEC 合成光谱
├── <name>.cont            # SYNSPEC 连续谱
├── <name>.iden            # SYNSPEC 谱线证认表
├── <name>.log             # SYNSPEC 日志
├── <name>.bfac            # TLUSTY 最终 b 因子（快照 fort.12）
├── <name>.emflux          # TLUSTY 最终出射谱（快照 fort.14）
├── <name>.<label>.5       # 阶段输入卡快照
├── <name>.<label>.6       # 阶段输出日志快照
├── <name>.<label>.err     # 阶段错误日志快照
├── <name>.<label>.nst     # 阶段控制卡快照
├── <name>.<label>.7       # 阶段大气快照
└── <name>.<label>_chmax*.9  # 阶段收敛诊断（唯一保留的 .9）

8. 后续可选优化

• fort.13（出射辐射场，含 Eddington 因子 FH）未快照；如需保留，在 snapshot_tlusty_outputs 中加 ("fort.13", "emrad") 并在白名单加 emrad 后缀即可。
• fort.20（b 因子）、fort.22（绝对 b 因子）同属 b 因子家族；如需保留可在 TLUSTY 阶段结束后一并快照，但 fort.12 已覆盖相对 b 因子，绝对 b 因子可由 POPUL/POPLTE 重算。