22-EFT.WP.Metrology.Instrument v1.0 | Appendix A — Interface Reference (I70 Suite)

Home ／ Docs-Technical WhitePaper ／ 22-EFT.WP.Metrology.Instrument v1.0

Appendix A — Interface Reference (I70 Suite)

One-Sentence Objective
Aggregate the signatures, inputs/outputs, invariants, and error semantics of the I70 series interfaces in this volume, providing a unified, implementable, and auditable reference.

I. Scope & Notes

• This appendix covers I70-* interfaces for discovery/connection, acquisition/control, units/dimensions, timebase/synchronization, linearity/noise/bandwidth, environment & drift, traceability & certificates, conformity & dashboards, and manifest & publication.
• All scalars/vectors/time series must declare unit(x) and dim(x) and pass check_dim(expr); when time sequencing is involved, compute on tau_mono, publish on ts, and record offset/skew/J.
• Interfaces that involve path/arrival-time metrics must record both formulations in parallel and produce delta_form (see TimeBase and Cleaning).

II. Naming, Types & Common Invariants

1. Type conventions
   • T (number|string|bool), Vec[T], TS[T] (time series), Map[K,V], Blob, Path.
   • Session (instrument session), TraceID (sha256), Manifest (signed key–value bundle).
2. Invariants
   non_decreasing(ts); sum(w)/N ≈ 1 (when weights are used); check_dim(expr)=0; delta_form ≤ tol_Tarr; alpha_spent ≤ alpha_budget.
3. Unified error semantics
   E.CONN (connection/permissions), E.CFG (invalid configuration), E.TIME (timebase/sync), E.MET (metrology/units), E.IO (acquisition/persist), E.CONTRACT (contract violation).

III. Discovery, Connection & Control (SCPI/IVI)

1. I70-01 discover_instruments(filter) -> Vec<DeviceInfo>
   • Inputs: filter (vendor|model|iface)
   • Outputs: Vec<DeviceInfo> ({id, iface, driver, caps})
   • Invariants: unique(id) in the return set; driver and caps are complete.
2. I70-02 open_session(device_id, driver, opts) -> Session
   • Inputs: opts (timeout_ms, exclusive, retry)
   • Outputs: Session
   • Errors: E.CONN; concurrency guard prevents session leaks.
3. I70-03 scpi(session, cmd, expect) -> Resp
   • Notes: atomic SCPI transaction; automatic retry and timeout.
   • Invariants: latency_ms_p99 is accounted in panel.scpi.latency_ms_p99.
4. I70-04 ivi_call(session, fn, args) -> Resp
   Notes: IVI driver abstraction; record driver.version and TraceID.

IV. Acquisition, Sweeps & Batch Execution

1. I70-11 acquire(session, chan, rate_sps, n, trig) -> TS[float]
   • Inputs: trig ({mode, level, edge})
   • Outputs: time series with ts/tau_mono and offset/skew/J.
   • Invariants: sampling loss rate sample_loss_rate ≤ tol_loss.
2. I70-12 sweep_source_measure(src, meas, grid, dwell_ms) -> DS
   • Notes: unified source-sweep + measurement (SMU/DMM/SG/SA).
   • Invariants: non_decreasing(grid); units/dimensions self-check passes.
3. I70-13 batch_run(plan, sessions) -> BatchReport
   Notes: parallel/serial batch execution with idempotency and checkpoint-resume.

V. Units, Dimensions & Calibration Harmonization

1. I70-21 repair_units(ds, policy) -> Report
   • Notes: unit normalization, dim checks, and failure mapping.
   • Errors: E.MET.
2. I70-22 apply_calibration(ds, cal_curve|lut|poly) -> ds'
   Invariants: check_dim(y - f(x))=0; record U = k * u_c.
3. I70-23 estimate_uncertainty(ds, model) -> U_report
   • Inputs: model ∈ {typeA, typeB, pooled}
   • Outputs: {u_c, k, U} with method annotation.

VI. Timebase & Synchronization Alignment (hooks to TimeBase/Sync)

• I70-31 align_timebase(ds, sync_ref) -> ds'
  Outputs: write tau_mono, publish ts, record offset/skew/J and uncertainty.
• I70-32 time_corr_chains(manifest) -> DelayBudget
  Notes: end-to-end timestamp chain and delay-budget aggregation.
• I70-33 arrival_dual_forms(ds, c_ref, n_eff, gamma) -> {T_arr_1, T_arr_2, delta_form}
  Invariants: delta_form ≤ tol_Tarr; path domain and measure are explicit.

VII. Linearity & Nonlinear Calibration (INL/DNL/Poly/LUT)

• I70-41 estimate_inl_dnl(ds, n_bits) -> {INL, DNL}
  Outputs: peak-to-peak and RMS metrics, with unit(LSB).
• I70-42 fit_poly_correction(ds, order) -> poly
  Invariants: overfitting guarded (hold-out or cross-validation).
• I70-43 build_lut_correction(ds, bins) -> lut
  Notes: monotonicity and extrapolation strategy are explicit.
• I70-44 apply_linearity_correction(ds, poly|lut) -> ds'
  Invariants: check_dim holds before and after calibration.

VIII. Noise & Sensitivity (SNR/NF/NEP)

• I70-51 measure_snr_enob(ds, fs, bw) -> {SNR, ENOB}
  Equation: ENOB = ( SNR_dB - 1.76 ) / 6.02.
• I70-52 estimate_noise_figure(rx_chain, Ts, G) -> {NF, U}
  Notes: based on NF definition and cascaded gain.
• I70-53 estimate_nep(detector, bw) -> {NEP, U}
  Notes: photodetector NEP and equivalent bandwidth.

IX. Bandwidth & Response (Bode/Step/ImpResp/PSF)

• I70-61 measure_bode(session, stim, freq_grid) -> {mag, phase}
  Invariants: sweep stability; RBW/VBW fixed.
• I70-62 measure_step_response(session, amp, t_win) -> TS[float]
  Notes: step response and rise-time metrics.
• I70-63 estimate_impulse_response(ts_resp) -> h(t)
  Notes: windowing and de-noising conventions are explicit.
• I70-64 estimate_psf_otsf(ds_img) -> {PSF, OTF, MTF}
  Cross-ref: see Imaging Chapter 5.

X. Triggering, Sampling & Timebase

• I70-71 configure_trigger(session, spec) -> Ack
  Notes: unified description for hard/soft/hybrid triggers.
• I70-72 verify_sampling(clock, fs, jitter_spec) -> Report
  Outputs: J, skew, u(ts) and pass/fail.
• I70-73 resample(ds, fs_target, method) -> ds'
  Invariants: anti-aliasing enforced; dimensions preserved.

XI. Environment & Drift (Temp/Humidity / EMC / Aging)

• I70-81 log_environment(sensors, Delta_t) -> EnvTS
  Outputs: RefCond time series with unit and u(x).
• I70-82 estimate_drift(ds, env) -> {drift_level, psi, W1}
  Cross-ref: CrossStats Chapter 7.
• I70-83 aging_tracker(ds, horizon) -> DriftReport
  Notes: aging trends and recommended re-cal windows.

XII. Traceability, Calibration & Certificates

• I70-91 record_traceability_chain(manifest, si_links) -> manifest'
  Invariants: closed chain with auditable evidence.
• I70-92 ingest_cal_certificate(pdf|xml) -> CalMeta
  Outputs: {date, lab, scope, U, TUR, validity} with signature.
• I70-93 schedule_recalibration(policy, usage) -> Plan
  Notes: risk- and usage-aware dynamic planning.

XIII. Conformity, Contracts & Guardband

• I70-101 compute_tur(T_spec, U) -> TUR
  Criterion: TUR ≥ TUR_min.
• I70-102 guardband_decision(meas, U, policy) -> pass|fail|marginal
  Notes: ILAC-G8 and risk-weighted strategies.
• I70-103 evaluate_instrument_contract(ds, rules) -> Report
  Rule families: uniqueness/monotonicity/dimensions/drift/SLO/dual-form arrival-time.

XIV. Multi-Instrument Harmonization & Cross-Comparison (RRT/Interlab)

• I70-111 interlab_round_robin(datasets, ref) -> BiasVarReport
  Outputs: bias/variance decomposition and down-weighting advice.
• I70-112 cross_instrument_alignment(ds_list, anchors) -> ds'
  Invariants: anchor consistency and dual-form arrival-time recording.

XV. Data Interfaces, Metadata & Publication

• I70-121 emit_instrument_manifest(artifacts, tag) -> Manifest
  Keys: manifest.instrument.* with TraceID, timing, metrology, contracts, panel, signature.
• I70-122 freeze_release(ds, manifest, repo) -> ReleaseBundle
  Invariants: signatures, hashes, and tamper-proof checks pass.
• I70-123 panel_metrics(streams) -> PanelSlice
  Metrics: latency_ms_p99, rho, sample_loss_rate, u(ts)_p95, etc.

XVI. Runtime & Streaming Coordination (Back-Pressure/Retry/Idempotency)

• I70-131 configure_streaming(topology, chan, cap, q_len) -> Ack
  Criterion: rho = lambda/mu < 1.
• I70-132 retry_with_idempotency(op, key, policy) -> Result
  Invariants: idempotency(key); scoped retry window for E.IO.

XVII. Example Call Sequences (End-to-End Blueprints)

• discover_instruments → open_session → configure_trigger → acquire / sweep_source_measure
• repair_units → apply_calibration → estimate_uncertainty
• align_timebase → arrival_dual_forms
• estimate_inl_dnl / measure_snr_enob / measure_bode
• log_environment → estimate_drift
• compute_tur → guardband_decision → evaluate_instrument_contract
• emit_instrument_manifest → freeze_release

XVIII. Cross-References

• Timebase/Sync: EFT.WP.Metrology.TimeBase v1.0, EFT.WP.Metrology.Sync v1.0.
• Cleaning/Contracts: EFT.WP.Methods.Cleaning v1.0 Appendices A/B/C.
• Statistics/Drift: EFT.WP.Methods.CrossStats v1.0 Chapters 7/14.
• Imaging Response: EFT.WP.Methods.Imaging v1.0 Chapters 5/9.

XIX. Notes & Implementation Guidance

• Every interface output should embed TraceID and the minimal reproducible context (driver version, firmware, configuration digest).
• For parsing PDF/certificate artifacts, implement dual channels (structured first, OCR as fallback), and preserve evidence under manifest.evidence.*.
• On any E.CONTRACT, emit an auditable failure slice plus recommended rollback actions.