Execute Qx circuits on real IBM Quantum hardware.

Orchestrates the full pipeline:

circuit  →  QASM  →  qxportal transpile  →  IBM submit  →  poll
                                                 ↓
                                            IBM results
                                                 ↓
                                       Qx.SimulationResult

Configuration

All entry points require a Qx.Hardware.Config, which carries portal

• IBM credentials and execution preferences (backend, shots, optimization level). See Qx.Hardware.Config for details and Qx.Hardware.Config.from_env/1 for the environment-driven setup used in examples/hardware/run_on_ibm.exs.

Privacy invariant

The portal token never reaches Qx.Hardware.Ibm, and the IBM API key / CRN never reach Qx.Hardware.Portal. The two clients read only their own fields from the shared Qx.Hardware.Config struct.

Status callback

Pass :on_status in opts to receive pipeline events:

run(circuit, config, on_status: fn event -> Logger.debug(inspect(event)) end)

Events (all atoms, allowlisted — Iron Law #1):

• {:portal, :connecting} — emitted by connect/1
• {:portal, :listing_backends}
• {:portal, :transpiling}
• {:ibm, :authenticating}
• {:ibm, :fetching_backend}
• {:ibm, :submitting}
• {:ibm, :job_started, job_id} — job_id is a binary
• {:ibm, :polling, status} — status is a binary in ["Queued", "Running", "Completed", "Cancelled", ...]
• {:ibm, :fetching_results}

Error returns

Every failure mode normalises to {:error, {stage, reason}}, where stage is one of:

• :config — config validation or measurement check failed
• :portal — /api/v1/me or /api/v1/transpile failed
• :ibm_auth — IAM exchange or backend lookup failed
• :ibm_submit — POST /jobs failed
• :ibm_poll — poll request failed (not the same as terminal Failed/Cancelled)
• :ibm_poll_timeout — overall poll deadline exceeded
• :ibm_job_failed — IBM returned terminal Failed / Cancelled / Cancelled - Ran too long
• :ibm_results — results fetch / parse failed

Synchronous, blocking

run/3 and submit_qasm/3 block until the IBM job reaches a terminal status. Hardware queues can take hours; callers that need to surface progress should wire :on_status and/or run the call in a supervised Task. The Livebook integration in kino_qx wraps this in a monitored Task with a cancel button — non-Livebook callers must arrange their own supervision if they need async cancel.