本仓库用于 GRID 载荷标定数据的处理、拟合与质量检验。
前置依赖： uv（Python 环境管理）和 just（命令运行器）。
curl -LsSf https://astral.sh/uv/install.sh | sh # 安装 uv
cargo install just # 安装 just（或 brew install just）部署：
git clone <repo-url> && cd calibration_process
uv sync # 安装依赖到 .venv
just init {ver} {data-path} # 软链 data/{ver}/raw_data + 建输出目录（{ver} 用 `just` 查看）
just check {ver} [--fix] # 校验新配置/manifest 层与数据链接（--fix 自动建缺失输出目录）详细部署步骤（装 uv/just、挂数据、新载荷初始化等）见仓库根
AGENTS.md的「部署」一节。
跑数据（显式 workflow）：
just all {ver} # 处理该版本全部 TB + EC 数据（单拟合 + 全局拟合）
just all {ver} --until L3 # 只跑到单拟合（L2=只读出、L4=构造点、L5=全局）
just fit-one {ver} tb {id} # 单 measurement 单拟合
just global {ver} tb # TB 二维面拟合
just global {ver} ec # E-C 关系拟合
just discover {ver} {branch} # 扫描目录 -> manifest 草稿
just oracle {ver} # 把本版产物冻结到 .oracle/{ver}/ 供回归比对新版本由显式 workflow 驱动：配置在 src/calibration_process/configs/{ver}/（YAML + strict schema），每一步都调用同一个未改动的科学内核，因此结果与历史实现一致。
GRID 载荷标定分成 TB（温度-偏压）与 EC（能量-道址）两条线。处理是分层的，
每一层都可以选择落盘，just all {ver} --until L1|L2|L3|L4|L5 可停在任意一层：
[L0 原始数据] data/{ver}/raw_data（软链到外部）
│ discover → 人工确认 manifest
▼
[L1 忠实帧] 一个粒子 / 一次采样一行（含解析出的 crc_check）
│ data/{ver}/l1/<key>/{sci,hk,tl}.parquet
▼
[L2 处理输出] (sci, tel) 物理量：amp、遥测换算、CRC/run 过滤、按通道分组
│ data/{ver}/l2/<key>/*.parquet
▼
[L3 单谱拟合] peak / center / sigma / resolution / redchi / qa_flag（file_lib + util_lib 内核）
│ single_process/{TB,EC,NEUTRON}_fit_result/<stem>.{fit.json,spectrum.parquet,pickle}
▼
[L4 构造点] TBPoint / ECPoint（含通道过滤、能量映射；由 fit.json + L2 遥测重建）
▼
[L5 全局拟合] TB：峰位~(温度,偏压) 二维面；EC：按 K 边拆段二次 + 分辨率拟合
tb_logs/、ec_logs/（JSON / npy / 图，与历史格式兼容）
- L1 / L2 是透明加速缓存（
.gitignore，删掉可从 L0 重算）；L3 的*.fit.json/*.spectrum.parquet是跨项目可移植产物，dill*.pickle保留给旧消费方与冻结 oracle。 - TB 单谱峰拟合不做温度偏压校正（corr = 1），温压依赖交给 L5 的二维面建模。
- EC 单谱在 L3 生成阶段做 TV 校正：以 TB 二维面为参考（默认 25°C/28.5V），
把每个 EC 文件修正到该参考点（
get_spectrum里对 amp 乘因子）。 - 各层的落盘格式、缓存键与跨项目读取见 docs/intermediate_data.md。
- EC 再分成放射源与X 光机两条分支（背景/选点不同，见 workflows.md）。
- 每个版本的实际选择规则与特殊处理见 docs/workflows.md。
最小流程（新配置 + 新数据，无需改科学内核）：
calib scaffold {ver} --data-dir /path/to/data # 生成 configs/{ver}/*.yaml + 目录 + 软链 raw_data
# 1) 编辑 configs/{ver}/payload.yaml：reader / bin_width / adc_max / 分支路径 / channel_count
# 2) 若 reader 常量不同，改 configs/{ver}/reader.yaml（engine + handler + params）
# 3) 若包格式不同：新增 lib_reader/src/lib_reader/reader{ver}/，并在 lib_reader/__init__.py 注册
calib discover {ver} tb # 扫描 -> manifest 草稿（tb / ec_source / ec_xray 各一次）
# 4) 人工确认 manifest（去重、剔除坏点、设 use / channels.use）
# 5) 填 configs/{ver}/fit_range_tb.yaml / fit_range_ec_source.yaml / fit_range_ec_xray.yaml
calib check {ver} # 校验配置/manifest 层与数据链接
calib all {ver} # 全流程：单拟合 + TB/EC 全局拟合- 若该版本的流程与已有版本完全相同，在
workflows/versions/里复用对应文件的enumerate_measurements，并去workflows/registry.py注册即可（版本选择只发生一次）。 - 若流程真的不同（不同的选点/背景/分辨率/模型），在
workflows/versions/v{ver}.py里显式写出差异，并把差异点写进 docs/workflows.md。 - 配置都是 strict schema：未知字段/非法枚举/重复 id/指向缺失文件 都会在
calib check或 workflow 开始前失败，报错会带上 version/branch/measurement/字段。 - 参考：不同读者 / 包格式判定、HK 截取、找峰、Co60 双高斯等工程细节见 docs/data.md；每个载荷现有 workflow 见 docs/workflows.md。
详细文档在 docs/ 目录（清单与写作约定见 docs/README.md）：
| 文档 | 内容 |
|---|---|
| docs/workflows.md | 每个载荷各自的显式 workflow（选点、reader、背景轮转、分辨率、特殊处理） |
| docs/workflow_matrix.md | 历史 workflow 完整审计矩阵（每个版本实际做了什么） |
| docs/data.md | 数据准备与目录约定：新配置/manifest 格式、新载荷接入流程与方法论 |
| docs/results.md | 结果产物与 QA 指标说明 |
| docs/12B_13B/data.md | 12B/13B 类载荷的数据说明（点位对照表、各文件的特殊情况） |
| docs/N1/data.md | N1（GRIDN1）的数据说明（GAGG/CLYC 双数据集、扫描分段、坏点） |
| docs/payloads_data.md | 其它 7 个载荷的数据说明（简化版：通用结构 + 各版本选点/排除） |
| docs/intermediate_data.md | 分层中间数据（L1/L2 缓存、L3 可移植产物、pickle）、怎么读、跨项目分析、定制 pipeline |
每类载荷的数据说明单独放一个目录（如 docs/12B_13B/），新增载荷时仿照添加。
| 命令 | 说明 |
|---|---|
just |
查看所有命令 |
just init {ver} {path} |
初始化版本：软链数据 + 建目录 |
just check {ver} |
校验新配置/manifest 层与数据链接（--fix 建缺失目录） |
just all {ver} [--until LN] |
处理该版本全部数据；--until 停在 L1/L2/L3/L4/L5 |
just fit-one {ver} {branch} {id} |
处理单个 measurement 单拟合 |
just fit {ver} {branch} |
处理单个分支单拟合 |
just global {ver} {branch} |
TB/EC 全局拟合 |
just discover {ver} {branch} |
扫描目录生成 manifest 草稿 |
just list {ver} {branch} |
列出已确认 measurement |
just config {ver} {branch} {id} |
查看单个 measurement 的 resolved 配置 |
just new-payload {ver} |
为新载荷生成 YAML 配置/目录骨架 |
just oracle {ver} |
把本版产物冻结到 .oracle/{ver}/（回归基准） |
just compare {ver} |
新流程 vs 冻结 legacy oracle 差异对比 |
.
├── README.md
├── docs/ # 详细文档（清单见 docs/README.md）
│ ├── README.md # 文档目录说明与清单
│ ├── workflows.md # 每个载荷各自的显式 workflow
│ ├── workflow_matrix.md # 历史 workflow 审计矩阵
│ ├── data.md # 数据准备与目录约定、接入方法论
│ ├── results.md # 结果产物与 QA 指标
│ ├── payloads_data.md # 其它 7 个载荷的数据说明（简化版）
│ ├── intermediate_data.md # 分层中间数据（L1/L2 缓存、L3 可移植产物）/ 跨项目 / 定制 pipeline
│ ├── 12B_13B/ # 12B/13B 类载荷的数据说明（详细版）
│ │ └── data.md # 点位对照表、各数据文件的特殊情况
│ └── N1/ # GRIDN1 载荷的数据说明
│ └── data.md # GAGG/CLYC 双数据集、中子、EC、坏点
├── data/{ver}/ # 各版本数据目录
│ ├── raw_data -> /path/to/data # 原始数据软链（L0）
│ ├── l1/ # L1 忠实帧 parquet 缓存（可删可重算）
│ ├── l2/ # L2 处理输出 parquet 缓存（可删可重算）
│ ├── single_process/ # L3 单拟合产物（fit.json / spectrum.parquet / pickle / 图）
│ ├── tb_logs/ # TB 面拟合产物
│ └── ec_logs/ # E-C 拟合产物
├── lib_reader/ # 各版本数据读取库（workspace 子包）
├── lib_plot/ # 绘图库（workspace 子包）
├── grid_common/ # 共享数值（谱/分辨率/naming，中立包）
├── src/calibration_process/
│ ├── cli.py # calib 命令入口
│ ├── pipeline.py # 高层编排（discover/list/fit/global/all/--until）
│ ├── config_schema.py # strict Pydantic schema（payload/reader/analysis/fit_range/manifest）
│ ├── manifest.py # manifest 发现与加载（运行时不再扫目录）
│ ├── runtime.py # 解析后的运行时配置（resolved context）
│ ├── deploy.py # 部署校验 + 新载荷脚手架（calib check/scaffold）
│ ├── products.py # typed 中间产物（FileRunSpec/TBPoint/ECPoint）
│ ├── file_lib.py # 单文件读取与拟合（protected kernel）
│ ├── util_lib.py # 工具函数（拟合、阈值，protected kernel）
│ ├── configs/{ver}/ # 每版本 YAML 配置 + manifest
│ └── workflows/
│ ├── common.py # 复用内核的 stage（single fit/points/global）
│ ├── registry.py # 版本 -> workflow 模块（选择只发生一次）
│ └── versions/v{ver}.py # 每版本显式 workflow（文件选择规则）
├── pyproject.toml
├── uv.lock
└── justfile
- 12B 简易结果
- 12B 完整结果（TB: 备份目录全 54 点位温偏面拟合，适用偏压 ≥27.5V 内残差 <3.5%；EC: 与其他载荷相同的 K 边拆段二次拟合（EC_low/EC_high 输出 schema 一致），锚点为 Am241/Na22/Cs137/Co60（双高斯拟合 1332 keV）+ X光机 20-100 kV（低管压点的能量按管压赋值、有已知系统偏差，仅作参考；见 docs/12B_13B/data.md））
- N1 温偏 + EC（TB: GAGG/CLYC 分数据集二维面，合并后 GAGG ch1/2 与参考逐位一致、CLYC ch0/3 在 ±1.6%；EC: 放射源 + X 光机单条二次；中子束流为自洽快照；见 docs/N1/data.md）
- 13B 完整结果
- 10B, 11B 塑闪结果
- wqd
- 丘智勇
- Lee
- yhl
- xsq(Haruka Kujo)