当前设计The current design

项目有两条并行的“设计”：一条是管线（S2Fitting 软件本身，从 ODF 到拟合结果），一条是科学分析线（E018 系列的前向模型与速度场拟合）。两条都遵守同一个原则：SAS 拥有仪器，Python 拥有编排与验证，Sherpa/scipy 拥有似然拟合。The project has two parallel "designs": the pipeline (the S2Fitting software itself, from ODF to fit results) and the science line (the E018-series forward model and velocity fits). Both follow one principle: SAS owns the instrument, Python owns orchestration and validation, Sherpa/scipy owns the likelihood fit.

1. 所有权边界与进程分离1. Ownership boundaries and process separation

SAS 拥有 XMM 校准、事件坐标、源区域、beta 光谱、背景光谱与 RGS 响应矩阵；Sherpa 拥有物理模型求值、响应折叠、泊松似然、优化与置信区间；S2Fitting 只拥有编排、验证、溯源与结果格式。这条边界写在 docs/architecture.md 的开头，是项目的宪法。SAS owns XMM calibration, event coordinates, source regions, beta spectra, background spectra and RGS response matrices; Sherpa owns physical model evaluation, response folding, the Poisson likelihood, optimisation and confidence intervals; S2Fitting owns only orchestration, validation, provenance and result formatting. This boundary opens docs/architecture.md and is the project's constitution.

SAS 与 Sherpa 需要互不兼容的 HEADAS 环境，所以绝不能在同一个进程里运行。管线的做法：两个启动器都从清空了 SAS/CIAO/HEASoft/CALDB/PFILES/动态库变量的环境开始；SAS 启动器再初始化 HEASoft 与 SAS 20；Sherpa 启动器 source CIAO 脚本并把 HEADAS 与 XSPEC_MDATA_DIR 指向 CIAO 的谱模型数据。SAS and Sherpa need incompatible HEADAS environments, so they must never run in the same process. The pipeline's approach: both launchers start from an environment with SAS, CIAO, HEASoft, CALDB, PFILES and dynamic-library variables removed; the SAS launcher then initialises HEASoft and SAS 20; the Sherpa launcher sources the CIAO script and points HEADAS and XSPEC_MDATA_DIR at CIAO's spectral model data.

来源：docs/architecture.md（所有权边界与进程分离两节）；实现见 src/s2fitting/runtime.py（清空与重建环境）与 scripts/lang-python.sh（CIAO Python 启动器，转发调用者的线程变量）。Source: docs/architecture.md (the ownership boundaries and process separation sections); implemented in src/s2fitting/runtime.py (which clears and rebuilds the environment) and scripts/lang-python.sh (the CIAO Python launcher, which forwards the caller's thread variables).

2. 管线数据流2. The pipeline data flow

管线一次 run 的 9 步（docs/architecture.md 数据流一节）：The 9 steps of one pipeline run (docs/architecture.md, the data flow section):

1. 解析目标位置：schema v5 之后接受赤经/赤纬（十进制度），由 SAS rgsproc srcstyle=radec 换算到 RGS 场参考系的 DELTA_DISP/DELTA_XDSP。Resolve the target position: from schema v5 on, decimal-degree RA/Dec is accepted and SAS rgsproc srcstyle=radec converts it to the RGS field-reference DELTA_DISP/DELTA_XDSP.
2. 在源周围解析一个 DISP/XDSP 矩形网格（任意正格数），绝对坐标写进 run manifest。Resolve a rectangular DISP/XDSP grid with arbitrary positive cell counts around the source; its absolute coordinates are persisted in the run manifest.
3. 用 SAS prepare 选定的 RGS 事件与源表产品。Use SAS to prepare the selected RGS event and source-list products.
4. 用 rgsregions xdspregions 为每个 XDSP 行建一个固定矩形；行相对限先换算成绝对 RGS 场参考坐标。Build one fixed XDSP rectangle per row with rgsregions xdspregions; row-relative limits are converted to absolute RGS field-reference coordinates first.
5. 每个 XDSP 行抽一条原生 beta 源光谱（bkgcorrect=no），验证为 TOTAL COUNTS 产品。schema v6 把背景独立解析为观测泊松 COUNTS、rgsbkgmodel RATE/STAT_ERR 模板或无背景。Extract one native beta source spectrum per XDSP row (bkgcorrect=no) and validate it as a TOTAL COUNTS product. Schema v6 resolves the background independently as observed Poisson COUNTS, an rgsbkgmodel RATE/STAT_ERR template, or no background.
6. 从同一固定矩形为每个空间格生成一个 beta RSPMAT。rgsrmfgen 在每个 beta 通道上把随 beta 变化的点源 cross-PSF 积分过该多边形，所以孔径透过率随能量变化而几何边界固定。Generate one beta RSPMAT per spatial cell from the same fixed rectangle. rgsrmfgen integrates the beta-dependent point-source cross-PSF over that polygon at each beta channel, so the aperture transmission stays energy dependent while the geometric boundaries are fixed.
7. 在 Sherpa 里用 BIC 比较配置的热候选模型，然后把选中的共享谱形穿过每个 DISP 格的响应拟合，每格一个空间标度。观测 COUNTS 背景用 WStat；模板 RATE 缩放成固定通道期望加进源模型，用 CStat；无背景用纯源 CStat。In Sherpa, compare the configured thermal candidates with BIC, then fit the selected shared shape through every DISP-cell response with one spatial scale per cell. Observed COUNTS backgrounds use WStat; a template RATE is scaled into a fixed detector-channel expectation and added to the source model under CStat; no-background runs use source-only CStat.
8. 仅当请求了对比背景时，用对比背景重复选中模型；模板与无背景模式把敏感性检查记为不适用。Repeat the selected model with a comparison background only when an observed comparison PHA was requested; template and none modes record the sensitivity check as not applicable.
9. 发布热参数、模型选择证据、背景与 RSPMAT 有效面积诊断，以及一个 XDSP 行、DISP 列的归一化矩阵。Publish thermal parameters, model-selection evidence, background and RSPMAT effective-area diagnostics, and one normalization matrix with XDSP rows and DISP columns.

来源：docs/architecture.md 数据流一节（9 步逐条对应）；docs/input-output-contract.md（版本化文件与计数语义）。Source: docs/architecture.md, the data flow section (9 steps in order); docs/input-output-contract.md (the versioned file and count semantics).

3. 科学线：E018 前向模型3. The science line: the E018 forward model

科学线不走 s2fit run，而是围绕冻结的输入包（pack_.npz）构建：The science line does not go through s2fit run; it is built around the frozen input packs (pack_.npz):

1. 天空模板：Chandra O VII 波段图像（0.50–0.62 keV，E018c 冻结产品），在 0.05′ 天空网格上积分。Sky template: the Chandra O VII band image (0.50-0.62 keV, frozen E018c products), integrated on a 0.05 arcmin sky grid.
2. 速度模型：每个天空像素的视向速度 \(v = v_0 + \mathbf{g}\cdot\mathbf{x}\)，加一个高斯弥散 \(\sigma_v\)（模型 L）；或壳层加结点两分量（模型 C2）；或按色散符号把天空分成两半、各带自己的速度偏移与宽度（模型 L2，E018c）。Velocity model: a line-of-sight velocity \(v = v_0 + \mathbf{g}\cdot\mathbf{x}\) per sky pixel plus one Gaussian dispersion \(\sigma_v\) (model L); or a shell-plus-knot two-component model (C2); or the sky split by the dispersion sign into two halves with their own velocity offsets and widths (model L2, E018c).
3. 仪器算子：每个观测的探针响应（11 个交叉色散节点，第 2 阶段换成 65 个位置的细网格），把每个天空像素的光折叠成每条带的期望计数；曝光剖面 \(\epsilon\)（通道）与缩放背景相加。Instrument operator: each observation's probe responses (11 cross-dispersion nodes, replaced by the 65-position fine grid in stage 2) fold each sky pixel's light into expected counts per strip; the exposure profile \(\epsilon\) (per channel) and the scaled background are added.
4. 讨厌参数组：D0（无）、F（每观测偏移 \(\delta X_o\)）、A（加尺度 \(w\)）、E（再加线翼 \(f\) 与条带外接受度 \(a\)）、E-Cauchy（线翼换成 Cauchy 核）。Nuisance sets: D0 (none), F (one offset \(\delta X_o\) per observation), A (adds the scale \(w\)), E (adds the wing \(f\) and the out-of-strip acceptance \(a\)), E-Cauchy (the wing replaced by a Cauchy kernel).
5. 拟合：最小化所有观测、所有条带的联合 CStat；Fisher SD 与 profile 68 % 区间都报告。Fit: minimise the joint CStat over all observations and strips; both Fisher SDs and profile 68 % intervals are reported.

来源：cognition-os/experiments/E018_real-data-readiness.md（E018a–g 各子任务与红队 RT15/RT17 的设计检验）；.agent/jobs/2026-10-19-e018c-ovii-stage2/BRIEF.md（阶段 2 的细网格与 L2f 模型）；cognition-os/insights/I029_n132d-ovii-velocity-stage1.md（五组配置的测量表）。Source: cognition-os/experiments/E018_real-data-readiness.md (the E018a-g subtasks and the red-team RT15/RT17 design checks); .agent/jobs/2026-10-19-e018c-ovii-stage2/BRIEF.md (stage 2's fine grid and the L2f model); cognition-os/insights/I029_n132d-ovii-velocity-stage1.md (the measurement table of the five configurations).

4. run 目录与不可变性4. Run directories and immutability

每个 run 是一个不可变目录（docs/architecture.md run layout一节）：Every run is an immutable directory (docs/architecture.md, the run layout section):

//
  manifest.json
  state.json
  logs/
  prepare/
  extraction/
  responses/
  fit/
  results/

每个阶段只有在全部预期输出通过验证后才写状态；已存在的 run 目录默认不可变。绝不复用已发布的 run-id。Each stage writes its state only after all expected outputs pass validation; existing run directories are immutable by default. Never reuse a published run-id.

来源：docs/architecture.md run layout 一节；src/s2fitting/run.py（create_run 拒绝覆盖、sha256 与 atomic_json）。Source: docs/architecture.md, the run layout section; src/s2fitting/run.py (create_run refuses overwrite; sha256 and atomic_json).