34-EFT.WP.Astro.Acceleration v1.0 | Chapter 15 Implementation Bindings & APIs

Home ／ Docs-Technical WhitePaper ／ 34-EFT.WP.Astro.Acceleration v1.0

Chapter 15 Implementation Bindings & APIs

I. Abstract & Scope
This chapter specifies the unified standard and external interface family I80-* / API v1 for implementation bindings across CLI/SDK/HTTP layers, request–response contracts, unit & dimension carriage, Dataset/Model/Pipeline card integration, reproducible execution for simulation and fitting, error semantics & quotas, and security & audit. All equations and symbols use English notation in backticks; SI units with 3 significant figures by default. Any time-of-arrival (ToA) quantity must return both forms in parallel with explicit path gamma(ell) and measure d ell:
T_arr^A = ( 1 / c_ref ) * ( ∫_{gamma(ell)} n_eff d ell ) and T_arr^B = ( ∫_{gamma(ell)} ( n_eff / c_ref ) d ell ), with delta_form recorded.

II. Dependencies & References

1. Symbols & units: Chapter 2 (Tab. 2-1, P12-*).
2. Kinematics & channels: Chapter 3 S20-; reconnection/shear: Chapter 4 S30-, Chapter 5 S40-; comparator: Chapter 6 S45-.
3. Spectrum & transport: Chapter 7 S50-, Chapter 8 S52-.
4. GRB/FRB: Chapter 10 M62-, Chapter 11 M64-.
5. Simulation & benchmarks: Chapter 12 M70-*.
6. Data/pipelines/benchmarks: Chapter 14 I75-/M75-.
7. Inference & falsification: Chapter 13 M72-* (posterior, evidence, masks, falsification_line).

III. Normative Anchors (added here, I80-*)

8. I80-0 (Interface Layers): three bindings share a single contract & error semantics:
   • CLI: astroacc <command> [--flags]
   • SDK (Python): from astroacc import api
   • HTTP/JSON: POST /v1/...
9. I80-1 predict_spectrum(source_class, params) -> Spectrum
   Inputs: source_class ("SNR"|"AGN_Jet"|...), params (shape params for A_acc(E), E_grid, z).
   Outputs: N(E), Phi(E), alpha_loc(E) (units include sr and energy dimension).
10. I80-2 simulate_reconnection_accel(field_state, R_rec, seed_distribution) -> {dN/dE}
    Inputs: field_state = {T_fil, u_in, u_out, L_sheet, delta_sheet, chi_open}, R_rec, seed_distribution.
    Output: dN/dE with see: S30-*.
11. I80-3 shear_accel_cycle(velocity_field, scatter_model, E_init) -> E_final
    Inputs: velocity_field (or tensor S), scatter_model, E_init.
    Outputs: E_final and summary stats; see: S40-*.
12. I80-4 transport_loss(D_of_E, loss_terms, boundary) -> flux_at_obs
    Inputs: D(E), loss_terms={A_rad, A_ad, A_coll,...}, boundary (Dirichlet/Neumann/Mixed with kappa_esc).
    Outputs: Phi_obs(E), tau_esc(E), A_loss(E); see: S52-*.
13. I80-5 fit_multiband(data_bundle, model, priors) -> {posterior, evidence}
    Inputs: data_bundle (set of DatasetCards), model (ModelCard), priors.
    Outputs: posterior, Z, logZ, WAIC/LOO, masks; see: M72-*.
14. I80-6 arrival_time_model(paths, n_eff_model, c_ref) -> {T_arr, delta_form}
    Inputs: paths={gamma(ell), d ell}, n_eff_model(ν,r), c_ref.
    Outputs: {T_arr^A, T_arr^B, delta_form}; see: S50-9 / S52-8 / M62-0 / M64-0.
15. I80-7 export_cards(artifact) -> {DatasetCard|ModelCard|PipelineCard} (hooks to I75-*).
16. I80-8 benchmarks_run(task_id, SimCfg) -> {products, metrics} (hooks to M70-* and Tab. 12-4).
17. I80-9 metrics_validate(metrics, thresholds) -> {pass|fail, diff} (hooks to M75-3/M70-8).
18. I80-10 (Contract & Units): every numeric field must carry unit and dim; spectra/flux must include steradians and energy dimension; time in s; length in m; charge in C; magnetic field in T.
19. I80-11 (ToA Requirement): any request/response involving T_arr must return both T_arr^A and T_arr^B, with paths={gamma(ell), d ell} and delta_form.
20. I80-12 (Reproducibility): optional request seed; response must return rng_state and {code_hash, data_hash}; artifacts may be registered as benchmarks (register_benchmark).

IV. Body Structure

I. API Layers & Interface Style

• HTTP endpoints: /v1/spectrum/predict, /v1/accel/reconnection/simulate, /v1/accel/shear/cycle, /v1/transport/solve, /v1/fit/multiband, /v1/toa/compute, /v1/cards/export, /v1/benchmarks/run, /v1/metrics/validate.
• SDK: function names mirror I80-*; return unit-bearing structured objects.
• CLI: subcommands equivalent to SDK; default outputs in products/ and metrics.json.

II. Contracts & Schemas (examples)
Request (HTTP, /v1/fit/multiband):

{

"data_bundle": {"cards": ["cards/dataset_cr.json"], "unit": "SI"},

"model": {"card": "cards/model_s50.json"},

"priors": {"alpha_inj": {"type":"Normal","mu":2.2,"sigma":0.2}},

"seed": 1729

}

Response (excerpt):

{

"posterior": {"alpha_inj": {"mean": 2.18, "sd": 0.06, "unit": "1"}},

"evidence": {"Z": 1.23e3, "logZ": 7.11},

"info_criteria": {"WAIC": 512.3, "LOO": 510.8},

"masks": {"eta_dom": [{"E_min":"1e9 eV","E_max":"1e11 eV","channel":"reconnection"}]},

"rng_state": "...",

"hash": {"code_hash": "sha256:...", "data_hash": "sha256:..."}

}

III. Units & Dimensional Audit
All expressions carry units and Dim. Use m^-2·s^-1·sr^-1·eV^-1 for Phi(E); DM primary unit m^-2 (parallel pc·cm^-3); RM in rad·m^-2. Any dimensional mismatch (e.g., missing sr or energy dimension) returns 422 UNIT_MISMATCH.

IV. Error Semantics & Quotas

1. Error codes:
   • 400 INVALID_ARGUMENT (missing/invalid fields)
   • 412 PRECONDITION_FAILED (missing paths or delta_form)
   • 422 UNIT_MISMATCH (unit/dimension failure)
   • 409 CONFLICT (hash/version conflict)
   • 429 RATE_LIMIT
   • 500 INTERNAL
2. Every error returns a trace_id and see: anchors for audit & reproduction.

V. Security, Audit & Quotas

• Auth: API key (Authorization: Bearer), optional HMAC timestamp signing.
• Audit: log {who, when, where, code_hash, data_hash, rng_state} aligned with Chapter 14 registry.
• Quotas: configured by requests/min and compute-min/day; on limit, return 429 and recommend asynchronous segmented pipelines (via PipelineCard DAG).

VI. Workflows & Use Cases (map to M-series)

1. Use Case 1: Spectrum prediction & fitting
   predict_spectrum for prior spectrum; 2) fit_multiband → {posterior, evidence, masks}; 3) metrics_validate vs thresholds.
2. Use Case 2: Reconnection/Shear channel disentangling
   simulate_reconnection_accel, shear_accel_cycle; 2) transport_loss → Phi_obs(E); 3) fit_multiband with dominance masks.
3. Use Case 3: GRB/FRB ToA & polarization
   arrival_time_model → {T_arr^A, T_arr^B, delta_form}; 2) integrate with Ch.10/11 flows, include in L_ToA; 3) export_cards for delivery.

VII. Cross-References within/beyond this Volume
Mathematical/physical anchors: S20-/S30-/S40-/S50-/S52-/S45-; fitting & falsification: M72-; simulation/benchmarks: M70-; data & pipeline cards: I75-/M75-.

VIII. Validation, Criteria & Counterexamples

1. Positive criteria:
   • All response fields carry unit/dim and pass dimensional audits.
   • ToA returns both forms with clear delta_form; residuals consistent with the path model.
   • metrics_validate meets Tab. 12-4 thresholds.
   • Reproduction matches hash and rng_state.
2. Negative criteria:
   • Missing paths or a single T_arr form only.
   • UNIT_MISMATCH or degraded WAIC/LOO without rationale.
   • Post-register_benchmark regression fails.
3. Contrasts:
   • {only reconnection, only shear, mixed} call graphs.
   • ToA {Form A only, Form B only, A+B} impacts on evidence.
   • {one-zone, multi-zone} transport on the same data.

IX. Figures & Tables (this chapter)

• Tab. 15-1 Endpoint overview (HTTP)

• Tab. 15-2 Error codes & semantics

• Tab. 15-3 SDK prototypes (Python, excerpt)

• Tab. 15-4 Contract fields & units (excerpt)

X. Summary
I80-* / API v1 unifies CLI/SDK/HTTP interfaces, unit & dimension carriage, mandatory dual-form ToA, reproducibility & audit, and error & quota semantics, projecting this volume’s physical and statistical anchors into executable contracts that carry Chapters 3–14 methods, benchmarks, and deliverables.