30-EFT.WP.Propagation.TensionPotential v1.0 | 附录D 参考实现与测试脚本清单

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

附录D 参考实现与测试脚本清单

I. 一句话目标

一句话目标：提供与第10章 API 一致的最小参考实现与测试脚本清单，明确目录、入口、配置、运行与审计规范，使 Phi_T、n_eff、gamma(ell)、T_arr 的端到端流程可以直接落地与复现。

II. 适用范围与非目标

• 覆盖：参考实现的目录结构、核心模块最小接口、基准脚本与用途、运行示例、配置样例、日志与审计要点、复现流程与安全约束。
• 非目标：不提供装置级硬件代码，不依赖外部私有库；仅给出可替换的最小实现与脚本骨架。

III. 参考实现目录结构（建议）

1. core/ 物理与数值核心
   • phi.py（build_phi_t，fix_gauge，apply_boundary，gradient）
   • neff.py（estimate_n_eff，decompose_n_eff，local_speed）
   • arrival.py（arrival_time_constant，arrival_time_general，delta_arrival）
   • interfaces.py（detect_interfaces，apply_matching，segment_integrals，interface_correction）
   • metrics.py（check_dimension，check_dual_arrival_consistency，convergence_scan）
2. io/ 数据与契约
   • contract.py（Contract 读写与校验）
   • dataio.py（读写 SeaModel，Path，Field，Observations，NeffParams）
   • hashing.py（hash(Phi_T)，hash(gamma)，hash(code)）
3. utils/ 通用工具
   • solvercfg.py（build_solver_config）
   • logger.py（log_artifacts，运行与审计日志）
   • rng.py（可播种随机源）
4. scripts/ 基准与测试脚本（见第V节）
5. configs/ 运行配置与样例（见第VII节）
6. artifacts/ 结果输出与审计包（日志、报告、哈希清单）

要点：所有函数名与第10章一致；内联符号一律反引号；命名隔离 T_fil 与 T_trans，n 与 n_eff。

IV. 核心模块最小接口（与第10章一致）

• 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
• 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
• 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
• 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 }
• interface_correction( gamma, Sigma, params ) -> ΔT_sigma
• check_dimension( expr ) -> DimReport
• check_dual_arrival_consistency( inputs ) -> eta_T
• convergence_scan( problem, cfg_list ) -> Report
• build_solver_config( params ) -> SolverCfg
• log_artifacts( meta, hashes, metrics ) -> Log

注意：入口执行量纲核查，保证 dim(T_arr)=[T]，dim(n_eff)=1，dim(c_loc)=[L][T^-1]。

V. 脚本清单与用途（最小集合）

• scripts/run_uniform.py
  用途：基准一（均匀介质），验证 T_arr = L_path / c_ref 与量纲、下界。
• scripts/run_linear_phi.py
  用途：基准二（线性势梯度），比较解析近似与数值，校验步长与误差控制。
• scripts/run_layered.py
  用途：基准三（双层界面），验证分段积分、Sigma 匹配与零厚度修正。
• scripts/run_anisotropy.py
  用途：基准四（各向异性），检测 b1 · dot( grad_Phi_T , t_hat ) 显著性。
• scripts/run_dispersion.py
  用途：基准五（频带色散），拟合 n_path 多项式系数与差分线性区。
• scripts/run_calibrate_cref.py
  用途：标定 c_ref，输出漂移曲线与不确定度。
• scripts/run_decompose_neff.py
  用途：分解 n_common 与 n_path，输出 NeffParams 与协方差。
• scripts/run_dual_consistency.py
  用途：两口径一致性 eta_T 审计。
• scripts/run_uncertainty_gum.py
  用途：GUM 传播，输出 mean ± k·u_c。
• scripts/run_uncertainty_mc.py
  用途：MC 传播，输出分位数与尾部指标（可播种）。
• scripts/run_dqc.py
  用途：数据质量检查（附录B第VIII节 Q1…Q7）。
• scripts/run_report.py
  用途：汇总 Log 与指标，生成审计报告与哈希清单。

VI. 运行示例（CLI）

• 基准一（均匀介质）

python scripts/run_uniform.py \

--contract configs/contract.constant.json \

--path paths/p001.path.jsonl \

--cref calib/c_ref.json \

--solvercfg configs/solver.uniform.json \

--out artifacts/uniform/

• 分解 n_eff 与差分校核

python scripts/run_decompose_neff.py \

--contract configs/contract.constant.json \

--phi fields/phi_t.zarr \

--gphi fields/grad_phi_t.zarr \

--obs obs/p001.obs.jsonl \

--fgrid configs/fgrid.json \

--out artifacts/decompose/

python scripts/run_dual_consistency.py \

--contract configs/contract.general.json \

--path paths/p001.path.jsonl \

--neff fields/neff.zarr \

--cref calib/c_ref.json \

--out artifacts/consistency/

• 层间接口与分段

python scripts/run_layered.py \

--contract configs/contract.constant.json \

--path paths/p_layered.path.jsonl \

--sigma interfaces/sigma.json \

--neff fields/neff_layered.zarr \

--solvercfg configs/solver.layered.json \

--out artifacts/layered/

• 不确定度（GUM 与 MC）

python scripts/run_uncertainty_gum.py \

--contract configs/contract.constant.json \

--inputs artifacts/uniform/results.json \

--out artifacts/uncertainty/gum/

python scripts/run_uncertainty_mc.py \

--contract configs/contract.constant.json \

--inputs artifacts/uniform/results.json \

--nsamples 20000 --seed 20250905 \

--out artifacts/uncertainty/mc/

VII. 配置样例（最小可用）

• configs/contract.constant.json

{

"id": "ct-001",

"spec_version": "EFT.WP.Propagation.TensionPotential v1.0",

"coords_spec": "Cartesian",

"units_spec": {"length":"m","time":"s","speed":"m·s^-1","frequency":"Hz"},

"mode": "constant",

"gauge": {"x_ref":[0,0,0], "t_ref":"2025-01-01T00:00:00Z"},

"boundary_config": {"type":"Dirichlet","Phi_T_far":0},

"tolerances": {"eps_T":1e-9,"eta_T":5e-10},

"n_eff_dependencies": "F(Phi_T, grad_Phi_T, rho, f)"

}

• configs/solver.uniform.json

{

"quad":"adaptive_simpson",

"step_rule":"curvature_and_medium",

"tau_geom":0.02,

"tau_medium":0.01,

"convergence":{"levels":[1.0,0.5,0.25],"eps_T":1e-9},

"parallel":{"freq":"threads","paths":"threads"},

"cache":{"neighborhood_radius":0.1}

}

• configs/fgrid.json

{"f0":1.0e9,"band":[-5.0e7,5.0e7],"nodes":[9.5e8,1.0e9,1.05e9]}

VIII. 输出与日志（最小集）

• 结果主文件：results.json
  含 T_arr_mod_s，ΔT_arr（若适用），eta_T，u_c 或分位数，hashes，SolverCfg 快照。
• 审计日志：audit.log
  含 check_dimension 结果、口径选择、步长与误差统计、界面触发与零厚度修正次数、n_eff 夹持触发率。
• 哈希清单：hashes.json
  hash(Phi_T)，hash(grad_Phi_T)，hash(n_eff)，hash(gamma)，hash(code)。
• 报告：report.md
  概览、指标、否证样本、重放命令、环境与版本。

IX. 复现流程（一键重放）

• 固化 Contract、SolverCfg、Path、NeffParams、Phi_T/grad_Phi_T 或 n_eff、seed、hash(code) 到 artifacts/manifest.json。
• 运行 python scripts/run_report.py --manifest artifacts/manifest.json --out artifacts/report/。
• 检查 hashes.json 与新生成哈希一致；若不一致，标记为复现失败并输出差异摘要。

X. 安全与完整性

• 只读输入：/contracts、/obs、/interfaces 建议只读挂载，防止篡改。
• 量纲守护：所有脚本在入口调用 check_dimension，若失败直接拒绝。
• 命名隔离：脚本层禁止将 T_fil 与 T_trans、n 与 n_eff 混用。
• 随机可播种：MC 相关脚本必须接受 --seed 并在日志中落盘。

XI. 交叉引用

• 《EFT.WP.Propagation.TensionPotential v1.0》第9章（建模方法与数值实现），第10章（实现绑定与 API 规范），第11章（验证实验与对标数据集），第12章（误差预算与系统误差防护）
• 《EFT.WP.Core.Equations v1.1》S06-*
• 《EFT.WP.Core.Metrology v1.0》M05-，M10-
• 《EFT.WP.Core.Errors v1.0》M20-*

XII. 产出物

• 参考实现最小骨架（ref/core, ref/io, ref/utils）与与之配套的脚本集合（scripts/）。
• 可直接运行的配置样例（configs/、fgrid.json）与基准路径/观测样例占位。
• 审计与复现产物模板（artifacts/：results.json，audit.log，hashes.json，report.md，manifest.json）。