Using native gates with the IonQ API

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, and PennyLane.

​

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.

​

Gates

​

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

• Direct API submission
• API reference for POST /jobs
• Writing quantum programs
• Getting started with native gates
• Using native gates with Qiskit, Cirq, and PennyLane