41-EFT.WP.Comms.Navigation v1.0 | Chapter 12: Interfaces & Implementation Bindings

Home ／ Docs-Technical WhitePaper ／ 41-EFT.WP.Comms.Navigation v1.0

Chapter 12: Interfaces & Implementation Bindings

I. Scope & Principles

• S120-1 (Objective)
  Fix cross-team/cross-pipeline external interfaces and implementation bindings spanning path/arrival time, observation construction, geometry/deployment, synchronization, dynamics, fusion, robustness, measurement matrix, and simulation stack.
• S120-2 (Unified conventions)
  Requests/responses must include unit_system:"SI", references:["<volume vX.Y: anchor>"], contract_version, and schema_version. All formulas/symbols/definitions are in English and must pass check_dim.
• S120-3 (Naming & idempotency)
  Interface IDs I12-*; idempotent ops carry request_id and a replay policy.
• S120-4 (Arrival-time conventions)
  If T_arr is involved, contracts must declare exactly one of pulled_const|integrand and provide delta_form, gamma(ell), and d_ell.
• S120-5 (Error model)
  Unified error object:
• { "code":"E/…","message":"…","at":"stage.name","hint":"…","refs":["…"] }

with code ∈ {E/INPUT,E/UNIT,E/CONTRACT,E/NUMERIC,E/IDENTIFIABILITY,E/RESOURCE,E/INTERNAL}.

II. Interface Overview & Alias Mapping

1. S120-6 (Families)
   • AT (Path/Arrival): I12-AT-* ↔ Ch.3 I3-*
   • OBS (Observation build): I12-OBS-* ↔ Ch.4 I4-*
   • GEO (Geometry/Deployment): I12-GEO-* ↔ Ch.5 I5-*
   • SYNC (Synchronization): I12-SYNC-* ↔ Ch.6 I6-*
   • KIN (Kinematics/Preintegration): I12-KIN-* ↔ Ch.7 I7-*
   • FUSE (Fusion): I12-FUSE-* ↔ Ch.8 I8-*
   • ROB (Robustness): I12-ROB-* ↔ Ch.9 I9-*
   • MAT (Measurement/Design): I12-MAT-* ↔ Ch.10 I10-*
   • SIM (Simulation/Synthetic): I12-SIM-* ↔ Ch.11 I11-*
2. S120-7 (Alias table — excerpt)
   I3-1≡I12-AT-deembed_path, I4-2≡I12-OBS-build_jacobian, I5-1≡I12-GEO-compute_dop_maps, I6-1≡I12-SYNC-estimate_clock, I7-2≡I12-KIN-imu_preintegrate, I8-1≡I12-FUSE-ekf_step, I9-3≡I12-ROB-robust_reweight, I10-2≡I12-MAT-compute_fisher, I11-6≡I12-SIM-make_synthetic.

III. Common Data Contract & Object Schemas

• S120-8 (Request prototype)
• {
• "request_id":"uuid",
• "inputs":{...},
• "contracts":{
• "unit_system":"SI",
• "arrival_time":{
• "convention":"pulled_const|integrand",
• "delta_form":"c_ref^-1 * ∫ n_eff dℓ | ∫ (n_eff/c_ref) dℓ",
• "gamma":"piecewise: free|fixture|substrate|device|environment",
• "d_ell":"m"
• }
• },
• "cal_bundle":{...},
• "priors":{...},
• "references":["EFT.WP.Core.Equations v1.1:Ch.2 S20-*","..."],
• "schema_version":"12.0.0",
• "contract_version":"1.0"
• }
• S120-9 (Response prototype)
• {
• "request_id":"uuid",
• "outputs":{...},
• "meta":{"ci":{...},"units":{...},"runtime":{...}},
• "warnings":[{"code":"W/…","message":"…","refs":["…"]}],
• "errors":[]
• }
• S120-10 (Units & dimensions)
  All tensors/arrays carry units, e.g., {"T_arr":{"unit":"s"},"AOA":{"unit":"rad"}}; implementations must pass check_dim.

IV. AT (Path/Arrival) Interfaces

• I12-AT-deembed_path (I3-1)
• in : {standards, scheme}
• out: {n_bg(ω), T_arr_bg, drift_model}
• I12-AT-unwrap_and_delay (I3-2)
• in : {S21_or_trace}
• out: {phi(ω), τ_g, seg_uncertainty}
• I12-AT-compute_arrival_time (I3-3)
• in : {phi_or_τg, convention, path}
• out: {T_arr(ω), meta}
• I12-AT-estimate_doppler (I3-4)
• in : {trace_or_phase, f_c, mode}
• out: {f_D, f_CFO, ci}
• I12-AT-nlos_mitigation (I3-5)
• in : {features, cfg}
• out: {NLOS_flag, b_NLOS, Σ_y_updated}

V. OBS (Observation Construction) Interfaces

• I12-OBS-build_observation (I4-1)
• in : {y_channels, config, cal_bundle}
• out: {y, meta}
• I12-OBS-build_jacobian (I4-2)
• in : {x, y_channels, geometry}
• out: {H, blocks}
• I12-OBS-update_covariance (I4-3)
• in : {y, flags, models}
• out: {Σ_y, robust_weights}
• I12-OBS-fix_ambiguity_cp (I4-4)
• in : {y_CP, H_CP, mode}
• out: {N_hat, status, cov}
• I12-OBS-fuse_channels (I4-5)
• in : {y, H, Σ_y, priors}
• out: {x̂, P, innovations}

VI. GEO (Geometry/Deployment) Interfaces

• I12-GEO-compute_dop_maps (I5-1)
• in : {anchors, y_channels, Σ_y, grid}
• out: {maps, stats}
• I12-GEO-select_anchors (I5-2)
• in : {anchors, grid, objective, budget}
• out: {selected, score}
• I12-GEO-plan_layout (I5-3)
• in : {area, constraints}
• out: {S_positions, GDOP_map}
• I12-GEO-reconfigure_runtime (I5-4)
• in : {state, flags, thresholds}
• out: {actions, expected_DOP}

VII. SYNC (Synchronization) Interfaces

• I12-SYNC-estimate_clock (I6-1)
• in : {sync_obs}
• out: {b_t, dot_b_t, cov}
• I12-SYNC-calibrate_asymmetry (I6-2)
• in : {path_logs, env}
• out: {b_asym_model, ci}
• I12-SYNC-fuse_sources (I6-3)
• in : {gnss, ptp, twr, priors}
• out: {post, cov}
• I12-SYNC-propagate_cov (I6-4)
• in : {cov_clock, channels}
• out: {Σ_y_updated}
• I12-SYNC-holdover_predict (I6-5)
• in : {clock_state, horizon}
• out: {pred_state, pred_cov}

VIII. KIN (Kinematics/Preintegration) Interfaces

• I12-KIN-imu_propagate (I7-1)
• in : {x, P, imu_stream, calib, dt}
• out: {x_pred, P_pred}
• I12-KIN-imu_preintegrate (I7-2)
• in : {imu_stream, calib}
• out: {ΔR, Δv, Δp, Σ_Δ, J_Δ}
• I12-KIN-build_wheel_factor (I7-3)
• in : {y_w, model, cov}
• out: {factor_w}
• I12-KIN-build_vision_factor (I7-4)
• in : {tracks, K, T_BC, timing}
• out: {factors_vo}
• I12-KIN-calibrate_extrinsics (I7-5)
• in : {sync_data}
• out: {T_BC, Δt_cam, cov}

IX. FUSE (Fusion) Interfaces

• I12-FUSE-ekf_step (I8-1)
• in : {x̂,P,u,y,H,R,Q}
• out: {x̂+, P+, stats}
• I12-FUSE-ukf_step (I8-2)
• in : {x̂,P,u,y,f,h,Q,R,usp}
• out: {x̂+, P+, stats}
• I12-FUSE-pf_step (I8-3)
• in : {particles, u, y, models, cfg}
• out: {particles+, est, Neff}
• I12-FUSE-build_graph / I12-FUSE-optimize_graph / I12-FUSE-marginalize (I8-4/5/6)
• in : {factors, priors, cfg} / {A,b,cfg} / {graph, keep_vars}
• out: {A,b,info} / {δξ, cov, report} / {graph+, prior_factor}
• I12-FUSE-assess_consistency (I8-7)
• in : {tracks, P, S}
• out: {NEES, NIS, pass@coverage}

X. ROB (Robustness) Interfaces

• I12-ROB-extract_features (I9-1)
• in : {raw, meta}
• out: {ϕ, stats}
• I12-ROB-score_nlos (I9-2)
• in : {ϕ, model}
• out: {score, nlos_flag, ci}
• I12-ROB-robust_reweight / I12-ROB-correct_bias (I9-3/4)
• in : {y, score, cfg} / {y, map_or_net}
• out: {w, Σ_y_updated} / {y_corr, μ̂_NLOS}
• I12-ROB-switchable_factor (I9-5)
• in : {y, score, cfg}
• out: {factor, switch_var}
• I12-ROB-drift_monitor (I9-6)
• in : {scores, residuals}
• out: {alarms, new_thresholds}

XI. MAT (Measurement/Design) Interfaces

• I12-MAT-build (I10-1)
• in : {config, cal_bundle, contracts}
• out: {J, B, Σ_y, meta}
• I12-MAT-fisher / I12-MAT-identifiability (I10-2/3)
• in : {J, Σ_y, priors?}
• out: {F, cond, rank, C} / {scores, weak_dirs, advice}
• I12-MAT-optimize_experiment (I10-4)
• in : {design_space, budget, criterion}
• out: {x_design*, F*, covθ*}
• I12-MAT-propagate_uncertainty / I12-MAT-stack_multi (I10-5/6)
• in : {J, Σ_y, Σ_ν?, priors?} / {mats, weights}
• out: {covθ, ci} / {J_stack, Σy_stack}
• I12-MAT-repro_bundle (I10-7)
• in : {J, Σ_y, F, config}
• out: {bundle, hash}

XII. SIM (Simulation/Synthetic) Interfaces

• I12-SIM-make_scene / I12-SIM-place_anchors (I11-1/2)
• in : {area, constraints, tag, seed} / {scene, policy}
• out: {scene, anchors, visibility} / {anchors, metrics}
• I12-SIM-simulate_channels / I12-SIM-simulate_clock (I11-3/4)
• in : {traj, scene, anchors, models, clocks} / {allan, sources, schedule}
• out: {y, Σ_y, meta} / {b_t, dot_b_t, cov_clock}
• I12-SIM-emit_contracts / I12-SIM-make_synthetic (I11-5/6)
• in : {cal_bundle, arrival, Σ_y, clocks} / {sim_config}
• out: {dataset_card} / {data, truths, repro_bundle}
• I12-SIM-run_sbc / I12-SIM-benchmarks (I11-7/8)
• in : {prior, sim_config, estimator, K} / {scene_set, configs}
• out: {coverage, ranks, report} / {scores, tables}

XIII. Dataset/Pipeline Cards — Interface Section (Mandatory Fields)

interfaces:

api_version: "12.0.0"

bindings:

- name: "I12-AT-compute_arrival_time"

request_id: "uuid"

inputs: {...}

contracts:

unit_system: "SI"

arrival_time:

convention: "pulled_const" # or "integrand"

delta_form: "c_ref^-1 * ∫ n_eff dℓ"

gamma: "piecewise: free|fixture|substrate|device|environment"

d_ell: "m"

references:

- "EFT.WP.Core.Equations v1.1:Ch.2 S20-*"

- "EFT.WP.Core.Metrology v1.0:Ch.1–3,5"

outputs:

- name: "T_arr(ω)"

unit: "s"

ci: {level: 0.95}

reproducibility:

bundle: {scripts:"...", env:"...", anchors:["S120-*","I12-*","M12-*"]}

schema_version: "12.0.0"

contract_version: "1.0"

XIV. Quality Gates, Validation & Regression

• M12-1 (Contract validation)
  Auto-check unit_system, the four arrival-time items convention/delta_form/gamma/d_ell, and citation anchors/versions.
• M12-2 (Dimension checks)
  Run check_dim on numeric outputs; missing/inconsistent units → E/UNIT.
• M12-3 (Identifiability pre-check)
  Call I12-MAT-fisher; if cond(F) > κ_th, raise E/IDENTIFIABILITY and return geometry/band suggestions.
• M12-4 (Numerical robustness)
  Detect Jacobian singularities, PDE/unwrapping failures, graph non-convergence; raise E/NUMERIC with hints.
• M12-5 (Regression tests)
  Upgrades must pass I12-SIM-benchmarks and case replays with error/coverage gates.
• M12-6 (Repro bundle)
  Every run outputs repro_bundle = {scripts, params, env, anchors, hash} for deterministic replay.

XV. Resources & Quotas (Implementation Constraints)

• S120-11 (Quotas)
  Allocate cpu_time, gpu_mem, max_walltime for EKF/UKF/PF, graph optimization, and simulations; excess → E/RESOURCE.
• S120-12 (Logging & audit)
  Log request_id, timestamps, RNG seeds, cal_bundle digests & hashes; in audit mode, export everything needed for replay.

XVI. Cross-Volume References & Anchors (This Chapter)

1. Cross-volume (fixed style): source interfaces from this volume Chs. 3–11; EFT.WP.Core.Equations v1.1 Ch.2 S20-* and EFT.WP.Core.Metrology v1.0 Ch.1–3,5.
2. Anchors:
   • Standards: S120-1—S120-12
   • Procedures: M12-1—M12-6
   • Interfaces: I12-AT-*,I12-OBS-*,I12-GEO-*,I12-SYNC-*,I12-KIN-*,I12-FUSE-*,I12-ROB-*,I12-MAT-*,I12-SIM-*

XVII. Summary
Centering on unified contracts → stable interfaces → quality gates, this chapter integrates path/arrival, observation construction, geometry/sync/dynamics, fusion, robustness, measurement, and simulation stacks. With alias mapping and regression suites, it ensures compatibility and reproducibility, providing a standardized path to deploy and collaborate across scenarios and platforms.