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.

Credits are whole: one credit is £1, and Backend.price gives each backend's price per task, circuit, 1,000 shots or minute. Submitting a job holds its quote (Job.hold); when it ends it is charged what it cost (Job.charge) and the rest returns to your balance.

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 (with PermissionDeniedError and NotAcquiredError beneath it), NotFoundError, InvalidRequestError (with InputValidationError), InsufficientCreditsError, CeilingReachedError, ApplicationUnavailableError, 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.