Using native gates with the IonQ API
Learn how to use our hardware-native gateset to run a circuit 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:
-
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). -
Your
circuit
array must only use native gates. These are formatted similar to QIS gates. The only gates allowed in a native gate circuit aregpi
,gpi2
, and eitherms
orzz
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
, andzz
. If you submit any other gates in the array, you’ll receive an error. -
phase
orphases
: 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
ortargets
: the number index (starting from zero) of the qubit to apply the gate to. For two-qubit gates, use an array of qubit indices labeledtargets
instead.
Gates
Gate | Description | Parameters |
---|---|---|
gpi | GPI gate | phase , target |
gpi2 | GPI2 gate | phase , target |
ms | Mølmer–Sørensen gate (only on Aria systems) | phases , angle (optional), targets |
zz | ZZ 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
- Direct API submission
- API reference for POST /jobs
- Writing quantum programs
- Getting started with native gates
- Using native gates with Qiskit, Cirq, and PennyLane
Was this page helpful?