​
Introduction

This guide covers how to use IonQ’s native gates in Cirq. To learn more about what the native gates are and when to use them, refer to our guide on getting started with 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 Cirq, we recommend reviewing our guides on Getting Started with Native Gates and Getting Started with Cirq. Native gates are also supported in the IonQ API, Qiskit, and PennyLane.
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.

​
Building a circuit with native gates

IonQ’s native gates are provided as part of the cirq-ionq package, including:
  • GPIGate(phi)
  • GPI2Gate(phi)
  • MSGate(phi0, phi1, theta=0.25) for Aria systems
The ZZ two-qubit gate used on our Forte systems is currently not available in cirq-ionq. To use this type of native gate, build and submit circuits via the IonQ API or Qiskit. The native gates can be imported from cirq_ionq.ionq_native_gates:
Import circuit and gate definitions
import cirq
import cirq_ionq
from cirq_ionq.ionq_native_gates import GPIGate, GPI2Gate, MSGate
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 gates are used like other gates when building a circuit:
Build a circuit using native gates
# Initialize the quantum circuit
q0, q1, q2 = cirq.LineQubit.range(3)

# Define gates (with parameter values in turns) and build the circuit
gpi = GPIGate(phi=0.5).on(q0)
gpi2 = GPI2Gate(phi=0.5).on(q1)
ms = MSGate(phi0=0, phi1=0.5).on(q1, q2)
meas = cirq.measure(q0, q1, q2, key='output')
circuit = cirq.Circuit([gpi, gpi2, ms, meas])

print(circuit)

0: ---GPI(0.5)--------------M('output')---
                            │
1: ---GPI2(0.5)---MS(0)-----M-------------
                  │         │
2: ---------------MS(0.5)---M-------------
Note that Cirq also defines an MS gate in cirq.MSGate, but this gate is not equivalent to the IonQ native gates. To build a circuit in IonQ native gates, make sure you’re using the MS gate imported from cirq_ionq.

​
Submitting a circuit with native gates

No changes or special arguments are needed to submit a native gate circuit to a cirq_ionq.Service—the gateset will be detected automatically.
Submit a circuit
service = cirq_ionq.Service(api_key=YOUR_API_KEY)
result = service.run(
    circuit=circuit,
    repetitions=1024,
    target="simulator",
    name="Native gates in Cirq"
)
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.

​
Transpiling a circuit to native gates

As of November 2024, conversion to native gates using Cirq’s transpiler is supported in the latest pre-release/development version of Cirq. You can install this version with pip install cirq~=1.0.dev. This capability should be included in the next full release after version 1.4.1. Start by constructing a circuit using abstract (QIS) gates:
Build a circuit
import cirq

q0, q1 = cirq.LineQubit.range(2)
circuit_abstract = cirq.Circuit(
    cirq.H(q0),
    cirq.CNOT(q0, q1),
    cirq.measure(q0, q1, key='x') 
)

print(circuit_abstract)
Here’s our basic example circuit: 
0: ---H---@---M('x')---
          |   |
1: -------X---M--------
To convert this circuit to IonQ’s native gates, first import one of IonQ’s native gatesets from cirq_ionq, then use cirq.optimize_for_target_gateset().
Transpile to native gates
from cirq_ionq.ionq_native_target_gateset import AriaNativeGateset

circuit_aria = cirq.optimize_for_target_gateset(
    circuit_abstract,
    gateset=AriaNativeGateset()
)

print(circuit_aria)
The circuit is now a sequence of GPI2, GPI, and MS gates. Note that these gate parameters are also in turns rather than radians (where one turn is 2π radians). 
0: ---GPI2(0.0)---GPI(-0.125)---GPI2(0.5)---GPI2(0.5)---GPI(0.125)---GPI2(0.5)---MS(0)---GPI2(0.0)----GPI(0.0)------GPI2(0.75)---M('x')---
                                                                                 │                                               │
1: -----------------------------------------GPI2(0.0)---GPI(0.0)-----GPI2(0.5)---MS(0)---GPI2(0.25)---GPI(-0.125)---GPI2(0.25)---M---------
This circuit can be submitted to an IonQ backend (simulator or Aria) as shown above.
Submit the circuit
import cirq_ionq
service = cirq_ionq.Service(api_key=YOUR_API_KEY)

result = service.run(
    circuit=circuit_aria,
    repetitions=1024,
    target="simulator",
    name="Native gates in Cirq"
)
Support for transpilation to Forte’s gateset via Cirq is in progress.

​
Additional resources

Please reach out to [email protected] or the IonQ Slack Community if you have questions about our native gates and transpilation, or if you have requests for additional features and capabilities!