33-EFT.WP.Cosmo.EarlyObjects v1.0 | 附录D 参考实现与测试脚本清单

目录 ／ 文档-技术白皮书（V5.05） ／ 33-EFT.WP.Cosmo.EarlyObjects v1.0

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

I. 一句话目标

一句话目标：提供与模板 v0.1接口族一致的最小参考实现与测试脚本清单，给出目录、入口、配置、运行与审计规范，使 Catalog/Seeds/Trajectory、Phi_T/grad_Phi_T、L_nu/LC、n_eff、{ ell_i }、Delta_T_sigma、{R_env,T_trans,A_sigma} 与两类 T_arr/Delta_T_arr 的端到端流程可落地、可复现、可审计。

II. 适用范围与非目标

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

III. 目录结构（建议）

1. core/ 物理与数值核心
   • catalog.py（I.Build.Catalog → build_early_object_catalog）
   • seed.py（I.Build.Seeds|Triggers → seed_and_trigger）
   • evolve.py（I.Build.* → evolve_object_state）
   • sed.py（I.Build.Phi/谱 → synthesize_spectrum）
   • transport.py（I.Arrival.Constant|General|Delta → predict_arrival_signature）
   • interfaces.py（I.Interface.ApplyMatching|I.Path.Segment|I.Path.InterfaceCorrection → detect_interfaces，segment_integrals，interface_correction_sea）
   • rt.py（I.RT.Estimate → estimate_energy_triplet）
   • metrics.py（I.Consistency.DualMode|ThinThick/I.Uncertainty.GUM|MC → check_dual_arrival_consistency，consistency_thin_vs_thick_EO，propagate_uncertainty_GUM，propagate_uncertainty_MC）
2. io/ 数据与契约
   • contract.py（Contract 读写/校验/DimReport 生成）
   • dataio.py（读写 Catalog/Seeds/Trajectory/SeaProfile/Path/Observations 等）
   • hashing.py（hash(Catalog/Seeds/Trajectory/SeaProfile/Phi_T/n_eff/gamma/code)）
3. utils/ 通用工具
   • solvercfg.py（求积法/步长阈值/并发策略构建）
   • logger.py（I.Report.Log|Emit → log_artifacts_EO，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. 核心接口（模板接口族 → 本卷 I70-*）

• I.Build.Catalog → build_early_object_catalog(params) -> Catalog（I70-1）
• I.Build.Seeds|Triggers → seed_and_trigger(Phi_T, env, priors) -> Seeds（I70-2）
• I.Build.*（演化）→ evolve_object_state(O, env, tgrid) -> Trajectory（I70-3）
• I.Build.Phi（谱/场）→ synthesize_spectrum(O, state, fgrid) -> L_nu（I70-4）
• I.Arrival.Constant|General|Delta → predict_arrival_signature(n_eff, gamma, mode, c_ref) -> { T_arr, Delta_T_arr }（I70-6）
• I.Interface.ApplyMatching / I.Path.Segment / I.Path.InterfaceCorrection → detect_interfaces，segment_integrals，interface_correction_sea
• I.RT.Estimate → estimate_energy_triplet(data, Sigma_env) -> { R_env, T_trans, A_sigma }（I70-7）
• I.Consistency.DualMode|ThinThick → check_dual_arrival_consistency，consistency_thin_vs_thick_EO
• I.Uncertainty.GUM|MC → propagate_uncertainty_GUM，propagate_uncertainty_MC
• I.Report.Log|Emit → log_artifacts_EO，emit_measurement_report

统一约束：入口 check_dimension；校验 T_arr ≥ L_path/c_ref 与 R_env + T_trans + A_sigma = 1；分段端点 { ell_i } 显式入积，禁止跨界面插值。

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

• scripts/run_catalog.py —— 生成 Catalog 与环境引用（I.Build.Catalog）。
• scripts/run_seed.py —— 采样 Seeds/Triggers 并落盘（I.Build.Seeds|Triggers）。
• scripts/run_evolve.py —— 推进 Trajectory，记录事件（I.Build.*）。
• scripts/run_spectrum.py —— 合成 L_nu/LC（谱学）。
• scripts/run_transport.py —— 装配 n_eff、分段、两口径 T_arr/Delta_T_arr（I.Arrival.* + I.Path.*）。
• scripts/run_interfaces.py —— 界面识别/匹配、Delta_T_sigma 与 {R_env,T_trans,A_sigma}（I.Interface.* + I.RT.Estimate）。
• scripts/run_dispersion.py —— 频带差分与 n_path 系数拟合（I.Arrival.Delta）。
• scripts/run_dual_consistency.py —— 两口径一致性 eta_T（I.Consistency.DualMode）。
• scripts/run_thin_vs_thick.py —— 薄/厚层一致性 tau_switch（I.Consistency.ThinThick）。
• scripts/run_uncertainty_gum.py / scripts/run_uncertainty_mc.py —— GUM/MC 传播与尾部风险。
• scripts/run_report.py —— 汇总日志与指标，生成报告与哈希清单。

VI. 运行示例（CLI）

• 目录→成因→演化（基础链路）

python scripts/run_catalog.py --contract configs/eo.contract.json --out artifacts/catalog/

python scripts/run_seed.py --contract configs/eo.contract.json --priors configs/priors.json --out artifacts/seeds/

python scripts/run_evolve.py --contract configs/eo.contract.json --catalog artifacts/catalog/catalog.json --seeds artifacts/seeds/sd.json --out artifacts/traj/

• 谱学→传播→一致性

python scripts/run_spectrum.py --contract configs/eo.contract.json --traj artifacts/traj/trajectory.jsonl --fgrid configs/fgrid.json --out artifacts/sed/

python scripts/run_transport.py --contract configs/eo.contract.json --path paths/p001.path.jsonl --phi fields/phi_t.zarr --gphi fields/grad_phi_t.zarr --sea seaprofile/sea.v1.json --out artifacts/transport/

python scripts/run_dual_consistency.py --contract configs/eo.contract.json --path paths/p001.path.jsonl --neff fields/neff.zarr --cref calib/c_ref.json --out artifacts/consistency/

• 差分/薄厚/不确定度

python scripts/run_dispersion.py --contract configs/eo.contract.json --obs obs/p001.obs.jsonl --fgrid configs/fgrid.json --out artifacts/dispersion/

python scripts/run_thin_vs_thick.py --contract configs/eo.contract.json --path paths/p001.path.jsonl --sea seaprofile/sea.v1.json --out artifacts/switch/

python scripts/run_uncertainty_gum.py --contract configs/eo.contract.json --inputs artifacts/transport/results.json --out artifacts/uncertainty/gum/

python scripts/run_uncertainty_mc.py --contract configs/eo.contract.json --inputs artifacts/transport/results.json --nsamples 20000 --seed 20250905 --out artifacts/uncertainty/mc/

• 报告

python scripts/run_report.py --manifest artifacts/manifest.json --out artifacts/report/

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

• configs/eo.contract.json

{

"spec_version":"EFT.WP.Cosmo.EarlyObjects v1.0",

"coords_spec":"Comoving-Spherical",

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

"metric_spec":{"type":"FLRW-like","S_k":"sin","a_ref":1.0},

"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/priors.json

{"BHSeed":{"M0":{"dist":"lognormal","mu":2e4,"sigma":0.3},"a_bh0":{"dist":"uniform","low":0.1,"high":0.9}}}

• configs/solver.eo.json

{"quad":"adaptive_simpson","step_rule":"curvature_medium_layer",

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

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

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

• configs/fgrid.json

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

VIII. 输出与审计（最小集）

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

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

• 固化 artifacts/manifest.json（包含 Contract、Catalog/Seeds/Trajectory、SeaProfile/Path、Fields/Neff、SolverCfg/metric_spec、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.Catalog|Seeds|Trajectory|Phi|Neff
• 路径：I.Path.Capture|Segment|InterfaceCorrection
• 到达时：I.Arrival.Constant|General|Delta
• 界面/能量：I.Interface.ApplyMatching，I.RT.Estimate
• 计量/一致性/不确定度：I.Consistency.DualMode|ThinThick，I.Uncertainty.GUM|MC
• 报告：I.Report.Log|Emit

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

XII. 交叉引用

• 《EFT.WP.Cosmo.EarlyObjects v1.0》：第3–10、11–12章（对象、成因、生长、辐射、传播、计量、界面、数值、验证与误差）。
• 模板 v0.1：接口族与 I/O 契约分层。
• 《EFT.WP.Cosmo.LayeredSea v1.0》：分段、匹配、一致性。
• 《EFT.WP.Propagation.TensionPotential v1.0》：两口径与差分流程。
• 《EFT.WP.Core.*》：Equations/Metrology/Errors。

XIII. 产出物

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