抽谱教程 Thread：让每一步都能被你纠正

从 observation root 到 no-fit handoff；每一步注明来源、gate 与待教问题

发布于

2026年7月13日

Thread 的使用方式

这不是“照着跑就行”的 cookbook。每个 thread block 都有四个部分：

  • 我从真实材料学到什么；
  • 我准备怎么做；
  • 什么时候必须停；
  • 请你纠正什么。

你可以一边阅读，一边在 交互配置器 填同一组 RPC / ODF / region，最后在 教 Hermes 给出你的标准答案。

警告Runtime boundary

本文讲的是本地 xmmsas_20211130_0941 exemplar 所调用的 legacy mos-spectra / mos_back。当前 SAS 文档使用 mosspectra / mosback；在用户指定 golden runtime 和迁移规则前，不自动替换 task 名或宣称 current-SAS compatibility。Evidence IDs 与官方链接见 四套材料对比。

Thread 0 — 先选“我要做什么”，再选 mode

XMM/ESAS 工作至少有三种不同任务，不能混成“抽谱”：

flowchart LR
  A[Raw ODF] -->|once per OBSID| B[Field-ready RPC]
  B -->|per approved region batch| C[Source + QPB + RMF + ARF]
  C -->|after acceptance| D[No-fit QA / fitting handoff]

任务 输入 输出 代表材料 是否 routine region extraction
ODF reduction raw ODF calibrated/filter events M31CGM mode=redu 否
field preparation clean events/source list/masks/WCS frozen field-ready RPC XARTATOMS prior field state 否；一次/OBSID
C-mode extraction field-ready RPC + approved region source/QPB/RMF/ARF XARTATOMS Phase2 / M31HotISM E009 是
product release extracted products verifier report + no-fit plots + overlay XARTATOMS qualification / M31HotISM 84 gates 否；验收层

我准备的规则： 新 region 不自动重跑 cifbuild → emchain → filter → edetect_stack。只有 RPC 不满足 field-ready contract 时才回到前两行。

你实际使用 esas_playground 时，如何命名并区分这三种任务？redu、C、full、resume 分别应该承担什么？

Thread 1 — 识别 observation root、ODF 与 RPC

我学到的目录约定

esas_playground 配置不是直接填一个 RPC absolute path，而是组合：

datafolder / obsID / odffolder
                     rpcfolder

例如交互页会从 observation root 推导：

<DATA_ROOT>/<OBSID>/odf
<DATA_ROOT>/<OBSID>/rpc

启动前要检查的最小集合

  • OBSID 为 10 位；
  • ODF 目录真实存在；
  • SAS_ODF 指向唯一、非空 *SUM.SAS 或 engine 能唯一解析；
  • RPC 目录真实存在；
  • ccf.cif 与本次 observation 一致；
  • HEADAS、SAS、SAS_CCFPATH、ESAS_CCFPATH 明确；
  • 本次 shell 中 mos-spectra / mos_back 指向预期程序；
  • engine 与 .par 记录 SHA-256。

来自真实材料的提醒

  • XARTATOMS clean-shell wrapper 明确检查一个 SUM、tool path 和 hashes；
  • M31CGM historical log 中同一个 observation 在 cluster/home/work path 之间变化，说明配置中的 path 与 runtime environment 必须一起审计；
  • M31HotISM 使用 short RPC 解决 HEASOFT 长路径问题，这是一次性工程恢复，不是科学步骤。

你希望网页配置器的第一字段是 datafolder + OBSID，还是直接输入 observation root 更符合你的习惯？ODF 应填目录还是具体 SUM.SAS？

Thread 2 — 判断 RPC 是否 field-ready

我暂定的 field-ready contract

对计划使用的每个 camera/exposure，至少存在并可读：

  • clean event file；
  • corner event / QPB 所需 anchor；
  • object image 与 mask image；
  • attitude / WCS 支持；
  • ccf.cif 与 SUM provenance；
  • source exclusion / region seed；
  • flare/residual-SP 和 anomalous-CCD disposition。

若要直接走 XARTATOMS 式 4.background=yes，还必须确认 4.background 的 support state 来自哪一层（2.filter 或 2.1.filter），不能靠隐式 copy 猜。

停止条件

  • camera-region 只有 CCD1 且没有 outer-corner QPB anchor；
  • 计划使用的 CCD 被 anomalous state 排除；
  • clean event / mask / obj image 的 WCS 不一致；
  • 只有 parent/other-region QPB，没有 region-specific QPB 生成路径。

XARTATOMS S8 的处理是正确示范：unavailable，而不是硬凑一条谱。

请你定义 field-ready RPC 的 authoritative checklist。哪些文件是 esas_playground 自己会补的，哪些缺失时必须停止？

Thread 3 — source exclusion 和 science region 是两件事

source exclusion

作用：排除点源/展源，通常进入 extra_region_file 或 camera-specific region mask。

science region

作用：限定要抽的 annulus/sector/polygon，通常进入 extra_region_list。

[back]
extra_region_file = "<source-exclusion.reg>"
extra_region_list = <science-region-01.reg>,<science-region-02.reg>,
MASK = 1,

为什么不能混

M31HotISM 初始 historical mask 是一个大 ROTBOX，不是点源排除 mask；它恰好落在 science polygon 内，导致新旧谱近似相同。E009 重建 camera-specific point-source mask 后，BACKSCAL 和 channel counts 才真正发生合理变化（HOTISM-E009 / HOTISM-E009-QA）。

你现在最推荐的 source exclusion 是 extra_region_file 直接 DS9 exclude region，还是先构建 camera-specific XMM region FITS？MASK=1 在你的标准配置中具体负责什么？

Thread 4 — exact DS9 region 先视觉批准，再转换

必须保存的证据

  • exact .reg 文件；
  • coordinate frame（通常 fk5）；
  • region semantics（include/exclude）；
  • camera image + mask + source exclusion overlay；
  • conversion engine/module/hash；
  • converted DET expression；
  • camera×region coverage / active CCD。

不能只做机器检查的原因

  • angle/PA convention 可以整体旋转但仍通过 closure；
  • positive/negative wrap 可能把 45° sector 变成 315°；
  • outer annulus 可在 DET 中变成超出 response support 的大 polygon；
  • 只看文件存在不能证明抽的是正确 sky region。
重要固定规则

新的 spatial transform 在 visual approval 前不能抽谱。页面配置器只接受 region 字符串并生成草案，不做坐标转换，也不宣称 geometry approved。

警告已否决路线，不作为教材

E021 的 custom FullFOV-clipped DET expression 与 DETX/DETY visual QA 已被用户否决并撤回。未来输入必须是 canonical FK5/RA-Dec region，走 native Mode-C conversion，并用 sky-coordinate region + camera/mask overlay 审计；不能把迟到子审计中的 E021 clipping 建议复活。

请你指定最值得 Hermes 学习的 DS9→DET conversion 实现和 golden overlay。是 v1.4.1 的 ds9_to_xmmexpr，还是 XARTATOMS 另一个 validated converter/replay？

Thread 5 — 编译 camera × region matrix

engine 往往把 INST × extra_region_list 当 Cartesian product。实际 coverage 可能是：

Region MOS1 MOS2 正确批次
R1 READY READY dual-MOS batch
R2 SKIP READY MOS2-only batch
R3 READY SKIP MOS1-only batch

所以不能用一个 INST=mos1,mos2 + 所有 regions 的配置启动 unsupported pairs。

我准备的编译规则

  1. 每个 camera-region 先得到 READY / SKIP / BLOCK；
  2. 按 camera readiness 分组；
  3. 每组生成一个 homogeneous .par；
  4. BLOCK 不进入 extraction；
  5. batch 内任一 output namespace 已存在时 fail closed，避免覆盖。

你在 esas_playground 中通常如何处理不同 camera coverage？是拆 .par、让 engine 自动跳过，还是在 region-specific CCD preflight 后生成列表？

Thread 6 — routine extraction 的配置应很短

对 field-ready RPC，XARTATOMS recent production 的核心就是：

[full]
4.background = yes
extra_region = yes
background = yes
4.fitting = no

[back]
INST = mos2,
generate_spectra_and_back = yes
EMINLIST = 700,
EMAXLIST = 1000,
MASK = 1,
extra_region_file = "<approved-exclusion.reg>"
extra_region_list = <approved-region.reg>,

两条已观察到的 background-only profile

XARTATOMS v1.4.1 recent production：

[full]
3B.background = no
4.background = yes
extra_region = yes
background = yes
4.fitting = no

M31HotISM v1.3.2 accepted E009：

[C]
3B.background = yes
4.background = no
extra_region = no
background = yes
4.fitting = no

它们都能进入 region extraction，但 stage semantics 不同。不能只替换 mode= 名称；交互配置器按 evidence-bound profile 生成整组开关。

launch 仍然只有一条：

python3 '<QUALIFIED_ENGINE.py>' '<CONFIG.par>'

哪些不应该混进 routine core

  • 重新下载/校准 ODF；
  • 每个 annulus 重跑 source detection；
  • runtime copy 并 patch engine；
  • 人工复制 parent QPB/ARF/RMF；
  • fitting；
  • Cloudflare publication；
  • 独立 agent 对每个 shell line 做 science 解释。

对你的标准 extended-source extraction，储存谱的 energy range 应统一多宽？XART R4–7 使用 700–1000 eV 是当前特殊诊断，M31HotISM E009 存 300–7200 eV、在 fitting 时另行忽略 MOS 污染带。你希望通用教材写哪一个策略？

Thread 7 — exit 0 不是产品通过

每个 camera-region 的技术产品

  • source PHA；
  • region-specific QPB PHA；
  • RMF；
  • ARF；
  • exact converted region expression；
  • executed command / config / engine hash；
  • source image / mask / camera overlay。

最小验收

  • FITS readable；
  • OBS_ID / INSTRUME / EXP_ID 正确；
  • source/QPB channel grid 相容；
  • exposure、BACKSCAL、AREASCAL finite positive；
  • source PHA links 到 camera-matched background/response；
  • ARF non-zero；RMF energy grid 覆盖目标范围；
  • source/QPB SLCTEXPR 包含同一 science region；
  • QPB active CCD / outer-corner anchor 合理；
  • 不存在 unintended camera products；
  • no surrogate / parent-scaled QPB / copied response。

M31HotISM E009 的 84 gates（HOTISM-E009-QA）和 XARTATOMS Phase2 qualification（XART-E04）分别提供了两个实现。它们不必原样合并，但必须由你决定最小共同集合。

请选出你认为所有新光谱都必须通过的 10–20 个 hard gates；其余项目特定 gates 应放到哪里？

Thread 8 — no-fit handoff 先于 fitting

每次新抽谱的可视交付：

  1. exact DS9 FK5 / RA-Dec region；
  2. source PHA 路径与 camera；
  3. 无拟合 xsherpa inspect；
  4. region + camera mask + source exclusion overlay；
  5. product manifest 与 caveats。

只有技术产品与空间证据都通过后，才进入 grouping / fitting。对 M31HotISM，MOS 1.4–2.0 keV 的处理是 fitting contract，不应伪装成“stored spectrum 没有这些 channels”。

你希望 no-fit inspect 的固定图组是什么？rate / sb / sb_flux，1col/2col，linear/log 是否每次都全部生成，还是 pilot 全套、batch 只生成简版？

Thread 9 — pilot 后才 scale-up

pilot 应覆盖最危险情况

  • boundary/wrap 最复杂；
  • counts 较弱但仍可用；
  • camera coverage 最容易不同；
  • QPB outer anchor 最边缘；
  • representative source exclusion。

scale-up 前 gate

  • pilot release manifest 通过；
  • exact engine/config/region hashes 不变；
  • product verifier、no-fit inspect、spatial overlay 通过；
  • batch output namespace 全部干净；
  • homogeneous camera groups 已生成；
  • 每个并发 task 使用独立 working directory / output namespace；禁止多个 ESAS task 同时写同一目录，以避免临时文件和固定文件名冲突（HEASARC ESAS warning）；
  • parallel 数量不超过环境承受能力。

最小失效矩阵

变化 重跑 field preparation 重跑 extraction
新 OBSID 是 是
同 OBSID 新 region 否 仅新区
native region converter 改动 否 受影响区域
energy band 改动 否 是
clean event / GTI / CCF / mask policy 改动 新 field generation 全部
verifier 修复 否 不跑 SAS，只重验
图样式、报告或网页修复 否 否

这个表是“减少重复”的核心：verification/publication failure 不能倒逼 SAS 重跑；field-owned asset 不变时，新 region 不能触发 ODF/clean/source-detection 重做。

XARTATOMS recent branch就是 pilot Wind N → remaining batch；M31CGM historical root script则直接遍历 OBSID/qsub，缺少同等级 pilot-product gate。

你通常怎么选 pilot？按最困难 region、最典型 region、还是最简单 region？你希望 Hermes 默认一条谱通过后并行到几条？

Thread 10 — 用户决定已收到，下一次 run 仍需逐次输入

用户已经明确给出：

  • canonical engine：esas_playground_v1.4.1.py；
  • 单一 program + 每次 .par 配置，不复制 per-OBSID engine；
  • 先盘点 ODF/RPC stage state，只补缺失 field stages；
  • pre-extraction evselect RA/Dec image visual QA；
  • post-extraction mos-spectra image + exact RA/Dec region overlay + xsherpa inspect；
  • 保留全部 11 个 safety/QA patterns。

用户没有指定 golden wrapper、golden .par、successful/failure log；本教程不会替他补写。每次实际 run 前必须重新询问：band、region、是否扣点源、是否去掉展源，并取得 exact spatial approval。原 decision 为 execution_authorized=false。

请继续到 交互配置器 填本次输入；需要修改方法时再到 教 Hermes 导出新版决定。