Pre-flight transport modelling, calibration parameter estimation, and receipt-backed QUA/OPX gating support.
Namespace /api/v1/usl. Returns receipts, not claims — advisory timing, suppression, coherence, and estimator outputs for downstream review.
research_harness_preflight_only;
QM Bridge routes use template_generation_and_calibration_assist_only;
Control Assist routes use control_recommendation_only.
Prepend this host to every path below (e.g. /api/v1/usl/status, /api/v1/usl/transport/simulate).
Send header X-API-Key (or Authorization: Bearer) on authenticated routes.
GET /api/v1/usl/statusD_target: POST /api/v1/usl/transport/coherence-lossPOST /api/v1/usl/transport/simulate| Route type | Auth required |
|---|---|
GET /api/v1/usl, /status, /openapi.json | No |
All POST /api/v1/usl/* | Yes |
All GET /api/v1/usl/fixtures/* | Yes |
| Tier | Example | Step limits (simulate / sweep / scan) |
|---|---|---|
| Demo | demo-sparse-supernova-2026 | 1000 / 50 / 100 |
| Production | Your issued key | 10000 / 500 / 2000 |
Demo key is for examples and integration tests only. Rate limit: 60 requests per 60s per key+route.
Default clock_cycle_ns is 4 for Quantum Machines compatibility.
Responses also include duration_cycles (for the selected clock) and duration_cycles_4ns (4 ns convention).
Optional request: clock_cycle_ns, duration_seconds, duration_cycles, or duration_cycles_4ns.
Physical lab outcomes can be treated as validation receipts comparing predicted CL(D) with measured transport loss.
They are evidence artefacts, not model-training events. The API does not update the closed-form law from uploads.
stored: false, model_update: none)
Closed-loop lab runners should batch observations and call the API at a bounded cadence.
Use /transport/sweep for grids rather than many individual /simulate calls.
Default limit: 60 requests / 60s per API key + route.
All JSON responses include honesty fields:
| Field | Description |
|---|---|
ok | Overall protocol pass (may be false with HTTP 200) |
boundary | D_crit, isInverted, D_boundary, feasible, lambdaDB, deltaR |
phases.verify | Feasibility phase receipt |
phases.transit | t_window, timingOk, dissolutionOk, trajectory, minFrai |
phases.suppress / phases.restore | Schedule arrays |
fidelity | fraiEff_A/B, relativeTransferScore, fidelity |
summary | dissolutionOk, timingOk, coherenceOk, transportFidelity, … |
qm_bridge | duration_cycles_4ns = ceil(t_window / 4e-9) — planning only, not QUA compile |
closed_form_coherence_loss | Extra pre-flight receipt when D_target or D_suppress is set (dim=1 CL formula; does not replace ok) |
qm_bridge | When t_window > 0: cycles, gammas, CL, QEC flag, template input names (v0.1; template assist only) |
USL transport coherence loss follows CL = (2D+1)/(D+1)2 under the dim=1 transport-quality convention. In the current API/model curve, the result is independent of λdB, rB, N, and trap frequency.
D_target is the experimental object. Conservative QEC design rule: D_target > 200 for CL < 1%.
| Target | Rule |
|---|---|
| CL < 1% | D_target > 200 |
| Formula | (2D+1)/(D+1)^2 |
| Claim level | research_harness_preflight_only |
Generate reviewable QUA/Python templates and bounded calibration-step recommendations from USL transport receipts. The bridge emits timing in 4 ns QUA clock cycles, candidate amplitude values, and safety notes for local lab review.
qm.execute, and does not prove physical quantum transport.
Local lab software remains responsible for configuration, safety checks, execution, and measurement.
Local Python collects readout traces, posts FRAI observations to the API, receives an estimated D and a bounded next amplitude recommendation, then the lab runner decides whether to execute the next QUA sequence.
claim_level, claim_statement, forbidden_claim, caveats[].summary — quick-glance ok, key flags, and next_step on simulate, sweep, and ODE routes.detail — summary | light | full on simulate/sweep/ode-router to trim trajectories and schedules.ok only — single success flag (legacy success removed).warnings[] — prominent array for regime, cost, and calibration caveats.USL Control Assist turns observed D error into bounded recommendations for ramp amplitude, transit velocity, and D suppression targets. It uses the closed-form coherence-loss curve CL = (2D+1)/(D+1)2 as a nonlinear gain modifier.
/api/v1/usl/transport/simulate before local lab software acts on it.
Sparse Q adds ODE-based routing receipts for logical-vs-physical strategy planning. This is pre-flight routing guidance only. It does not certify hardware performance or replace provider-side benchmarking.
| Route | What it returns |
|---|---|
POST /api/v1/usl/ode-router | Routing recommendation, confidence, D estimate, fitted correlation indicators, and claim tier |
POST /api/v1/usl/ode-router/calibrate | Posterior coherent-fraction calibration receipt from observed {D, R_phys} points |
POST /api/v1/usl/ode-router/quote | Broker cost/shot estimate from live qBraid and IBM Runtime pricing (broker_quote_estimate_only) |
IBM_QUANTUM_API_KEY and IBM_QUANTUM_CRN are configured on the Worker.
If you see ibm_runtime_error (403), refresh the CRN from quantum.ibm.com → Instances:
npx wrangler secret put IBM_QUANTUM_CRN --env production.
Optional: QBRAID_API_KEY for multi-provider live per-shot USD.
Maps tensor-network bond dimension χ to USL D using a two-component gate-error model that separates truncation error from Trotter floor.
dt_ns,
and does not validate physical quantum transport.
Classification priority: chi_ratio, then p_norm, then em_bootstrap (no fixed p-threshold rules).
Diagnostic: model.xi_chi_dependence reports how much inferred ξ varies across adjacent truncation-dominated χ pairs
(ge(χ_hi)/ge(χ_lo) < 0.1 only). When xi_chi_dependence > 2,
chi_prediction.chi_min_conservative is true — provide a denser χ sweep for a tighter chi_min bound.
Fits C(d)=g₀·exp(-b·d^α), extracts ξ, and optionally estimates μ from ξ(tₐ) scaling.
Fast research diagnostic only; not a replacement for full multi-size KZ collapse.
Validated on real Dryad data from Tindall et al. Science 2026 Figure 5.
All paths relative to https://signal.sparse-supernova.com
Auth: None · Returns: operational flag + versions
Auth: Required · Body: full runTransportProtocol input · Returns 200 even when ok: false
Optional D_target adds closed_form_coherence_loss using the dim=1 formula
CL = (2D+1)/(D+1)2. If omitted, D_suppress is used as the CL reference.
This is an extra receipt only — monolith ok / summary are unchanged.
When ok: false because D_suppress violates the detected regime, the response includes
constraint_hint with isInverted, D_crit, and the standard vs inverted rule
(CL receipt may still be present).
| Field | Type | Required | Description |
|---|---|---|---|
dim | integer | yes | Hilbert-space dimension factor (≥1) |
lambdaDB | number | yes | de Broglie wavelength scale |
D_A, D_B | number | yes | Field values at endpoints A and B |
r_A, r_B | number | yes | Radii at A and B |
D_boundary | number | yes | Boundary field value |
deltaR | number | yes | Transport distance (m) |
D_suppress | number | yes | Suppressed field target (also used for closed_form_coherence_loss when D_target omitted) |
D_target | number | no | Explicit ramp-amplitude target for closed-form CL receipt (overrides D_suppress for CL only) |
Gamma_suppress | number | yes | Suppression rate |
Gamma_restore | number | yes | Restoration rate |
v_atom | number | yes | Transit velocity |
v_sound | number | no | Optional sound-speed cap for v_min |
steps | integer | no | Trajectory steps (default 200; tier limits apply) |
fraiThreshold | number | no | Coherence gate in [0,1] (default 0.33) |
epsilon | number | no | Numerical floor (default 1e-6) |
ok: false)Auth: Required · Claim: research_harness_preflight_only
Sweeps D_suppress and returns recommended_operating_band from valid rows where inputVelocityOk, t_window > 0, and minFrai >= fraiThreshold. Invalid points use valid_regime=false and rejection_reason instead of failing the whole sweep.
D_crit; computed as criticalSuppressionD(lambdaDB, deltaR); monolith generates levels (sweep_input_mode: auto_from_D_crit).D_suppress_min + D_suppress_max linear grid (sweep_input_mode: explicit_D_suppress_bounds).D_crit in the body.D_values or D_min/D_max (explicit bounds mode).| Field | Required | Description |
|---|---|---|
D_boundary | yes | Boundary field scale |
D_crit | no | Critical suppression; computed from lambdaDB + deltaR if omitted |
D_suppress_min, D_suppress_max | no | Explicit sweep bounds (API-friendly mode) |
Gamma_restore, deltaR, v_atom, lambdaDB, dim | yes | Transport geometry |
steps | no | Sweep resolution (integer ≥2; demo max 50, prod max 500) |
fraiThreshold | no | Filter for recommended band |
sweep_input_mode, D_crit, isInverted, count, valid_count,
results[] (each row: D_suppress, valid_regime, rejection_reason,
t_window, v_min, minFrai, inputVelocityOk, isInverted).
Optional warning when bounds cross the invalid regime boundary.
If no valid points: HTTP 200, ok: false, reason explains empty valid set.
All POST routes return claim_statement, warnings[], and summary. Use detail: summary | light | full on simulate/sweep/ode-router.
Auth: Required · Log-spaced radius scan at fixed D.
| Field | Required |
|---|---|
D, dim, lambdaDB, rMin, rMax | yes |
steps, epsilon | no |
Each row includes r, lambdaDB, fraiBase, kernel, fraiEff.
Auth: Required · Numeric bisection estimator (numeric_bisection_full_frai_eff). Needs ≥3 observations with r, lambdaDB, fraiEff.
Auth: Required · Sparse Q claim: routing receipt only (pre-flight decision support).
Accepts sample traces plus hardware/code context and returns a routing recommendation
(LOGICAL, PHYSICAL, INDETERMINATE) with model diagnostics.
Auth: Required · Returns calibration receipt for f_coh/sigma posterior updates.
Auth: Required · Broker cost and shot estimates per provider using live qBraid device pricing and/or IBM Quantum Runtime backends. Pass samples (≥128) to derive recommendation from USL ODE preflight. Optional circuit_type / topology fields are accepted for client metadata but do not select layouts. Secrets: QBRAID_API_KEY, IBM_QUANTUM_*.
Auth: Required · Claim: control_recommendation_only
Theory-B-weighted bounded P controller. Always follow with /transport/simulate before QUA/OPX.
Auth: Required · Claim: template_generation_and_calibration_assist_only
Returns reviewable Python/QUA template text. Modes: constants or input_stream. No OPX execution from Cloudflare.
Auth: Required · Bounded amplitude recommendation from FRAI observations.
Decisions: PASS_NO_ADJUST, ADJUST_AND_RETRY, CALIBRATION_LIMITED.
Auth: Required · Body: D_target (required), loss_target (optional, default 0.01)
Returns coherence_loss, qec_compatibility, formula receipt, and claim boundary fields.
Auth: Required · Body: loss_target (optional, default 0.01)
Returns threshold.min_integer_D, conservative_design_rule (Use D_target > 200 at 1%).
Auth: Required · Submit a physical transport measurement as a validation receipt.
Does not update the model (model_update: none, stored: false). Use to compare predicted CL(D) with measured loss after a lab run.
Auth: Required · Claim: template_generation_and_calibration_assist_only
Maps tensor-network bond dimension χ to USL D using truncation + Trotter gate-error model. Classification: chi_ratio → p_norm → em_bootstrap.
| Field | Required | Description |
|---|---|---|
dt_ns | yes | Trotter time step (ns) |
observations[] | yes (≥2 distinct χ) | chi, ta, gate_error from saturated regime |
mu_kz | no | Default 2.75 |
target_gate_error, target_ta_ns | no | χ_min prediction targets |
xi_chi_dependence: model.xi_chi_dependence = max/min ξ from adjacent truncation pairs with ge(χ_hi)/ge(χ_lo) < 0.1.
Null if insufficient pairs. When > 2, chi_prediction.chi_min_conservative is true and chi_min_note recommends a denser χ sweep.
Auth: Required · Claim: research_harness_preflight_only
Fits C(d) = g₀·exp(-b·d^α), extracts ξ = (1/b)^(1/α). Multi-series mode fits ξ(tₐ) = ξ₀·tₐ^(1/μ) when ta_max/ta_min ≥ 4 and n_series ≥ 4.
Validated on real Dryad data from Tindall et al. Science 2026 Figure 5 (R² > 0.999, alpha_mean ≈ 1.42, mu_fitted ≈ 2.53 vs paper μ≈2.75). Not a replacement for full multi-size KZ collapse.
Auth: Required · Canned receipts for integration tests (no body).
| Path | What you get |
|---|---|
.../transport-standard | ok: true, standard regime, dissolutionOk + timingOk |
.../transport-inverted | ok: true, summary.isInverted: true |
.../estimator-roundtrip | estimated_D ≈ 0.2 from scan at D=0.2 |
| Code | When |
|---|---|
200 | Success (simulate may return ok: false in body) |
400 | Invalid JSON, missing fields, step limit exceeded, core validation error |
401 | Missing or invalid API key |
429 | Rate limit (per key + route) |
404 | Unknown path under /api/v1/usl |
Calls production API with demo key. Full JSON below — inspect summary, boundary, phases.transit.
Click a button to call the API…