42-EFT.WP.Heat.Decoherence v1.0 | 第12章 接口与实现绑定

目录 ／ 文档-技术白皮书 ／ 42-EFT.WP.Heat.Decoherence v1.0

第12章 接口与实现绑定

I. 范围与原则

• S120-1（目标）：固化本卷跨团队/跨管线的对外接口与实现绑定，统一谱估计、开放系统、传热、平台通道、工程设计、计量反演与仿真栈。
• S120-2（统一口径）：请求/响应对象必须包含 unit_system:"SI"、references:["<卷名 vX.Y: 锚点>"]、contract_version、schema_version；所有公式/符号/定义统一英文并通过 check_dim。
• S120-3（命名与幂等）：本章接口前缀 I12-*；幂等操作携带 request_id 与重放策略。
• S120-4（到达时复用）：若复用传播/到达时链路，contracts.arrival_time 必须声明 pulled_const|integrand 二选一，并给出 delta_form、gamma(ell)、d_ell。
• S120-5（错误模型）：统一错误对象
• { "code":"E/INPUT|E/UNIT|E/NUMERIC|E/CP|E/IDENTIFIABILITY|E/SPECTRA|E/RESOURCE|E/INTERNAL",
• "message":"...", "at":"stage.name", "hint":"...", "refs":["..."] }

II. 接口总览与别名映射

1. S120-6（家族分组）：
   • SPEC（谱/估计）：I12-SPEC-* ↔ 第5章 I50-*
   • OQS（开放量子系统）：I12-OQS-* ↔ 第4章 I40-*
   • HEAT（传热/非平衡）：I12-HEAT-* ↔ 第6章 I60-*
   • PLAT（平台通道）：I12-PLAT-* ↔ 第7章 I70-*
   • ENG（相干工程）：I12-ENG-* ↔ 第8章 I80-*
   • MET（计量与估计）：I12-MET-* ↔ 第9章 I90-*
   • SIM（仿真栈/合成数据）：I12-SIM-* ↔ 第11章 I110-*
2. S120-7（别名表·节选）：I50-1≡I12-SPEC-estimate_psd，I40-1≡I12-OQS-lindblad_rates，I60-3≡I12-HEAT-solve_bte，I70-2≡I12-PLAT-map_rates，I80-2≡I12-ENG-thermal_balance，I90-3≡I12-MET-infer_spectrum，I110-5≡I12-SIM-make_synthetic。

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

• S120-8（Request 原型）
• {
• "request_id":"uuid",
• "inputs":{...},
• "contracts":{
• "unit_system":"SI",
• "arrival_time":{
• "convention":"pulled_const|integrand",
• "delta_form":"c_ref^-1 * ∫ n_eff dℓ | ∫ (n_eff/c_ref) dℓ",
• "gamma":"piecewise: free|fixture|substrate|device|environment",
• "d_ell":"m"
• }
• },
• "cal_bundle":{...},
• "priors":{...},
• "references":["EFT.WP.Core.Metrology v1.0:Ch.1–3,5","Heat.Decoherence v1.0:Sxx-*"],
• "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（如 {"S_xx":{"unit":"rad^2/Hz"},"kappa":{"unit":"W·m^-1·K^-1"}}）；实现需通过 check_dim。

IV. SPEC（谱/估计）接口

• I12-SPEC-estimate_psd（别名 I50-1）
• in : {signal, fs, method, params}
• out: {S_xx(ω), edof, ci}
• I12-SPEC-estimate_cpsd（I50-2）
• in : {x, y, fs, method, params}
• out: {S_xy(ω), coherence}
• I12-SPEC-fit_noise_models（I50-3）
• in : {S_xx, family}
• out: {A, gamma, w_tls, tau_tls, omega_c, ci}
• I12-SPEC-fdt_map_to_chi（I50-4） / I12-SPEC-build_Seff（I50-5）

V. OQS（开放量子系统）接口

• I12-OQS-lindblad_rates（I40-1）
• I12-OQS-redfield_tensor（I40-2） / I12-OQS-tcl2_generator（I40-3）
• I12-OQS-influence_functional（I40-4） / I12-OQS-simulate（I40-5）
• I12-OQS-filter_function（I40-6） / I12-OQS-dd_optimize（I40-7）
• I12-OQS-infer_params（I40-8）
  （入参/出参沿用来源章节，单位与锚点必填。）

VI. HEAT（传热/非平衡）接口

• I12-HEAT-solve_fourier（I60-1） / I12-HEAT-solve_cattaneo（I60-2）
• I12-HEAT-solve_bte（I60-3） / I12-HEAT-landauer（I60-4）
• I12-HEAT-fit_params（I60-5） / I12-HEAT-consistency（I60-6）

VII. PLAT（平台通道）接口

• I12-PLAT-assemble_psd（I70-1）
• I12-PLAT-map_rates（I70-2）
• I12-PLAT-scan_response（I70-3）
• I12-PLAT-decompose_channels（I70-4）
• I12-PLAT-validate_sequences（I70-5）

VIII. ENG（相干工程）接口

• I12-ENG-synthesize_filter（I80-1）
• I12-ENG-thermal_balance（I80-2）
• I12-ENG-design_phononic_gap（I80-3）
• I12-ENG-map_to_rates（I80-4）
• I12-ENG-multiobjective_opt（I80-5）
• I12-ENG-validate_thermal_coherence（I80-6）

IX. MET（计量与估计）接口

• I12-MET-assemble_protocol（I90-1）
• I12-MET-estimate_T1T2（I90-2）
• I12-MET-infer_spectrum（I90-3）
• I12-MET-noise_thermometry（I90-4）
• I12-MET-design_experiment（I90-5）
• I12-MET-validate_coverage（I90-6）

X. SIM（仿真栈/合成数据）接口

• I12-SIM-prep_thermo_spectra（I110-1）
• I12-SIM-simulate_langevin（I110-2）
• I12-SIM-simulate_bte（I110-3）
• I12-SIM-simulate_sle（I110-4）
• I12-SIM-make_synthetic（I110-5）
• I12-SIM-run_sbc（I110-6）

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

interfaces:

api_version: "12.0.0"

bindings:

- name: "I12-SPEC-estimate_psd"

request_id: "uuid"

inputs: {signal: "...", fs: "<Hz>", method: "Welch|Multitaper|Bayes", params:{...}}

contracts:

unit_system: "SI"

references:

- "Heat.Decoherence v1.0:Ch.5 S50-*"

- name: "I12-OQS-lindblad_rates"

request_id: "uuid"

inputs: {H_S: "...", L_ops: "...", J: "...", T: "<K>"}

contracts: {unit_system: "SI"}

references:

- "Heat.Decoherence v1.0:Ch.4 S40-*"

outputs:

- name: "S_xx(ω)"

unit: "rad^2/Hz"

ci: {level: 0.95}

- name: "Gamma1"

unit: "s^-1"

reproducibility:

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

schema_version: "12.0.0"

contract_version: "1.0"

XII. 质量门、校验与回归

• M12-1（契约校验）：核查 unit_system、到达时四项（如适用）与引用锚点/版本。
• M12-2（量纲校核）：所有数值通过 check_dim；单位缺失/不一致抛 E/UNIT。
• M12-3（可辨识性前置）：对估计/反演类调用计算 Fisher；若 cond(F) > κ_th 抛 E/IDENTIFIABILITY 并返回采样/带宽建议。
• M12-4（数值稳健）：检测非正谱、主方程非 CP、能量不守恒/非收敛；抛 E/NUMERIC 并附 hint。
• M12-5（回归测试）：接口升级需通过 I12-SIM-run_sbc 与案例回放，误差门限与覆盖度达标。
• M12-6（复现包）：每次运行输出 repro_bundle = {scripts, params, env, anchors, seed, hash}，可确定性重放。

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

• S120-11（配额控制）：为谱估计/OQS/BTE/QEC/仿真分配 cpu_time、gpu_mem、max_walltime；超配返回 E/RESOURCE。
• S120-12（日志与审计）：记录 request_id、时间戳、随机种子、cal_bundle 摘要与哈希；审计模式导出重放所需全部信息。

XIV. 跨卷引用与本章锚点

1. 交叉引用（固定写法）：本卷第4–11章接口来源；EFT.WP.Core.Equations v1.1 Ch.2 S20-* 与 EFT.WP.Core.Metrology v1.0 Ch.1–3,5。
2. 本章锚点：
   • 规范：S120-1—S120-12
   • 流程：M12-1—M12-6
   • 接口：I12-SPEC-*,I12-OQS-*,I12-HEAT-*,I12-PLAT-*,I12-ENG-*,I12-MET-*,I12-SIM-*

XV. 小结
本章以统一契约—稳定接口—质量门为核心，整合谱/开放系统/传热/平台通道/工程设计/计量反演/仿真栈的端到端实现绑定；通过家族分组与别名映射保证兼容与可复现，为跨平台/跨温区的退相干建模、估计与工程部署提供标准化路径。