IonQProvider
Runtime integration for streamlined access to IonQ simulators and QPUs.
API Reference: qbraid.runtime.ionq
Overview
The qbraid.runtime.IonQProvider
provides support for IonQ’s trapped-ion systems. This means that you can write quantum circuits in
Qiskit, Cirq, Amazon Braket, Pennylane, PyTKET, or any other library compatible with OpenQASM (version 2 or 3),
and run them on IonQ’s simulators and trapped-ion quantum computers, all from within the qBraid Runtime framework.
Getting started
Before you begin, make sure you have an IonQ Quantum Cloud account and API key. For help, see IonQ’s guide on creating and managing API keys.
Set up the qBraid-SDK
Install qBraid with the ionq
extra from PyPI using pip:
Note: The qBraid-SDK requires Python 3.10 or greater. You can check your
Python version by running python --version
from the command line.
We encourage doing this inside an environment management system, such as virtualenv or conda. Alternatively, you can bypass this step by using a pre-configured qBraid Lab environment. See qBraid-SDK installation and setup for more.
Set up your environment
By default, qBraid will look in your local environment for a variable named IONQ_API_KEY
, so if you’ve already followed IonQ’s guide on
setting up and managing your API keys, qBraid will automatically find it.
Alternatively, you can set a “temporary” environment variable from your command line:
While we recommend setting an environment variable so that qBraid can find your API key, you can also pass in your API key explicitly
within your Python code, when creating the IonQ Provider object that authenticates your connection to the IonQ Cloud Platform. This might
be necessary if you’ve named your environment variable something other than IONQ_API_KEY
, or if you are working from a Python environment
where accessing environment variables is not straightforward. You can import your key explicitly or load it from a file, and pass it into
the IonQProvider()
object directly:
In the examples below, we show IonQProvider()
initialized with no arguments and assume that qBraid will automatically find your API key,
but you can always use this approach instead.
List available devices
Use the IonQProvider
to list all of the devices to which you have access:
Running this script should print the results below—something like this:
If this works correctly then your qBraid-SDK installation is correct, your IonQ API key is valid, and you have access to the IonQ devices!
Submit a circuit to the simulator
First, let’s try running a simple Bell state circuit on the ideal simulator. Here, we’ll use 1000 shots, and give the circuit a name that will show up in the IonQ Cloud Console.
Your input OpenQASM program should not include measurement statements. Measurement will be applied over all qubits at the end of the circuit, automatically. Mid-circuit measurements and partial measurements are not supported.
This returns:
As expected, the ideal simulator creates a quantum state with a 50-50 probability of being measured as “00” or “11”.
To view the calculated probabilities for a circuit run on the simulator, use result.data.get_probabilities()
.
You can return histogram data in decimal format for either of these result.data
methods using argument decimal=True
.
Submit a circuit with noise
Get a list of all noise models supported by the IonQ simulator:
Then, to run a noisy simulation, simply specify a noise model and an optional random seed:
You can read more about simulation with noise models here.
Submit a circuit to a QPU
You can view your access to IonQ systems in the “Backends” tab of the IonQ Cloud Console. Before submitting to any QPU, we recommend testing your code on a simulator (including with noise model) and following the other steps in the QPU submission checklist to confirm your access and the QPU availability.
To run a circuit on a QPU, use the same setup as before, just with a different device ID:
Verify that the device is ONLINE
:
View device characterization data including the connectivity, fidelity, timings, and more:
Next, construct your quantum program, ensuring it aligns with the device’s supported gateset. In this example, we’ll define GHZ state circuit using OpenQASM 3:
Estimate Cost
You can use the device.run()
method with the preflight=True
option to obtain a cost estimate for the anticipated job
without actually executing the program on a QPU.
If you plan to run your job with debiasing, be sure to include the
error_mitigation
parameter in the preflight submission to ensure it is accounted for in the cost estimate:
Submit to QPU
When you are ready to submit the job on the QPU, simply set preflight=False
, or don’t specify any preflight
value.
Optionally include job tags or other metadata for your convenience, specifying up to 10 key-value pairs.
When submitting jobs to a QPU, your job may need to wait in the queue. You can print and record the job’s unique ID, which can be used to retrieve the job (including its status and results) at a later time, see Retrieve a job.
Check the status of your job:
Once the job is COMPLETED
, you can retrieve the results:
Submit a multi-circuit job
The flexibility of qBraid-SDK allows you to write your circuit not just in OpenQASM, but in Qiskit, Cirq, Amazon Braket, PyTKET,
or any other registered program type that can be
transpiled to qBraid’s qasm2
or qasm3
format.
In this example, we’ll install the qiskit
and cirq
extras,
and submit a multi-circuit job containing one of each program type:
This script submits two quantum circuits in a single job. When the job completes, it prints the counts for each circuit:
All of the necessary program type conversions are carried out automatically within the device.run()
method. However, you can also perform
this “transpile” step manually, if needed (e.g. to inspect the ultimate OpenQASM submission format). This can be done as follows:
qBraid offers native support for 10 major quantum programming libraries including 20+ inter-library conversions. For more details, including how to configure your own custom conversions, refer to the qBraid transpiler documentation.
Manage jobs
Retrieve a job
You can retrieve results for a previously run job using its job ID. You can save the job ID after submitting a job (as in the QPU example above) or copy it from the “ID” column in the “My Jobs” tab on the IonQ Cloud Console.
Cancel a job
You can cancel a job while it’s waiting in the queue:
Visualize Results
To plot the results of a job, first, install the qBraid visualization extra:
You can visualize the histogram counts data using plot_histogram
, or display the probability distribution with plot_distribution
.
The “counts” input may be either a single dictionary or a list of dictionaries for multi-circuit jobs. In the latter case, histogram data
for each circuit will be plotted side-by-side. The X-axis labels will display in decimal if you set decimal=True
when retrieving measurement
counts with get_counts()
. If decimal=False
or left unspecified, the default quantum state labels in hexadecimal will be used.
See Plot Experimental Results for more.
Supported gates
For actual execution, gates will be compiled into optimal operations for our trapped ion hardware. For convenience, IonQ provide a more expressive gateset for programming. However, not all gates supported by the OpenQASM 3 standard library are accepted by IonQ backends. See full list of supported gates.
You can also view a list of the OpenQASM gates supported by a given device directly from an IonQDevice
. For example:
Which would return:
Note: the returned gateset includes both the abstract QIS and IonQ-native gates supported by the device; however, circuits must be constructed using either exclusively QIS gates or exclusively native gates—you cannot mix the two within a single circuit. In the next section, we’ll explore using IonQ native gates in greater detail.
Native Gates
Building and submitting circuits using IonQ’s hardware-native gateset enables you to bypass our compiler and optimizer, providing more control and transparency than the default abstract gateset (though often at the cost of performance and convenience).
Before working with native gates in qBraid, we recommend reviewing our guides on Getting Started with Native Gates and the IonQ Native Gates API.
This is an advanced-level feature. Using the hardware-native gate interface without a thorough understanding of quantum circuits is likely to result in less-optimal circuit structure and worse algorithmic performance overall than using our abstract gate interface.
IonQ’s native gates are incorporated as a natural extension of the OpenQASM standard library within the qbraid[ionq]
runtime integration.
qBraid supports the following IonQ native gates:
gpi(phi)
gpi2(phi)
ms(phi0, phi1, theta=0.25)
for Aria systemszz(theta)
for Forte systems
For more details about these gate definitions and parameters, refer to the native gates guide.
The parameters in the IonQ native gate specification are always defined in turns, not in radians. One turn is 2π radians.
Native gate circuits can then be built and executed as follows:
Each quantum circuit submitted to the IonQ Cloud must use a consistent gateset throughout—you cannot mix and match native gates and abstract gates in the same circuit.
The qbraid[ionq]
runtime integration does not currently support automatic transpilation from abstract to native gates, but we may add this
capability in the future. For now, we recommend following this general procedure (also described in IonQ’s main native gates guide)
or using a different SDK.
Additional resources
Great work! You successfully ran your first quantum circuits - what next?
Explore more resources for using qBraid:
Find examples for using IonQ systems with other quantum programming libraries: