30-EFT.WP.Propagation.TensionPotential v1.0 | Appendix B — Data Specification & I/O

Home ／ Docs-Technical WhitePaper ／ 30-EFT.WP.Propagation.TensionPotential v1.0

Appendix B — Data Specification & I/O

• I. One-Sentence Aim
  Provide the end-to-end data objects, field specifications, and I/O contracts needed in this volume—covering file organization, serialization formats, units and coordinates, hashing and reproducibility, validation and error semantics—so that the data flows for Phi_T, n_eff, gamma(ell), and T_arr can be deployed directly under both arrival-time gauges.
• II. Applicability & Non-Goals
• Covered: data objects and primary keys; fields and units; serialization formats and directory conventions; I/O interface contracts; quality validation and consistency checks; examples and ready-to-use checklists.
• Not covered: theory derivations and algorithmic details; device-level hardware datasheets; dependence on proprietary external formats.
• III. Global Constraints & Conventions
• Coordinates & units: coords_spec is required, default Cartesian; units_spec uses SI. If inputs contain km or ms, they must be mapped to m and s at ingress and the mapping must be recorded.
• Inline symbols: wrap all inline formula symbols with backticks (e.g., T_arr, n_eff, c_ref, gamma(ell)).
• Naming isolation: never mix T_fil with T_trans; never mix n with n_eff.
• Dimensional consistency: at ingress, enforce dim(T_arr) = [T], dim(n_eff) = 1, dim(c_ref) = [L][T^-1].
• Hashing & reproducibility: attach hash(·) and source_meta to all critical objects; persist a SolverCfg snapshot and RNG seed in logs.
• Text encoding & line endings: UTF-8, LF. Timestamps use ISO-8601 (UTC).
• IV. Data Objects & Primary Keys (minimal fields)
• Contract (metrology contract)
• Required: id, spec_version, coords_spec, units_spec, mode ∈ {constant, general}, gauge:{x_ref,t_ref}, boundary_config, tolerances:{eps_T,eta_T}.
• Dependencies: n_eff_dependencies (e.g., F(Phi_T, grad_Phi_T, rho, f)).
• Hashes: hash(Phi_T), hash(gamma), hash(code).
• SeaModel
• Required: model_name, domain_bbox, resolution or analytic expression expr, time_ref, interpolation_policy.
• Optional: layers_meta (stratification and interface Sigma metadata).
• Path
• Required: path_id, gamma:[x...], Δell:[…] (same length as gamma); optional t_hat:[…], interface_marks:[idx…].
• Constraints: zero-based indices; Δell[k] > 0; coordinates/units must match Contract.
• Field
• Required: name ∈ {Phi_T, grad_Phi_T, n_eff}, storage_class ∈ {grid, trajectory}, coords_spec.
• Grid: grid_axes:{x:[],y:[],z:[]}; Trajectory: samples:{path_id:[…]}.
• NeffParams
• Required: a0,a1,a2; optional b1 (directional term); c_m:{m:coef…} (band terms); n_min=1, n_max.
• Observations
• Required: obs_id, path_id, f_hz, T_arr_obs_s, u_stat_s, u_sys_s, timestamp.
• Optional: env_block (temperature/humidity, timebase source, etc.).
• CalibCref
• Required: gamma_ref_id, T_arr_ref_s, n_eff_ref_hash, c_ref_est, u_stat, u_sys, env_block.
• Interfaces (Sigma)
• Required: sigma_id, type ∈ {continuous, jump_phi, jump_flux, anisotropic}, location (coordinates or implicit function); optional C_sigma, J_sigma, R_sigma, T_trans, A_sigma.
• Reports/Logs
• Required: run_id, contract_id, hashes, metrics:{eps_T,eta_T,GB,u_c}, notes.
• V. Serialization & Directory Layout
• Formats: prefer JSONL or Parquet for static data; for large grids use Zarr/NetCDF as containers (field names must still follow this spec).
• Suggested directory tree
• /contracts/: *.contract.json
• /paths/: *.path.jsonl
• /seamodel/: grid or analytic metadata
• /fields/: phi_t.*, grad_phi_t.*, neff.*
• /obs/: arrival-time observations *.obs.jsonl
• /calib/: c_ref.*
• /interfaces/: sigma.*
• /artifacts/: reports, logs, hash manifests
• Naming convention: <object>-<id>-<hash8>.<ext> where hash8 is the first 8 chars of the content hash.
• VI. Field & Unit Norms (key fields)
• f_hz in Hz = s^-1; T_arr_obs_s in s; Δell in m; c_ref in m·s^-1.
• n_eff, n_common, n_path, R_sigma, T_trans, A_sigma are dimensionless.
• Phi_T may be non-dimensionalized; if not, declare Phi_ref in Contract and persist it.
• grad_Phi_T has units dim(Phi_T)[L^-1].
• All timestamp fields must be ISO-8601 (UTC).
• VII. I/O Contracts (minimal sets)
• Inputs for arrival-time computation (both gauges)
• Contract, Path, and either n_eff or Phi_T + grad_Phi_T + NeffParams, plus c_ref or CalibCref.
• Outputs for arrival-time computation
• T_arr_mod_s; residual_s = T_arr_obs_s − T_arr_mod_s (if observations present); eta_T (two-gauge consistency); hashes and Log.
• Inputs for term separation
• Observations (same path across multiple bands), Phi_T & grad_Phi_T (or measurable approximations), Contract.
• Outputs for term separation
• NeffParams (a0,a1,a2,b1,c_m), uncertainties u(·) and covariance.
• VIII. Quality Checks & Consistency (automated)
• Q1 Dimensional checks: call check_dimension to validate both gauges; emit DimReport.
• Q2 Unit consistency: Δell, gamma, and c_ref units must match; if not, convert at ingress and record.
• Q3 Lower bound: enforce T_arr_obs_s ≥ L_path / c_ref; allow edge samples within a k·u_c negative tolerance band but flag them.
• Q4 Gauge consistency: when both gauges are applicable, require eta_T ≤ threshold.
• Q5 Term-separation residuals: in n_eff = n_common + n_path, route residuals into u_sys and keep them below threshold.
• Q6 Interface energy consistency: R_sigma + T_trans + A_sigma = 1.
• Q7 Clamping log: for n_eff ∈ [1, n_max], log clamping trigger rate and impact assessment.
• IX. Error Semantics (aligned with Chapter 10 codes)
• E-DIM-001: dimensional inconsistency; reject.
• E-GAUGE-002: gauge not fixed or conflicting; request gauge.
• E-NEFF-003: n_eff < 1 or decomposition failure; reject and emit a falsification sample.
• E-PATH-004: illegal path discretization; request rebuilding {gamma, Δell}.
• E-INTF-005: interface matching failure or parameters out of bounds.
• E-QAD-006: quadrature not converged or eps_T unmet.
• E-CREF-007: c_ref calibration unsolved or unstable.
• E-CONSIST-008: two-gauge consistency failure.
• X. JSONL Examples (minimal usable samples)
• 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. Typical I/O Workflow Wiring (aligned with Chapter 10 interfaces)
• Arrival-time computation (constant-factored)
• Ingest: Contract, Path, NeffParams and Phi_T, grad_Phi_T or n_eff.
• Compute: arrival_time_constant( n_eff, gamma, c_ref ) -> T_arr_mod_s.
• Record: write hash(·), eps_T, eta_T, GB into Log.
• Term separation (same path, multiple bands)
• Ingest: Observations, Phi_T, grad_Phi_T, Contract.
• Compute: decompose_n_eff, fit_n_eff_params -> NeffParams.
• Verify: delta_arrival and two-gauge consistency.
• Interface segmentation & corrections
• Ingest: Path and Interfaces (Sigma).
• Compute: segment_integrals + interface_correction -> {T_arr_i}, ΔT_sigma.
• Verify: energy consistency and lower bound.
• XII. Data Quality & Audit Checklist (ready to use)
• DQC-1 Units & dimensions: units_spec and DimReport are mandatory.
• DQC-2 Path coherence: gamma and Δell are synchronized; reuse the same discretization for cross-band differencing.
• DQC-3 Band configuration: declare f_grid and out-of-band suppression thresholds.
• DQC-4 Clamping statistics: record n_eff clamping trigger rate and impact assessment.
• DQC-5 Interface integrity: complete Sigma labels, C_sigma/J_sigma, and R_sigma/T_trans/A_sigma.
• DQC-6 Reproducibility factors: SolverCfg, RNG seed, and hash manifest are complete.
• XIII. Security & Integrity
• Read-only containers: mount /contracts and /obs read-only to prevent tampering.
• Content hashing: use content hashes (excluding filenames and timestamps) to ensure cross-environment consistency.
• Minimal metadata: logs should record only necessary metrics and hashes, avoiding sensitive path/system disclosures.
• Integrity checks: store sha256 and file size for critical objects; re-validate on import.
• XIV. Cross-Volume Alignment (data-side)
• With EFT.WP.Core.Metrology v1.0: align units_spec, coords_spec, and traceability fields.
• With EFT.WP.Core.Equations v1.1: align symbol/operator names (e.g., grad_Phi_T, d ell).
• With EFT.WP.Core.Errors v1.0: align naming and reporting conventions for u_stat/u_sys/u_c.
• With EFT.WP.Metrology.PathCorrection v1.0: reuse identical keys and semantics for path-correction fields.
• XV. Deliverables
• Data architecture roster: field specs and examples for Contract/SeaModel/Path/Field/NeffParams/Observations/CalibCref/Interfaces/Report.
• I/O contract templates: inputs/outputs, units, requiredness, and error-semantics mapping.
• Audit package template: hash manifest, DimReport, SolverCfg, run logs, and falsification sample list.