32-EFT.WP.Cosmo.LayeredSea v1.0 | Appendix D — Reference Implementation & Test Script Catalog

Home ／ Docs-Technical WhitePaper ／ 32-EFT.WP.Cosmo.LayeredSea v1.0

Appendix D — Reference Implementation & Test Script Catalog

• I. One-Sentence Objective
  Provide a minimal reference implementation and a test-script catalog that are consistent with template v0.1 (EFT Technical White Paper & Tech Memo Template · Complete Checklist v0.1). Specify directory layout, entry points, configuration, run procedures, and audit norms so that SeaProfile, Phi_T/grad_Phi_T, n_eff, { ell_i }, Delta_T_sigma, R_sea/T_trans/A_sigma, and both T_arr / ΔT_arr formulations can be executed end-to-end in a way that is deployable, reproducible, and auditable.
• II. Applicability & Non-Goals
• Covers: reference tree layout; minimal interfaces of core modules (mapping template interface family → this volume’s I60-*); benchmark scripts and purposes; CLI examples; example configs; logging & auditing essentials; replay flow; security constraints.
• Does not cover: device-level hardware code; any proprietary libraries; anything beyond a minimal viable implementation with strict dimensional guarding.
• III. Reference Implementation Layout (suggested)
• ref_ls/ — project root
• core/ — physics & numerics
• phi.py (I.Build.Phi → apply_sea_matching, gradient)
• neff.py (I.Build.Neff → estimate_neff_sea)
• arrival.py (I.Arrival.Constant|General|Delta → arrival_time_in_sea, delta_arrival_in_sea)
• interfaces.py (I.Interface.ApplyMatching / I.Path.Segment / I.Path.InterfaceCorrection → detect_sea_intersections, segment_integrals, interface_correction_sea)
• echo.py (multipath / echo → simulate_multipath_LS)
• metrics.py (I.Consistency.DualMode|ThinThick / I.Uncertainty.GUM|MC → check_dual_arrival_consistency, consistency_thin_vs_thick_LS, propagate_uncertainty_GUM, propagate_uncertainty_MC)
• io/ — data & contracts
• contract.py (read/validate Contract)
• dataio.py (I/O for SeaProfile, Path, Field, Observations, RTParams)
• hashing.py (hash(SeaProfile), hash(Phi_T), hash(grad_Phi_T), hash(n_eff), hash(gamma))
• utils/ — common utilities
• solvercfg.py (quadrature, step thresholds, concurrency policies)
• logger.py (I.Report.Log|Emit → log_artifacts_LS, emit_measurement_report)
• rng.py (seedable RNG for MC)
• scripts/ — benchmarks & tests (see §V)
• configs/ — runnable configs & samples (see §VII)
• artifacts/ — results & audit outputs (logs, reports, hash manifests, replay manifests)
• Name isolation & guards (hard rules): never conflate T_fil with T_trans, or n with n_eff. Every public entrypoint enforces n_eff ≥ 1 and performs dimensional checks.
• IV. Minimal Interfaces for Core Modules (template → this volume I60-*)
• I.Build.Phi → apply_sea_matching(Phi_T, SeaProfile) -> Phi_T_matched; gradient(Phi_T) -> grad_Phi_T
• I.Build.Neff → estimate_neff_sea(Phi_T, grad_Phi_T, rho, f, SeaProfile) -> n_eff
• I.Path.Capture → capture_path(raw_track, coord_spec) -> { gamma[k], Δell[k], t_hat[k] }
• I.Path.Segment → detect_sea_intersections(gamma, SeaProfile) -> { ell_i, layer_id }; segment_integrals(n_eff, gamma, { ell_i }, mode) -> { T_arr_i }
• I.Path.InterfaceCorrection → interface_correction_sea(gamma, SeaProfile, params) -> Delta_T_sigma
• I.Arrival.Constant|General → arrival_time_in_sea(n_eff, gamma, mode, c_ref) -> T_arr
• I.Arrival.Delta → delta_arrival_in_sea(n_path_params, f1, f2, gamma, mode, c_ref) -> ΔT_arr
• I.RT.Estimate → estimate_RT_sea(data, SeaProfile) -> R_sea, T_trans, A_sigma
• I.Fit.Profile → fit_sea_profile(observations, Phi_T, grad_Phi_T, prior, model_spec) -> theta_hat, Cov
• I.Consistency.DualMode → check_dual_arrival_consistency(inputs) -> eta_T
• I.Consistency.ThinThick → consistency_thin_vs_thick_LS(inputs) -> tau_report
• I.Uncertainty.GUM|MC → propagate_uncertainty_GUM(inputs) -> u_c; propagate_uncertainty_MC(inputs, Nsamples, seed) -> dist(T_arr)
• I.Report.Log|Emit → log_artifacts_LS(meta, hashes, metrics) -> Log; emit_measurement_report(contract, logs, artifacts) -> Report
• V. Script Catalog & Purpose (minimum set)
• scripts/run_uniform.py
  Purpose: Benchmark 1 (uniform outer region) — verify T_arr = L_path / c_ref and dimensional/lower-bound checks.
• scripts/run_thinlayer.py
  Purpose: Single thin band — Delta_T_sigma vs. thick volumetrics consistency (produce the tau_switch curve).
• scripts/run_thicklayer.py
  Purpose: Explicit thick-layer volumetrics — endpoint/step refinement, audit error slopes.
• scripts/run_interfaces.py
  Purpose: Three matching types (continuous / potential jump / flux jump) and energy balance R_sea + T_trans + A_sigma = 1.
• scripts/run_dispersion.py
  Purpose: In-band differencing ΔT_arr; fit n_path polynomial coefficients; evaluate out-of-band leakage.
• scripts/run_anisotropy.py
  Purpose: Significance of directional terms b1 / b1_n (cross-azimuth path set).
• scripts/run_dual_consistency.py
  Purpose: Two-formulation agreement eta_T.
• scripts/run_thin_vs_thick.py
  Purpose: Dual-chain thin/thick agreement report tau_switch.
• scripts/run_uncertainty_gum.py / scripts/run_uncertainty_mc.py
  Purpose: GUM / MC uncertainty propagation and tail-risk assessment.
• scripts/run_dqc.py
  Purpose: Data-quality checks (aggregate DQC-1 … DQC-9).
• scripts/run_report.py
  Purpose: Summarize logs & metrics; generate report and hash manifest.
• VI. CLI Examples
• Single thin-band consistency
• python scripts/run_thinlayer.py \
• --contract configs/ls.contract.json \
• --sea configs/ls.tanh.json \
• --path paths/p001.path.jsonl \
• --solvercfg configs/solver.ls.json \
• --out artifacts/thinlayer/
• In-band differencing & two-formulation agreement
• python scripts/run_dispersion.py \
• --contract configs/ls.contract.json \
• --phi fields/phi_t.zarr --gphi fields/grad_phi_t.zarr \
• --obs obs/p001.obs.jsonl --fgrid configs/fgrid.json \
• --out artifacts/dispersion/
• python scripts/run_dual_consistency.py \
• --contract configs/ls.contract.json \
• --path paths/p001.path.jsonl --neff fields/neff.zarr \
• --cref calib/c_ref.json --out artifacts/consistency/
• Uncertainty (GUM / MC)
• python scripts/run_uncertainty_gum.py \
• --contract configs/ls.contract.json \
• --inputs artifacts/dispersion/results.json \
• --out artifacts/uncertainty/gum/
• python scripts/run_uncertainty_mc.py \
• --contract configs/ls.contract.json \
• --inputs artifacts/dispersion/results.json \
• --nsamples 20000 --seed 20250905 \
• --out artifacts/uncertainty/mc/
• VII. Sample Configurations (minimal)
• configs/ls.contract.json
• {
• "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"},
• "tolerances":{"eps_T":1e-9,"eta_T":5e-10,"eta_w":0.03,"tau_switch":5e-12}
• }
• configs/ls.tanh.json
• {"layers":[{"model":"tanh","chi_k":1.2e3,"Delta_k":2.0e2,"sigma_k":1.0e2}],"eta_w":0.03}
• configs/solver.ls.json
• {"quad":"adaptive_simpson","step_rule":"curvature_medium_layer",
• "tau_geom":0.02,"tau_medium":0.01,"tau_sea":0.005,
• "convergence":{"levels":[1.0,0.5,0.25],"eps_T":1e-9},
• "parallel":{"freq":"threads","paths":"threads"}}
• configs/fgrid.json
• {"f0":1.0e9,"band":[-5.0e7,5.0e7],"nodes":[9.5e8,1.0e9,1.05e9]}
• VIII. Outputs & Logs (minimum set)
• Results: results.json (includes T_arr_mod_s, optional Delta_T_sigma_s, eta_T, tau_switch, key hashes, and snapshots of SolverCfg/metric_spec).
• Audit: audit.log (dimension checks; formulation selection; step & error stats; interface triggers & energy-balance residual; clamping trigger rate).
• Hashes: hashes.json (hash(SeaProfile), hash(Phi_T), hash(grad_Phi_T), hash(n_eff), hash(gamma), hash(code)).
• Report: report.md (metric dashboard, falsification samples, replay commands, environment & versions).
• IX. Reproduction Flow (one-click replay)
• Produce artifacts/manifest.json (bundling Contract, SeaProfile, Path, Fields/Neff, SolverCfg, metric_spec, seed, and all hashes).
• Execute:
• python scripts/run_report.py --manifest artifacts/manifest.json --out artifacts/report/
• Verify that the new hashes.json matches the archived one; any mismatch flags replay failure and prints a diff summary.
• X. Security & Integrity
• Read-only inputs: mount /contracts, /obs, /interfaces as read-only to prevent tampering.
• Dimensional guarding: every script entry calls check_dimension; failures must abort computation and be logged.
• Name isolation: script layer must never conflate T_fil with T_trans, or n with n_eff.
• Seedable randomness: MC scripts must accept --seed and persist the seed in logs.
• XI. Template Interface Family Quick Map (anchored to template v0.1)
• Build: I.Build.Phi, I.Build.Neff
• Path: I.Path.Capture, I.Path.Segment, I.Path.InterfaceCorrection
• Arrival: I.Arrival.Constant|General|Delta
• Matching / Energy: I.Interface.ApplyMatching, I.RT.Estimate
• Metrology / Consistency: I.Consistency.DualMode|ThinThick, I.Uncertainty.GUM|MC
• Reporting: I.Report.Log|Emit
  Engineering mapping: see this volume’s I60-* list in §IV.
• XII. Cross-References
• EFT.WP.Cosmo.LayeredSea v1.0: Chs. 3–9, 11–12 (equations, parameterization, propagation, matching, numerics, validation, and error budget).
• Template v0.1: interface family and I/O contract layering.
• EFT.WP.Propagation.TensionPotential v1.0: two formulations and differencing workflow.
• EFT.WP.Core.Equations v1.1 / Metrology v1.0 / Errors v1.0: notation, metrology, and error families.
• XIII. Deliverables
• Minimal reference skeleton (ref_ls/core|io|utils) with script set (scripts/).
• Runnable configuration samples (configs/) and placeholder paths/observations.
• Audit & replay artifact templates (artifacts/: results.json, audit.log, hashes.json, report.md, manifest.json).