40-EFT.WP.Materials.Superconductivity v1.0 | 第12章 接口与实现绑定

目录 ／ 文档-技术白皮书 ／ 40-EFT.WP.Materials.Superconductivity v1.0

第12章 接口与实现绑定

I. 范围与原则

• S120-1（目标）：本章固化跨团队与跨管线的对外接口与实现绑定，覆盖到达时/传播、测量矩阵、仿真栈、推断与模型比较、材料设计与张度工程、案例库与数据管理。
• S120-2（统一口径）：请求/响应对象一律显式声明 unit_system:"SI"、references（“卷名 + 版本 + 锚点”）、contract_version、schema_version；所有公式/符号/定义统一英文并通过 check_dim。
• S120-3（命名与幂等）：接口代号 I12-*；幂等操作要求提供 request_id 与重放策略。
• S120-4（路径与到达时）：凡涉及 T_arr 必须在 contracts 中声明两口径之一（pulled_const 或 integrand）、delta_form、gamma(ell) 与 d ell。
• S120-5（错误模型）：错误对象统一为
• { "code": "E/…", "message": "...", "at": "stage.name", "hint": "...", "refs": ["..."] }

其中 code 分为 E/INPUT、E/UNIT、E/CONTRACT、E/NUMERIC、E/IDENTIFIABILITY、E/RESOURCE、E/INTERNAL。

II. 接口总览与别名映射（从各章占位到最终绑定）

1. S120-6（类别）：
   • 到达时/传播：I12-AT-*（对应第7章 I7-*）
   • 测量矩阵/计量：I12-MM-*（对应第8章 I8-*）
   • 仿真栈：I12-SIM-*（对应第10章 I10-6）
   • 推断/比较：I12-INF-*（对应第10章 I10-1~5,7）
   • 设计与张度工程：I12-DES-*（对应第9章 I9-*）
   • 案例库/数据：I12-CASE-*（对应第11章 I11-*）
2. S120-7（别名）：维持向后兼容的别名表：I7-1≡I12-AT-fit_from_cavity，I8-1≡I12-MM-build_measurement_matrix，I10-1≡I12-INF-run_hmc，……（完整表见本章附录）。

III. 通用数据契约与对象模式

• S120-8（Request 原型）：
• {
• "request_id": "uuid",
• "inputs": {...},
• "contracts": {
• "unit_system": "SI",
• "convention": "pulled_const|integrand",
• "delta_form": "c_ref^-1 * ∫ n_eff dℓ | ∫ (n_eff/c_ref) dℓ",
• "gamma": "piecewise: free|fixture|substrate|film|sample",
• "d_ell": "m"
• },
• "priors": {...},
• "cal_bundle": {...},
• "references": ["EFT.WP.Core.Equations v1.1:Ch.2 S20-*", "..."],
• "schema_version": "12.0.0",
• "contract_version": "1.0"
• }
• S120-9（Response 原型）：
• {
• "request_id": "uuid",
• "outputs": {...},
• "meta": {"ci": {...}, "units": {...}, "runtime": {...}},
• "warnings": [{"code":"W/...", "message":"...", "refs":["..."]}],
• "errors": []
• }
• S120-10（单位与量纲）：所有数组/张量附带 units 字段，如 {"lambda_L":{"unit":"m"}, "xi":{"unit":"m"}}；接口实现必须通过 check_dim。

IV. 到达时与传播接口（I12-AT-*, 第7章绑定）

• I12-AT-fit_from_cavity（原 I7-1）
• inputs: { f, Q, phi(ω), mode_map, convention, path }
• returns: { lambda_L(T), sigma(ω), xi(T), ci }
• I12-AT-compute_arrival_time（原 I7-2）
• inputs: { S21_or_trace, convention, path, unwrap }
• returns: { T_arr(ω), meta:{unwrap_stats, phase_jumps} }
• I12-AT-fit_thinfilm_transmission（原 I7-3）
• inputs: { T_arr(ω), model, priors }
• returns: { lambda_L, sigma(ω), d, post }
• I12-AT-deembed_path（原 I7-4）
• inputs: { standards, scheme }
• returns: { n_bg(ω), T_arr_bg, drift_model }
• I12-AT-fuse_multi_band（原 I7-5）
• inputs: { results[], weights }
• returns: { merged_params, consistency }

V. 测量矩阵与计量接口（I12-MM-*, 第8章绑定）

• I12-MM-build_measurement_matrix（原 I8-1）
• inputs: { config, cal_bundle, contracts }
• returns: { J, B, Σ_y, meta }
• I12-MM-compute_fisher（原 I8-2）
• inputs: { J, Σ_y, priors? }
• returns: { F, cond, rank, C }
• I12-MM-optimize_design（原 I8-3）
• inputs: { design_space, budget, criterion }
• returns: { x*, F*, covθ* }
• I12-MM-propagate_uncertainty（原 I8-4）
• inputs: { J, Σ_y, Σ_ν?, priors? }
• returns: { covθ, ci }
• I12-MM-assess_identifiability（原 I8-5）
• inputs: { J, Σ_y }
• returns: { scores, weak_dirs, suggestions }
• I12-MM-fuse_matrices（原 I8-6）
• inputs: { J_list, Σy_list, weights }
• returns: { J_stack, Σy_stack }
• I12-MM-validate_contracts（新增）
• inputs: { dataset_card }
• returns: { pass: bool, report, anchors_checked }

VI. 仿真栈接口（I12-SIM-*, 第10章绑定）

• I12-SIM-forward（原 I10-6）
• inputs: { θ, η, x, channels }
• returns: { y_hat, J, meta }
• I12-SIM-make_synthetic（原 I10-7）
• inputs: { case_id, noise, drift, outliers }
• returns: { data, truth }
• I12-SIM-benchmark_suite（新增）
• inputs: { suite_id, configs[] }
• returns: { results, scores }

VII. 推断与模型比较接口（I12-INF-*, 第10章绑定）

• I12-INF-run_hmc（原 I10-1）
• inputs: { model, data, priors, init, adapt }
• returns: { posterior, rhat, ess, traces }
• I12-INF-run_vi（原 I10-2）
• inputs: { model, data, priors, family }
• returns: { q(θ), elbo_hist, diag }
• I12-INF-run_smc（原 I10-3）
• inputs: { model, data, schedule }
• returns: { weighted_samples, logZ }
• I12-INF-evidence（原 I10-4）
• inputs: { traces_or_q, method }
• returns: { logZ, se }
• I12-INF-posterior_predictive（原 I10-5）
• inputs: { traces_or_q, sim, N }
• returns: { y_rep, metrics }
• I12-INF-orchestrate（新增，端到端）
• inputs: { y, J, Σ_y, priors, strategy }
• returns: { θ_hat, post, logZ, diagnostics }

VIII. 设计变量与张度工程接口（I12-DES-*, 第9章绑定）

• I12-DES-update_design_variables（原 I9-1）
• inputs: { targets, constraints }
• returns: { θ*, recipe, risk, cost }
• I12-DES-plan_strain_field（原 I9-2）
• inputs: { mask, ε_target, budget }
• returns: { ε_ij(r), process }
• I12-DES-engineer_interface（原 I9-3）
• inputs: { stack, Γ_if_target, symmetry }
• returns: { Γ_if, ρ_int, QA }
• I12-DES-thickness_coupling_scan（原 I9-4）
• inputs: { d_grid, s_grid }
• returns: { lambda_L(d), H_c2(d), K_T, K_G }
• I12-DES-close_loop_infer（原 I9-5）
• inputs: { A, α_*, K_*, data }
• returns: { posterior, ΔA, Δα, ΔK }

IX. 案例库与数据管理接口（I12-CASE-*, 第11章绑定）

• I12-CASE-load_card（原 I11-1）
• inputs: { path }
• returns: { data, meta }
• I12-CASE-clean_and_deembed（原 I11-2）
• inputs: { data, scheme }
• returns: { clean, Σ_y, weights }
• I12-CASE-build_J（原 I11-3）
• inputs: { clean, config }
• returns: { J, B, Σ_y }
• I12-CASE-infer_theta（原 I11-4）
• inputs: { J, Σ_y, priors, algo }
• returns: { posterior, logZ, diag }
• I12-CASE-falsify_and_ppc（原 I11-5）
• inputs: { posterior, clean }
• returns: { tests, passrate }
• I12-CASE-recommend_design（原 I11-6）
• inputs: { posterior, objectives }
• returns: { Δθ_design, recipe }

X. 质量门、校验与回归（M12-*）

• M12-1（契约校验）：自动检查 unit_system、delta_form、gamma(ell)、d ell、引用锚点与版本号。
• M12-2（量纲校核）：对数值返回执行 check_dim；单位缺失或不一致抛出 E/UNIT。
• M12-3（可辨识性前置）：调用 I12-MM-compute_fisher，若 cond(F)>κ_th 抛出 E/IDENTIFIABILITY 并返回几何/频段建议。
• M12-4（数值稳健性）：检测雅可比奇异、PDE 求解不收敛、相位解缠失败；对应 E/NUMERIC 并附 hint。
• M12-5（回归测试）：接口升级需通过基准套件（I12-SIM-benchmark_suite）与案例回放，误差门限与置信区间重合率达标。
• M12-6（复现包）：每次运行输出 repro_bundle = {scripts, params, env, anchors}，用于审计与再现。

XI. 数据卡与管线卡：接口段模板（强制字段）

interfaces:

api_version: "12.0.0"

bindings:

- name: "I12-AT-compute_arrival_time"

request_id: "uuid"

inputs: {...}

contracts:

unit_system: "SI"

convention: "pulled_const" # or "integrand"

delta_form: "c_ref^-1 * ∫ n_eff dℓ"

gamma: "piecewise: free|fixture|substrate|film|sample"

d_ell: "m"

references:

- "EFT.WP.Core.Equations v1.1:Ch.2 S20-*"

- "EFT.WP.Core.Metrology v1.0:Ch.1–3,5"

outputs:

- name: "T_arr(ω)"

unit: "s"

ci: {level: 0.95}

reproducibility:

bundle: {scripts: "...", env: "...", anchors: ["S120-*","I12-*","M12-*"]}

schema_version: "12.0.0"

contract_version: "1.0"

XII. 资源与配额（实现侧约束）

• S120-11（资源限额）：为 HMC/SMC/仿真分配 cpu_time, gpu_mem, max_walltime；超过配额返回 E/RESOURCE。
• S120-12（日志与审计）：所有接口记录 request_id、时间戳、随机种子、cal_bundle 摘要与哈希；审计模式下输出 deterministic replay 所需信息。

XIII. 跨章引用与本章锚点

1. 跨章引用（固定写法）：本卷第6章（相干窗与提取）、第7章（到达时与去嵌）、第8章（测量矩阵与可辨识性）、第9章（设计变量与张度工程）、第10章（仿真与推断）、第11章（案例库）。
2. 本章锚点（S/M/I）：
   • 规范：S120-1—S120-12
   • 流程：M12-1—M12-6
   • 接口：I12-AT-*, I12-MM-*, I12-SIM-*, I12-INF-*, I12-DES-*, I12-CASE-*

XIV. 小结
本章以统一契约—稳定接口—质量门为核心，将到达时/传播、计量与测量矩阵、仿真栈、推断与模型比较、以及材料设计与案例库有机联接；通过别名映射与回归套件保障兼容与可复现，为全卷的工程化落地与跨团队协同提供标准化实现路径。