Getting started with IonQ and Cirq on Azure Quantum

View on QuantumAI Run in Google Colab View source on GitHub Download notebook

This notebooks shows how to send a basic quantum circuit to an IonQ target via Azure Quantum.


  • To work in Azure Quantum, you need an Azure subscription. If you don't have an Azure subscription, create a free account.
  • Create an Azure Quantum workspace and enable IonQ. For more information, see Create an Azure Quantum workspace.

First, install azure-quantum with the Cirq dependencies:

pip install 'azure-quantum[cirq]' --quiet

Connecting to the Azure Quantum service

To connect to the Azure Quantum service, find the resource ID and location of your Workspace from the Azure Quantum portal here: Navigate to your Azure Quantum workspace and copy the values from the header.

Paste the values into the AzureQuantumService constructor below to create a service that connects to your Azure Quantum Workspace. Optionally, specify a default target:

from azure.quantum.cirq import AzureQuantumService
service = AzureQuantumService(

List all IonQ targets

You can now list all the targets that you have access to, including the current queue time and availability. To only return the IonQ provider's targets, you can specify the optional provider_id input argument:

[<Target name="ionq.qpu", avg. queue time=19 s, Available>,
 <Target name="ionq.simulator", avg. queue time=0 s, Available>

To read more about the Simulator and QPU specifications such as number of qubits, connectivity, system time scales and fidelities, you can check out the IonQ Provider Reference.

Run a simple circuit

Let's create a simple Cirq circuit to run. This circuit uses the square root of X gate, native to the IonQ hardware system.

import cirq

q0, q1 = cirq.LineQubit.range(2)
circuit = cirq.Circuit(
    cirq.X(q0)**0.5,             # Square root of X
    cirq.CX(q0, q1),              # CNOT
    cirq.measure(q0, q1, key='b') # Measure both qubits

You can now run the program via the Azure Quantum service and get the result. The following cell will submit a job that runs the circuit with 100 repetitions, wait until the job is completed and return the results.

result =, repetitions=100)

This returns a cirq.Result object.

b=0001101010110000111010001110010111010001101010001111100011100001111100101011101101001000001000011000, 0001101010110000111010001110010111010001101010001111100011100001111100101011101101001000001000011000

Run on IonQ QPU

Note: The time required to run a circuit on the QPU may vary depending on current queue times.

The previous job ran on the default simulator you specified, "ionq.simulator". To run on the QPU, provide "ionq.qpu" as the target argument:

result =
    timeout_seconds=500 # Set timeout to 500 seconds to accommodate current queue time on QPU

Again, this returns a cirq.Result object.

b=0101011011011111100001011101101011011110100010000000011110111000100100110110101100110001001111101111, 0101011011011111100001011101101011011110100010000000011110111000100100110110101100110001001111101111

Asynchronous model using Jobs

For long-running circuits, it can be useful to run them asynchronously. The service.create_job method returns a Job, which you can use to get the results after the job has run successfully.

job = service.create_job(

To check on the job status, use job.status():


To wait for the job to be done and get the results, use the blocking call job.results():

result = job.results()
00: 0.5
11: 0.5

This returns a SimulatorResult object that contains the state probabilities to represent the output. For instance, in the example above, you measure either "00" or "11". To get the probabilities for each bit string, use the .probabilities() method. This returns a dictionary where the keys are the classical register values:

{0: 0.5, 3: 0.5}

To convert this to a cirq.Result object, use result.to_cirq_result():

b=1101000111010101101001011100001111101110011000100111101000010100101000001100010010011010111010011101, 1101000111010101101001011100001111101110011000100111101000010100101000001100010010011010111010011101