This guide covers how to use IonQ’s native gates via our API. 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, we recommend reviewing our guides on Getting Started with Native Gates and Writing Quantum Programs. Native gates are also supported in Qiskit, Cirq, PennyLane, and qBraid.

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.

​
Native gate JSON specification

If you have used our abstract gate specification, the native gate specification should feel quite familiar. Its parameters are slightly different though, and we’ll walk through them here.

To specify a circuit using native gates, you must do two things:

  1. Set the parameter gateset to "native" inside the circuit body. This is an optional parameter that defaults to "qis", which signifies our abstract gateset based on the general-purpose gates of quantum information science (QIS).

  2. Your circuit array must only use native gates. These are formatted similar to QIS gates. The only gates allowed in a native gate circuit are gpi, gpi2, and either ms or zz depending on the backend. You cannot mix and match native and abstract gates in the same circuit.

Much more detailed information about the native gate definitions can be found in our native gates guide

​
Parameters

Available parameters (depending on gate type) are:

  • gate: a string representation of the gate name. This works just like the abstract gate interface, but you can only use the available native gates: gpi, gpi2, ms, and zz. If you submit any other gates in the array, you’ll receive an error.

  • phase or phases: a number representation of the phase parameter or parameters in the gate. It is represented in turns, where one turn is 2π radians. We accept floating point values between -1 and 1 for this parameter.

  • angle: an optional number representation of the angle parameter, available for the MS gate only. This value is also represented in turns and can range from 0 to 0.25 (fully entangling), with 0.25 being the default.

  • target or targets: the number index (starting from zero) of the qubit to apply the gate to. For two-qubit gates, use an array of qubit indices labeled targets instead.

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

​
Gates

GateDescriptionParameters
gpiGPI gatephase, target
gpi2GPI2 gatephase, target
msMølmer–Sørensen gate (only on Aria systems)phases, angle (optional), targets
zzZZ gate (only on Forte systems)angle, targets

​
Basic example

Here’s a simple example circuit using native gates with the IonQ API.

{
  "name": "Hello native gates!",
  "shots": 1024,
  "target": "simulator",
  "input": {
    "gateset": "native",
    "qubits": 2,
    "circuit": [
      {
        "gate": "ms",
        "targets": [0, 1],
        "phases": [0, 0]
      },
      {
        "gate": "gpi",
        "phase": 0,
        "target": 0
      },
      {
        "gate": "gpi2",
        "phase": 0,
        "target": 1
      }
    ]
  }
}

Like any other API job, you can save this to a file, like native_gates_circuit.json, and submit it:

curl -X POST "https://api.ionq.co/v0.3/jobs" \
    -H "Authorization: apiKey $IONQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d @native_gates_circuit.json

​
Additional resources