Qx.Hardware.Portal (Qx - Quantum Computing Simulator v0.8.0)

View Source

HTTP client for the qxportal transpilation service (/api/v1).

Used by Qx.Hardware to:

  • confirm a portal token and fetch the authenticated identity (me/1); and
  • transpile an OpenQASM 3.0 program for a target IBM backend (transpile/3).

Wraps Req. Maps the documented error shapes to plain tuples callers can pattern-match on.

Privacy invariant

This module reads config.portal_url and config.portal_token only — the IBM API key and CRN never leave Qx.Hardware.Ibm.

Error mapping

Common to GET and POST:

HTTPReturned
200 OK{:ok, decoded_data}
401{:error, :unauthorized}
404{:error, :not_found}
429 + retry-after header{:error, {:rate_limited, secs}}
Other 4xx/5xx{:error, {:http, status, body}}
Network / Req exception{:error, {:network, reason}}

POST-only (transpile/3):

HTTPReturned
422{:error, {:invalid_qasm, detail}}
502{:error, :transpile_failed}
503{:error, :transpile_unavailable}
504{:error, :transpile_timeout}

Summary

Types

identity()

The shape returned by /api/v1/me.

transpile_result()

Successful transpile response payload.

Functions

me(config)

Confirms the portal token is valid and returns the authenticated identity.

transpile(config, qasm, opts \\ [])

Transpiles an OpenQASM 3.0 program for a target IBM backend.

Types

identity()

@type identity() :: %{email: String.t(), role: String.t(), api_key_name: String.t()}

The shape returned by /api/v1/me.

transpile_result()

@type transpile_result() :: %{
  qasm: String.t(),
  metadata: %{
    depth: non_neg_integer(),
    size: non_neg_integer(),
    num_qubits: non_neg_integer()
  }
}

Successful transpile response payload.

Functions

me(config)

@spec me(Qx.Hardware.Config.t()) :: {:ok, identity()} | {:error, term()}

Confirms the portal token is valid and returns the authenticated identity.

transpile(config, qasm, opts \\ [])

@spec transpile(Qx.Hardware.Config.t(), String.t(), keyword()) ::
  {:ok, transpile_result()} | {:error, term()}

Transpiles an OpenQASM 3.0 program for a target IBM backend.

qasm is the source program; opts may include:

  • :coupling_map — list of qubit-pair connections.
  • :basis_gates — list of basis gates supported by the backend.
  • :optimization_level — integer 0..3. Defaults to config.optimization_level.
  • :seed_transpiler — optional integer seed.
  • :backend — backend name (string). Defaults to config.backend.

Returns {:ok, %{qasm: ..., metadata: %{depth: _, size: _, num_qubits: _}}} on success.