Quick Start

This guide covers installing the SDK, connecting to the service, and submitting your first quantum circuit. For deeper topics see Working with Jobs and Composite Jobs.

Note

This is an early release and the public API may change before 1.0.0.

Installation

Install the SDK from PyPI using pip:

pip install oqc-qcaas-sdk

To include optional support for FermionIQ emulator runs, install with the experimental extra:

pip install "oqc-qcaas-sdk[experimental]"

Connecting

All SDK operations run inside an async with OqcSdk(...) context manager, which handles authentication and ensures connections are properly closed:

import asyncio
from oqc_qcaas_sdk import OqcSdk

async def main():
    async with OqcSdk(
        url="https://cloud.oqc.app",
        authentication_token="your_token_here"
    ) as sdk:
        ...

asyncio.run(main())

Submitting a Job

Pass a program string and a QPU ID to create_job(), then call execute() to submit, poll until complete, and return the results. The example below confirms the 'c' register is present in the output. For a full explanation of result fields and access patterns see Accessing Results. For other QPU ID patterns see QPU Selection.

>>> from oqc_qcaas_sdk import OqcSdk
>>> import os
>>> import asyncio
>>> async def run():
...     async with OqcSdk(url=os.environ["OQC_URL"], authentication_token=os.environ["OQC_AUTHENTICATION_TOKEN"]) as client:
...         qpu_id = 'qpu:uk:2:d865b5a184'  # Simulator
...         program = 'OPENQASM 2.0; include "qelib1.inc"; qreg q[1]; creg c[1]; h q[0]; measure q[0] -> c[0];'
...         job = client.create_job(program=program, qpu_id=qpu_id)
...         await job.execute(timeout_s=10)
...         return job.completed, 'c' in job.result.data, '0' in job.result.data['c'], '1' in job.result.data['c']
>>> asyncio.run(run())
(True, True, True, True)

Checking for Errors

By default, execution errors are stored on the job object rather than raised as exceptions. Check job.error after execute() to detect failure:

>>> from oqc_qcaas_sdk import OqcSdk
>>> import os
>>> import asyncio
>>> async def run():
...     async with OqcSdk(url=os.environ["OQC_URL"], authentication_token=os.environ["OQC_AUTHENTICATION_TOKEN"]) as client:
...         qpu_id = 'qpu:uk:2:d865b5a184'  # Simulator
...         bad_program = 'OPENQASM 5.0; include "qelib1.inc"; qreg q[1]; creg c[1]; h q[0]; measure q[0] -> c[0];'
...         job = client.create_job(program=bad_program, qpu_id=qpu_id)
...         outputs = await job.execute(timeout_s=15)
...         return job.completed, bool(job.error)
>>> asyncio.run(run())
(False, True)

For exception-based error handling see Exception-based Error Handling in Working with Jobs.