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.

Setting up Qiskit

First, we’ll install Qiskit and the IonQ Provider from PyPI using pip:

pip install qiskit qiskit-ionq

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 that is set, it will find it automatically there. From your command line, run:

export IONQ_API_KEY="your_api_key_here"

Note: If you’d prefer, you can also pass your key as an argument to the IonQProvider object directly.

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 ionq-examples project includes a number of Jupyter notebooks and other approaches to check out.

Open your a file up in whatever IDE you prefer, and add the following:

from qiskit_ionq import IonQProvider
provider = IonQProvider()


It should print the results below—something like this:

[<IonQSimulatorBackend('ionq_simulator')>, <IonQQPUBackend('ionq_qpu')>]

If this works correctly then your Qiskit installation works, your API key is valid, and you have access to the IonQ simulator! If you had access to a QPU, you’d see it in this list, as well.

Submitting Circuits

Running a Simple Bell State Circuit

First, let’s try running a simple Bell state circuit. Try running this script:

from qiskit import QuantumCircuit
from qiskit_ionq import IonQProvider

provider = IonQProvider()
simulator_backend = provider.get_backend("simulator")

# Create a basic Bell State circuit:
qc = QuantumCircuit(2, 2)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

# Run the circuit on IonQ's platform:
job = simulator_backend.run(qc, shots=10000)

# Print the counts

When you run it, you should see something like:

{'00': 4984, '11': 5016}

The simulator is simulating the circuit we defined, running it 10,000 times, and counting each state that it evaluated to.

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:

from qiskit import QuantumCircuit
from qiskit_ionq import IonQProvider

provider = IonQProvider()
backend = provider.get_backend("simulator")

# Define two quantum circuits
qc1 = QuantumCircuit(2, name="bell state")
qc1.cx(0, 1)

qc2 = QuantumCircuit(3, name="ghz state")
qc2.cx(0, 1)
qc2.cx(0, 2)

# Submit both circuits as a single job
job = backend.run([qc1, qc2])

# Print the results

# Or a specific job

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:

[{'00': 519, '11': 505}, {'000': 505, '111': 519}]
{'00': 519, '11': 505}

Viewing job results

Results are available from the API using the GET /jobs/{UUID}/results or found (with all your other jobs) on the “My Jobs” tab in the IonQ Quantum Cloud application.

"My Jobs" in the IonQ Cloud Console

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, our resource center includes 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.