Qubitra Python SDK

The Python client for the Qubitra platform. Submit quantum circuits to a backend, wait for them to finish, and read normalized results.

Full documentation, including a quickstart and the API reference, is at q-plat-dev.cloud.qubitra.io/docs.

Install

pip install qubitra-sdk

The distribution is qubitra-sdk and the import is qubitra. Python 3.11 or newer is required. Optional extras integrate with quantum frameworks: qubitra-sdk[qiskit], qubitra-sdk[cirq], qubitra-sdk[pennylane], qubitra-sdk[openqarp].

Quickstart

Create an API key in the Qubitra console and set it as QUBITRA_API_KEY, then:

from qubitra import QubitraClient

BELL = (
    'OPENQASM 3.0; include "stdgates.inc"; qubit[2] q; bit[2] c; '
    "h q[0]; cx q[0], q[1]; c = measure q;"
)

with QubitraClient() as client:
    for backend in client.backends.list():
        print(backend.id, backend.qubit_count, backend.supported_formats)

    job = client.jobs.submit(
        backend_id="sim-statevector-26q",
        circuit=BELL,
        shots=1024,
        name="bell-pair",
    )

    job = client.jobs.wait(job.id, timeout=600)
    if job.status.is_terminal and job.error:
        raise SystemExit(f"job {job.id} failed: {job.error}")

    print(client.jobs.result(job.id).counts)   # {"00": 512, "11": 512}

Note that include "stdgates.inc"; is required in OpenQASM 3 programs: the language defines no gates of its own, so h and cx are undefined without it.

Configuration

Both can also be passed as constructor arguments — QubitraClient(api_key=…, api_url=…) — which take precedence over the environment.

API surface

A job carries an ordered list of PUBs (Primitive Unit Blocs). A Pub is a circuit plus optional observables, parameter_values rows, and a shots count. JobResult.pubs is index-aligned with the submission; each entry is a CountsResult, ProbabilitiesResult, ExpectationValuesResult, or ErrorResult. For a single-circuit submission, the convenience properties result.counts, .values, .probabilities, and .shots read the first entry.

A Session groups a run of jobs under one id and bounds what the run may spend via max_credits and max_seconds. It does not reserve hardware or affect queue priority.

jobs.result is available once a job is COMPLETED; calling it earlier raises InvalidRequestError.

Errors

Every failure the SDK raises is a QubitraError. The subclasses are AuthenticationError, NotFoundError, InvalidRequestError, InsufficientCreditsError, and ProviderError. Each carries the platform's error body on .detail and the HTTP status on .status_code.

Typing

All models are frozen pydantic models, and the package ships py.typed, so the full surface is visible to type checkers.