30-EFT.WP.Propagation.TensionPotential v1.0 | 第10章 实现绑定与 API 规范

目录 ／ 文档-技术白皮书 ／ 30-EFT.WP.Propagation.TensionPotential v1.0

第10章 实现绑定与 API 规范

I. 一句话目标

一句话目标：将本卷物理量与计算口径绑定为可复用、可审计、可追溯的 API，定义数据类型、函数原型、契约对象与日志规范，确保跨项目一致性与工程落地。

II. 范围与非目标

• 覆盖内容：接口分层、数据类型、函数原型、契约与参数校验、单位与量纲、错误码、并发与可复现、日志与审计、示例工作流。
• 非目标：不重复第4章 Phi_T 的物理构建与第5章 n_eff 的理论推导；不讨论装置级机械与电学设计。

III. 术语与符号最小集

• 场与势：T_fil(x,t)，Phi_T(x,t)，grad_Phi_T(x,t)。
• 折射率与速度：n_eff(x,t,f)，c_ref，c_loc(x,t,f) = c_ref / n_eff(x,t,f)。
• 路径与测度：gamma(ell)，d ell，界面集合 Sigma。
• 到达时口径：T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )，或 T_arr = ∫ ( n_eff / c_ref ) d ell。
• 分解：n_eff = n_common(x,t) + n_path(x,t,f)。
• 约定：严禁将 T_fil 与 T_trans 混用，严禁将 n 与 n_eff 混用；内联符号一律使用反引号。

IV. 设计原则与契约（Contract）

1. 不变性与可复现
   输入不可变，函数无副作用，所有随机过程可播种，输出与日志含哈希。
2. 量纲一致
   入口执行量纲核查，保证 dim(T_arr) = [T]，dim(n_eff) = 1，dim(c_loc) = [L][T^-1]。
3. 规范固定与接口显性
   规范 Phi_T(x_ref,t_ref) = 0 与边界 boundary_config 必须显式记录在契约中。
4. 契约对象 Contract（最小字段）
   • id，spec_version，units_spec，coords_spec
   • mode ∈ {constant, general}
   • n_eff_dependencies（如 F(Phi_T, grad_Phi_T, rho, f)）
   • gauge（x_ref,t_ref）
   • boundary_config，Sigma_meta
   • tolerances（eps_T, eta_T）
   • guardband，uncertainty_method ∈ {GUM, MC, both}
   • hashes（hash(Phi_T), hash(gamma), hash(code)，等）
   • seed，random_policy

V. 数据结构与类型（最小定义）

• SeaModel
  来源与网格/解析描述，坐标、单位、时间戳、插值策略。
• Path
  gamma[k]（坐标点），Δell[k]（线元），t_hat[k]（可选切向），interface_marks（与 Sigma 的交点索引）。
• Field
  标量或向量场句柄，支持位置查询与梯度查询。
• NeffParams
  标量系数 a0,a1,a2,b1，频带系数 c_m 或其字段映射；夹持区间 n_min=1, n_max。
• SolverCfg
  求积法、步长策略、曲率与介质阈值、收敛准则、并行与缓存策略。
• Report / Log
  指标、阈值、误差预算、否证样本、哈希与运行元数据。

VI. 接口分层与函数原型（I 层全集）

I. 构建与规范

• build_phi_t( T_fil, params_G ) -> Phi_T
• fix_gauge( Phi_T, x_ref, t_ref ) -> Phi_T
• apply_boundary( Phi_T, boundary_config ) -> Phi_T

II. 势与折射率映射

• gradient( Phi_T ) -> grad_Phi_T
• estimate_n_eff( Phi_T, grad_Phi_T, rho, f, params ) -> n_eff
• decompose_n_eff( n_eff, f_grid ) -> n_common, n_path_params
• local_speed( n_eff, c_ref ) -> c_loc

III. 路径与接口

• capture_path( raw_track, coord_spec ) -> { gamma[k], Δell[k], t_hat[k] }
• detect_interfaces( gamma, sea_meta ) -> { ell_i }, Sigma
• apply_matching( Phi_T, Sigma, params ) -> Phi_T_matched
• segment_integrals( n_eff, gamma, { ell_i }, mode ) -> { T_arr_i }

IV. 到达时计算（两口径）

• arrival_time_constant( n_eff, gamma, c_ref ) -> T_arr
• arrival_time_general( n_eff, gamma, c_ref ) -> T_arr
• delta_arrival( n_path_params, f1, f2, gamma, mode, c_ref ) -> ΔT_arr

V. 标定与一致性

• calibrate_c_ref( gamma_ref, T_arr_ref, n_eff_ref, mode ) -> c_ref
• fit_n_eff_params( Phi_T, grad_Phi_T, data_multi_f, model_spec ) -> theta_hat, Cov
• check_dual_arrival_consistency( inputs ) -> eta_T

VI. 不确定度与守护

• propagate_uncertainty_GUM( inputs ) -> u_c
• propagate_uncertainty_MC( inputs, Nsamples, seed ) -> dist(T_arr)
• check_dimension( expr ) -> DimReport

VII. 性能、收敛与审计

• build_solver_config( params ) -> SolverCfg
• convergence_scan( problem, cfg_list ) -> Report
• benchmark_suite( runlist ) -> Summary
• cache_neighborhood( field, gamma, radius ) -> Handle
• log_artifacts( meta, hashes, metrics ) -> Log
• emit_report( contract, logs, artifacts ) -> Report

约束：所有原型的输入输出单位、坐标与规范需与 Contract 一致；mode ∈ {constant, general} 对应第6章两口径。

VII. 参数校验与单位/量纲

• 单位核查：入口强制校验长度、时间、速度、无量纲量，输出 DimReport。
• 坐标一致：Path 与 SeaModel 必须声明同一坐标系；如不同需提供显式可逆变换。
• 夹持规则：n_eff ∈ [1, n_max]，触发计数需进入日志。
• 规范一致：跨函数调用保持固定的 x_ref,t_ref 与 boundary_config。

VIII. 错误码与异常（最小集）

• E-DIM-001 量纲不一致或单位缺失
• E-GAUGE-002 规范未固定或冲突
• E-NEFF-003 n_eff < 1 或分解失败
• E-PATH-004 路径离散非法或与测度不一致
• E-INTF-005 界面匹配失败或参数越界
• E-QAD-006 求积不收敛或误差阈值未满足
• E-CREF-007 c_ref 标定不可解或不稳定
• E-CONSIST-008 两口径一致性失败（eta_T 超阈）
• E-IO-009 契约/日志/哈希缺失或不匹配

处理：返回错误对象，保留全部中间日志与随机种子，供重放与审计。

IX. 并发、确定性与可复现

• 确定性：核心函数应纯函数化；涉及随机的仅限 MC，不影响确定性路径；所有随机过程记录 seed。
• 并发：频带与路径可并行；避免共享可变状态；缓存以只读句柄传递。
• 复现：所有入口含 hash(Phi_T), hash(gamma), hash(code)；报告含 SolverCfg 快照。

X. 安全、完整性与命名隔离

• 完整性：接口严禁外部网络依赖；输入输出校验、哈希与签名可选启用。
• 命名隔离：T_trans 仅用于界面透射，不得在张力或折射率场中使用；n 与 n_eff 严格区分。
• 日志隐私：仅记录必要元数据，屏蔽敏感源数据路径。

XI. 日志与审计（最小字段）

• 运行：时间戳、平台、库版本、spec_version、SolverCfg。
• 物理：hash(Phi_T), hash(grad_Phi_T), hash(n_eff)，c_ref，mode。
• 几何：hash(gamma)，N，step_rule，eps_T，interface_marks。
• 误差：u_stat，u_sys，u_c，guardband，eta_T，夹持触发率。
• 否证：违反下界、n_eff < 1、口径不一致、能量守恒破坏等样本清单与重放入口。

XII. 示例工作流（可直接落地）

A. 网格法：从 T_fil 到 T_arr(f)

• Phi_T = build_phi_t( T_fil, params_G )
• Phi_T = fix_gauge( Phi_T, x_ref, t_ref )，Phi_T = apply_boundary( … )
• grad_Phi_T = gradient( Phi_T )
• n_eff = estimate_n_eff( Phi_T, grad_Phi_T, rho, f, params )
• T_arr = arrival_time_constant( n_eff, gamma, c_ref )（或 arrival_time_general）
• log_artifacts( … )，emit_report( … )

B. 参照速度标定与两口径一致性

• c_ref = calibrate_c_ref( gamma_ref, T_arr_ref, n_eff_ref, mode )
• eta_T = check_dual_arrival_consistency( inputs )（应满足 eta_T ≤ 阈值）

C. 多频带差分隔离 path term

• n_common, n_path_params = decompose_n_eff( n_eff, f_grid )
• ΔT_arr = delta_arrival( n_path_params, f1, f2, gamma, mode, c_ref )
• 与观测差分对比，更新 NeffParams 或 c_ref

XIII. 交叉引用

• 《EFT.WP.Propagation.TensionPotential v1.0》第4章，第5章，第6章，第7章，第8章，第9章
• 《EFT.WP.Core.Equations v1.1》S06-*
• 《EFT.WP.Core.Metrology v1.0》M05-，M10-
• 《EFT.WP.Core.Errors v1.0》M20-*

XIV. 产出物

• API 参考清单：原型、入参/出参、单位与量纲要求、错误码。
• 契约模板：Contract、SolverCfg、Path、NeffParams、Report、Log 的字段规范。
• 审计与复现实例包：示例工作流 A/B/C 的日志与哈希集合。