How your circuit is compiled
The circuit that runs on IonQ hardware is not the one you wrote. What the compiler changes, IonQ native gates, and why your gate count moves.
The circuit that runs on IonQ hardware is not the circuit you wrote. IonQ compiles it first. A circuit submitted through the abstract gate interface has already been rewritten by the time it reaches the hardware, and the rewrite is sometimes considerable.
Two consequences follow. The gate count you wrote is not the one submitted, and a circuit that looks small in your editor can still exceed a backend's limits.
What the compiler changes
Three transformations happen between pressing Run and the circuit executing:
- Multi-qubit gates are decomposed into two-qubit operations. A three-qubit gate does not exist on the hardware, so it becomes a sequence of two-qubit ones.
- Standard gates are converted to native equivalents.
RX,RY,RZandCNOTare all abstractions. Each is rewritten into the gates the machine physically performs. - Redundancy is removed, then the whole thing is optimised again. Extraneous gates are optimised away or commuted into different places, then transpiled into native gates using special heuristics and optimised again. The sequence repeats rather than running once.
The first two usually grow the circuit. The third shrinks it. Which effect wins depends on what you wrote.
IonQ's native gates
Native gates are the ones IonQ hardware physically executes, by addressing ions with resonant lasers via stimulated Raman transitions. Everything else is a convenience that compiles down to these.
| Gate | What it is | Systems |
|---|---|---|
GPi | A π rotation with an embedded phase | Aria and Forte |
GPi2 | A π/2 rotation with an embedded phase | Aria and Forte |
| Virtual Z | Phase propagation, not a physical operation | Aria and Forte |
MS | Møller-Sørensen, the two-qubit entangling gate | Aria |
ZZ | The two-qubit entangling gate | Forte |
Qollab's IonQ hardware backends are Forte 1 and Forte Enterprise 1, so ZZ is the entangler behind your hardware runs. The Aria rows apply when you pick an Aria noise-model simulator from the Select QPU dialog.
Virtual Z is the one worth remembering. The hardware has no true Z gate at all. A Virtual Z advances or retards the phase of the following operation instead, which removes the RZ gate by folding its angle into the phase parameters of the gates that come after it. So it costs no physical gate on the machine, and a circuit heavy in Z rotations can compile smaller than its written gate count suggests.
Why your gate count changed
Because the submitted circuit is a rewrite, the number in your editor is not what the backend counts against its limits. This is the mechanism behind two entries in the Error reference: TooManyGates fires on the compiled count, not the written one, and UnsupportedGate means a gate survived to submission that the target does not accept.
The quieter version of the same effect is more common. More gates means more opportunity for error, so a circuit that compiles larger comes back noisier without failing at all. See Why your results look wrong.
Why a local transpile does not match
Running Qiskit's transpile() yourself shows you a version of this, and it is worth doing because it costs nothing and submits no job. It will not match what runs.
IonQ compiles again on its own side after you submit, and those steps are proprietary transformations you cannot inspect. So treat a local transpile as a lower bound on the gate count rather than a transcript of the run.
Should you write native gates yourself
Usually not. IonQ recommends reaching for native gates only when the abstract interface cannot do what you need: when you have to know exactly which circuit ran, or when you specifically want a circuit that is not optimised.
The examples IonQ gives are research work: investigating and characterising noise, designing noise-aware circuits, exploring new error mitigation techniques, and developing or testing methods for circuit optimisation and compilation.
For anything else, including a hackathon project, the abstract interface is the better choice. IonQ's own position is that if the goal is simply to run a quantum circuit for evaluation or algorithm investigation, native gates will often give lower-quality output than the abstract gate interface.
Native gates also switch things off. Submitting in native gates is currently the only way to bypass IonQ's compiler and optimiser, and it turns error mitigation off by default too, though debiasing can be turned back on. See Error mitigation and debiasing.
One more constraint: a circuit has to use one gateset throughout. You cannot mix native gates and abstract gates in the same circuit.
Related
Gate descriptions and compiler behaviour on this page are from IonQ's native gates guide, the source of truth. Crawled 2026-09-09.
Stay in the loop.
Get the latest tutorials, demos, and project showcases straight to your inbox. No noise, just the good stuff.