35-EFT.WP.EDX.OrientedTension v1.0 | 附录 C 数据/模型/管线卡（OT）

目录 ／ 文档-技术白皮书 ／ 35-EFT.WP.EDX.OrientedTension v1.0

附录 C 数据/模型/管线卡（OT）

I. 摘要与范围
本附录定义 OT（Oriented Tension）工程中的 DatasetCard、ModelCard、MetrologyCard、PipelineCard 四类卡片之统一模式（Schema）、必填字段、Unit/Dim 携带规则、see: 锚点、哈希与版本化、校验与发布流程。若包含 ToA 字段，必须并行记录两口径并显式 {gamma(ell), d ell} 与 delta_form。

II. 依赖与引用

• 版式与编号：EFT 技术白皮书与技术备忘模板 全面清单 v0.1。
• 本卷锚点：Ch.2（P80-1/4/5/6），Ch.3（S80-1/2），Ch.4（S80-3/4），Ch.5（M80-1…4），Ch.6（S80-5/6），Ch.7（S80-7/8），Ch.10（S80-15…18），Ch.12（I80-*）。
• 数据与管线体系：I75-*/M75-*（第14章口径，沿用本卷符号与单位）。

III. 规范锚点（本附录新增，I75-/M75-）

• I75-OT-0（卡片模式与注册）：四类卡片以 JSON Schema 定义，统一必填字段、Unit/Dim、see: 锚点、{code_hash,data_hash,rng_state} 与语义化版本。
• I75-OT-1（ToA 字段强制）：若出现 ToA，卡片并列 T_arr^A/T_arr^B/delta_form，在 integrals 指定 {path:"gamma(ell)", measure:"d ell"}。
• M75-OT-1（校验与发布流程）：Schema 校验→Unit/Dim 审计→指标门限核验→注册表发布；失败即阻断。

IV. 正文结构

I. DatasetCard（数据卡）模式与示例

• 最小字段（★ 为必填）
  | 区段 | 字段 | 说明 | 示例/单位 |
  |---|---|---|---|
  | ★meta | dataset_id, version, instrument, band, time_span | 基础元数据 | "OT_LC_V1","1.0.0","POLCAM","400–800 nm","2023-2025" |
  | ★spec | columns[{name, unit, dim, description, see}] | 列定义（含 Unit/Dim） | Q11: 1, 1；Phi_E: W·m^-2 |
  | | sampling, calibration | 采样与标定口径 | "scan=HEALPix; calib=v2" |
  | ★quality | systematics, covariance, masks | 系统学、协方差、掩码 | masks: eta_dom |
  | integrals | path, measure | ToA 路径与测度（若适用） | "gamma(ell)","d ell" |
  | ToA | T_arr^A, T_arr^B, delta_form | ToA 双口径（若适用） | s, s, "A" |
  | ★hash | data_hash, card_hash | 完整性 | sha256:* |
  | ★see | anchors | 物理/方法锚点 | S80-1/4/7 |
• JSON 示例（节选）

{

"meta": {"dataset_id":"OT_LC_V1","version":"1.0.0","instrument":"POLCAM","band":"400–800 nm","time_span":"2023-2025"},

"spec": {

"columns": [

{"name":"E","unit":"eV","dim":"E","description":"photon energy","see":"Ch.6"},

{"name":"Q11","unit":"1","dim":"1","description":"order tensor component","see":"S80-2"},

{"name":"Phi_E","unit":"W·m^-2","dim":"M T^-3","description":"energy flux","see":"S80-7"}

],

"sampling":"healpix-nside=64",

"calibration":"pol_v2_gainmap"

},

"quality":{"systematics":"3% abs","covariance":"provided","masks":["eta_dom"]},

"hash":{"data_hash":"sha256:...","card_hash":"sha256:..."},

"see":["S80-1","S80-7"]

}

II. ModelCard（模型卡）模式与示例

• 最小字段（★ 为必填）
  | 区段 | 字段 | 说明 | 示例 |
  |---|---|---|---|
  | ★meta | model_id, version, family | 模型族与版本 | "OT_S80_v1","1.1.0","S80" |
  | ★params | {name, transform, prior, bounds, unit, dim, see} | 参见附录 B | A,K,tau_relax,D_Q,Λ_{ijkl} |
  | channels | {couplings} | {χ_E,χ_B,χ_u,D1,α_E,α_B,κ_s} | {...} |
  | constraints | symmetry, SPD, traceless | 物理/数学约束 | "Q:traceless, D_eff:SPD" |
  | diagnostics | evidence, IC | 证据与信息准则（可选） | logZ, WAIC |
  | ★hash | code_hash, card_hash | 追溯 | sha256:* |
  | ★see | anchors | 物理锚点 | S80-3/4/5/6 |
• JSON 示例（节选）

{

"meta":{"model_id":"OT_S80_v1","version":"1.1.0","family":"S80"},

"params":[

{"name":"A","transform":"log","prior":"LogU[1e0,1e6]","bounds":[1e-2,1e9],"unit":"J·m^-3","dim":"M L^-1 T^-2","see":"S80-4"},

{"name":"tau_relax","transform":"log","prior":"LN(-2,1)","bounds":[1e-6,1e4],"unit":"s","dim":"T","see":"S80-4"},

{"name":"D_Q","transform":"log","prior":"LogU[1e-14,1e-8]","bounds":[1e-16,1e-6],"unit":"m^2·s^-1","dim":"L^2 T^-1","see":"S80-4"}

],

"channels":{"chi_E":{"prior":"N(0,σ)"}, "alpha_E":{"prior":"U[-0.2,0.2]"}},

"constraints":{"symmetry":"material-group","SPD":["D_eff"],"traceless":["Q"]},

"hash":{"code_hash":"sha256:...","card_hash":"sha256:..."},

"see":["S80-3","S80-4","S80-5","S80-6"]

}

III. MetrologyCard（计量卡）模式与示例

• 最小字段（★ 为必填）
  | 区段 | 字段 | 说明 | 示例 |
  |---|---|---|---|
  | ★meta | metrology_id, version, instrument | 标识 | "OT_METRICS_V1","1.0.0","POL+MECH" |
  | ★obs | R_inst, noise, covariance | 仪器核与噪声 | R_inst: psf, MTF; S_n: PSD |
  | ★products | observables | 观测项列表与单位 | S_pol, strain, Phi_E |
  | audit | UnitsAudit.log | 量纲审计引用 | path/to/log |
  | ★see | anchors | M80-1…4 | ["M80-1","M80-2"] |
• JSON 示例（节选）

{

"meta":{"metrology_id":"OT_METRICS_V1","version":"1.0.0","instrument":"POL+MECH"},

"obs":{"R_inst":{"type":"psf+mtf","version":"2.1"},"noise":{"PSD":"provided"},"covariance":"provided"},

"products":[{"name":"S_pol","unit":"1","dim":"1","see":"M80-1"},{"name":"strain","unit":"1","dim":"1","see":"M80-2"}],

"see":["M80-1","M80-2","M80-4"]

}

IV. PipelineCard（管线卡）模式与示例

• 最小字段（★ 为必填）
  | 区段 | 字段 | 说明 | 示例 |
  |---|---|---|---|
  | ★meta | pipeline_id, version | 标识 | "OT_PIPE_V2","2.0.0" |
  | ★graph | nodes[], edges[] | DAG 节点类型∈{ingest, calibrate, simulate, fit, validate, export} | 见下 |
  | node[i] | {type, inputs, outputs, image/env, seed, resources} | 节点参数 | docker://ot:1.3 |
  | acceptance | thresholds | 指标门限表 | SpecMAE, EDX-closure |
  | exports | {products/, metrics.json, masks/, repro/} | 导出布局 | 固定目录 |
  | audit | {code_hash, data_hash, rng_state} | 审计字段 | — |
  | ★see | anchors | 关联锚点 | M80-31…38, M80-41 |
• JSON 示例（节选）

{

"meta":{"pipeline_id":"OT_PIPE_V2","version":"2.0.0"},

"graph":{

"nodes":[

{"id":"n1","type":"ingest","inputs":["cards/dataset_ot.json"],"outputs":["staged/"],"env":"docker://ot:1.3","seed":1729},

{"id":"n2","type":"fit","inputs":["staged/","cards/model_ot.json"],"outputs":["products/posterior.zarr"],"env":"docker://ot:1.3"},

{"id":"n3","type":"validate","inputs":["products/posterior.zarr"],"outputs":["metrics.json"],"env":"docker://ot:1.3"}

],

"edges":[["n1","n2"],["n2","n3"]]

},

"acceptance":{"SpecMAE":"<=0.03","EDX-closure":"<=1σ"},

"exports":{"products/":true,"metrics.json":true,"masks/":true,"repro/":true},

"audit":{"code_hash":"sha256:...","data_hash":"sha256:...","rng_state":"..."},

"see":["M80-31","M80-35","M80-41"]

}

V. 校验与一致性（M75-OT-1）

• Schema 校验：四类卡片均须通过 JSON Schema 与必填字段校核。
• Unit/Dim 审计：所有数值列必须携带 unit/dim，Q_ij 为无量纲且 Tr(Q)=0；Phi(E)（若有）为 m^-2·s^-1·sr^-1·eV^-1。
• ToA 合规（若适用）：并行 T_arr^A/T_arr^B/delta_form，integrals 显式 {gamma(ell), d ell}。
• 哈希一致性：data_hash 与载荷一致；code_hash 与运行环境一致；失败即拒绝发布。

VI. 发布与审计（I75-OT-0 / M75-OT-1）

• 环境锁定：导出 repro/（容器镜像、依赖版本、随机种子）。
• 审计清单：汇总 {code_hash, data_hash, rng_state, cards, masks, metrics} 并入注册表。
• 版本与兼容：MAJOR 变更须附迁移脚本；MINOR/PATCH 保持后向兼容字段。

VII. 指标与门限（与 Ch.10/11 对齐）

• 指标集合：SpecMAE、EDX-closure、AnisoMap-PSNR、logZ、ΔlogZ。
• 通过条件：达到门限即 pass，否则 fail 并输出差分报告与 DiffReport.md。

VIII. 模板清单

• DatasetCard 列模板（摘录）
  | name | unit | dim | description | see |
  |---|---|---|---|---|
  | E | eV | E | photon energy | Ch.6 |
  | Q11,Q22,Q33,... | 1 | 1 | order-tensor comps | S80-2 |
  | Phi_E | W·m^-2 | M T^-3 | energy flux | S80-7 |
  | T_arr^A/B* | s | T | ToA dual-form | Ch.12 |

* 若使用 ToA。

• ModelCard 参数模板（摘录）
  | name | transform | prior | bounds | unit | dim | see |
  |---|---|---|---|---|---|---|
  | A | log | LogU[1e0,1e6] | [1e-2,1e9] | J·m^-3 | M L^-1 T^-2 | S80-4 |
  | tau_relax | log | LN(-2,1) | [1e-6,1e4] | s | T | S80-4 |
  | D_Q | log | LogU[1e-14,1e-8] | [1e-16,1e-6] | m^2·s^-1 | L^2 T^-1 | S80-4 |
• Pipeline 节点模板（摘录）
  | type | inputs | outputs | 必填 | 说明 |
  |---|---|---|---|---|
  | ingest | DatasetCard | staged/ | ★ | 校验与标准化 |
  | fit | staged/, ModelCard | posterior, evidence | ★ | 反演与证据 |
  | validate | products/ | metrics.json | ★ | 指标与门限 |
  | export | targets | bundle | ★ | 注册与发布 |

—— 本附录为 OT 的卡片化与工程发布基线，确保数据—模型—管线在全链路内的可验证、可复现与可审计。