Skip to main content

Platform-agnostic quantum runtime framework.

Project description

qbraid-sdk-header

CI codecov Documentation Status PyPI version Downloads License DOI

The qBraid-SDK is a platform-agnostic quantum runtime framework designed for both quantum software and hardware providers.

This Python-based tool streamlines the full lifecycle management of quantum jobs—from defining program specifications to job submission and through to the post-processing and visualization of results. Unlike existing runtime frameworks that focus their automation and abstractions on quantum components, qBraid adds an extra layer of abstractions that considers the ultimate IR needed to encode the quantum program and securely submit it to a remote API. Notably, the qBraid-SDK does not adhere to a fixed circuit-building library, or quantum program representation. Instead, it empowers providers to dynamically register any desired input program type as the target based on their specific needs. This flexibility is extended by the framework’s modular pipeline, which facilitates any number of additional program validation, transpilation, and compilation steps.

By addressing the full scope of client-side software requirements necessary for secure submission and management of quantum jobs, the qBraid-SDK vastly reduces the overhead and redundancy typically associated with the development of internal pipelines and cross-platform integrations in quantum computing.


Runtime Diagram

Resources

Installation & Setup

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, Rigetti, and IQM, as well as on-demand simulators from qBraid and AWS. See qBraid Quantum Jobs for more.

Local install

The qBraid-SDK, and all of its dependencies, can 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.

To use qBraid Runtime locally, you must also install the necessary extras and configure your account credentials according to the device(s) that you are targeting. Follow the linked, provider-specific, instructions for the QbraidProvider, BraketProvider, QiskitRuntimeProvider, IonQProvider, and OQCProvider, as applicable.

Quickstart

Check version

You can view the version of the qBraid-SDK you have installed and get detailed information about the installation within Python using the following commands:

In [1]: import qbraid

In [2]: qbraid.__version__

In [3]: qbraid.about()

Transpiler

Graph-based approach to quantum program type conversions.

Below, QPROGRAM_REGISTRY 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 QPROGRAM_REGISTRY
>>> QPROGRAM_REGISTRY
{'cirq': cirq.circuits.circuit.Circuit,
 'qiskit': qiskit.circuit.quantumcircuit.QuantumCircuit,
 'pennylane': pennylane.tape.tape.QuantumTape,
 'pyquil': pyquil.quil.Program,
 'pytket': pytket._tket.circuit.Circuit,
 'braket': braket.circuits.circuit.Circuit,
 'openqasm3': openqasm3.ast.Program,
 'pyqir': pyqir.Module,
 'qasm2': str,
 'qasm3': str}

Pass any registered quantum program along with a target package from QPROGRAM_REGISTRY 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────────

Behind the scenes, the qBraid-SDK uses rustworkx to create a directional graph that maps all possible conversions between supported program types:

from qbraid.transpiler import ConversionGraph

# Loads native conversions from QPROGRAM_REGISTRY
graph = ConversionGraph()

graph.plot(legend=True)

You can use the native conversions supported by qBraid, or define your own. For example:

from unittest.mock import Mock

from qbraid.programs import register_program_type
from qbraid.transpiler import Conversion

# replace with any program type
register_program_type(Mock, alias="mock")

# replace with your custom conversion function
example_qasm3_to_mock_func = lambda x: x

conversion = Conversion("qasm3", "mock", example_qasm3_to_mock_func)

graph.add_conversion(conversion)

# using a seed is helpful to ensure reproducibility
graph.plot(seed=20, k=3, legend=True)

QbraidProvider

Run experiements using on-demand simulators provided by qBraid. Retrieve a list of available devices:

from qbraid.runtime import QbraidProvider

provider = QbraidProvider()
devices = provider.get_devices()

Or, instantiate a known device by ID and submit quantum jobs from any supported program type:

device = provider.get_device("qbraid_qir_simulator")
jobs = device.run([qiskit_circuit, braket_circuit, cirq_circuit, qasm3_str], shots=1000)

results = [job.result() for job in jobs]
batch_counts = [result.data.get_counts() for result in results]

print(batch_counts[0])
# {'00': 483, '01': 14, '10': 486, '11': 17}

And visualize the results:

from qbraid.visualization import plot_distribution, plot_histogram

plot_distribution(batch_counts)

plot_histogram(batch_counts)

Get Involved

Community GitHub Issues Stack Exchange Discord

Launch on qBraid

The "Launch on qBraid" button (top) 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

License

GNU General Public License v3.0

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

qbraid-0.8.0.dev20240922195512.tar.gz (332.8 kB view details)

Uploaded Source

Built Distribution

qbraid-0.8.0.dev20240922195512-py3-none-any.whl (248.3 kB view details)

Uploaded Python 3

File details

Details for the file qbraid-0.8.0.dev20240922195512.tar.gz.

File metadata

File hashes

Hashes for qbraid-0.8.0.dev20240922195512.tar.gz
Algorithm Hash digest
SHA256 0634d0d442c3830a1e35ed284014313b8915c8c39f097495468fdc47d920ab90
MD5 72cf55a07c2be15f2e528e1cf06b6576
BLAKE2b-256 2df50a298fb0225e4986c69f0e9075ef28319921689de93440a9a3e048fb0491

See more details on using hashes here.

File details

Details for the file qbraid-0.8.0.dev20240922195512-py3-none-any.whl.

File metadata

File hashes

Hashes for qbraid-0.8.0.dev20240922195512-py3-none-any.whl
Algorithm Hash digest
SHA256 1bc423756fc358119dc2101d9983cb5d7355e241769a3e45c2073e2d2ea6ca0a
MD5 f2580ac688c3ae691c62719bce47c77d
BLAKE2b-256 6282550aabf066d06acafd6e7817e5aa71e85d38f7476def2bfb8f125f519a25

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page