Getting started with Qiskit
Learn how to use the Qiskit SDK to submit quantum circuits to IonQ’s simulators and quantum computers.
What is Qiskit?
Qiskit is an open-source Python SDK for working with quantum computers at a variety of levels—from the “metal” itself, to pulses, gates, circuits and higher-order application areas like quantum machine learning and quantum chemistry. It has “Providers” that enable support for different vendors and the various “backends” (read: quantum computers or simulators) that they offer.
IonQ maintains an IonQ Provider for Qiskit that allows you to work with our trapped-ion systems and our high-performance cloud simulator, which we’ll install and use here.
Before you begin
You’ll need an account on the IonQ Quantum Cloud, and you’ll need to create an API key. We also have a guide about setting up and managing your API keys if you need some help.
You’ll also need Python 3.11 running locally on your machine.
Run python --version
from your command line if you aren’t sure which version
you have running.
Set up Qiskit
First, we’ll install Qiskit and the IonQ Provider from PyPI using pip:
Note: We encourage doing this inside an environment management system like virtualenv or conda so as to avoid this fate, but do what makes the most sense for you.
Set up your environment
By default, Qiskit will look in your local environment for a variable named IONQ_API_KEY
, so if you’ve already followed our guide on setting up and managing your API keys, Qiskit will automatically find it.
Alternatively, you can set an environment variable temporarily from your command line, by running:
While we recommend setting an environment variable so that Qiskit 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 Qiskit will automatically find your API key, but you can always use this approach instead.
Start a script
For this exercise, we’ll create a Python file and run it as a script. If you’re comfortable and familiar with Python, you can approach this any number of ways—our getting-started repository includes Jupyter notebooks that can be downloaded or run in Google Colab.
Open a file up in whatever IDE you prefer, and add the following:
Running this script should print the results below—something like this:
If this works correctly then your Qiskit installation works, your API key is valid, and you have access to the IonQ simulator! If you have access to a QPU, you’ll see it in this list, as well.
Submit a circuit to the simulator
Running a simple Bell state circuit
First, let’s try running a simple Bell state circuit on the ideal quantum simulator. Try running this script:
When you run it, you should see something like:
The simulator is simulating the circuit we defined, running it 10,000 times, and counting the number of times each state was measured. In this case, the circuit evaluated to a “00” state 5,016 times, and a “11” state 4,984 times.
.get_counts()
method samples from this probability distribution, so we didn’t end up with exactly 5,000 counts for each state. You can use job.get_probabilities()
to see the calculated probabilities for a circuit that was run on the simulator.Submitting multiple circuits in a single job
To submit multiple circuits in a single job submission, pass all of the circuits to the run()
function in a list instead:
This script submits two quantum circuits in a single job: a Bell state circuit and a GHZ state circuit. When the job completes, it prints the counts for each circuit:
Submit a circuit to the noisy simulator
To run the same circuit (or circuits) using the simulator with a noise model, we just need to modify one line of code in the above script: here, we’ll add the argument noise_model="aria-1"
when calling simulator_backend.run()
. The available noise models are harmony
(legacy), aria-1
, aria-2
, and forte-1
. You can read more about these noise models here.
When this simulation includes the effects of noise, we would expect to see results that are similar to the ideal simulation shown above, but with a few instances of measuring the “01” and “10” states. For example:
Submit a circuit to a QPU
To run the same circuit on IonQ’s quantum hardware (QPU), we need to define a different backend at the beginning of the script and submit the circuit to that backend. Available QPU backend options may include ionq_qpu.aria-1
, ionq_qpu.aria-2
, or ionq_qpu.forte-1
. You can view your access to these systems on the “Backends” tab of the IonQ Cloud Console.
When submitting jobs to a QPU, your job may need to wait in the queue, so you probably won’t get the results right away. Next, we’ll show how to check a previously submitted job’s status and retrieve its results.
Viewing job status and results
On the “My Jobs” tab in the IonQ Quantum Cloud application, you can always view the status of all of your jobs, and you can view and download their results.
You can also get the job status and results within Qiskit. You’ll need the job ID, which you can save after submitting a job (as in the QPU example above) or copy from the “ID” column in the “My Jobs” tab.
Once you’ve retrieved a job, you can use the same methods as in the above examples to print counts, probabilities, and other information.
Learning more
Great work! You successfully ran your first quantum circuits—now what?
For additional resources on using Qiskit, we recommend their getting started page and learning resources. For more detailed information on Qiskit, we recommend the Qiskit documentation.
For advanced features on IonQ systems with Qiskit, refer to our guides on using native gates and error mitigation with debiasing and sharpening.
For examples using different SDKs, more complex circuits, and in other languages, check out our IonQ Samples library on GitHub.
Finally (and maybe most importantly,) you can also request access to IonQ Quantum Computers here.
Was this page helpful?