32-EFT.WP.Cosmo.LayeredSea v1.0 | 附录B 数据规范与输入输出

目录 ／ 文档-技术白皮书 ／ 32-EFT.WP.Cosmo.LayeredSea v1.0

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

I. 一句话目标

一句话目标：以模板 v0.1（《EFT 技术白皮书与技术备忘模板 全面清单 v0.1》）为唯一锚点，定义层化 Energy Sea 的数据对象、字段与单位、序列化与目录、I/O 契约与错误语义，确保 SeaProfile、W_k/ Xi_k、Phi_T/grad_Phi_T、n_eff、{ ell_i }、Delta_T_sigma、R_sea/T_trans/A_sigma 与两类 T_arr/ΔT_arr 的数据流可落地、可复现、可审计。

II. 适用范围与非目标

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

III. 总体约束与约定

• 坐标/度规/单位：coords_spec、metric_spec、units_spec 必填；入口统一到 SI。若输入含 km/ms，必须映射为 m/s 并记录映射。
• 内联符号：T_arr、n_eff、c_ref、gamma(ell)、Sigma_sea、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_sea + 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，metric_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(SeaProfile)，hash(Phi_T)，hash(grad_Phi_T)，hash(n_eff)，hash(gamma)，hash(code)
2. SeaProfile（层剖面）
   • 必填：model_k ∈ {tanh, logistic, spline}，chi_k，Delta_k，sigma_k（若适用），eta_w
   • 可选：角向系数 a_{lm}^{(k)}、带限 L
   • 派生：Sigma_sea 隐式函数/网格近似，hash(SeaProfile)
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；可选：u0_k,u1_k,b1,b1_n,c_m:{m:coef}，n_min=1，n_max
6. RTParams
   必填：R_sea(f)，T_trans(f)，A_sigma(f) 的采样/插值模型与夹持区间
7. Interfaces (Sigma_sea)
   • 必填：sigma_id，type ∈ {continuous, jump_phi, jump_flux, anisotropic}，location（坐标或隐式函数参数）
   • 可选：C_sigma，J_sigma，R_sea,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
   • /seaprofile/：*.sea.json
   • /paths/：*.path.jsonl
   • /fields/：phi_t.*，grad_phi_t.*，neff.*
   • /interfaces/：sigma_sea.*
   • /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_sea、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. 输入输出契约（与模板接口族一致）

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

1. 到达时计算（两口径）
   • 输入：Contract，Path，n_eff 或 Phi_T+grad_Phi_T+NeffParams+SeaProfile，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. 层剖面反演（SeaProfile）
   • 输入：Observations（多频带/多路径），Phi_T/grad_Phi_T（或近似），Contract
   • 接口族：I.Fit.Profile，I.RT.Estimate，I.Consistency.DualMode，I.Consistency.ThinThick，I.Report.Emit
   • 输出：SeaProfile(theta_hat, Cov)，RTParams，一致性与否证清单
3. 界面匹配与能量一致
   • 输入：SeaProfile，Interfaces，Path，Fields，Contract
   • 接口族：I.Interface.ApplyMatching，I.Path.Segment，I.Path.InterfaceCorrection，I.RT.Estimate，I.Report.Log
   • 输出：侧限 n_eff^± 概要，R_sea/T_trans/A_sigma 余量曲线，Log

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

• DQC-1 量纲检查：check_dimension 覆盖两口径、分段离散式与层项（见附录 A）
• DQC-2 单位一致：Δell、gamma、c_ref 单位一致；不一致按入口映射并记录
• DQC-3 下界：T_arr_obs ≥ L_path / c_ref；边缘样本可在 −k·u_c 内但须标注
• DQC-4 两口径一致：若两口径可用，eta_T ≤ 阈值
• DQC-5 能量一致：每个界面/频带 R_sea + T_trans + A_sigma = 1
• DQC-6 薄/厚层一致：tau_switch = | T_arr^{thick} − (T_arr^{thin}+Delta_T_sigma) | ≤ 门限
• DQC-7 差分一致：同一路径多频点差分复用同一 { gamma[k], Δell[k] } 与相同 Delta_T_sigma 设置
• DQC-8 夹持统计：记录 n_eff ∈ [1,n_max] 夹持触发率与影响评估
• DQC-9 可复现：SolverCfg、随机 seed、hash(*)、重放命令齐备

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

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

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

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

{

"id": "ct-ls-001",

"spec_version": "EFT.WP.Cosmo.LayeredSea 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"},

"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(SeaProfile)":"aa22bb33","hash(Phi_T)":"ab12cd34","hash(grad_Phi_T)":"de98fa76","hash(gamma)":"ef56ab78","hash(code)":"aa11bb22"}

}

• SeaProfile（/seaprofile/layered.v1.sea.json）

{

"layers": [

{"model":"tanh","chi_k":1.2e3,"Delta_k":2.0e2,"sigma_k":1.0e2},

{"model":"spline","chi_k":2.1e3,"Delta_k":3.0e2,"spline_nodes":[[1.95e3,0.05],[2.1e3,0.5],[2.25e3,0.95]]}

],

"eta_w": 0.03,

"Sigma_sea_meta": {"implicit":"W_k(chi)-0.5=0","grid_hash":"22cc99aa"},

"hash(SeaProfile)": "77cc11dd"

}

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

{"path_id":"p001","gamma":[[0,0,1.1e3],[0,0,1.3e3],[0,0,2.3e3]],"Δell":[2.0e2,1.0e3],"t_hat":[[0,0,1],[0,0,1]],"interface_marks":[1]}

• Interfaces（/interfaces/sigma_sea.jsonl）

{"sigma_id":"s001","type":"jump_phi","location":{"implicit":"W_1(chi)-0.5=0"},"C_sigma":0.08,"J_sigma":0.0}

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

{"obs_id":"o001","path_id":"p001","f_hz":1.0e9,"T_arr_obs_s":6.2001e-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":6.2008e-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_sea":[["9.5e8",0.18],["1.0e9",0.20],["1.05e9",0.19]],"T_trans":[["9.5e8",0.77],["1.0e9",0.76],["1.05e9",0.78]],"A_sigma":[["9.5e8",0.05],["1.0e9",0.04],["1.05e9",0.03]]}

• CalibCref（/calib/c_ref.json）

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

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

以模板接口族为准；工程映射可附“模板接口族 → I60-*”。

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|General
• 记录与审计：I.Report.Log|Emit

B. 层剖面反演（SeaProfile）

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

C. 界面匹配与能量一致

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

D. 频带差分与 path term 隔离

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

XII. 数据质量与审计清单（发布前自检）

• DimReport 必填；Δell/c_ref 单位一致；metric_spec 显式
• { ell_i } 端点显式入积；无跨界面插值
• eta_T、tau_switch、下界余量与能量一致余量达标
• 差分复用同一路径离散与修正配置；记录带外泄漏比
• 夹持触发率入日志；hash(*)、SolverCfg、seed、重放命令齐备

XIII. 安全与完整性

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

XIV. 跨卷对照（数据侧）

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

XV. 产出物

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