30-EFT.WP.Propagation.TensionPotential v1.0 | Chapter 10 — Implementation Bindings & API Specification

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

Chapter 10 — Implementation Bindings & API Specification

• I. One-Sentence Aim
  Bind this volume’s physical quantities and computational gauges into reusable, auditable, and traceable APIs. Define data types, function prototypes, contract objects, and logging standards to guarantee cross-project consistency and real-world deployment.
• II. Scope & Non-Goals
• Covered: interface layering, data types, function prototypes, contracts and parameter validation, units and dimensions, error codes, concurrency and reproducibility, logging and audit, example workflows.
• Non-goals: no repetition of Chapter 4’s physical construction of Phi_T or Chapter 5’s theory for n_eff; no device-level mechanical/electrical design.
• III. Minimal Terms & Symbols
• Fields & potentials: T_fil(x,t), Phi_T(x,t), grad_Phi_T(x,t).
• Index & speeds: n_eff(x,t,f), c_ref, c_loc(x,t,f) = c_ref / n_eff(x,t,f).
• Path & measure: gamma(ell), d ell, interface set Sigma.
• Arrival-time gauges: T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ), or T_arr = ( ∫ ( n_eff / c_ref ) d ell ).
• Decomposition: n_eff = n_common(x,t) + n_path(x,t,f).
• Conventions: never mix T_fil with T_trans; never mix n with n_eff; wrap inline symbols in backticks.
• IV. Design Principles & Contract (Contract)
• Invariance & reproducibility
• Immutable inputs; pure functions; all stochastic processes are seedable; outputs and logs include content hashes.
• Dimensional consistency
• Enforce entry-point dimensional checks: dim(T_arr) = [T], dim(n_eff) = 1, dim(c_loc) = [L][T^-1].
• Gauge fixation & explicit interfaces
• The gauge Phi_T(x_ref,t_ref) = 0 and boundary_config must be explicitly recorded in the contract.
• Contract object (minimal fields)
• id, spec_version, units_spec, coords_spec
• mode ∈ {constant, general}
• n_eff_dependencies (e.g., F(Phi_T, grad_Phi_T, rho, f))
• gauge (x_ref,t_ref)
• boundary_config, Sigma_meta
• tolerances (eps_T, eta_T)
• guardband, uncertainty_method ∈ {GUM, MC, both}
• hashes (hash(Phi_T), hash(gamma), hash(code), …)
• seed, random_policy
• V. Data Structures & Types (minimal definitions)
• SeaModel
• Source and grid/analytic description; coordinates; units; timestamp; interpolation policy.
• Path
• gamma[k] (coordinates), Δell[k] (line elements), t_hat[k] (optional tangent), interface_marks (indices of intersections with Sigma).
• Field
• Handle to scalar/vector fields supporting value and gradient queries.
• NeffParams
• Scalar coefficients a0,a1,a2,b1; band coefficients c_m (or mapped fields); clamping interval n_min=1, n_max.
• SolverCfg
• Quadrature method; step-size policy; curvature/medium thresholds; convergence criteria; parallelism and caching policies.
• Report / Log
• Metrics, thresholds, error budgets, falsification samples, hashes, and runtime metadata.
• VI. Interface Layers & Function Prototypes (I-layer, full set)
• I. Build & gauge
• build_phi_t( T_fil, params_G ) -> Phi_T
• fix_gauge( Phi_T, x_ref, t_ref ) -> Phi_T
• apply_boundary( Phi_T, boundary_config ) -> Phi_T
• II. Potential–index mapping
• gradient( Phi_T ) -> grad_Phi_T
• estimate_n_eff( Phi_T, grad_Phi_T, rho, f, params ) -> n_eff
• decompose_n_eff( n_eff, f_grid ) -> n_common, n_path_params
• local_speed( n_eff, c_ref ) -> c_loc
• III. Path & interfaces
• capture_path( raw_track, coord_spec ) -> { gamma[k], Δell[k], t_hat[k] }
• detect_interfaces( gamma, sea_meta ) -> { ell_i }, Sigma
• apply_matching( Phi_T, Sigma, params ) -> Phi_T_matched
• segment_integrals( n_eff, gamma, { ell_i }, mode ) -> { T_arr_i }
• IV. Arrival-time computation (two gauges)
• arrival_time_constant( n_eff, gamma, c_ref ) -> T_arr
• arrival_time_general( n_eff, gamma, c_ref ) -> T_arr
• delta_arrival( n_path_params, f1, f2, gamma, mode, c_ref ) -> ΔT_arr
• V. Calibration & consistency
• calibrate_c_ref( gamma_ref, T_arr_ref, n_eff_ref, mode ) -> c_ref
• fit_n_eff_params( Phi_T, grad_Phi_T, data_multi_f, model_spec ) -> theta_hat, Cov
• check_dual_arrival_consistency( inputs ) -> eta_T
• VI. Uncertainty & guarding
• propagate_uncertainty_GUM( inputs ) -> u_c
• propagate_uncertainty_MC( inputs, Nsamples, seed ) -> dist(T_arr)
• check_dimension( expr ) -> DimReport
• VII. Performance, convergence & audit
• build_solver_config( params ) -> SolverCfg
• convergence_scan( problem, cfg_list ) -> Report
• benchmark_suite( runlist ) -> Summary
• cache_neighborhood( field, gamma, radius ) -> Handle
• log_artifacts( meta, hashes, metrics ) -> Log
• emit_report( contract, logs, artifacts ) -> Report
• Constraint: The units, coordinates, and gauge of all prototype inputs/outputs must match the Contract. mode ∈ {constant, general} corresponds to the two gauges in Chapter 6.
• VII. Parameter Validation & Units/Dimensions
• Unit checks: enforce length, time, speed, and dimensionless quantities at entry; emit DimReport.
• Coordinate consistency: Path and SeaModel must declare the same coordinate system; if not, provide an explicit invertible transform.
• Clamping rule: enforce n_eff ∈ [1, n_max]; log clamping trigger counts.
• Gauge consistency: keep x_ref,t_ref and boundary_config fixed across calls.
• VIII. Error Codes & Exceptions (minimal set)
• E-DIM-001 Inconsistent dimensions or missing units
• E-GAUGE-002 Gauge not fixed or conflicting
• E-NEFF-003 n_eff < 1 or decomposition failure
• E-PATH-004 Illegal path discretization or measure mismatch
• E-INTF-005 Interface matching failure or parameter out of bounds
• E-QAD-006 Quadrature not converged or error threshold unmet
• E-CREF-007 c_ref calibration unsolved or unstable
• E-CONSIST-008 Dual-gauge consistency failure (eta_T over threshold)
• E-IO-009 Missing/inconsistent contract/log/hash
• Handling: return an error object and preserve all intermediate logs and RNG seeds for replay and audit.
• IX. Concurrency, Determinism & Reproducibility
• Determinism: core functions are pure; randomness restricted to MC and never affects deterministic paths; record seed for every stochastic run.
• Concurrency: parallelize over frequency bands and paths; avoid shared mutable state; pass caches via read-only handles.
• Reproducibility: every entry point includes hash(Phi_T), hash(gamma), hash(code); reports include a SolverCfg snapshot.
• X. Security, Integrity & Naming Isolation
• Integrity: interfaces must not depend on external networks; optional input/output validation, hashing, and signatures.
• Naming isolation: T_trans is only for interface transmission; do not use it in tension or index fields; strictly distinguish n from n_eff.
• Log privacy: record only necessary metadata; redact sensitive source-data paths.
• XI. Logging & Audit (minimal fields)
• Runtime: timestamp, platform, library versions, spec_version, SolverCfg.
• Physics: hash(Phi_T), hash(grad_Phi_T), hash(n_eff), c_ref, mode.
• Geometry: hash(gamma), N, step_rule, eps_T, interface_marks.
• Errors: u_stat, u_sys, u_c, guardband, eta_T, clamping trigger rate.
• Falsification: lists and replay handles for violations of lower bounds, n_eff < 1, gauge inconsistency, and energy-conservation breaches.
• XII. Example Workflows (directly deployable)
• A. Grid-first: from T_fil to T_arr(f)
• Phi_T = build_phi_t( T_fil, params_G )
• Phi_T = fix_gauge( Phi_T, x_ref, t_ref ), then Phi_T = apply_boundary( … )
• grad_Phi_T = gradient( Phi_T )
• n_eff = estimate_n_eff( Phi_T, grad_Phi_T, rho, f, params )
• T_arr = arrival_time_constant( n_eff, gamma, c_ref ) (or arrival_time_general)
• log_artifacts( … ), emit_report( … )
• B. Reference-speed calibration & dual-gauge consistency
• c_ref = calibrate_c_ref( gamma_ref, T_arr_ref, n_eff_ref, mode )
• eta_T = check_dual_arrival_consistency( inputs ) (require eta_T ≤ threshold)
• C. Multi-band differencing to isolate the path term
• n_common, n_path_params = decompose_n_eff( n_eff, f_grid )
• ΔT_arr = delta_arrival( n_path_params, f1, f2, gamma, mode, c_ref )
• Compare against observed differentials; update NeffParams or c_ref.
• XIII. Cross-References
• EFT.WP.Propagation.TensionPotential v1.0 Chapters 4, 5, 6, 7, 8, 9
• EFT.WP.Core.Equations v1.1 S06-*
• EFT.WP.Core.Metrology v1.0 M05-, M10-
• EFT.WP.Core.Errors v1.0 M20-*
• XIV. Deliverables
• API reference checklist: prototypes; input/output; unit and dimensional requirements; error codes.
• Contract templates: field specifications for Contract, SolverCfg, Path, NeffParams, Report, Log.
• Audit & reproducibility examples: logs and hash sets for workflows A/B/C.