31-EFT.WP.BH.TensionWall v1.0 | 附录B 数据规范与输入输出

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

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

I. 一句话目标

一句话目标：以《EFT 技术白皮书与技术备忘模板 全面清单 v0.1》（下称“模板 v0.1”）为唯一锚点，定义围绕张度墙 Sigma_TW 的数据对象、字段与单位、序列化与目录、I/O 契约与错误语义，确保 TWProfile、Phi_T/grad_Phi_T、n_eff、{ ell_i }、Delta_T_sigma、R_TW/T_trans/A_sigma 与两类到达时 T_arr 的数据流可直接落地、复现与审计。

II. 适用范围与非目标

• 覆盖：对象模型与主键、字段与单位、序列化与目录、输入输出契约、质量校验与一致性检查、示例与模板接口族对接。
• 非目标：不重述物理推导与数值算法；不给出装置级硬件口径；不依赖私有或不可验证的外部格式。

III. 总体约束与约定

• 坐标与单位：coords_spec 必填（Cartesian/Spherical 或 ECEF/ENU），units_spec 统一 SI。若输入含 km/ms 等，入口必须映射为 m/s 并记录映射。
• 内联符号：文内一律用反引号（如 T_arr、n_eff、c_ref、gamma(ell)、Sigma_TW、Delta_T_sigma）。
• 命名隔离：T_fil（张力）与 T_trans（透射系数）严禁混用；n（数密度）与 n_eff（有效折射率）严禁混用。
• 量纲与下界：入口强制 check_dimension，保证 dim(T_arr)=[T]、dim(n_eff)=1、dim(c_ref)=[L][T^-1]；任意结果需满足 T_arr ≥ L_path / c_ref（一般口径在被积函数内等价）。
• 能量一致：界面事件满足 R_TW + T_trans + A_sigma = 1，并在带内给出曲线与余量。
• 两口径：mode ∈ {constant, general}；常量外提 T_arr = (1/c_ref) * ( ∫ n_eff d ell )，一般口径 T_arr = ( ∫ ( n_eff / c_ref ) d ell )。

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

1. Contract（计量契约）
   • 必填：id，spec_version，coords_spec，units_spec，mode，gauge:{x_ref,t_ref}，boundary_config，tolerances:{eps_T,eta_T,eta_w,tau_switch}
   • 依赖：n_eff_dependencies（如 F(Phi_T, grad_Phi_T, rho, f)）
   • 哈希：hash(Phi_T)，hash(grad_Phi_T)，hash(n_eff)，hash(gamma)，hash(code)
2. TWProfile（壁剖面）
   • 必填：model ∈ {tanh, logistic, spline, exp_tail}，r_H 或 r_H(theta,phi)，Delta_w 或 Delta_w(theta,phi)，sigma_w（若适用），eta_w
   • 可选：样条节点/系数，alpha, lambda（尾部项），a_{lm}（非球对称）
   • 派生：Sigma_TW_meta（隐式函数/网格近似）、hash(TWProfile)
3. Path
   • 必填：path_id，gamma:[…]（坐标点），Δell:[…]（线元，等长），可选 t_hat:[…]
   • 界面：interface_marks:[idx…]（与 { ell_i } 对应的离散索引或插值位置）
4. Field
   • 必填：name ∈ {Phi_T, grad_Phi_T, n_eff}，storage ∈ {grid, trajectory}，coords_spec，units_spec
   • 网格：grid_axes:{x:[],y:[],z:[]}；轨迹：samples:{path_id:[…]}
5. NeffParams
   必填：a0,a1,a2；可选：b1,b1_sigma，c_m:{m:coef}，n_min=1，n_max
6. RTParams
   必填：R_TW(f)，T_trans(f)，A_sigma(f) 的采样/插值模型与夹持区间
7. Interfaces (Sigma_TW)
   • 必填：sigma_id，type ∈ {continuous, jump_phi, jump_flux, anisotropic}，location（坐标或隐式函数参数）
   • 可选：C_sigma，J_sigma，R_TW,T_trans,A_sigma（若事件级估计）
8. Observations
   • 必填：obs_id，path_id，f_hz，T_arr_obs_s，u_stat_s，u_sys_s，timestamp（ISO-8601，UTC）
   • 可选：env_block（温湿度、时标源等）
9. CalibCref
   必填：gamma_ref_id，T_arr_ref_s，n_eff_ref_hash，c_ref_est，u_stat，u_sys，env_block
10. Report/Log
    必填：run_id，contract_id，hashes，metrics:{eps_T,eta_T,eta_c,eta_w,tau_switch,GB,u_c}，notes

V. 序列化与目录布局

1. 格式：静态数据用 JSONL/Parquet；大体积网格场用 Zarr/NetCDF（字段名仍遵本规范）。
2. 目录（建议）
   • /contracts/：*.contract.json
   • /twprofile/：*.tw.json
   • /paths/：*.path.jsonl
   • /fields/：phi_t.*，grad_phi_t.*，neff.*
   • /interfaces/：sigma_tw.*
   • /obs/：*.obs.jsonl
   • /calib/：c_ref.*
   • /rtparams/：rt.*
   • /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_TW、T_trans、A_sigma：无量纲
• Phi_T 可无量纲化；若未无量纲化，Contract 必须声明 Phi_ref；grad_Phi_T 单位 dim(Phi_T)[L^-1]
• Delta_T_sigma、tau_switch：s
• 坐标与单位必须与 Contract 一致；跨系数据需提供显式变换与映射日志

VII. 输入输出契约（与模板 v0.1 接口族一致）

说明：本节锚定模板接口族（而非本卷实现）。如需实现映射，可在工程手册中补充“模板接口族 → I40-*”。

1. 到达时计算（两口径）
   • 输入：Contract，Path，n_eff 或 Phi_T+grad_Phi_T+NeffParams+TWProfile，c_ref 或 CalibCref
   • 接口族：I.Path.Capture，I.Path.Segment，I.Build.Phi，I.Build.Neff，I.Arrival.Constant|General，I.Path.InterfaceCorrection（薄壁可选）
   • 输出：T_arr_mod_s，（可选）Delta_T_sigma_s，eta_T，hashes，Log
2. 壁剖面反演（TWProfile）
   • 输入：Observations（多频带/多路径），Phi_T/grad_Phi_T（或近似），Contract
   • 接口族：I.Fit.Profile，I.RT.Estimate，I.Consistency.DualMode，I.Consistency.ThinThick，I.Report.Emit
   • 输出：TWProfile(theta_hat, Cov)，RTParams，一致性指标与否证清单
3. 界面匹配与能量一致
   • 输入：TWProfile，Interfaces，Path，Fields，Contract
   • 接口族：I.Interface.ApplyMatching，I.Path.Segment，I.Path.InterfaceCorrection，I.RT.Estimate，I.Report.Log
   • 输出：侧限 n_eff^± 概要，R_TW/T_trans/A_sigma 余量曲线，Log

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

• Q1 量纲检查：check_dimension 覆盖两口径、分段离散式与 TW 项（见附录 A）
• Q2 单位一致：Δell、gamma、c_ref 单位一致；不一致按入口映射并记录
• Q3 下界：T_arr_obs ≥ L_path / c_ref；边缘样本可在 −k·u_c 内但须标注
• Q4 两口径一致：若两口径可用，eta_T ≤ 阈值
• Q5 能量一致：每个界面/频带 R_TW + T_trans + A_sigma = 1
• Q6 薄/厚壁一致：tau_switch = | T_arr^{thick} − (T_arr^{thin}+Delta_T_sigma) | ≤ 门限
• Q7 差分一致：同一路径多频点差分复用同一 { gamma[k], Δell[k] } 与相同 Delta_T_sigma 设置
• Q8 夹持统计：记录 n_eff ∈ [1,n_max] 夹持触发率与影响评估

IX. 错误语义（与模板 v0.1 错误族对齐）

• E-DIM-001：量纲不一致或单位缺失（拒收）
• E-GAUGE-002：规范未固定或冲突（要求补充 gauge）
• E-NEFF-003：n_eff < 1 或分解失败（拒收并登记否证样本）
• E-PATH-004：路径离散非法或与测度不一致（要求重建 {gamma, Δell}）
• E-INTF-005：界面匹配失败或参数越界（拒收，并附 Sigma_TW 标签）
• E-QAD-006：求积不收敛或 eps_T 未满足（返回局部误差明细）
• E-CREF-007：c_ref 标定不可解或不稳定（返回环境块）
• E-CONSIST-008：两口径一致性失败
• E-TW-010：薄/厚壁一致性失败或 Delta_T_sigma 与体积分差值超阈

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

• Contract（/contracts/tw.contract.json）

{

"id": "ct-tw-001",

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

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

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

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

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

}

• TWProfile（/twprofile/p001.tw.json）

{

"model": "tanh",

"r_H": 1.8e9,

"Delta_w": 1.2e6,

"sigma_w": 6.0e5,

"eta_w": 0.03,

"Sigma_TW_meta": {"implicit":"r - r_H = 0","grid_hash":"22cc99aa"},

"hash(TWProfile)": "77cc11dd"

}

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

{"path_id":"p001","gamma":[[0,0,1.8e9-8e5],[0,0,1.8e9+8e5]],"Δell":[1.6e6],"t_hat":[[0,0,1]],"interface_marks":[0]}

• Interfaces（/interfaces/sigma_tw.jsonl）

{"sigma_id":"s001","type":"jump_phi","location":{"implicit":"r - r_H = 0"},"C_sigma":0.12,"J_sigma":0.0}

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

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

{"obs_id":"o002","path_id":"p001","f_hz":1.05e9,"T_arr_obs_s":5.9998e-3,"u_stat_s":2.0e-6,"u_sys_s":3.0e-6,"timestamp":"2025-01-01T00:00:01Z"}

• RTParams（/rtparams/rt.p001.json）

{"R_TW":[["9.5e8",0.21],["1.0e9",0.24],["1.05e9",0.23]],"T_trans":[["9.5e8",0.73],["1.0e9",0.71],["1.05e9",0.72]],"A_sigma":[["9.5e8",0.06],["1.0e9",0.05],["1.05e9",0.05]]}

• CalibCref（/calib/c_ref.json）

{"gamma_ref_id":"p_ref","T_arr_ref_s":6.0000e-3,"n_eff_ref_hash":"99aa33bb","c_ref_est":3.0e8,"u_stat":5.0e3,"u_sys":1.0e3,"env_block":{"temp_C":20.0,"clock":"UTC"}}

XI. 典型 I/O 工作流对接（与模板 v0.1 接口族一致）

下列流程以模板接口族为准；如需工程实现映射，请在工程手册中附“模板接口族 → I40-*”。

A. 到达时计算（常量外提 / 一般口径）

• 路径获取：I.Path.Capture → 生成 { gamma[k], Δell[k] }；I.Path.Segment → 生成 { ell_i }
• 场与折射率装配：I.Build.Phi、I.Build.Neff
• 界面修正（薄壁可选）：I.Path.InterfaceCorrection
• 到达时计算：I.Arrival.Constant / I.Arrival.General
• 记录与审计：I.Report.Log / I.Report.Emit

B. 壁剖面反演（TWProfile）

• 数据编排：I.Path.Capture / I.Path.Segment；I.Build.Phi / I.Build.Neff
• 反演求解：I.Fit.Profile
• 能量三元组：I.RT.Estimate
• 一致性校核：I.Consistency.DualMode，I.Consistency.ThinThick
• 报告归档：I.Report.Emit

C. 界面匹配与能量一致

• 匹配与侧限：I.Interface.ApplyMatching；I.Build.Neff
• 分段与修正：I.Path.Segment / I.Path.InterfaceCorrection
• 能量一致：I.RT.Estimate
• 记录：I.Report.Log

D. 频带差分与 path term 隔离

• 分解与差分：I.Arrival.Delta
• 带外与一致性：I.Consistency.DualMode / I.Report.Log

E. 不确定度传播与风险评估

• GUM：I.Uncertainty.GUM
• MC：I.Uncertainty.MC
• 发布：I.Report.Emit

XII. 数据质量与审计清单（DQC）

• DQC-1 量纲/单位：DimReport 必填；跨系转换记录映射与哈希
• DQC-2 路径一致：gamma、Δell 同步；{ ell_i } 端点显式入积；禁止跨界面插值
• DQC-3 频带配置：f_grid 声明；差分复用同一离散；记录带外泄漏比
• DQC-4 薄/厚壁：在 eta_w 邻域双算并出具 tau_switch；超阈固定厚壁链路
• DQC-5 能量一致：R_TW/T_trans/A_sigma 余量面板；侧限 n_eff^± ≥ 1
• DQC-6 两口径：eta_T 达标；一般口径需记录 c_ref(x,t,f) 模型与不确定度
• DQC-7 夹持统计：n_eff ∈ [1,n_max] 触发率与影响评估
• DQC-8 可复现：SolverCfg、随机 seed、hash(*)、重放命令齐备

XIII. 安全与完整性

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

XIV. 跨卷对照（数据侧）

• 与《EFT.WP.Propagation.TensionPotential v1.0》：两口径字段、Path/Field 命名与单位一致
• 与《EFT.WP.Core.Metrology v1.0：units_spec、coords_spec、traceability` 对齐
• 与《EFT.WP.Core.Errors v1.0》：u_stat/u_sys/u_c 与报告口径一致
• 与《EFT.WP.Metrology.PathCorrection v1.0》：路径修正相关字段沿用同名键与语义

XV. 产出物

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