Skip to content

Core SDK Examples

Common workflows using the openquantum-sdk package.

Note

All examples assume you have valid SDK key credentials. See Authentication for setup.

Submit a QASM File from Disk

from openquantum_sdk.auth import ClientCredentials, ClientCredentialsAuth
from openquantum_sdk.clients import SchedulerClient, JobSubmissionConfig

auth = ClientCredentialsAuth(
    creds=ClientCredentials(
        client_id="s_your_client_id",
        client_secret="your_client_secret",
    ),
)

scheduler = SchedulerClient(auth=auth)

config = JobSubmissionConfig(
    backend_class_id="ionq:forte-1",
    name="File Upload Job",
    job_subcategory_id="oth:oth",
    shots=1024,
)

job = scheduler.submit_job(config, file_path="my_circuit.qasm")
output = scheduler.download_job_output(job)
print(output)

scheduler.close()

Submit a QASM String

from openquantum_sdk.auth import ClientCredentials, ClientCredentialsAuth
from openquantum_sdk.clients import SchedulerClient, JobSubmissionConfig

auth = ClientCredentialsAuth(
    creds=ClientCredentials(
        client_id="s_your_client_id",
        client_secret="your_client_secret",
    ),
)

scheduler = SchedulerClient(auth=auth)

qasm = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q[0] -> c[0];
measure q[1] -> c[1];
"""

config = JobSubmissionConfig(
    backend_class_id="ionq:forte-1",
    name="String QASM Job",
    job_subcategory_id="oth:oth",
    shots=1024,
)

job = scheduler.submit_job(config, file_content=qasm.encode("utf-8"))
output = scheduler.download_job_output(job)
print(output)

scheduler.close()

List and Filter Backends

from openquantum_sdk.auth import ClientCredentials, ClientCredentialsAuth
from openquantum_sdk.clients import ManagementClient

auth = ClientCredentialsAuth(
    creds=ClientCredentials(
        client_id="s_your_client_id",
        client_secret="your_client_secret",
    ),
)

management = ManagementClient(auth=auth)

# List all backends
result = management.list_backend_classes()
for bc in result.backend_classes:
    status = "accepting jobs" if bc.accepting_jobs else "not accepting"
    print(f"{bc.short_code} ({bc.type}, {bc.status}, {status})")

# Filter by provider
ionq_backends = management.list_backend_classes(provider_id="ionq")
for bc in ionq_backends.backend_classes:
    print(f"IonQ: {bc.short_code} - {bc.name}")

management.close()

Check Job Status

from openquantum_sdk.auth import ClientCredentials, ClientCredentialsAuth
from openquantum_sdk.clients import SchedulerClient

auth = ClientCredentialsAuth(
    creds=ClientCredentials(
        client_id="s_your_client_id",
        client_secret="your_client_secret",
    ),
)

scheduler = SchedulerClient(auth=auth)

job = scheduler.get_job("your-job-uuid")
print(f"Job: {job.id}")
print(f"Status: {job.status}")
print(f"Submitted: {job.submitted_at}")

if job.status == "Completed" and job.output_data_url:
    output = scheduler.download_job_output(job)
    print(f"Results: {output}")

scheduler.close()

List Organization Jobs

from openquantum_sdk.auth import ClientCredentials, ClientCredentialsAuth
from openquantum_sdk.clients import SchedulerClient

auth = ClientCredentialsAuth(
    creds=ClientCredentials(
        client_id="s_your_client_id",
        client_secret="your_client_secret",
    ),
)

scheduler = SchedulerClient(auth=auth)

# List recent jobs (organization is auto-discovered)
result = scheduler.list_jobs()
for job in result.jobs:
    print(f"{job.name}: {job.status} ({job.submitted_at})")

# Filter by status
completed = scheduler.list_jobs(status="Completed")
for job in completed.jobs:
    print(f"Completed: {job.name} - {job.credits_used} credits")

scheduler.close()

Use the CLI

The Core SDK includes a command-line interface:

python -m openquantum_sdk \
    --input circuit.qasm \
    --backend ionq:forte-1 \
    --subcategory oth:oth \
    --shots 1024 \
    --client-id "s_your_client_id" \
    --client-secret "your_client_secret" \
    --auto-approve

Or with an SDK key file:

python -m openquantum_sdk \
    --input circuit.qasm \
    --backend ionq:forte-1 \
    --subcategory oth:oth \
    --shots 1024 \
    --sdk-key credentials.json

The SDK key file is a JSON file with client_id and client_secret fields:

{
    "client_id": "s_your_client_id",
    "client_secret": "your_client_secret"
}