Introduction
Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device, and optimize the circuit instructions for execution on noisy quantum systems. This documentation covers the tooling and workflows for local transpilation available to all Qiskit users, as well as for the cloud-based Qiskit transpiler service available to Premium Plan users. If you're using primitives and are only interested in the default transpilation options provided by the Qiskit Runtime service, read the Configure runtime compilation for Qiskit Runtime topic.
A central component of Qiskit, the transpiler is designed for modularity and extensibility. Its central goal is to write new circuit transformations (known as transpiler passes), and combine them with other existing passes, greatly reducing the depth and complexity of quantum circuits. Which passes are chained together and in which order has a major effect on the final outcome. This pipeline is determined by the PassManager
and StagedPassManager
objects. The StagedPassManager
orchestrates the execution of one or more PassManagers
and determines the order in which they are executed, while the PassManager
object is merely a collection of one or more passes. Think of the StagedPassManager
as the conductor in an orchestra, the PassManagers
as the different instrument sections, and the Pass
es as the individual musicians. In this way, you can compose hardware-efficient quantum circuits that let you execute utility-scale work while keeping noise manageable.
Find more information about the pass manager stages in the Transpiler stages topic.
If you perform transpilation locally and submit the transpiled circuits to the Qiskit Runtime service, set the skip_transpilation
option to True
so that the service does not try to apply further transformations to your circuit. See Advanced runtime compilation options.
Transpiler stages
Qiskit's prebuilt transpiler pipeline consists of six fundamental stages:
init
- This pass runs any initial passes that are required before we start embedding the circuit to the backend. This typically involves unrolling custom instructions and converting the circuit to all single- and two-qubit gates. (By default this will just validate the circuit instructions and translate multi-qubit gates into single- and two-qubit gates.)layout
- This pass applies a layout, mapping/assigning the virtual qubits in your circuit to the physical qubits of a backend.routing
- This pass runs after a layout has been applied and will inject gates (i.e., SWAPs) in the original circuit in order to make it compatible with the backend's connectivity/coupling map.translation
- This pass translates the gates in the circuit to the backend's basis set of instructions.optimization
- This pass runs an optimization loop to find more efficient decompositions of your quantum circuit until a condition is met (such as a fixed depth).scheduling
- This stage is for any hardware-aware scheduling passes. If the user specifies a scheduling method, this stage accounts for all idle time in the circuit.
If you decide to customize your own transpilation workflow, we suggest using these stages as a guideline during development.
Transpile with pass managers
The recommended way to transpile a circuit is to create a staged pass manager and then execute its run
method with your circuit as input. You can use the generate_preset_pass_manager
function to generate a staged pass manager with reasonable defaults.
More advanced users can customize a set of PassManager
and StagedPassManager
objects and determine the order in which each stage is run. This can dramatically change the final output circuit. In fact, a custom approach to transpiling a quantum algorithm often produces more efficient error suppression than the default approach. This involves rewriting quantum circuits to match hardware constraints and suppress the effects of noise. The flow of logic for this tool chain is quite customizable and need not be linear. The transpilation process can even prepare iterative loops, conditional branches, and other complex behaviors. A good starting place when developing a set of custom passes is to examine the default sequence of transformations.
For an overview of transpiling using pass managers, see Transpile with pass managers.
Default transpilation
For a simpler , but less customizable, "out-of-the-box" way to use the transpiler, use the qiskit.compiler.transpile
function. This generates and runs one of the preset StagedPassManager
s based on, among other options, an optimization_level
flag that can be set to 0, 1, 2, or 3. Higher levels generate more optimized circuits, at the expense of longer transpilation times.
Next steps
- To learn how to use the
transpile
function, start with the Transpilation default settings and configuration options topic. - Continue learning about transpilation with the Transpiler stages topic.
- Try the Submit transpiled circuits (opens in a new tab) tutorial.
- Use transpilation with Qiskit Patterns in the Reduce transpiled circuit depth, with circuit cutting (opens in a new tab) tutorial.
- Try an end-to-end example that uses transpiled circuits in the Variational quantum eigensolver (VQE) (opens in a new tab) tutorial.
- See the Transpile API documentation. (opens in a new tab)