34-EFT.WP.Astro.Acceleration v1.0 | 第15章 实现绑定与 API

目录 ／ 文档-技术白皮书 ／ 34-EFT.WP.Astro.Acceleration v1.0

第15章 实现绑定与 API

I. 摘要与范围
本章定义实现绑定与 API 的统一规范与对外接口族 I80-* / API v1，覆盖：CLI/SDK/HTTP 三层接口风格、请求—响应契约、单位与量纲携带、数据卡/管线卡对接、仿真与拟合的可复现执行、错误语义与配额、安全与审计。所有公式与符号以英文记号并用反引号书写；单位采用 SI（默认 3 位有效数字）；凡涉及到达时（ToA）的一切量一律并行返回两种口径并显式声明路径 gamma(ell) 与测度 d ell：
T_arr^A = ( 1 / c_ref ) * ( ∫_{gamma(ell)} n_eff d ell ) 与 T_arr^B = ( ∫_{gamma(ell)} ( n_eff / c_ref ) d ell )，并记录 delta_form。

II. 依赖与引用

1. 符号与单位：第2章（表 2-1，P12-*）。
2. 运动学与通道：第3章 S20-；重联/剪切：第4章 S30-、第5章 S40-；对照：第6章 S45-。
3. 谱形成与传输：第7章 S50-、第8章 S52-。
4. GRB/FRB：第10章 M62-、第11章 M64-。
5. 仿真与基准：第12章 M70-*。
6. 数据/管线/基准卡与发布：第14章 I75-/M75-。
7. 推断与证伪：第13章 M72-*（posterior, evidence, masks, falsification_line）。

III. 规范锚点（本章新增，I80-*）

8. I80-0（接口层次）：提供三层绑定：
   • CLI：astroacc <command> [--flags]；
   • SDK（Python）：from astroacc import api；
   • HTTP/JSON：POST /v1/...。三层共享统一契约与错误语义。
9. I80-1 predict_spectrum(source_class, params) -> Spectrum
   • 入参：source_class（"SNR"|"AGN_Jet"|...），params（含 A_acc(E) 相关形参、E_grid、z）。
   • 出参：N(E)、Phi(E)、alpha_loc(E)（单位含 sr 与能量维度）。
10. I80-2 simulate_reconnection_accel(field_state, R_rec, seed_distribution) -> {dN/dE}
    • 入参：field_state（{T_fil, u_in, u_out, L_sheet, delta_sheet, chi_open}）、R_rec、seed_distribution。
    • 出参：dN/dE，附 see: S30-*。
11. I80-3 shear_accel_cycle(velocity_field, scatter_model, E_init) -> E_final
    • 入参：velocity_field（或张量 S）、scatter_model、E_init。
    • 出参：E_final 与统计量；see: S40-*。
12. I80-4 transport_loss(D_of_E, loss_terms, boundary) -> flux_at_obs
    • 入参：D(E)、loss_terms = {A_rad, A_ad, A_coll, ...}、boundary（Dirichlet/Neumann/Mixed 与 kappa_esc）。
    • 出参：Phi_obs(E)、tau_esc(E)、A_loss(E)；see: S52-*。
13. I80-5 fit_multiband(data_bundle, model, priors) -> {posterior, evidence}
    • 入参：data_bundle（数据卡集合）、model（模型卡）、priors。
    • 出参：posterior、Z、logZ、WAIC/LOO、masks；see: M72-*。
14. I80-6 arrival_time_model(paths, n_eff_model, c_ref) -> {T_arr, delta_form}
    • 入参：paths = {gamma(ell), d ell}、n_eff_model(ν,r)、c_ref。
    • 出参：{T_arr^A, T_arr^B, delta_form}；see: S50-9/S52-8/M62-0/M64-0。
15. I80-7 export_cards(artifact) -> {DatasetCard|ModelCard|PipelineCard}（对接 I75-*）。
16. I80-8 benchmarks_run(task_id, SimCfg) -> {products, metrics}（对接 M70-* 与表 12-4）。
17. I80-9 metrics_validate(metrics, thresholds) -> {pass|fail, diff}（对接 M75-3/M70-8）。
18. I80-10（合同与单位）：所有数值字段强制携带 unit 与 dim；能谱/通量强制包含立体角与能量维度；时间量以 s；长度以 m；电荷以 C；磁场以 T。
19. I80-11（ToA 强制）：凡涉及 T_arr 的请求/响应，必须并行返回 T_arr^A 与 T_arr^B，并附 paths = {gamma(ell), d ell} 与 delta_form。
20. I80-12（可复现性）：请求可选 seed，响应回传 rng_state 与 code_hash/data_hash；产物可注册为基准（register_benchmark）。

IV. 正文结构

I. API 层次与接口风格

• HTTP：/v1/spectrum/predict、/v1/accel/reconnection/simulate、/v1/accel/shear/cycle、/v1/transport/solve、/v1/fit/multiband、/v1/toa/compute、/v1/cards/export、/v1/benchmarks/run、/v1/metrics/validate。
• SDK：函数名与 I80-* 一致；返回带单位的结构化对象。
• CLI：与 SDK 等价子命令，默认输出 products/ 与 metrics.json。

II. 契约与模式（示例）

• 请求示例（HTTP，/v1/fit/multiband）：
• {
• "data_bundle": {"cards": ["cards/dataset_cr.json"], "unit": "SI"},
• "model": {"card": "cards/model_s50.json"},
• "priors": {"alpha_inj": {"type":"Normal","mu":2.2,"sigma":0.2}},
• "seed": 1729
• }
• 响应示例（节选）：
• {
• "posterior": {"alpha_inj": {"mean": 2.18, "sd": 0.06, "unit": "1"}},
• "evidence": {"Z": 1.23e3, "logZ": 7.11},
• "info_criteria": {"WAIC": 512.3, "LOO": 510.8},
• "masks": {"eta_dom": [{"E_min":"1e9 eV","E_max":"1e11 eV","channel":"reconnection"}]},
• "rng_state": "...",
• "hash": {"code_hash": "sha256:...", "data_hash": "sha256:..."}
• }

III. 单位与量纲校核

• 表达式一律带单位与 Dim；Phi(E) 用 m^-2·s^-1·sr^-1·eV^-1；DM 主单位 m^-2（可并列 pc·cm^-3）；RM 用 rad·m^-2。
• 量纲不闭合（如缺失 sr 或能量维度）即返回 422 UNIT_MISMATCH。

IV. 错误语义与配额

1. 错误码：
   • 400 INVALID_ARGUMENT（字段缺失/类型不符）；
   • 412 PRECONDITION_FAILED（缺少 paths 或 delta_form）；
   • 422 UNIT_MISMATCH（单位/量纲不匹配）；
   • 409 CONFLICT（hash/版本冲突）；
   • 429 RATE_LIMIT；
   • 500 INTERNAL。
2. 响应一律返回 trace_id 与 see: 锚点，便于审计与复现。

V. 安全、审计与配额

• 认证：API key（Authorization: Bearer），可选 HMAC 时间戳签名。
• 审计：记录 {who, when, where, code_hash, data_hash, rng_state}，与第14章注册表对齐。
• 配额：按 requests/min 与 compute-min/day 配置；达到配额返回 429 并建议使用异步分段管线（通过 PipelineCard 描述 DAG）。

VI. 工作流与用例（M-系列映射）

1. M-用例 1：谱预测与拟合
   • predict_spectrum 生成先验谱；
   • fit_multiband 产出 {posterior, evidence, masks}；
   • metrics_validate 对照阈值。
2. M-用例 2：重联/剪切通道分离
   • simulate_reconnection_accel、shear_accel_cycle；
   • transport_loss 生成 Phi_obs(E)；
   • fit_multiband 与占优掩码联合剥离。
3. M-用例 3：GRB/FRB ToA 与偏振
   • arrival_time_model 返回 {T_arr^A, T_arr^B, delta_form}；
   • 与第10/11章工作流联合，纳入 L_ToA；
   • export_cards 打包交付。

VII. 与本卷/他卷的交叉引用

• 数学与物理锚点：S20-/S30-/S40-/S50-/S52-/S45-；
• 拟合与证伪：M72-*；
• 仿真与基准：M70-*；
• 数据与管线卡：I75-/M75-。

VIII. 验证、判据与反例

1. 阳性判据：
   • 所有响应字段带 unit/dim 且通过量纲校核；
   • ToA 并行返回两口径且 delta_form 明确，残差可由路径模型解释；
   • metrics_validate 达到表 12-4 阈值；
   • 复现实验 hash 与 rng_state 一致。
2. 阴性判据：
   • 省略 paths 或仅返回单一 T_arr；
   • UNIT_MISMATCH 或 WAIC/LOO 退化未给出原因；
   • register_benchmark 后回归不通过。
3. 对照设计：
   • {only reconnection, only shear, mixed} 三套 API 调用图；
   • {Form A only, Form B only, A+B} ToA 返回对证据的影响；
   • {one-zone, multi-zone} 传输求解在同一数据上的差异。

V. 图表与清单（本章）

4. 表 15-1 端点一览（HTTP）

1. 表 15-2 错误码与语义

1. 表 15-3 SDK 原型（Python，节选）

1. 表 15-4 契约字段与单位（摘录）

IX. 小结
本章以 I80-* / API v1 统一了 CLI/SDK/HTTP 三层接口、单位与量纲携带、ToA 双口径强制、复现与审计、错误与配额，并将本卷物理与统计锚点落在可执行契约之上，用于承载第3–14章的方法、基准与交付。