40-EFT.WP.Materials.Superconductivity v1.0 | Chapter 12: Interfaces & Implementation Bindings

Home ／ Docs-Technical WhitePaper ／ 40-EFT.WP.Materials.Superconductivity v1.0

Chapter 12: Interfaces & Implementation Bindings

I. Scope & Principles

• S120-1 (Objective)
  This chapter fixes cross-team, cross-pipeline external interfaces and implementation bindings covering arrival time/propagation, measurement matrix, simulation stack, inference & model comparison, materials design & tension engineering, case library, and data management.
• S120-2 (Unified conventions)
  Every request/response must declare unit_system:"SI", references (use “volume + version + anchor”), contract_version, and schema_version. All formulas/symbols/definitions are in English and must pass check_dim.
• S120-3 (Naming & idempotency)
  Interface IDs use I12-*. Idempotent operations must carry a request_id and a replay policy.
• S120-4 (Path & arrival time)
  Any T_arr usage must specify in contracts exactly one convention (pulled_const or integrand), plus delta_form, gamma(ell), and d ell.
• S120-5 (Error model)
  Errors follow the unified object:
• { "code": "E/…", "message": "...", "at": "stage.name", "hint": "...", "refs": ["..."] }

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

II. Interface Overview & Alias Mapping (from per-chapter placeholders to final bindings)

1. S120-6 (Families)
   • Arrival time / propagation: I12-AT-* (binds Chapter 7 I7-*)
   • Measurement matrix / metrology: I12-MM-* (binds Chapter 8 I8-*)
   • Simulation stack: I12-SIM-* (binds Chapter 10 I10-6/7)
   • Inference / comparison: I12-INF-* (binds Chapter 10 I10-1…5)
   • Design & tension engineering: I12-DES-* (binds Chapter 9 I9-*)
   • Case library / data: I12-CASE-* (binds Chapter 11 I11-*)
2. S120-7 (Aliases)
   Backward-compatible aliases (excerpt): I7-1 ≡ I12-AT-fit_from_cavity, I8-1 ≡ I12-MM-build_measurement_matrix, I10-1 ≡ I12-INF-run_hmc, … (full table in Appendix).

III. Common Data Contract & Object Schemas

• S120-8 (Request prototype)
• {
• "request_id": "uuid",
• "inputs": {...},
• "contracts": {
• "unit_system": "SI",
• "convention": "pulled_const|integrand",
• "delta_form": "c_ref^-1 * ∫ n_eff dℓ | ∫ (n_eff/c_ref) dℓ",
• "gamma": "piecewise: free|fixture|substrate|film|sample",
• "d_ell": "m"
• },
• "priors": {...},
• "cal_bundle": {...},
• "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 arrays/tensors include units (e.g., {"lambda_L":{"unit":"m"},"xi":{"unit":"m"}}). Implementations must validate with check_dim.

IV. Arrival-Time & Propagation Interfaces (I12-AT-*, bound to Chapter 7)

• I12-AT-fit_from_cavity (alias of I7-1)
• inputs : { f, Q, phi(ω), mode_map, convention, path }
• returns: { lambda_L(T), sigma(ω), xi(T), ci }
• I12-AT-compute_arrival_time (alias of I7-2)
• inputs : { S21_or_trace, convention, path, unwrap }
• returns: { T_arr(ω), meta:{unwrap_stats, phase_jumps} }
• I12-AT-fit_thinfilm_transmission (alias of I7-3)
• inputs : { T_arr(ω), model, priors }
• returns: { lambda_L, sigma(ω), d, post }
• I12-AT-deembed_path (alias of I7-4)
• inputs : { standards, scheme }
• returns: { n_bg(ω), T_arr_bg, drift_model }
• I12-AT-fuse_multi_band (alias of I7-5)
• inputs : { results[], weights }
• returns: { merged_params, consistency }

V. Measurement-Matrix & Metrology Interfaces (I12-MM-*, bound to Chapter 8)

• I12-MM-build_measurement_matrix (alias of I8-1)
• inputs : { config, cal_bundle, contracts }
• returns: { J, B, Σ_y, meta }
• I12-MM-compute_fisher (alias of I8-2)
• inputs : { J, Σ_y, priors? }
• returns: { F, cond, rank, C }
• I12-MM-optimize_design (alias of I8-3)
• inputs : { design_space, budget, criterion }
• returns: { x*, F*, covθ* }
• I12-MM-propagate_uncertainty (alias of I8-4)
• inputs : { J, Σ_y, Σ_ν?, priors? }
• returns: { covθ, ci }
• I12-MM-assess_identifiability (alias of I8-5)
• inputs : { J, Σ_y }
• returns: { scores, weak_dirs, suggestions }
• I12-MM-fuse_matrices (alias of I8-6)
• inputs : { J_list, Σy_list, weights }
• returns: { J_stack, Σy_stack }
• I12-MM-validate_contracts (new)
• inputs : { dataset_card }
• returns: { pass: bool, report, anchors_checked }

VI. Simulation-Stack Interfaces (I12-SIM-*, bound to Chapter 10)

• I12-SIM-forward (alias of I10-6)
• inputs : { θ, η, x, channels }
• returns: { y_hat, J, meta }
• I12-SIM-make_synthetic (alias of I10-7)
• inputs : { case_id, noise, drift, outliers }
• returns: { data, truth }
• I12-SIM-benchmark_suite (new)
• inputs : { suite_id, configs[] }
• returns: { results, scores }

VII. Inference & Model-Comparison Interfaces (I12-INF-*, bound to Chapter 10)

• I12-INF-run_hmc (alias of I10-1)
• inputs : { model, data, priors, init, adapt }
• returns: { posterior, rhat, ess, traces }
• I12-INF-run_vi (alias of I10-2)
• inputs : { model, data, priors, family }
• returns: { q(θ), elbo_hist, diag }
• I12-INF-run_smc (alias of I10-3)
• inputs : { model, data, schedule }
• returns: { weighted_samples, logZ }
• I12-INF-evidence (alias of I10-4)
• inputs : { traces_or_q, method }
• returns: { logZ, se }
• I12-INF-posterior_predictive (alias of I10-5)
• inputs : { traces_or_q, sim, N }
• returns: { y_rep, metrics }
• I12-INF-orchestrate (new, end-to-end)
• inputs : { y, J, Σ_y, priors, strategy }
• returns: { θ_hat, post, logZ, diagnostics }

VIII. Design-Variable & Tension-Engineering Interfaces (I12-DES-*, bound to Chapter 9)

• I12-DES-update_design_variables (alias of I9-1)
• inputs : { targets, constraints }
• returns: { θ*, recipe, risk, cost }
• I12-DES-plan_strain_field (alias of I9-2)
• inputs : { mask, ε_target, budget }
• returns: { ε_ij(r), process }
• I12-DES-engineer_interface (alias of I9-3)
• inputs : { stack, Γ_if_target, symmetry }
• returns: { Γ_if, ρ_int, QA }
• I12-DES-thickness_coupling_scan (alias of I9-4)
• inputs : { d_grid, s_grid }
• returns: { lambda_L(d), H_c2(d), K_T, K_G }
• I12-DES-close_loop_infer (alias of I9-5)
• inputs : { A, α_*, K_*, data }
• returns: { posterior, ΔA, Δα, ΔK }

IX. Case-Library & Data-Management Interfaces (I12-CASE-*, bound to Chapter 11)

• I12-CASE-load_card (alias of I11-1)
• inputs : { path }
• returns: { data, meta }
• I12-CASE-clean_and_deembed (alias of I11-2)
• inputs : { data, scheme }
• returns: { clean, Σ_y, weights }
• I12-CASE-build_J (alias of I11-3)
• inputs : { clean, config }
• returns: { J, B, Σ_y }
• I12-CASE-infer_theta (alias of I11-4)
• inputs : { J, Σ_y, priors, algo }
• returns: { posterior, logZ, diag }
• I12-CASE-falsify_and_ppc (alias of I11-5)
• inputs : { posterior, clean }
• returns: { tests, passrate }
• I12-CASE-recommend_design (alias of I11-6)
• inputs : { posterior, objectives }
• returns: { Δθ_design, recipe }

X. Quality Gates, Validation & Regression (M12-*)

• M12-1 (Contract validation)
  Auto-check unit_system, delta_form, gamma(ell), d ell, citation anchors and versions.
• M12-2 (Dimension checks)
  Run check_dim on returned numerics; missing/inconsistent units → E/UNIT.
• M12-3 (Identifiability pre-check)
  Call I12-MM-compute_fisher; if cond(F) > κ_th, raise E/IDENTIFIABILITY with geometry/band suggestions.
• M12-4 (Numerical robustness)
  Detect Jacobian singularities, PDE non-convergence, phase-unwrapping failures; raise E/NUMERIC with hint.
• M12-5 (Regression tests)
  Any interface upgrade must pass the benchmark suite (I12-SIM-benchmark_suite) and case replays with error and coverage gates.
• M12-6 (Reproducibility bundle)
  Every run exports repro_bundle = {scripts, params, env, anchors} for audit and replay.

XI. Dataset/Pipeline Card — Interface Section Template (Mandatory Fields)

interfaces:

api_version: "12.0.0"

bindings:

- name: "I12-AT-compute_arrival_time"

request_id: "uuid"

inputs: {...}

contracts:

unit_system: "SI"

convention: "pulled_const" # or "integrand"

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

gamma: "piecewise: free|fixture|substrate|film|sample"

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"

XII. Resources & Quotas (Implementation Constraints)

• S120-11 (Resource limits)
  Allocate cpu_time, gpu_mem, max_walltime for HMC/SMC/simulations; exceeding quotas raises E/RESOURCE.
• S120-12 (Logging & audit)
  All interfaces log request_id, timestamps, RNG seeds, cal_bundle digest and hashes; in audit mode, export all info required for deterministic replay.

XIII. Cross-Chapter Links & Anchors (This Chapter)

• Internal links (fixed style): This volume Ch. 6 (coherence windows & extraction), Ch. 7 (arrival time & de-embedding), Ch. 8 (measurement matrix & identifiability), Ch. 9 (design variables & tension engineering), Ch. 10 (simulation & inference), Ch. 11 (case library).
• Anchors (S/M/I):
  Standards: S120-1—S120-12
  Procedures: M12-1—M12-6
  Interfaces: I12-AT-*, I12-MM-*, I12-SIM-*, I12-INF-*, I12-DES-*, I12-CASE-*

XIV. Summary
Centering on unified contracts, stable interfaces, and quality gates, this chapter binds arrival-time/propagation, metrology & measurement matrix, simulation stack, inference & model comparison, and materials design & case workflows into a coherent, auditable whole. Alias mapping and regression suites ensure backward compatibility and reproducibility, providing a standardized path for engineering deployment and cross-team collaboration across the volume.