31-EFT.WP.BH.TensionWall v1.0 | 附录D 参考实现与测试脚本清单

目录 ／ 文档-技术白皮书 ／ 31-EFT.WP.BH.TensionWall v1.0

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

I. 一句话目标

一句话目标：提供与模板 v0.1（《EFT 技术白皮书与技术备忘模板 全面清单 v0.1》）接口族一致的最小参考实现与测试脚本清单，给出目录、入口、配置、运行与审计规范，使 TWProfile、Phi_T/grad_Phi_T、n_eff、{ ell_i }、Delta_T_sigma、R_TW/T_trans/A_sigma 与两口径 T_arr 的端到端流程可直接落地与复现。

II. 适用范围与非目标

• 覆盖：参考实现目录结构、核心模块最小接口（模板接口族 → 本卷 I40-* 映射）、基准脚本与用途、CLI 运行示例、配置样例、日志与审计要点、复现流程与安全约束。
• 非目标：不提供装置级硬件代码；不依赖私有库；实现以最小可用为设计原则。

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

1. core/ 物理与数值核心
   • phi.py（I.Build.Phi → apply_TW_matching，gradient）
   • neff.py（I.Build.Neff → estimate_neff_TW）
   • arrival.py（I.Arrival.Constant|General|Delta → arrival_time_with_TW，delta_arrival_TW）
   • interfaces.py（I.Interface.ApplyMatching / I.Path.Segment / I.Path.InterfaceCorrection → detect_TW_intersections，segment_integrals，interface_correction）
   • echo.py（多路径与回声 → simulate_multipath_TW）
   • metrics.py（I.Consistency.DualMode|ThinThick / I.Uncertainty.GUM|MC → check_dual_arrival_consistency，consistency_thin_vs_thick_TW，propagate_uncertainty_GUM，propagate_uncertainty_MC）
2. io/ 数据与契约
   • contract.py（Contract 读写与校验）
   • dataio.py（读写 TWProfile，Path，Field，Observations，RTParams）
   • hashing.py（hash(Phi_T)，hash(grad_Phi_T)，hash(n_eff)，hash(gamma)，hash(TWProfile)）
3. utils/ 通用工具
   • solvercfg.py（求积法/步长阈值/并行策略构建）
   • logger.py（I.Report.Log|Emit → log_tw_propagation，emit_measurement_report）
   • rng.py（可播种随机源，MC 用）
4. scripts/ 基准与测试脚本（见 V）
5. configs/ 运行配置与样例（见 VII）
6. artifacts/ 结果与审计产物（日志、报告、哈希清单、重放清单）

命名隔离：严禁将 T_fil 与 T_trans 混用，严禁将 n 与 n_eff 混用；入口强制 n_eff ≥ 1 与量纲核查。

IV. 核心模块最小接口（模板接口族 → 本卷 I40-*）

• I.Build.Phi → apply_TW_matching(Phi_T, TWProfile) -> Phi_T_matched；gradient(Phi_T) -> grad_Phi_T
• I.Build.Neff → estimate_neff_TW(Phi_T, grad_Phi_T, rho, f, TWProfile) -> n_eff
• I.Path.Capture → capture_path(raw_track, coord_spec) -> { gamma[k], Δell[k], t_hat[k] }
• I.Path.Segment → detect_TW_intersections(gamma, TWProfile) -> { ell_i }；segment_integrals(n_eff, gamma, { ell_i }, mode) -> { T_arr_i }
• I.Path.InterfaceCorrection → interface_correction(gamma, Sigma_TW, params) -> Delta_T_sigma
• I.Arrival.Constant|General → arrival_time_with_TW(n_eff, gamma, Sigma_TW, mode, c_ref) -> T_arr
• I.Arrival.Delta → delta_arrival_TW(n_path_params, f1, f2, gamma, mode, c_ref) -> ΔT_arr
• I.RT.Estimate → estimate_RT_TW(data, TWProfile) -> R_TW, T_trans, A_sigma
• I.Fit.Profile → fit_TW_profile(observations, Phi_T, grad_Phi_T, prior, model_spec) -> theta_hat, Cov
• I.Consistency.DualMode → check_dual_arrival_consistency(inputs) -> eta_T
• I.Consistency.ThinThick → consistency_thin_vs_thick_TW(inputs) -> tau_report
• I.Uncertainty.GUM|MC → propagate_uncertainty_GUM(inputs) -> u_c；propagate_uncertainty_MC(inputs, Nsamples, seed) -> dist(T_arr)
• I.Report.Log|Emit → log_tw_propagation(meta, hashes, metrics) -> Log；emit_measurement_report(contract, logs, artifacts) -> Report

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

• scripts/run_uniform.py
  用途：基准一（均匀外区，无壁），验证 T_arr = L_path / c_ref 与量纲/下界。
• scripts/run_thinwall.py
  用途：薄壁单界面；Delta_T_sigma 与厚壁体积分一致性（生成 tau_switch 曲线）。
• scripts/run_thickwall.py
  用途：显式厚壁体积分，细化端点与步长，审计误差斜率。
• scripts/run_interfaces.py
  用途：连续/势跃迁/通量跃迁三型匹配与能量一致 R_TW + T_trans + A_sigma = 1。
• scripts/run_dispersion.py
  用途：频带差分 ΔT_arr，拟合 n_path 多项式系数与带外泄漏评估。
• scripts/run_anisotropy.py
  用途：定向项 b1, b1_sigma 显著性（跨方位路径组）。
• scripts/run_dual_consistency.py
  用途：两口径一致性 eta_T 审计。
• scripts/run_thin_vs_thick.py
  用途：薄/厚壁双链路一致性报告 tau_switch。
• scripts/run_uncertainty_gum.py / scripts/run_uncertainty_mc.py
  用途：GUM/MC 不确定度传播与尾部风险。
• scripts/run_dqc.py
  用途：数据质量检查（DQC-1…DQC-8 聚合）。
• scripts/run_report.py
  用途：汇总日志与指标，生成报告与哈希清单。

VI. 运行示例（CLI）

• 薄壁一致性

python scripts/run_thinwall.py \

--contract configs/tw.contract.json \

--tw configs/tw.tanh.json \

--path paths/p001.path.jsonl \

--solvercfg configs/solver.tw.json \

--out artifacts/thinwall/

• 频带差分与两口径一致

python scripts/run_dispersion.py \

--contract configs/tw.contract.json \

--phi fields/phi_t.zarr --gphi fields/grad_phi_t.zarr \

--obs obs/p001.obs.jsonl --fgrid configs/fgrid.json \

--out artifacts/dispersion/

python scripts/run_dual_consistency.py \

--contract configs/tw.contract.json \

--path paths/p001.path.jsonl --neff fields/neff.zarr \

--cref calib/c_ref.json --out artifacts/consistency/

• 不确定度（GUM/MC）

python scripts/run_uncertainty_gum.py \

--inputs artifacts/dispersion/results.json \

--out artifacts/uncertainty/gum/

python scripts/run_uncertainty_mc.py \

--inputs artifacts/dispersion/results.json \

--nsamples 20000 --seed 20250905 \

--out artifacts/uncertainty/mc/

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

• configs/tw.contract.json

{

"spec_version":"EFT.WP.BH.TensionWall v1.0",

"coords_spec":"Spherical",

"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"},

"tolerances":{"eps_T":1e-9,"eta_T":5e-10,"eta_w":0.03,"tau_switch":5e-12}

}

• configs/tw.tanh.json

{"model":"tanh","r_H":1.8e9,"Delta_w":1.2e6,"sigma_w":6.0e5,"eta_w":0.03}

• configs/solver.tw.json

{"quad":"adaptive_simpson","step_rule":"curvature_medium_wall",

"tau_geom":0.02,"tau_medium":0.01,"tau_wall":0.005,

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

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

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

• 结果：results.json（含 T_arr_mod_s、可选 Delta_T_sigma_s、eta_T、tau_switch、主要哈希与 SolverCfg 快照）。
• 审计：audit.log（量纲核查结果、口径选择、步长与误差统计、界面触发与能量一致余量、夹持触发率）。
• 哈希：hashes.json（hash(Phi_T)，hash(grad_Phi_T)，hash(n_eff)，hash(gamma)，hash(TWProfile)，hash(code)）。
• 报告：report.md（指标面板、否证样本、重放命令、环境与版本）。

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

• 生成 artifacts/manifest.json（包含 Contract、TWProfile、Path、Fields/Neff、SolverCfg、seed、全部哈希）。
• 执行

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. 模板接口族映射速览（锚定模板 v0.1）

• 构建：I.Build.Phi，I.Build.Neff
• 路径：I.Path.Capture，I.Path.Segment，I.Path.InterfaceCorrection
• 到达时：I.Arrival.Constant|General|Delta
• 匹配/能量：I.Interface.ApplyMatching，I.RT.Estimate
• 计量/一致性：I.Consistency.DualMode|ThinThick，I.Uncertainty.GUM|MC
• 报告：I.Report.Log|Emit

工程映射：参见本卷 I40-* 清单（第 IV 节）。

XII. 交叉引用

• 《EFT.WP.BH.TensionWall v1.0》：第3–9、11–12章（方程、参数化、传播、匹配、数值、验证与误差）。
• 模板 v0.1：接口族与 I/O 契约分层。
• 《EFT.WP.Propagation.TensionPotential v1.0》：两口径与数据口径。
• 《EFT.WP.Core.Equations v1.1》、Core.Metrology v1.0、Core.Errors v1.0。

XIII. 产出物

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