ParetoGTICal

如何亲手继续（最重要的一页）How to continue by hand (the most important page)

目标：一个没有 AI 的一年级本科生，能从零开始跑数据、检查结果、推进下一步。本页所有命令都在 lang 上验证过（--help 实测；见页面底部命令表）。

Goal: a first-year undergraduate with no AI can run the data, check the results and advance the next step from scratch. Every command on this page was verified on lang (real --help runs; see the command table at the bottom).

本页目录On this page
  1. 机器与分工Machines and roles
  2. 数据、代码、结果在哪里Where data, code and results live
  3. 复制即用命令Copy-paste commands
  4. 必须遵守的规则Rules you must keep
  5. 下一步（编号计划）Next steps (numbered plan)
  6. 命令帮助实测表Verified --help table

1. 机器与分工1. Machines and roles

机器Machine做什么Role限制Limits
langlang 一切分析与绘图；本仓库的全部脚本。All analysis and plotting; every script in this repo. 最多 2 个单线程 Python;临时文件用 $TMPDIR,绝不用 /tmp。At most 2 single-thread Python processes; temp files go to $TMPDIR, never /tmp.
VirgoVirgo 只做 SAS/ESAS 数据还原（emchain、espfilt、2.filter）。SAS/ESAS data reduction only (emchain, espfilt, 2.filter). CPU 与内存 ≤ 60%;中间文件放 NVMe;绝不在 Virgo 上拟合。ODF 在 lang 下载再拷去 Virgo（lang 到 XSA 约 1 MB/s,Virgo 只有 70–130 KB/s）。CPU and memory ≤ 60%; intermediates on NVMe; never fit on Virgo. Download ODFs on lang and copy them to Virgo (lang→XSA ≈ 1 MB/s; Virgo only 70–130 KB/s).
来源：Source: ParetoGTICal/cognition-os/PITFALLS.md （§迁移与执行）(§Migration and execution) ;父项目; parent DiffuseXrayCalibration/cognition-os/00_AI_BRIEFING.md (T02).

2. 数据、代码、结果在哪里2. Where data, code and results live

内容What位置Location
代码（脚本、预注册、认知 OS、legacy）Code (scripts, prereg, cognition OS, legacy)/u/Lang3/program/DiffuseXrayCalibration/ParetoGTICal/
数据与结果（inputs、results）Data and results (inputs, results)/u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/
只读旧输入根（M31 2.filter 产品等）Read-only old input root (M31 2.filter products etc.)/u/Lang3/program/CDFS/inputs
git 历史git history分支 feat/pareto-gti-cal（当前 checkout 的分支属于别的子项目）：git log feat/pareto-gti-cal -- ParetoGTICalbranch feat/pareto-gti-cal (the currently checked-out branch belongs to another sub-project): git log feat/pareto-gti-cal -- ParetoGTICal
Python 环境Python environment/home/huangrui/software/miniconda3/bin/python3 (numpy、scipy、astropy、matplotlib 3.10)(numpy, scipy, astropy, matplotlib 3.10)

3. 复制即用命令3. Copy-paste commands

所有命令都先进入仓库根目录再运行:cd /u/Lang3/program/DiffuseXrayCalibration/ParetoGTICal。收据路径用数据根 /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/ 下的完整路径（仓库里没有 results/ 目录，相对路径会报 FileNotFoundError）。

Every command starts by entering the repo root: cd /u/Lang3/program/DiffuseXrayCalibration/ParetoGTICal. Receipt paths are written in full under the data root /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/ (the repo has no results/ directory; relative paths give FileNotFoundError).

3.1 迁移校验器（只读，几秒）3.1 The migration verifier (read-only, seconds)

cd /u/Lang3/program/DiffuseXrayCalibration/ParetoGTICal
PYTHONDONTWRITEBYTECODE=1 TMPDIR=$TMPDIR \
  python3 tools/verify_migration.py

若 CDFS 源不可用，加 --offline 只校验目标快照。E001 记录：在线与离线均 PASS（69 个文件，3,145,929 字节，57 个 Python 文件解析，5 份历史收据）。

If the CDFS source is unavailable, add --offline to verify only the destination snapshot. E001 records PASS both online and offline (69 files, 3,145,929 bytes, 57 Python files parsed, 5 historical receipts).

来源：Source: cognition-os/experiments/E001_migration_verification.md; ParetoGTICal/README.md.

3.2 主脚本：M31 或 CDFS、MOS1/MOS2 的不变量运行（约 30–50 分钟/次）3.2 The main script: the invariant run for M31 or CDFS, MOS1/MOS2 (≈30-50 min per run)

cd /u/Lang3/program/DiffuseXrayCalibration/ParetoGTICal
# M31 MOS1(2026-10-13 实跑 1843 s ≈ 31 min,30/30 ObsID):# M31 MOS1 (real run 2026-10-13: 1843 s ≈ 31 min, 30/30 ObsIDs):
mkdir -p /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_m31_mos1
PYTHONDONTWRITEBYTECODE=1 python3 scripts/m31_mos2_line_continuum_invariant.py \
  --field m31 --camera M1 \
  --out /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_m31_mos1
# CDFS(M1 与 M2 各一次。已于 2026-10-13 实跑完成:M1 47 min、M2 45 min,各 34/34 ObsID;收据在 results/p001_cdfs_m1|m2/):# CDFS (one run per camera. Already run for real on 2026-10-13: M1 47 min, M2 45 min, 34/34 ObsIDs each; receipts in results/p001_cdfs_m1|m2/):
mkdir -p /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_cdfs_m1 \
         /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_cdfs_m2
PYTHONDONTWRITEBYTECODE=1 python3 scripts/m31_mos2_line_continuum_invariant.py \
  --field cdfs --camera M1 \
  --out /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_cdfs_m1
PYTHONDONTWRITEBYTECODE=1 python3 scripts/m31_mos2_line_continuum_invariant.py \
  --field cdfs --camera M2 \
  --out /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_cdfs_m2

注意：--out 必须在数据根 /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/ 之下（代码会拒绝写到 /u/Lang3/program 或 legacy/）。--dry-load 只做结构性检查、不写任何文件。CDFS 的两次运行已按 P001 §8 条款 9 完成（E003），不要重跑 —— 重写收据会破坏盲测记录。

Note: --out must lie under the data root /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/ (the code rejects output paths under /u/Lang3/program or legacy/). --dry-load is a structural check that writes nothing. Both CDFS runs are already complete per P001 §8 item 9 (E003); do not rerun them — overwriting the receipts would break the blind-test record.

来源：Source: cognition-os/experiments/E002_p001_m31_mos1.md （命令、种子 20260914、200 次抽样、1843 s）(command, seed 20260914, 200 draws, 1843 s); E003_p001_cdfs_blank_field.md （命令、M1 47 min 与 M2 45 min、各 34/34）(commands, wall time 47 min M1 and 45 min M2, 34/34 each).

3.3 终点评估器（秒级，不重新拟合）3.3 The endpoint evaluator (seconds; never refits)

cd /u/Lang3/program/DiffuseXrayCalibration/ParetoGTICal
# 4 份收据一起传（CDFS M1+M2 与两份 M31 收据，M31 用于 E4/E6）——2026-10-13 实跑产出 p001_endpoints_all.json:# Pass all 4 receipts (CDFS M1+M2 and both M31 receipts, for E4/E6) — run for real on 2026-10-13, producing p001_endpoints_all.json:
mkdir -p /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_cdfs
PYTHONDONTWRITEBYTECODE=1 python3 scripts/p001_endpoints.py \
  /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_cdfs_m1/line_continuum_invariant.json \
  /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_cdfs_m2/line_continuum_invariant.json \
  /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_m31_mos1/line_continuum_invariant.json \
  /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_regression/m31_mos2_full_a2/line_continuum_invariant.json \
  --out /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_cdfs/p001_endpoints_all.json

只传两份 M31 收据时给 E4;CDFS 收据一起传时给描述性的 E6。--out 的目录必须先 mkdir -p。现有收据 p001_endpoints_all.json 已存在（D006 记录的终点即出自它）；重新运行会覆盖，除非你改 --out。本手册作者于 2026-10-13 用两份 M31 收据实跑过此命令（输出与 p001_endpoints_m31.json 一致）。

With the two M31 receipts alone it gives E4; with the CDFS receipts added it gives the descriptive E6. The --out directory must exist (mkdir -p first). The receipt p001_endpoints_all.json already exists (the endpoints recorded in D006 come from it); rerunning overwrites it unless you change --out. The author ran this command for real on 2026-10-13 with the two M31 receipts (output identical to p001_endpoints_m31.json).

3.4 回归门（冻结代码 vs 未修改 g1 脚本的重跑）3.4 The regression gate (frozen code vs the rerun of the unmodified g1 script)

cd /u/Lang3/program/DiffuseXrayCalibration/ParetoGTICal
PYTHONDONTWRITEBYTECODE=1 python3 scripts/p001_regression_check.py \
  /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_regression/m31_mos2_full_a2/line_continuum_invariant.json \
  --g1 /u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_regression/orig_m31_mos2_full/line_continuum_invariant.json

D004 记录的 PASS 就是这次比较：冻结代码（a2）对未修改 g1 脚本的重跑(orig_m31_mos2_full),26,111 个数字，最大相对差 0。本手册作者 2026-10-13 实跑输出：{"n_numbers": 26111, "max_rel": 0.0, "mismatch": [], "verdict": "PASS"}。

The recorded PASS (D004) is exactly this comparison: the frozen code (a2) against the rerun of the unmodified g1 script (orig_m31_mos2_full), 26,111 numbers, max relative difference 0. The author's real run on 2026-10-13 printed {"n_numbers": 26111, "max_rel": 0.0, "mismatch": [], "verdict": "PASS"}.

注意：对存档的 g1 收据（legacy/…g1/line_continuum_invariant.json）同一命令是 FAIL,且失败是已知的 2 处:元数据键 source_receipt_status（只在 a2 里有），和 line_response.within_observation_dL_dC.significance（−0.597961 vs −0.597988,相对差 4.6e-5）。g1 收据在该点与它自己存的 slope/stderr 不一致 —— 差异来自 g1 的存档脚本（其 mtime 晚于收据 2 分钟），不是 P001 代码引入。来源：D004 与 P001 §6。

Note: the same command against the stored g1 receipt (legacy/…g1/line_continuum_invariant.json) is a FAIL, with exactly 2 known mismatches: the metadata key source_receipt_status (present only in a2), and line_response.within_observation_dL_dC.significance (−0.597961 vs −0.597988, relative 4.6e-5). The g1 receipt disagrees there with its own stored slope and stderr — the difference comes from g1's archived script (its mtime is 2 min after the receipt), not from P001 code. Source: D004 and P001 §6.

/u/Lang3/Data/DiffuseXrayCalibration/ParetoGTICal/results/p001_regression/regression_check_a2_vs_orig.json;

4. 必须遵守的规则4. Rules you must keep

  1. 绝不在观测之间平均/排名/合并 R。R 的上限由该次观测自己的耀斑含量决定（从 1.0 到 11.8,见"物理"页图）。Never average, rank or pool R across observations. R's ceiling is set by each observation's own flare content (it runs from 1.0 to 11.8; see the figure on the physics page).
  2. K 与 B 必须不相交;选择能段 2.5–8.0 keV 与测量窗口 1.000–2.395 keV 必须不重叠（重叠时代码必须中止）。K and B must be disjoint; the 2.5–8.0 keV selection band and the 1.000–2.395 keV measurement window must not overlap (the code must abort on overlap).
  3. 冻结代码在盲测前不改。任何修改都是带日期的修正案 (amendment),且必须在看到结果之前由 PI 批准。Frozen code is not edited before a blind run. Any change is a dated amendment approved by the PI before outcomes are seen.
  4. 活时间来自 EXPOSU(TIMEDEL×FRACEXP),不是"有事件的 cell × cell 宽度"。Live time comes from EXPOSU (TIMEDEL×FRACEXP), never "cells with events × cell width".
  5. 绝不提交 FITS/PHA/ARF/RMF;临时文件用 $TMPDIR,绝不用 /tmp。Never commit FITS/PHA/ARF/RMF; temp files go to $TMPDIR, never /tmp.
  6. MOS1+MOS2 为基础,pn 只作交叉检验。MOS1+MOS2 is the basis; pn is a cross-check only.
  7. 每个数字记录来源（文件路径 + 行）。Record the source of every number (file path and line).
  8. 盲测集不被探索代码触碰:改代码先在 M31 MOS2（已消费）上测，并复现 g1 收据后再冻结。Blind sets are never touched by exploratory code: test code changes on M31 MOS2 (already consumed) and reproduce the g1 receipt before freezing.
来源：Source: cognition-os/PITFALLS.md; cognition-os/02_CURRENT_QUESTION.md §边界§Boundaries; prereg/P001_mos1_and_blank_field.md.

5. 下一步（编号计划；PI 在 (a) 与 (b) 之间选择，本手册不代选）5. Next steps (numbered plan; the PI chooses between (a) and (b) — this handbook does not choose)

已完成：CDFS 盲测（M1 与 M2，2026-10-13，E003）DONE: the CDFS blind run (M1 and M2, 2026-10-13, E003)

结果Outcome: 34/34 ObsID × 2 相机，冻结代码 46d8df3。E1 在主集上 NOT_EVALUABLE（无规则零控制；敏感性集 PASS,0/9);E2 PASS;E3 在两台相机上失败（MOS1 24/29,符号 p = 2.7e-4;MOS2 27/29,符号 p = 8.1e-7;Stouffer Z = 1.55 与 1.73,阈值 Z > 3);E5 角落两台相机都 USABLE（σ = 0.0044 / 0.0038）。P001 关闭，结论否定（D006）。34/34 ObsIDs × 2 cameras with the frozen code 46d8df3. E1 NOT_EVALUABLE on the primary set (no rule zero control; sensitivity set PASS, 0/9); E2 PASS; E3 fails on both cameras (MOS1 24/29, sign p = 2.7e-4; MOS2 27/29, sign p = 8.1e-7; Stouffer Z = 1.55 and 1.73 against the threshold Z > 3); E5 corner USABLE on both (σ = 0.0044 / 0.0038). P001 is closed, negative (D006).

先读Read first: cognition-os/experiments/E003_p001_cdfs_blank_field.md;results/p001_cdfs/p001_endpoints_all.json。

路线 (a)——定义下游成功判据（D002 第 3 步，briefing 的下一步 3）Route (a): define the downstream success criterion (D002 step 3, briefing "Next steps" item 3)

目标Goal: 把 f_T–R 平面变成可决策的标量：1% 活时间损失值多少连续谱增益？E3 失败后，任何 GTI 政策改变只有经它才能被证明值得。turn the f_T–R plane into a decidable scalar: how much continuum gain is 1% of live time worth? After E3 failed, any change of GTI policy can only be justified through it.

输入Inputs: 父项目的响应折叠弥散天空拟合（DXC 的 ESAS + Sherpa 合同）；本项目的 f_T、R 收据（results/p001_cdfs_m1|m2/、results/p001_m31_mos1/）。the parent project's response-folded diffuse-sky fit (DXC's ESAS + Sherpa contract); this project's f_T and R receipts (results/p001_cdfs_m1|m2/, results/p001_m31_mos1/).

方法Method: 建议（未经评审）：在父项目合同内，对同一观测在不同保留率下做响应折叠拟合，量出天空参数（或其系统预算）随 f_T 的变化率；由 PI 评审后写进预注册。Suggestion (not reviewed): within the parent's contract, run response-folded fits of the same observation at several retentions and measure how sky parameters (or their systematic budget) vary with f_T; write it into a pre-registration after PI review.

成败判据Success vs failure: 得到一个带不确定度的兑换率数字；若拟合对 f_T 不敏感，记录之（它本身就是重要结果）。an exchange-rate number with uncertainty; if the fit is insensitive to f_T, record that (it is itself an important result).

时间估计Time estimate: 设计 + 评审约 1–2 周（建议，未经评审）。design + review ≈ 1–2 weeks (suggestion, not reviewed).

先读Read first: DiffuseXrayCalibration/README.md;ParetoGTICal/cognition-os/00_AI_BRIEFING.md §下一步 第 3 步§Next steps step 3。

路线 (b)——Al 线是否跟随角落粒子水平（建议，未经评审；需新预注册）Route (b): does the Al line track the corner particle level (suggestion, not reviewed; needs a new pre-registration)

目标Goal: 判定 CDFS 的探索性张力（被删时间角落数子水平高 2–4%,门内 Al 线比不跟随，相隔 3.2σ 与 7.7σ）的来源：Al 线本来就不跟随角落连续谱，还是线测量有未建模的 K/B 系统误差（T005/T016/T017）。decide the origin of the CDFS exploratory tension (rejected time has a 2–4% higher corner particle level, the as-gated Al-line ratio does not follow it, 3.2σ and 7.7σ apart): either the Al line genuinely does not track the corner continuum, or the line measurement has an unmodelled K/B systematic (T005/T016/T017).

输入Inputs: CDFS 收据里的 corner_split_archived_2filter 与线比块（results/p001_cdfs_m1|m2/line_continuum_invariant.json）;M31 MOS2 的历史故障注入收据（耦合 s 的来源）。the corner_split_archived_2filter and line-ratio blocks of the CDFS receipts (results/p001_cdfs_m1|m2/line_continuum_invariant.json); the historical M31 MOS2 fault-injection receipt (the source of the coupling s).

方法Method: 建议（未经评审）：预注册一个直接检验 —— 例如按角落粒子水平把观测分组，检验 Al 线比是否随组变化；或做 CDFS 自己的注入实验，测相机专属的耦合。在预注册获批前，不跑、不看。Suggestion (not reviewed): pre-register a direct test — for example, group observations by corner particle level and test whether the Al-line ratio varies across groups; or run CDFS's own injection experiment to measure a camera-specific coupling. Nothing is run or looked at before the pre-registration is approved.

成败判据Success vs failure: 若 Al 线比随角落粒子水平变化 → 线门需要 K/B 系统误差项；若不变 → Al 线是比 2.5–8 keV 连续谱更稳的锚，T005 按"未建模系统误差"关闭并记录。if the Al-line ratio varies with the corner particle level → the line gate needs a K/B systematic term; if not → the Al line is a steadier anchor than the 2.5–8 keV continuum, and T005 closes as "unmodelled systematic", recorded.

时间估计Time estimate: 预注册起草 + 评审约 1 周；若做注入实验，再加约 30 分钟运行 × 每相机（建议，未经评审）。pre-registration draft + review ≈ 1 week; if the injection experiment is included, add ≈30 min per camera (suggestion, not reviewed).

先读Read first: cognition-os/experiments/E003_p001_cdfs_blank_field.md Reading 4;03_TRUST_TABLE.md T005、T017。

6. 命令帮助实测表（2026-10-13,--help 实跑）6. Verified --help table (2026-10-13, real runs)

命令Command--help 证实的关键旗标flags confirmed
tools/verify_migration.py--offline, --source-root
scripts/m31_mos2_line_continuum_invariant.py--out, --draws, --seed, --select-lo, --select-hi, --obsids, --field {m31,cdfs}, --camera {M1,M2}, --cdfs-roots, --dry-load, --archived-only, --allow-overlap-diagnostic, --coupling-receipt
scripts/p001_endpoints.pyreceipts… （位置参数）(positional), --out
scripts/p001_regression_check.pynew （位置参数）(positional), --g1, --rtol, --obsids
scripts/m31_mos2_invariant_fault_injection.py--out, --trials, --coupling-replicates, --seed
scripts/m31_mos2_line_stability.py--block, --out, --obsids
来源：本手册作者于 2026-10-13 在 lang 上对每个命令实跑 --help（退出码 0）；旗标列表取自其输出。Source: the author ran --help on every command on lang on 2026-10-13 (exit 0); the flag lists are copied from that output.