30-EFT.WP.Propagation.TensionPotential v1.0 | 附录B 数据规范与输入输出

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

附录B 数据规范与输入输出

I. 一句话目标

一句话目标：给出本卷端到端所需的数据对象、字段规范与输入输出契约，覆盖文件组织、序列化格式、单位与坐标、哈希与可复现、校验与错误语义，使 Phi_T、n_eff、gamma(ell)、T_arr 的数据流在两类到达时口径下可直接落地。

II. 适用范围与非目标

• 覆盖：数据对象与主键、字段与单位、序列化格式与目录约定、输入输出接口契约、质量校验与一致性检查、示例与清单。
• 非目标：不重复模型推导与算法细节；不给出装置级硬件数据表；不依赖外部私有格式。

III. 总体约束与约定

• 坐标与单位：coords_spec 必填，默认 Cartesian；units_spec 统一 SI。若输入含 km 或 ms，必须在入口映射到 m 与 s 并记录映射。
• 内联符号：公式内联一律反引号包裹（如 T_arr，n_eff，c_ref，gamma(ell)）。
• 命名隔离：严禁将 T_fil 与 T_trans 混用，严禁将 n 与 n_eff 混用。
• 量纲一致：入口校验 dim(T_arr) = [T]，dim(n_eff) = 1，dim(c_ref) = [L][T^-1]。
• 哈希与复现：所有关键对象附 hash(·) 与 source_meta；日志中固化 SolverCfg 快照与随机 seed。
• 文件字符集与行尾：UTF-8，LF。时间戳采用 ISO-8601（UTC）。

IV. 数据对象与主键（对象最小字段）

1. Contract（计量契约）
   • 必填：id，spec_version，coords_spec，units_spec，mode ∈ {constant, general}，gauge:{x_ref,t_ref}，boundary_config，tolerances:{eps_T,eta_T}。
   • 依赖：n_eff_dependencies（如 F(Phi_T, grad_Phi_T, rho, f)）。
   • 哈希：hash(Phi_T)，hash(gamma)，hash(code)。
2. SeaModel
   • 必填：model_name，domain_bbox，resolution 或解析式 expr，time_ref，interpolation_policy。
   • 可选：layers_meta（层化与接口 Sigma 元数据）。
3. Path
   • 必填：path_id，gamma:[x...]，Δell:[…]（与 gamma 同长），可选 t_hat:[…]，interface_marks:[idx…]。
   • 约束：零基索引；Δell[k] > 0；坐标与单位与 Contract 一致。
4. Field
   • 必填：name ∈ {Phi_T, grad_Phi_T, n_eff}，storage_class ∈ {grid, trajectory}，coords_spec。
   • 网格：grid_axes:{x:[],y:[],z:[]}；轨迹：samples:{path_id:[…]}。
5. NeffParams
   必填：a0,a1,a2，可选 b1（定向项），c_m:{m:coef…}（频带项），n_min=1，n_max。
6. Observations
   • 必填：obs_id，path_id，f_hz，T_arr_obs_s，u_stat_s，u_sys_s，timestamp。
   • 可选：env_block（温湿度、时标来源等）。
7. CalibCref
   必填：gamma_ref_id，T_arr_ref_s，n_eff_ref_hash，c_ref_est，u_stat，u_sys，env_block。
8. Interfaces (Sigma)
   必填：sigma_id，type ∈ {continuous, jump_phi, jump_flux, anisotropic}，location（坐标或隐式函数），可选 C_sigma，J_sigma，R_sigma，T_trans，A_sigma。
9. Reports/Logs
   必填：run_id，contract_id，hashes，metrics:{eps_T,eta_T,GB,u_c}，notes。

V. 序列化与目录布局

1. 格式：静态数据优先 JSONL 或 Parquet；大体积网格可用 Zarr/NetCDF（仅作为容器，字段命名仍遵本规范）。
2. 目录（建议）
   • /contracts/：*.contract.json
   • /paths/：*.path.jsonl
   • /seamodel/：网格或解析元数据
   • /fields/：phi_t.*，grad_phi_t.*，neff.*
   • /obs/：到达时观测 *.obs.jsonl
   • /calib/：c_ref.*
   • /interfaces/：sigma.*
   • /artifacts/：报告、日志、哈希清单
3. 命名：<object>-<id>-<hash8>.<ext>；哈希为内容哈希前 8 字符。

VI. 字段与单位规范（关键字段清单）

• f_hz 单位 Hz = s^-1；T_arr_obs_s 单位 s；Δell 单位 m；c_ref 单位 m·s^-1。
• n_eff、n_common、n_path、R_sigma、T_trans、A_sigma 无量纲。
• Phi_T 可无量纲化，若未无量纲化需在 Contract 中声明 Phi_ref 并固化。
• grad_Phi_T 的单位为 dim(Phi_T)[L^-1]。
• 所有时间戳 timestamp 必须为 ISO-8601（UTC）。

VII. 输入输出契约（I/O 最小集合）

• 到达时计算输入（两口径共用）
  Contract，Path，n_eff 或 Phi_T+grad_Phi_T+NeffParams，c_ref 或 CalibCref。
• 到达时计算输出
  T_arr_mod_s，residual_s = T_arr_obs_s − T_arr_mod_s（若有观测），eta_T（双口径一致性），hashes 与 Log。
• 分项识别输入
  Observations（同一路径多频带），Phi_T 与 grad_Phi_T 或其可测近似，Contract。
• 分项识别输出
  NeffParams（a0,a1,a2,b1,c_m），u(·) 与协方差。

VIII. 质量校验与一致性检查（自动化）

• Q1 量纲检查：调用 check_dimension 核验两口径表达，输出 DimReport。
• Q2 单位一致：Δell、gamma、c_ref 单位一致；若不一致，入口转换并记录。
• Q3 下界：T_arr_obs_s ≥ L_path / c_ref；边缘样本允许在 k·u_c 负容差内但须标注。
• Q4 口径一致：若两口径均可用，要求 eta_T ≤ 阈值。
• Q5 分项残差：n_eff = n_common + n_path 的残差进入 u_sys 且低于阈值。
• Q6 界面能量一致：R_sigma + T_trans + A_sigma = 1。
• Q7 夹持记录：n_eff ∈ [1, n_max] 的夹持触发率与影响评估必须入日志。

IX. 错误语义（与第10章错误码对齐）

• E-DIM-001：量纲不一致；拒收。
• E-GAUGE-002：未固定规范或冲突；要求补充 gauge。
• E-NEFF-003：n_eff < 1 或分解失败；拒收并输出否证样本。
• E-PATH-004：路径离散非法；要求重建 {gamma, Δell}。
• E-INTF-005：界面匹配失败或越界。
• E-QAD-006：求积不收敛或 eps_T 未满足。
• E-CREF-007：c_ref 标定不可解或不稳定。
• E-CONSIST-008：两口径一致性失败。

X. JSONL 示例（最小可用样例）

• Contract（/contracts/example.contract.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)",

"hashes": {"hash(Phi_T)":"ab12cd34","hash(gamma)":"ef56ab78","hash(code)":"aa11bb22"}

}

• Path（/paths/p001.path.jsonl）

{"path_id":"p001","gamma":[[0,0,0],[0,0,1.0],[0,0,2.0]],"Δell":[1.0,1.0],"t_hat":[[0,0,1],[0,0,1]],"interface_marks":[]}

• Observations（/obs/p001.obs.jsonl）

{"obs_id":"o001","path_id":"p001","f_hz":1.0e9,"T_arr_obs_s":6.6713e-9,"u_stat_s":2.0e-11,"u_sys_s":3.0e-11,"timestamp":"2025-01-01T00:00:00Z"}

{"obs_id":"o002","path_id":"p001","f_hz":1.1e9,"T_arr_obs_s":6.6720e-9,"u_stat_s":2.0e-11,"u_sys_s":3.0e-11,"timestamp":"2025-01-01T00:00:01Z"}

• NeffParams（/fields/neff.params.json）

{"a0":1.0002,"a1":0.015,"a2":0.002,"b1":0.0001,"c_m":{"1":3.0e-12,"2":5.0e-24},"n_min":1.0,"n_max":1.1}

XI. 典型 I/O 工作流对接（与第10章接口一致）

1. 到达时计算（常量外提）
   • 读入：Contract，Path，NeffParams 与 Phi_T, grad_Phi_T 或 n_eff。
   • 计算：arrival_time_constant( n_eff, gamma, c_ref ) -> T_arr_mod_s。
   • 记录：Log 中写入 hash(·)，eps_T，eta_T，GB。
2. 分项识别（多频带同一路径）
   • 读入：Observations，Phi_T, grad_Phi_T，Contract。
   • 计算：decompose_n_eff，fit_n_eff_params -> NeffParams。
   • 校核：delta_arrival 与两口径一致性。
3. 界面分段与修正
   • 读入：Path 与 Interfaces (Sigma)。
   • 计算：segment_integrals + interface_correction -> {T_arr_i}, ΔT_sigma。
   • 校核：能量一致与下界。

XII. 数据质量与审计清单（落地即用）

• DQC-1 单位与量纲：units_spec 与 DimReport 必填。
• DQC-2 路径一致：gamma 与 Δell 同步；跨频带差分复用同一离散。
• DQC-3 频带配置：f_grid 声明与带外抑制阈值。
• DQC-4 夹持统计：记录 n_eff 夹持触发率与影响评估。
• DQC-5 界面一致：Sigma 标签、C_sigma/J_sigma、R_sigma/T_trans/A_sigma 完整。
• DQC-6 复现要素：SolverCfg、随机 seed、哈希清单齐备。

XIII. 安全与完整性

• 只读容器：推荐将 /contracts 与 /obs 以只读方式挂载，防止篡改。
• 内容哈希：采用内容哈希（不含文件名与时间戳）以保证跨环境一致。
• 最小化元数据：日志仅记录必要指标与哈希，避免泄露敏感路径与系统信息。
• 完整性校验：关键对象写入 sha256 与文件大小，导入前二次校验。

XIV. 跨卷对照（数据侧）

• 与《EFT.WP.Core.Metrology v1.0》：units_spec、coords_spec、traceability 字段对齐。
• 与《EFT.WP.Core.Equations v1.1》：符号与算子命名一致（如 grad_Phi_T、d ell）。
• 与《EFT.WP.Core.Errors v1.0》：u_stat/u_sys/u_c 的命名与报告口径一致。
• 与《EFT.WP.Metrology.PathCorrection v1.0》：路径修正相关字段沿用同名键与语义。

XV. 产出物

• 数据架构清单：Contract/SeaModel/Path/Field/NeffParams/Observations/CalibCref/Interfaces/Report 的字段说明与示例集合。
• I/O 契约样板：输入输出字段、单位、必填性、错误语义映射。
• 审计包模板：哈希清单、DimReport、SolverCfg、运行日志与否证样本清单。