Transpiler

qiskit.transpiler

Overview

Transpilation is the process of rewriting a given input circuit to match the topology of a specific quantum device, and/or to optimize the circuit for execution on present day noisy quantum systems.

Most circuits must undergo a series of transformations that make them compatible with a given target device, and optimize them to reduce the effects of noise on the resulting outcomes. Rewriting quantum circuits to match hardware constraints and optimizing for performance can be far from trivial. The flow of logic in the rewriting tool chain need not be linear, and can often have iterative sub-loops, conditional branches, and other complex behaviors. That being said, the standard compilation flow follows the structure given below:

Qiskit uses the graph-based DAGCircuit intermediate representation (IR) of a circuit throughout the transpiler stack, rather than the tree-based QuantumCircuit. A transpiler pipeline is a PassManager object, whose PassManager.run() method takes in a QuantumCircuit and converts it to a DAGCircuit, then subjects the IR to a sequence of passes, finally returning a QuantumCircuit back. A pass is either an AnalysisPass, which calculates and stores properties about the circuit in the stateful PropertySet, or a TransformationPass, which modifies the IR to achieve a particular singular goal. You can think of a pipeline as being split into “stages”, where each stage is responsible for one high-level transformation.

Qiskit exposes a default transpilation pipeline builder using the function generate_preset_pass_manager(). This returns a properly configured pipeline for complete transpilation, at a chosen optimization_level (between 0 and 3, inclusive). Unless you are looking for something highly specialized, this is almost certainly the entry point you want. A sample transpilation looks like:

from qiskit.circuit import QuantumCircuit
from qiskit.transpiler import generate_preset_pass_manager
from qiskit_ibm_runtime import QiskitRuntimeService
 
# Any abstract circuit you want:
abstract = QuantumCircuit(2)
abstract.h(0)
abstract.cx(0, 1)
 
# Any method you like to retrieve the backend you want to run on:
backend = QiskitRuntimeService().backend("some-backend")
 
# Create the pass manager for the transpilation ...
pm = generate_preset_pass_manager(backend=backend)
# ... and use it (as many times as you like).
physical = pm.run(abstract)

For most use cases, this is all you need. All of Qiskit’s transpiler infrastructure is highly extensible and configurable, however. The rest of this page details how to harness the low-level capabilities of the transpiler stack.

Preset pass managers

The function generate_preset_pass_manager() creates the “preset pass managers”. These are all instances of PassManager, so are used by passing a QuantumCircuit to the PassManager.run() method. More specifically, the preset pass managers are instances of StagedPassManager, which allows greater configuration of the individual stages of a transpilation, including pre- and post-stage hooks.

A preset pass manager has up to six named stages. These are summarized, in order of execution, below, with more in-depth information in the following subsections.

init

Abstract-circuit optimizations, and reduction of multi-qubit operations to one- and two-qubit operations. See Initialization stage for more details.

layout

Choose an initial mapping of virtual qubits to physical qubits, including expansion of the circuit to contain explicit ancillas. This stage sometimes subsumes routing. See Layout stage for more details.

routing

Insert gates into the circuit to ensure it matches the connectivity constraints of the Target. The inserted gates need not match the target ISA yet, so are often just swap instructions. This stage is sometimes omitted, when the layout stage handles its job. See Routing stage for more details.

translation

Convert all gates in the circuit to ones matching the ISA of the Target. See Translation stage for more details.

optimization

Low-level, hardware-aware optimizations. Unlike the abstract optimizations of the init stage, this stage acts on a physical circuit. See Optimization stage for more details.

scheduling

Insert Delay instructions to make the wall-clock timing of a circuit explicit. This may also include hardware-aware online error reduction techniques such as dynamical decoupling, which are dependent on knowing wall-clock timings. See Scheduling stage for more details.

The preset transpiler pipelines can also be configured at a high level by setting an optimization_level. This is an integer from 0 to 3, inclusive, indicating the relative effort to exert in attempting to optimize the circuit for the hardware. Level 0 disables all unnecessary optimizations; only transformations needed to make the circuit runnable are used. On the other end, level 3 enables a full range of optimization techniques, some of which can be very expensive in compilation time. Similar to classical compilers, optimization level 3 is not always guaranteed to produce the best results. Qiskit defaults to optimization level 2, as a trade-off between compilation time and the expected amount of optimization.

The optimization level affects which implementations are used for a given stage by default, though this can be overridden by passing explicit <stage>_method="<choice>" arguments to generate_preset_pass_manager().

Choosing preset stage implementations

Qiskit includes several implementations of the above stages, and more can be installed as separate “plugins”. To control which implementation of a stage is used, pass its name to the <stage>_method keyword argument of the two functions, such as translation_method="translator". To read more about implementing such external plugins for a stage, see qiskit.transpiler.preset_passmanagers.plugin.

For example, to generate a preset pass manager at optimization level 1 that explicitly uses the trivial method for layout with the sabre method for routing, we would do:

from qiskit.transpiler import generate_preset_pass_manager
from qiskit.providers.fake_provider import GenericBackendV2
 
# Whatever backend you like:
backend = GenericBackendV2(num_qubits=5)
 
pass_manager = generate_preset_pass_manager(
    optimization_level=1,
    backend=backend,
    layout_method="trivial",
    routing_method="sabre",
)

Since the output of generate_preset_pass_manager() is a StagedPassManager, you can also modify the pass manager after its creation to provide an entirely custom stage implementation. For example, if you wanted to run a custom scheduling stage using dynamical decoupling (using the PadDynamicalDecoupling pass) and also add initial logical optimization prior to routing, you would do something like the following (building off the previous example):

import numpy as np
from qiskit.providers.fake_provider import GenericBackendV2
from qiskit.circuit import library as lib
from qiskit.transpiler import PassManager, generate_preset_pass_manager
from qiskit.transpiler.passes import (
    ALAPScheduleAnalysis,
    CXCancellation,
    InverseCancellation,
    PadDynamicalDecoupling,
)
 
backend = GenericBackendV2(num_qubits=5)
dd_sequence = [lib.XGate(), lib.XGate()]
scheduling_pm = PassManager(
    [
        ALAPScheduleAnalysis(target=backend.target),
        PadDynamicalDecoupling(target=backend.target, dd_sequence=dd_sequence),
    ]
)
inverse_gate_list = [
    lib.CXGate(),
    lib.HGate(),
    (lib.RXGate(np.pi / 4), lib.RXGate(-np.pi / 4)),
    (lib.PhaseGate(np.pi / 4), lib.PhaseGate(-np.pi / 4)),
    (lib.TGate(), lib.TdgGate()),
]
logical_opt = PassManager([InverseCancellation(inverse_gate_list)])
 
pass_manager = generate_preset_pass_manager(optimization_level=0)
# Add pre-layout stage to run extra logical optimization
pass_manager.pre_layout = logical_opt
# Set scheduling stage to custom pass manager
pass_manager.scheduling = scheduling_pm

Now, when the staged pass manager is run via the run() method, the logical_opt pass manager will be called before the layout stage, and the scheduling_pm pass manager will be used for the scheduling stage instead of the default.

If you are constructing custom stages for the preset pass managers, you may find some of the low-level helper functions in qiskit.transpiler.preset_passmanagers useful.

Initialization stage

The init stage is responsible for high-level, logical optimizations on abstract circuits, and for lowering multi-qubit (3+) operations down to a series of one- and two-qubit operations. As this is the first stage run, its input is a fully abstract circuit. The init stage must be able to handle custom user-defined gates, and all the high-level abstract circuit-description objects, such as AnnotatedOperation.

The output of the init stage is an abstract circuit that contains only one- and two-qubit operations.

When writing stage plugins, the entry point for init is qiskit.transpiler.init. The built-in plugins are:

Built-in default plugin

At optimization level 0, no abstract optimization is done. The default plugin simply “unrolls” operations with more than three qubits by accessing their hierarchical definition fields.

At optimization levels 1 and above, the default plugin also does simple cancellation of adjacent inverse gates, such as two back-to-back cx gates.

At optimization levels 2 and 3, the default plugin enables a much wider range of abstract optimizations. This includes:

• “Virtual permutation elision” (see ElidePermutations), where explicit permutation-inducing operations are removed and instead effected as remapping of virtual qubits.
• Analysis of the commutation structure of the IR to find pairs of gates that can be canceled out.
• Numerical splitting of two-qubit operations that can be expressed as a series of separable one-qubit operations.
• Removal of imperceivable operations, such as tiny-angle Pauli rotations and diagonal operations immediately preceding measurements.

Layout stage

The layout stage is responsible for making an initial mapping between the virtual qubits of the input circuit, and the hardware qubits of the target. This includes expanding the input circuit with explicit ancillas so it has as many qubits as the target has, and rewriting all operations in terms of hardware qubits. You may also see this problem called the “placement” problem in other toolkits or literature.

The layout stage must set the properties layout and original_qubit_indices in the pipeline’s PropertySet.

At any given point in a circuit, we can identify a mapping between currently active “virtual” qubits of the input circuit to hardware qubits of the backend. A hardware qubit can only ever represent a single virtual qubit at a given point, but the mapping might vary over the course of the circuit. In principle, some virtual qubits might not be mapped at all points in the circuit execution, if the lifetime of a virtual qubit state can be shortened, though Qiskit’s built-in pipelines do not use this currently.

The layout stage is not responsible for ensuring that the connectivity of the target is respected all the way through the circuit, nor that all operations are valid for direct execution on the target; these are the responsibilities of the routing and translation stages, respectively.

The choice of initial layout is one of the most important factors that affects the quality of the output circuit. The layout stage is often the most computationally expensive stage in the default pipelines; the default plugin for layout even tries several different algorithms (described in more detail in Built-in default plugin).

The ideal situation for the layout stage is to find a “perfect” layout, where all operations respect the connectivity constraints of the Target such that the routing stage is not required. This is typically not possible for arbitrary input circuits, but when it is, the VF2Layout pass can be used to find a valid initial layout. If multiple perfect layouts are found, a scoring heuristic based on estimated error rates is used to decide which one to use.

In all built-in plugins, passing the generate_preset_pass_manager() argument initial_layout causes the given layout to be used verbatim, skipping the individual “choosing” logic. All built-in plugins also handle embedding the circuit into the full width of the device, including assigning ancillas.

If you write your own layout plugin, you might find generate_embed_passmanager() useful for automating the “embedding” stage of the layout application.

When writing stage plugins, the entry point for layout is qiskit.transpiler.layout. The built-in plugins are:

At all optimization levels, the default layout method is default, though the structure of this stage changes dramatically based on the level.

Built-in default plugin

An amalgamation of several different layout techniques.

At optimization level 0, the trivial layout is chosen.

At optimization levels above 0, there is a two-step process:

1. First, use VF2Layout to attempt to find a “perfect” layout. The maximum number of calls to the isomorphism evaluator increases with the optimization level. For huge, complex targets, we are not guaranteed to find perfect layouts even if they exist, but the chance increases with the optimization level.
2. If no perfect layout can be found, use SabreLayout to choose an initial layout, with the numbers of initial layout trials, swap-map trials, and forwards–backwards iterations increasing with the optimization level.

In addition, optimization level 1 also tries the trivial layout before the VF2-based version, for historical backwards compatibility.

Built-in dense plugin

Uses the DenseLayout pass to choose the layout. This pass finds the densest connected subgraph of the complete target connectivity graph, where “densest” means that hardware qubits with the greatest number of available connections are preferred. The virtual-to-hardware mapping is completed by assigning the highest-degree virtual qubits to the highest-degree hardware qubits.

This is a relatively cheap heuristic for choosing an initial layout, but typically has far worse output quality than Sabre-based methods. The default layout plugin uses the initial mapping selected by DenseLayout as one of its initial layouts to seed the Sabre algorithm.

Built-in trivial plugin

Uses the TrivialLayout pass to choose the layout. This is the simplest assignment, where each virtual qubit is assigned to the hardware qubit with the same index, so virtual qubit 0 is mapped to hardware qubit 0, and so on.

This method is most useful for hardware-characterization experiments, where the incoming “abstract” circuit is already full-width on the device, its operations correspond to physical operations, and the transpiler is just being invoked to formalize the creation of a physical QuantumCircuit.

Built-in sabre plugin

Uses the SabreLayout to choose an initial layout, using Qiskit’s modified Sabre routing algorithm as the subroutine to swap-map the candidate circuit both forwards and backwards.

Summarily, the layout component of the original Sabre algorithm chooses an initial layout arbitrarily, then tries to “improve” it by running routing on the circuit, reversing the circuit, and running routing on the reversed circuit with the previous “final” virtual-to-hardware assignment as the initial state. The configured optimization level decides how many iterations of this to-and-fro to do, and how many different random initial layouts to try.

The principal difference to the default stage at optimization levels other than 0 is that this plugin only runs the Sabre-based algorithm. It does not attempt to find a perfect layout, nor attempt the trivial layout.

Routing stage

The routing stage ensures that the virtual connectivity graph of the circuit is compatible with the hardware connectivity graph of the target. In simpler terms, the routing stage makes sure that all two-qubit gates in the circuit are mapped to hardware qubits that have a defined two-qubit operation in the target ISA. You may also see this problem referred to as the “mapping” or “swap-mapping” problem in other toolkits or literature.

Routing algorithms typically do this by inserting swap gates into the circuit, and modifying the virtual-to-hardware mapping of qubits over the course of the circuit execution.

The routing stage does not need to ensure that all the gates in the circuit are valid for the target ISA. For example, a routing plugin can leave literal swap gates in the circuit, even if the Target does not contain SwapGate. However, there must be at least one two-qubit gate defined in the Target for any pair of hardware qubits that has a gate applied in the circuit.

The routing stage must set the final_layout and virtual_permutation_layout properties in the PropertySet if routing has taken place.

All of Qiskit’s built-in routing stages will additionally run the VF2PostLayout pass after routing. This might reassign the initial layout, if lower-error qubits can be found. This pass is very similar to the VF2Layout class that the default layout plugin uses, except in VF2PostLayout we can guarantee that there is at least one isomorphic induced subgraph of the target topology that matches the circuit topology.

When writing stage plugins, the entry point for routing is qiskit.transpiler.routing. The built-in plugins are:

Built-in none plugin

A dummy plugin used to disable routing entirely. This can occasionally be useful for hardware-configuration experiments, or in certain special cases of partial compilation.

Built-in basic plugin

Uses the BasisSwap greedy swap-insertion algorithm. This is conceptually very simple; for each operation in topological order, insert the shortest-path swaps needed to make the connection executable on the device.

The optimization level only affects the amount of work the VF2PostLayout step does to attempt to improve the initial layout after routing.

This method typically has poor output quality.

Built-in stochastic plugin

Uses the StochasticSwap algorithm to route. In short, this stratifies the circuit into layers, then uses a stochastic algorithm to find a permutation that will allow the layer to execute, and a series of swaps that will implement that permutation in a hardware-valid way.

The optimization level affects the number of stochastic trials used for each layer, and the amount of work spent in VF2PostLayout to optimize the initial layout.

This was Qiskit’s primary routing algorithm for several years, until approximately 2021. Now, it is reliably beaten in runtime and output quality by Qiskit’s custom Sabre-based routing algorithm.

Built-in lookahead plugin

Uses the LookaheadSwap algorithm to route. This is essentially a breadth-first search at producing a swap network, where the tree being explored is pruned down to a small number of candidate swaps at each depth.

This algorithm is similar to the basic heuristic of the “sabre” plugin, except it considers the following effects of each swap to a small depth as well.

The optimization level affects the search depth, the amount of per-depth pruning, and amount of work done by VF2PostLayout to post-optimize the initial layout.

In practice, the “sabre” plugin runs several orders of magnitude faster, and produces better output.

Built-in sabre plugin

Uses the SabreSwap algorithm to route. This uses Qiskit’s enhanced version of the original Sabre routing algorithm.

This routing algorithm runs with threaded parallelism to consider several different possibilities for routing, choosing the one that minimizes the number of inserted swaps.

The optimization level affects how many different stochastic seeds are attempted for the full routing, and the amount of work done by VF2PostLayout to post-optimize the initial layout.

This is almost invariably the best-performing built-in plugin, and the one Qiskit uses by default in all cases where routing is necessary.

Translation stage

The translation stage is responsible for rewriting all gates in the circuit into ones that are supported by the target ISA. For example, if a cx is requested on hardware qubits 0 and 1, but the ISA only contains a cz operation on those qubits, the translation stage must find a way of representing the cx gate using the cz and available one-qubit gates.

The translation stage is called before entering the optimization stage. Optimization plugins (including Qiskit’s built-in plugins) may also use the translation stage as a “fixup” stage after the optimization loop, if the optimization loop returns a circuit that includes non-ISA gates. This latter situation is fairly common; the optimization loop may only be concerned with minimizing properties like “number of two-qubit gates”, and will leave its output in terms of locally equivalent gates, which the translation stage can easily rewrite without affecting the target optimization properties. This allows easier separation of concerns between the two stages. Some optimization plugins may be stricter in their output, and so this follow-up to the translation stage may no longer be necessary.

When writing stage plugins, the entry point for translation is qiskit.transpiler.translation. The built-in plugins are:

Built-in synthesis plugin

Collect runs of gates on the same qubits into matrix form, and then resynthesize using the UnitarySynthesis pass (with the configured unitary_synthesis_method). This is, in large part, similar to the optimization loop itself at high optimization levels.

The collection into matrices is typically more expensive than matrix-free translations, but in principle the quality of the translations can be better. In practice, this requires a synthesis algorithm tailored to the target ISA, which makes this method less general than other methods. It can produce higher-quality results when targeting simple ISAs that match the synthesis routines already in Qiskit.

If this method is used, you might not need the optimization loop.

The optimization level has no effect on this plugin.

Built-in translator plugin

Uses the BasisTranslator algorithm to symbolically translate gates into the target basis. At a high level, this starts from the set of gates requested by the circuit, and uses rules from a given EquivalenceLibrary (typically the SessionEquivalenceLibrary) to move towards the ISA.

This is the default translation method.

The optimization level has no effect on this plugin.

Optimization stage

The optimization stage is for low-level hardware-aware optimizations. Unlike the init stage, the input to this stage is a circuit that is already ISA-compatible, so a low-level optimization plugin can be tailored for a particular ISA.

There are very few requirements on an optimization plugin, other than it takes in ISA-supported circuits, and returns ISA-supported circuits. An optimization plugin will often contain a loop, such as the DoWhileController, and might include the configured translation stage as a fix-up pipeline.

Qiskit’s built-in optimization plugins are general, and apply well to most real-world ISAs for non-error-corrected devices. The built-in plugins are less well-suited to ISAs that have no continuously parametrized single-qubit gate, such as a Clifford+T basis set.

When writing stage plugins, the entry point for optimization is qiskit.transpiler.optimization. The built-in plugins are:

Built-in default plugin

This varies significantly between optimization levels.

The specifics of this pipeline are subject to change between Qiskit versions. The broad principles are described below.

At optimization level 0, the stage is empty.

At optimization level 1, the stage does matrix-based resynthesis of runs of single-qubit gates, and very simple symbolic inverse cancellation of two-qubit gates, if they appear consecutively. This runs in a loop until the size and depth of the circuit are fixed.

At optimization level 2, in addition the optimizations of level 1, the loop contains commutation analysis of sets of gates to widen the range of gates that can be considered for cancellation. Before the loop, runs of both one- and two-qubit gates undergo a single matrix-based resynthesis.

At optimization level 3, the two-qubit matrix-based resynthesis runs inside the optimization loop. The optimization loop condition also tries multiple runs and chooses the minimum point in the case of fluctuating output; this is necessary because matrix-based resynthesis is relatively unstable in terms of concrete gates.

Optimization level 3 is typically very expensive for large circuits.

Scheduling stage

The scheduling stage, if requested, is responsible for inserting explicit Delay instructions to make idle periods of qubits explicit. Plugins may optionally choose to do walltime-sensitive transformations, such as inserting dynamical decoupling sequences.

The input to the scheduling stage is an ISA-compatible circuit. The output of the scheduling stage must also be an ISA-compatible circuit, with explicit Delay instructions that satisfy the hardware’s timing information, if appropriate.

The scheduling stage should set the node_start_time property in the pipeline’s PropertySet.

When writing stage plugins, the entry point for scheduling is qiskit.transpiler.scheduling. The built-in plugins are:

Built-in default plugin

Do nothing, unless the circuit already contains instructions with explicit timings. If there are explicitly timed operations in the circuit, insert additional padding to ensure that these timings satisfy the alignment and other hardware constraints.

Builtin alap plugin

Explicitly schedule all operations using an “as late as possible” strategy. This uses the ALAPScheduleAnalysis algorithm to decide where to place gates.

Builtin asap plugin

Explicitly schedule all operations using an “as soon as possible” strategy. This uses the ASAPScheduleAnalysis algorithm to decide where to place gates.

Custom pass managers

In addition to modifying preset pass managers, it is also possible to construct a pass manager to build an entirely custom pipeline for transforming input circuits. You can use the StagedPassManager class directly to do this. You can define arbitrary stage names and populate them with a PassManager instance. For example, the following code creates a new StagedPassManager that has two stages, init and translation.

from qiskit.transpiler.passes import (
    UnitarySynthesis,
    Collect2qBlocks,
    ConsolidateBlocks,
    UnitarySynthesis,
    Unroll3qOrMore,
)
from qiskit.transpiler import PassManager, StagedPassManager
 
basis_gates = ["rx", "ry", "rxx"]
init = PassManager([UnitarySynthesis(basis_gates, min_qubits=3), Unroll3qOrMore()])
translate = PassManager(
    [
        Collect2qBlocks(),
        ConsolidateBlocks(basis_gates=basis_gates),
        UnitarySynthesis(basis_gates),
    ]
)
 
staged_pm = StagedPassManager(
    stages=["init", "translation"], init=init, translation=translate
)

There is no limit on the number of stages you can put in a StagedPassManager. The stages do not need to correspond to the stages used by Qiskit’s preset pipelines.

The Stage generator functions may be useful for the construction of custom StagedPassManager instances. They generate pass managers which provide common functionality used in many stages. For example, generate_embed_passmanager() generates a PassManager to “embed” a selected initial Layout from a layout pass to the specified target device.

Representing Quantum Computers

To be able to compile a QuantumCircuit for a specific backend, the transpiler needs a specialized representation of that backend, including its constraints, instruction set, qubit properties, and more, to be able to compile and optimize effectively. While the BackendV2 class defines an interface for querying and interacting with backends, its scope is larger than just the transpiler’s needs including managing job submission and potentially interfacing with remote services. The specific information needed by the transpiler is described by the Target class

For example, to construct a simple Target object, one can iteratively add descriptions of the instructions it supports:

from qiskit.circuit import Parameter, Measure
from qiskit.transpiler import Target, InstructionProperties
from qiskit.circuit.library import UGate, RZGate, RXGate, RYGate, CXGate, CZGate
 
target = Target(num_qubits=3)
target.add_instruction(CXGate(), {(0, 1): InstructionProperties(error=.0001, duration=5e-7)})
target.add_instruction(
    UGate(Parameter('theta'), Parameter('phi'), Parameter('lam')),
    {
        (0,): InstructionProperties(error=.00001, duration=5e-8),
        (1,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RZGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RYGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RXGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    CZGate(),
    {
        (1, 2): InstructionProperties(error=.0001, duration=5e-7),
        (2, 0): InstructionProperties(error=.0001, duration=5e-7)
    }
)
target.add_instruction(
    Measure(),
    {
        (0,): InstructionProperties(error=.001, duration=5e-5),
        (1,): InstructionProperties(error=.002, duration=6e-5),
        (2,): InstructionProperties(error=.2, duration=5e-7)
    }
)
print(target)

Target
Number of qubits: 3
Instructions:
    cx
        (0, 1):
            Duration: 5e-07 sec.
            Error Rate: 0.0001
    u
        (0,):
            Duration: 5e-08 sec.
            Error Rate: 1e-05
        (1,):
            Duration: 6e-08 sec.
            Error Rate: 2e-05
    rz
        (1,):
            Duration: 5e-08 sec.
            Error Rate: 1e-05
        (2,):
            Duration: 6e-08 sec.
            Error Rate: 2e-05
    ry
        (1,):
            Duration: 5e-08 sec.
            Error Rate: 1e-05
        (2,):
            Duration: 6e-08 sec.
            Error Rate: 2e-05
    rx
        (1,):
            Duration: 5e-08 sec.
            Error Rate: 1e-05
        (2,):
            Duration: 6e-08 sec.
            Error Rate: 2e-05
    cz
        (1, 2):
            Duration: 5e-07 sec.
            Error Rate: 0.0001
        (2, 0):
            Duration: 5e-07 sec.
            Error Rate: 0.0001
    measure
        (0,):
            Duration: 5e-05 sec.
            Error Rate: 0.001
        (1,):
            Duration: 6e-05 sec.
            Error Rate: 0.002
        (2,):
            Duration: 5e-07 sec.
            Error Rate: 0.2

This Target represents a 3 qubit backend that supports CXGate between qubits 0 and 1, UGate on qubits 0 and 1, RZGate, RXGate, and RYGate on qubits 1 and 2, CZGate between qubits 1 and 2, and qubits 2 and 0, and Measure on all qubits.

There are also specific data structures to represent a specific subset of information from the Target. For example, the CouplingMap class is used to solely represent the connectivity constraints of a backend as a directed graph. A coupling map can be generated from a Target using the Target.build_coupling_map() method. These data structures typically pre-date the Target class but are still used by some transpiler passes that do not work natively with a Target instance yet or when dealing with backends that aren’t using the latest BackendV2 interface.

For example, if we wanted to visualize the CouplingMap for the example 3 qubit Target above:

from qiskit.circuit import Parameter, Measure
from qiskit.transpiler import Target, InstructionProperties
from qiskit.circuit.library import UGate, RZGate, RXGate, RYGate, CXGate, CZGate
 
target = Target(num_qubits=3)
target.add_instruction(CXGate(), {(0, 1): InstructionProperties(error=.0001, duration=5e-7)})
target.add_instruction(
    UGate(Parameter('theta'), Parameter('phi'), Parameter('lam')),
    {
        (0,): InstructionProperties(error=.00001, duration=5e-8),
        (1,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RZGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RYGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RXGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    CZGate(),
    {
        (1, 2): InstructionProperties(error=.0001, duration=5e-7),
        (2, 0): InstructionProperties(error=.0001, duration=5e-7)
    }
)
target.add_instruction(
    Measure(),
    {
        (0,): InstructionProperties(error=.001, duration=5e-5),
        (1,): InstructionProperties(error=.002, duration=6e-5),
        (2,): InstructionProperties(error=.2, duration=5e-7)
    }
)
 
target.build_coupling_map().draw()

This shows the global connectivity of the Target which is the combination of the supported qubits for CXGate and CZGate. To see the individual connectivity, you can pass the operation name to CouplingMap.build_coupling_map():

from qiskit.circuit import Parameter, Measure
from qiskit.transpiler import Target, InstructionProperties
from qiskit.circuit.library import UGate, RZGate, RXGate, RYGate, CXGate, CZGate
 
target = Target(num_qubits=3)
target.add_instruction(CXGate(), {(0, 1): InstructionProperties(error=.0001, duration=5e-7)})
target.add_instruction(
    UGate(Parameter('theta'), Parameter('phi'), Parameter('lam')),
    {
        (0,): InstructionProperties(error=.00001, duration=5e-8),
        (1,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RZGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RYGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RXGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    CZGate(),
    {
        (1, 2): InstructionProperties(error=.0001, duration=5e-7),
        (2, 0): InstructionProperties(error=.0001, duration=5e-7)
    }
)
target.add_instruction(
    Measure(),
    {
        (0,): InstructionProperties(error=.001, duration=5e-5),
        (1,): InstructionProperties(error=.002, duration=6e-5),
        (2,): InstructionProperties(error=.2, duration=5e-7)
    }
)
 
target.build_coupling_map('cx').draw()

from qiskit.circuit import Parameter, Measure
from qiskit.transpiler import Target, InstructionProperties
from qiskit.circuit.library import UGate, RZGate, RXGate, RYGate, CXGate, CZGate
 
target = Target(num_qubits=3)
target.add_instruction(CXGate(), {(0, 1): InstructionProperties(error=.0001, duration=5e-7)})
target.add_instruction(
    UGate(Parameter('theta'), Parameter('phi'), Parameter('lam')),
    {
        (0,): InstructionProperties(error=.00001, duration=5e-8),
        (1,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RZGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RYGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    RXGate(Parameter('theta')),
    {
        (1,): InstructionProperties(error=.00001, duration=5e-8),
        (2,): InstructionProperties(error=.00002, duration=6e-8)
    }
)
target.add_instruction(
    CZGate(),
    {
        (1, 2): InstructionProperties(error=.0001, duration=5e-7),
        (2, 0): InstructionProperties(error=.0001, duration=5e-7)
    }
)
target.add_instruction(
    Measure(),
    {
        (0,): InstructionProperties(error=.001, duration=5e-5),
        (1,): InstructionProperties(error=.002, duration=6e-5),
        (2,): InstructionProperties(error=.2, duration=5e-7)
    }
)
 
target.build_coupling_map('cz').draw()

Scheduling of circuits

After the circuit has been translated to the target basis, mapped to the device, and optimized, a scheduling phase can be applied to optionally account for all the idle time in the circuit. At a high level, the scheduling can be thought of as inserting delays into the circuit to account for idle time on the qubits between the execution of instructions. For example, if we start with a circuit such as:

we can then call transpile() on it with scheduling_method set:

from qiskit import QuantumCircuit, transpile
from qiskit.providers.fake_provider import GenericBackendV2
 
backend = GenericBackendV2(5)
 
ghz = QuantumCircuit(5)
ghz.h(0)
ghz.cx(0,range(1,5))
 
circ = transpile(ghz, backend, scheduling_method="asap")
circ.draw(output='mpl')

You can see here that the transpiler inserted Delay instructions to account for idle time on each qubit. To get a better idea of the timing of the circuit we can also look at it with the timeline.draw() function:

The scheduling of a circuit involves two parts: analysis and constraint mapping, followed by a padding pass. The first part requires running a scheduling analysis pass such as ALAPSchedulingAnalysis or ASAPSchedulingAnalysis which analyzes the circuit and records the start time of each instruction in the circuit using a scheduling algorithm (“as late as possible” for ALAPSchedulingAnalysis and “as soon as possible” for ASAPSchedulingAnalysis) in the property set. Once the circuit has an initial scheduling, additional passes can be run to account for any timing constraints on the target backend, such as alignment constraints. This is typically done with the ConstrainedReschedule pass which will adjust the scheduling set in the property set to the constraints of the target backend. Once all the scheduling and adjustments/rescheduling are finished, a padding pass, such as PadDelay or PadDynamicalDecoupling is run to insert the instructions into the circuit, which completes the scheduling.

Scheduling analysis with control-flow instructions

When running scheduling analysis passes on a circuit, you must keep in mind that there are additional constraints on classical conditions and control flow instructions. This section covers the details of these additional constraints that any scheduling pass will need to account for.

Topological node ordering in scheduling

The DAG representation of QuantumCircuit respects the node ordering in the classical register wires, though theoretically two conditional instructions conditioned on the same register could commute, i.e. read-access to the classical register doesn’t change its state.

qc = QuantumCircuit(2, 1)
qc.delay(100, 0)
qc.x(0).c_if(0, True)
qc.x(1).c_if(0, True)

The scheduler SHOULD comply with the above topological ordering policy of the DAG circuit. Accordingly, the asap-scheduled circuit will become

     ┌────────────────┐   ┌───┐
q_0: ┤ Delay(100[dt]) ├───┤ X ├──────────────
     ├────────────────┤   └─╥─┘      ┌───┐
q_1: ┤ Delay(100[dt]) ├─────╫────────┤ X ├───
     └────────────────┘     ║        └─╥─┘
                       ┌────╨────┐┌────╨────┐
c: 1/══════════════════╡ c_0=0x1 ╞╡ c_0=0x1 ╞
                       └─────────┘└─────────┘

Note that this scheduling might be inefficient in some cases, because the second conditional operation could start without waiting for the 100 dt delay. However, any additional optimization should be done in a different pass, not to break the topological ordering of the original circuit.

Realistic control flow scheduling (respecting microarchitecture)

In the dispersive QND readout scheme, the qubit (Q) is measured by sending a microwave stimulus, followed by a resonator ring-down (depopulation). This microwave signal is recorded in the buffer memory (B) with the hardware kernel, then a discriminated (D) binary value is moved to the classical register (C). A sequence from t0 to t1 of the measure instruction interval could be modeled as follows:

Q ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░
B ░░▒▒▒▒▒▒▒▒░░░░░░░░░
D ░░░░░░░░░░▒▒▒▒▒▒░░░
C ░░░░░░░░░░░░░░░░▒▒░

However, the QuantumCircuit representation is not accurate enough to represent this model. In the circuit representation, the corresponding circuit.Qubit is occupied by the stimulus microwave signal during the first half of the interval, and the Clbit is only occupied at the very end of the interval.

The lack of precision representing the physical model may induce edge cases in the scheduling:

        ┌───┐
q_0: ───┤ X ├──────
        └─╥─┘   ┌─┐
q_1: ─────╫─────┤M├
     ┌────╨────┐└╥┘
c: 1/╡ c_0=0x1 ╞═╩═
     └─────────┘ 0

In this example, a user may intend to measure the state of q_1 after the XGate is applied to q_0. This is the correct interpretation from the viewpoint of topological node ordering, i.e. The XGate node comes in front of the Measure node. However, according to the measurement model above, the data in the register is unchanged during the application of the stimulus, so two nodes are simultaneously operated. If one tries to alap-schedule this circuit, it may return following circuit:

     ┌────────────────┐   ┌───┐
q_0: ┤ Delay(500[dt]) ├───┤ X ├──────
     └────────────────┘   └─╥─┘   ┌─┐
q_1: ───────────────────────╫─────┤M├
                       ┌────╨────┐└╥┘
c: 1/══════════════════╡ c_0=0x1 ╞═╩═
                       └─────────┘ 0

Note that there is no delay on the q_1 wire, and the measure instruction immediately starts after t=0, while the conditional gate starts after the delay. It looks like the topological ordering between the nodes is flipped in the scheduled view. This behavior can be understood by considering the control flow model described above,

: Quantum Circuit, first-measure
0 ░░░░░░░░░░░░▒▒▒▒▒▒░
1 ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░

: In wire q0
Q ░░░░░░░░░░░░░░░▒▒▒░
C ░░░░░░░░░░░░▒▒░░░░░

: In wire q1
Q ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░
B ░░▒▒▒▒▒▒▒▒░░░░░░░░░
D ░░░░░░░░░░▒▒▒▒▒▒░░░
C ░░░░░░░░░░░░░░░░▒▒░

Since there is no qubit register overlap between Q0 and Q1, the node ordering is determined by the shared classical register C. As you can see, the execution order is still preserved on C, i.e. read C then apply XGate, finally store the measured outcome in C. But because DAGOpNode cannot define different durations for the associated registers, the time ordering of the two nodes is inverted.

This behavior can be controlled by clbit_write_latency and conditional_latency. clbit_write_latency determines the delay of the register write-access from the beginning of the measure instruction (t0), while conditional_latency determines the delay of conditional gate operations with respect to t0, which is determined by the register read-access. This information is accessible in the backend configuration and should be copied to the pass manager property set before the pass is called.

Due to default latencies, the alap-scheduled circuit of above example may become

        ┌───┐
q_0: ───┤ X ├──────
        └─╥─┘   ┌─┐
q_1: ─────╫─────┤M├
     ┌────╨────┐└╥┘
c: 1/╡ c_0=0x1 ╞═╩═
     └─────────┘ 0

If the backend microarchitecture supports smart scheduling of the control flow instructions, such as separately scheduling qubits and classical registers, the insertion of the delay yields an unnecessarily longer total execution time.

: Quantum Circuit, first-XGate
0 ░▒▒▒░░░░░░░░░░░░░░░
1 ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░

: In wire q0
Q ░▒▒▒░░░░░░░░░░░░░░░
C ░░░░░░░░░░░░░░░░░░░ (zero latency)

: In wire q1
Q ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░
C ░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░ (zero latency, scheduled after C0 read-access)

However, this result is much more intuitive in the topological ordering view. If a finite conditional latency value is provided, for example, 30 dt, the circuit is scheduled as follows:

     ┌───────────────┐   ┌───┐
q_0: ┤ Delay(30[dt]) ├───┤ X ├──────
     ├───────────────┤   └─╥─┘   ┌─┐
q_1: ┤ Delay(30[dt]) ├─────╫─────┤M├
     └───────────────┘┌────╨────┐└╥┘
c: 1/═════════════════╡ c_0=0x1 ╞═╩═
                      └─────────┘ 0

with the timing model:

: Quantum Circuit, first-xgate
0 ░░▒▒▒░░░░░░░░░░░░░░░
1 ░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░

: In wire q0
Q ░░▒▒▒░░░░░░░░░░░░░░░
C ░▒░░░░░░░░░░░░░░░░░░ (30dt latency)

: In wire q1
Q ░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░
C ░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░

See https://arxiv.org/abs/2102.01682 for more details.

Transpiler API

Hardware description

Pass Manager Definition

Layout and Topology

Scheduling

Abstract Passes

Exceptions

TranspilerError

TranspilerAccessError

CouplingError

LayoutError

CircuitTooWideForTarget

InvalidLayoutError