> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using native gates with Cirq

> Learn how to use our hardware-native gateset to run a circuit with Cirq

## Introduction

<Info>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](/guides/getting-started-with-native-gates).</Info>

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](/guides/getting-started-with-native-gates) and [Getting Started with Cirq](/sdks/cirq/index). Native gates are also supported in the [IonQ API](/api-reference/v0.3/native-gates-api), [Qiskit](/sdks/qiskit/native-gates-qiskit), and [PennyLane](/sdks/pennylane/native-gates-pennylane).

<Warning>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.</Warning>

***

## 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 (retired)

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](/api-reference/v0.3/native-gates-api) or [Qiskit](/sdks/qiskit/native-gates-qiskit).

The native gates can be imported from `cirq_ionq.ionq_native_gates`:

```python Import circuit and gate definitions theme={null}
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](/guides/getting-started-with-native-gates#introducing-the-native-gates).

<Tip>The parameters in the IonQ native gate specification are always defined in *turns*, not in radians. One turn is 2π radians.</Tip>

Native gates are used like other gates when building a circuit:

```python Build a circuit using native gates theme={null}
# 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)
```

```python theme={null}
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.

```python Submit a circuit theme={null}
service = cirq_ionq.Service(api_key=YOUR_API_KEY)
result = service.run(
    circuit=circuit,
    repetitions=1024,
    target="simulator",
    name="Native gates in Cirq"
)
```

<Tip>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.</Tip>

***

## 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:

```python Build a circuit theme={null}
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:

```python theme={null}
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()`.

```python Transpile to native gates theme={null}
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).

```python theme={null}
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 including with Aria noise model) as shown above.

```python Submit the circuit theme={null}
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

* [Getting Started with Native Gates](/guides/getting-started-with-native-gates)
* [Getting Started with Cirq](/sdks/cirq/index)

Please reach out to [support@ionq.co](mailto:support@ionq.co) 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!