Skip to main content
On error-corrected hardware you don’t run gates directly on physical qubits. Each logical qubit is a patch of many physical qubits protected by a surface code, and every logical operation is carried out as a lattice-surgery procedure: patches merge, interact, and split across repeated rounds of stabilizer measurement to realize the gate. Routing is the step that turns your logical circuit into this concrete, fault-tolerant execution plan: route_circuit works out where and when each operation happens on the surface-code lattice.

​
What routing produces

The plan lives on a 3-D lattice:
  • the two spatial axes are the grid of surface-code patches — your logical qubits and the free space they use to interact;
  • the third axis is time, measured in cycles.
A cycle is one logical time step, one z-layer of the lattice. The noise model assumes each cycle spans exactly d rounds of stabilizer measurement, where d is the code distance, so a program’s runtime on hardware is roughly its cycle count × d × the device’s round time. Each operation becomes a space-time volume in this lattice. The visualization draws these as cubes connected by pipes — the pipes are the channels along which patches merge and split to carry out gates. T gates get special treatment: they consume a magic state produced by a magic-state cultivation routine, which routing schedules alongside the Clifford operations. The output is a TopologicalProgram — a complete, cycle-by-cycle layout of the circuit on the lattice, together with summary statistics. Its size (how many patches, over how many cycles) is the real cost of running the circuit fault-tolerantly, and it’s what the later stages visualize and turn into an error estimate. Finding a good layout is a hard combinatorial problem; the engine solves it pragmatically to scale to circuits well beyond what hand-routing allows.
For an interactive, visual walkthrough of the routed lattice, see the Fault Tolerance Engine overview.

​
Routing a circuit

Routing expects a transpiled Clifford+T circuit — the gate set surface codes implement natively. Build and synthesize a model as usual, then export it to OpenQASM with a FaultTolerantTranspilationConfig so the circuit is decomposed into Clifford+T, and pass the resulting QASM to route_circuit:
Keep keep_hierarchy at its default, False, when exporting for routing. With keep_hierarchy=True, the exported QASM wraps rotation approximations in custom gates such as rz_approx_0, and route_circuit rejects them with Gate 'rz_approx_0' is not supported by the router. The router accepts only the Clifford+T gates h, s, sdg, t, tdg, x, y, z, and cx.
The resulting program is a TopologicalProgram. Next, you can visualize it or estimate its total error.