The qBraid-SDK is a Python toolkit for cross-framework abstraction, transpilation, and execution of quantum programs.
- Unified quantum frontend interface. Transpile quantum circuits between supported packages. Leverage the capabilities of multiple frontends through simple, consistent protocols.
- Build once, target many. Create quantum programs using your preferred circuit-building package, and execute on any backend that interfaces with a supported frontend.
- Benchmark, compare, interpret results. Built-in compatible post-processing enables comparing results between runs and across backends.
![qbraid-sdk-env](https://private-user-images.githubusercontent.com/46977852/238787487-c82d61b4-2518-4c7e-8f48-05106afa708e.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjM4MTU0NjMsIm5iZiI6MTcyMzgxNTE2MywicGF0aCI6Ii80Njk3Nzg1Mi8yMzg3ODc0ODctYzgyZDYxYjQtMjUxOC00YzdlLThmNDgtMDUxMDZhZmE3MDhlLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA4MTYlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwODE2VDEzMzI0M1omWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWI3YWU4ZDRhMjJhYTA1ZGYyODczMGI5MzRlZmQ1YmM0YzllYWY5YWM2ZTU3NTU5N2FlOGQyZWU3NWU0ZmI4NDYmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.hLx_OEz3zCIO5AkRKDw81k_bLVk-qJPVrC1gMuJCGw4)
For the best experience, install the qBraid-SDK environment on lab.qbraid.com. Login (or create an account) and follow the steps to install an environment.
Using the SDK on qBraid Lab means direct, pre-configured access to QPUs from IonQ, Oxford Quantum Circuits, QuEra, and Rigetti, as well as on-demand simulators from AWS, all with no additional access keys or API tokens required. See qBraid Quantum Jobs for more.
The qBraid-SDK, and all of its dependencies, can also be installed using pip:
pip install qbraid
You can also install from source by cloning this repository and running a pip install command in the root directory of the repository:
git clone https://github.com/qBraid/qBraid.git
cd qBraid
pip install .
Note: The qBraid-SDK requires Python 3.9 or greater.
If using locally, follow linked instructions to configure your qBraid, AWS, and IBMQ credentials.
You can view the version of the qBraid-SDK you have installed within Python using the following:
In [1]: import qbraid
In [2]: qbraid.__version__
qBraid documentation is available at docs.qbraid.com.
See also:
Construct a quantum program of any supported program type.
Below, SUPPORTED_QPROGRAMS
maps shorthand identifiers for supported quantum programs, each corresponding to a type in the typed QPROGRAM
Union.
For example, 'qiskit' maps to qiskit.QuantumCircuit
in QPROGRAM
. Notably, 'qasm2' and 'qasm3' both represent raw OpenQASM strings.
This arrangement simplifies targeting and transpiling between different quantum programming frameworks.
>>> from qbraid.programs import SUPPORTED_QPROGRAMS
>>> SUPPORTED_QPROGRAMS
{'cirq': 'cirq.circuits.circuit.Circuit',
'qiskit': 'qiskit.circuit.quantumcircuit.QuantumCircuit',
'pyquil': 'pyquil.quil.Program',
'pytket': 'pytket._tket.circuit.Circuit',
'braket': 'braket.circuits.circuit.Circuit',
'openqasm3': 'openqasm3.ast.Program',
'qasm2': 'str',
'qasm3': 'str'}
Pass any quantum program of type qbraid.programs.QPROGRAM
to the load_program()
and specify a target package
from SUPPORTED_QPROGRAMS
to "transpile" your circuit to a new program type:
>>> from qbraid.interface import random_circuit
>>> from qbraid.transpiler import transpile
>>> qiskit_circuit = random_circuit("qiskit")
>>> cirq_circuit = transpile(qiskit_circuit, "cirq")
>>> print(qiskit_circuit)
┌────────────┐
q_0: ──■──┤ Rx(3.0353) ├
┌─┴─┐└───┬────┬───┘
q_1: ┤ H ├────┤ √X ├────
└───┘ └────┘
>>> print(cirq_circuit)
0: ───@───Rx(0.966π)───
│
1: ───H───X^0.5────────
The same functionality can be achieved using the underlying transpile()
function directly:
>>> from qbraid.transpiler import transpile
>>> cirq_circuit = transpile(qiskit_circuit, "cirq")
Behind the scenes, the qBraid-SDK uses networkx
to create a directional graph that maps all possible conversions between supported program types:
from qbraid.transpiler import ConversionGraph
from qbraid.visualization import plot_conversion_graph
graph = ConversionGraph()
graph.plot()
You can use the native conversions supported by qBraid, or define your own custom nodes and/or edges. For example:
from qbraid_qir.qasm3 import qasm3_to_qir
from qbraid.transpiler import Conversion
conversion = Conversion("qasm3", "qir", qasm3_to_qir)
graph.add_conversion(conversion)
graph.plot()
Search for quantum backend(s) on which to execute your program.
>>> from qbraid import get_devices
>>> get_devices()
Device status updated 0 minutes ago
Device ID Status
--------- ------
aws_oqc_lucy ONLINE
aws_ionq_aria2 OFFLINE
aws_rigetti_aspen_m3 ONLINE
ibm_q_brisbane ONLINE
...
You can get a Python list of device objects using:
from qbraid.providers import QbraidProvider
provider = QbraidProvider()
qdevices = provider.get_devices()
Or, instantiate a known device by ID via the QbraidProvider.get_device()
method,
and submit quantum jobs from any supported program type:
>>> from qbraid import get_jobs
>>> from qbraid.providers import QbraidProvider
>>> provider = QbraidProvider()
>>> aws_device = provider.get_device("aws_oqc_lucy")
>>> ibm_device = provider.get_device("ibm_q_brisbane")
>>> aws_job = aws_device.run(qiskit_circuit, shots=1000)
>>> ibm_job = ibm_device.run(cirq_circuit, shots=1000)
>>> get_jobs()
Displaying 2 most recent jobs:
Job ID Submitted Status
------ --------- ------
aws_oqc_lucy-exampleuser-qjob-zzzzzzz... 2023-05-21T21:13:47.220Z QUEUED
ibm_q_brisbane-exampleuser-qjob-xxxxxxx... 2023-05-21T21:13:48.220Z RUNNING
...
Compare results in a consistent, unified format:
>>> aws_result = aws_job.result()
>>> ibm_result = ibm_job.result()
>>> aws_result.measurement_counts()
{'00': 483, '01': 14, '10': 486, '11': 17}
>>> ibm_result.measurement_counts()
{'00': 496, '01': 12, '10': 479, '11': 13}
To use the qBraid-SDK locally (outside of qBraid Lab), you must add your account credentials:
-
Create a qBraid account or log in to your existing account by visiting account.qbraid.com
-
Copy your API Key token from the left side of your account page:
-
Save your API key from step 2 by calling
QbraidSession.save_config()
:
from qbraid_core import QbraidSession
session = QbraidSession(api_key='API_KEY')
session.save_config()
The command above stores your credentials locally in a configuration file ~/.qbraid/qbraidrc
,
where ~
corresponds to your home ($HOME
) directory. Once saved, you can then connect to the
qBraid API and leverage functions such as get_devices()
and get_jobs()
.
Alternatively, the qBraid-SDK can discover credentials from environment variables:
export QBRAID_API_KEY='QBRAID_API_KEY'
Then instantiate the session without any arguments
from qbraid_core import QbraidSession
session = QbraidSession()
The "Launch on qBraid" button (below) can be added to any public GitHub
repository. Clicking on it automaically opens qBraid Lab, and performs a
git clone
of the project repo into your account's home directory. Copy the
code below, and replace YOUR-USERNAME
and YOUR-REPOSITORY
with your GitHub
info.
Use the badge in your project's README.md
:
[<img src="https://qbraid-static.s3.amazonaws.com/logos/Launch_on_qBraid_white.png" width="150">](https://account.qbraid.com?gitHubUrl=https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git)
Use the badge in your project's README.rst
:
.. image:: https://qbraid-static.s3.amazonaws.com/logos/Launch_on_qBraid_white.png
:target: https://account.qbraid.com?gitHubUrl=https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git
:width: 150px
- Interested in contributing code, or making a PR? See CONTRIBUTING.md
- For feature requests and bug reports: Submit an issue
- For discussions, and specific questions about the qBraid-SDK join our discord community
- For questions that are more suited for a forum, post to
Quantum Computing Stack Exchange
with the
qbraid
tag.