A step-by-step guide to implementing a new provider class.
QuantumProvider
should implement a get_devices
method to retrieve
QuantumDevice
objects, which describe the device’s supported operations, the program types accepted as run input, and other
dynamic runtime instructions. Finally, devices must implement a submit()
method to execute or
queue programs, returning a QuantumJob
object. This standardization allows users and APIs to uniformly submit jobs and retrieve
results, ensuring compatibility across different providers and devices.
Here are the high-level components required to establish a complete runtime implementation:
Provider Setup
QuantumProvider
subclass that manages authentication and
remote access to the available device(s).Device + Runtime Configuration
QuantumDevice
subclass and its submit()
method. Optionally
incorporate a custom ConversionScheme
to broaden the range of quantum
program types that can be accepted as run input.Job Management
QuantumJob
subclass that handles interactions with a running
job. Process and present data collected from job executions in unified
Result
class.GET
/devices
(or similar) - To retrieve metadata about available quantum devices.POST
/job
(or similar) - To submit a quantum job for execution on a specified device.GET
/job
(or similar) - To retrieve the status and results of an executed quantum job.qbraid.runtime.Session
, a subclass of requests.Session,
is designed to manage secure HTTP connections to custom endpoints. It ensures encrypted and authenticated communication for quantum
providers and offers customizations for management of headers and secret keys, configurable retries for 5xx
errors, and more.
Below is a minimal example demonstrating how one could set up authenticated requests to the previously mentioned endpoints:
base_url
corresponds to your API endpoint. The qBraid Session
class distinguishes between headers
and auth_headers
, ensuring that values in auth_headers
are masked in all responses to safeguard against the inadvertent
exposure of secret keys.
The qBraid Session
class offers additional customizable options such as the total number of retries for requests, the number
of connection retries, the backoff factor between retry attempts, and more. For further details, refer to the linked
API Reference below.
qbraid.runtime.TargetProfile
encapsulates the configuration settings and runtime protocol(s) for a quantum device, presenting
them as a read-only dictionary. This class plays a crucial role in orchestrating the processes required for the submission of
quantum jobs in the current environment.
Specifically, the TargetProfile
class specifies domain and device-specific instructions to tailor quantum programs to the
intermediate representation (IR) required for submission through the provider’s API and execution on the quantum backend. This
includes compilation steps, type conversions, data mappings, and other essential runtime transformations.
Below is an example implementation of a TargetProfile:
QuantumProvider
subclass must implement both a get_device
and a get_devices
method. These methods process raw device data,
adapting it into a TargetProfile
for each device, and return either a single QuantumDevice
object or a list of them. In this example,
we use the MySession
class to handle API requests; however, this is illustrative and not mandatory. API interactions can also be managed
directly through other means.
In cases where the API data does not directly conform to the format needed to instantiate a TargetProfile
, additional mappings and
adaptations will typically be necessary. Below is an example implementation of a provider using MySession
to construct a MyDevice
object. We will explore implementations of QuantumDevice
subclasses in the next section.
qbraid.runtime.QuantumDevice
class describes the unique parameters and operational settings necessary for executing quantum
programs on specific hardware.
QuantumDevice
subclass must
implement both a status
and submit
method.
A minimum working example could look like:
qbraid.runtime.QuantumJob
class represents the transitional states of quantum programs, managing both ongoing and completed
quantum computations.