Skip to main contentIBM Quantum Documentation

Transpilation default settings and configuration options

Abstract circuits need to be transpiled because systems have a limited set of basis gates and cannot execute arbitrary operations. The transpiler's function is to change arbitrary circuits so that they can run on a specified system. This is done by translating the circuits to the supported basis gates, and by introducing SWAP gates as needed, so that the circuit's connectivity matches that of the system.

You can pass circuits and a system to the transpile() function and use all default settings, or you can use parameters to fine tune the transpilation.

Basic usage without parameters

In this example, we pass a circuit and target system to the transpiler without specifying any further parameters.

Create a circuit and view the result:

from qiskit import transpile
from qiskit import QuantumCircuit
from qiskit.circuit.library import GroverOperator, Diagonal
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit.providers.fake_provider import FakeSherbrooke
# Create circuit to test transpiler on
oracle = Diagonal([1] * 7 + [-1])
qc = QuantumCircuit(3)
qc.h([0, 1, 2])
qc = qc.compose(GroverOperator(oracle))
# Add measurements to the circuit
# View the circuit
qc.draw(output='mpl', style="iqp")
Original circuit
Original circuit

Transpile the circuit and view the result:

# Specify the system to target
backend = FakeSherbrooke()
# Transpile the circuit
transpiled_circ = transpile(qc, backend)
# View the transpiled circuit
transpiled_circ.draw(output='mpl', style="iqp")
Transpiled circuit
Transpiled circuit

All available parameters

Following are all of the available parameters for the transpile() method. There are two classes of arguments: those that describe the target of compilation, and those that influence how the transpiler works.

All parameters except circuits are optional. For full details, see the Transpiler API documentation.

circuits (_CircuitT) - One or more circuits to transpile. This is the only required parameter.

Parameters used to describe the compilation target:

These arguments describe the system that the input circuit will be run on. For example, they may be used to ensure that the returned circuit can be run on the specified system, where the transpiler maps the circuit's virtual qubits to the physical qubits which may have limited connectivity as specified in the coupling_map, basis_gates that specify which single- and two-qubit gates are calibrated for the system, and possibly their error rates.

Many of these parameters are described in detail in Commonly used parameters for transpilation.

System (Backend) parameters

Backend parameters - If you specify backend, you don't need to specify target or any other backend options. Likewise, if you specify target, you don't need to specify backend or any other backend options.

  • backend (Backend) - If this is set, the transpiler compiles the input circuit to this device. If any other option is set that impacts these settings, such as coupling_map, it overrides the settings from backend.
  • target (Target) - A backend transpiler target. Normally this is specified as part of the backend argument, but if you manually constructed a Target object, you can specify it here. This overrides the target from backend.
  • backend_properties (BackendProperties) - Properties returned by a system, including information on gate errors, readout errors, qubit coherence times, and so on. Find a system that provides this information by running
  • dt (float | None) - Backend sample time (resolution) in seconds. If None is specified (default), backend.configuration().dt is used.
  • ignore_backend_supplied_default_methods (bool) - If set to True, any default methods specified by a system are ignored. Some systems specify alternative default methods to support custom compilation target-specific passes / plugins that support system-specific compilation techniques. If you prefer that these defaults are not used, this option disables those system-specific defaults.
  • instruction_durations (List[Tuple[str, Iterable[int], float, Iterable[float], str]] | List[Tuple[str, Iterable[int], float, Iterable[float]]] | List[Tuple[str, Iterable[int], float, str]] | List[Tuple[str, Iterable[int], float]] | InstructionDurations) - Durations of instructions. Applicable only if scheduling_method is specified. The gate lengths defined in are used by default. They are overwritten if instruction_durations is specified. The instruction_durations format must be as follows. The instruction_durations must be given as a list of tuples [(instruction_name, qubits, duration, unit), …]. | [(cx, [0, 1], 12.3, ns), (u3, [0], 4.56, ns)] | [(cx, [0, 1], 1000), (u3, [0], 300)] If unit is omitted, the default is dt, which is a sample time depending on system. If the time unit is dt, the duration must be an integer.
  • timing_constraints (Dict[str, int] | None) - An optional control hardware restriction on instruction time resolution. This information is provided by the system configuration. If the system doesn’t have any restriction on the instruction time allocation, timing_constraints is None and no adjustment is performed. A system might report a set of restrictions, namely:
    • granularity: An integer value representing the minimum pulse gate resolution in units of dt. A user-defined pulse gate should have duration that is a multiple of this granularity value.
    • min_length: An integer value representing the minimum pulse gate length in units of dt. A user-defined pulse gate should be longer than this length.
    • pulse_alignment: An integer value representing a time resolution of gate instruction starting time. Gate instructions should start at time that is a multiple of this value.
    • acquire_alignment: An integer value representing a time resolution of measure instruction starting time. Measure instruction should start at time that is a multiple of this value.

Layout and topology parameters

  • basis_gates (List[str] | None) - List of basis gate names to unroll to. For example ['u1', 'u2', 'u3', 'cx']. If None, do not unroll.
  • coupling_map (CouplingMap | List[List[int]]) - Directed coupling map (possibly custom) to target in mapping. If the coupling map is symmetric, both directions need to be specified. These formats are supported:
    • CouplingMap instance
    • List, must be given as an adjacency matrix, where each entry specifies all directed two-qubit interactions supported by the system. For example:[[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]]
  • inst_map (List[InstructionScheduleMap] | None) - Mapping of circuit operations to pulse schedules. If None, the system’s instruction_schedule_map is used.

Parameters used to influence how the transpiler works:

These parameters impact specific transpilation stages. Some of them might impact multiple stages, but have only been listed under one stage for simplicity. If you specify an argument, such as initial_layout for the qubits you want to use, that value overrides all the passes that could change it. In other words, the transpiler won't change anything that you manually specify. For details about specific stages, see Transpiler stages.

Initialization stage

  • hls_config (HLSConfig) - An optional configuration class HLSConfig that is passed directly to the HighLevelSynthesis transformation pass. This configuration class lets you specify the lists of synthesis algorithms and their parameters for various high-level objects.
  • init_method (str) - The plugin name to use for the initialization stage. By default, an external plugin is not used. You can see a list of installed plugins by running list_stage_plugins() with init for the stage name argument.
  • unitary_synthesis_method (str) - The name of the unitary synthesis method to use. By default, default is used. You can see a list of installed plugins by running unitary_synthesis_plugin_names().
  • unitary_synthesis_plugin_config (dict) - An optional configuration dictionary that is passed directly to the unitary synthesis plugin. By default this setting has no effect because the default unitary synthesis method does not take custom configuration. Applying a custom configuration should only be necessary when a unitary synthesis plugin is specified with the unitary_synthesis argument. As this is custom for each unitary synthesis plugin, refer to the plugin's documentation for how to use this option.

Translation stage

  • translation_method (str) - Name of translation pass (basis_translator, translator, or synthesis) This can also be the external plugin name to use for the translation stage. You can see a list of installed plugins by running list_stage_plugins() with translation for the stage_name argument. The default value is basis_translator.

Layout stage

  • initial_layout (Layout | Dict | List) - Initial position of virtual qubits on physical qubits. If this layout makes the circuit compatible with the coupling_map constraints, it will be used. The final layout is not guaranteed to be the same, as the transpiler might permute qubits through swaps or other means. For full details, see the Initial layout section.
  • layout_method (str) - Name of layout selection pass (trivial, dense, noise_adaptive, or sabre). This can also be the external plugin name to use for the layout stage. You can see a list of installed plugins by running list_stage_plugins() with layout for the stage_name argument. The default value is sabre.

Routing stage

  • routing_method (str) - Name of routing pass (basic, lookahead, stochastic, sabre, or none). This can also be the external plugin name to use for the routing stage. You can see a list of installed plugins by running list_stage_plugins() with routing for the stage_name argument. The default value is sabre.

Optimization stage

  • approximation_degree (float, in the range 0-1 | None) - Heuristic dial used for circuit approximation (1.0 = no approximation, 0.0 = maximal approximation). The default value is 1.0. Specifying None sets the approximation degree to the reported error rate. See the Approximation degree section for more details.
  • optimization_level (int) - How much optimization to perform on the circuits. Integer in the range (0 - 3). Higher levels generate more optimized circuits, at the expense of longer transpilation time. The default is 1. See the Set optimization topic for more details.
  • optimization_method (str) - The plugin name to use for the optimization stage. By default an external plugin is not used. You can see a list of installed plugins by running list_stage_plugins() with optimization for the stage_name argument.

Scheduling stage

  • scheduling_method (str) - Name of the scheduling pass. This can also be the external plugin name to use for the scheduling stage. You can see a list of installed plugins by running list_stage_plugins() with scheduling for the stage_name argument.
    • 'as_soon_as_possible': Schedule instructions greedily, as early as possible on a qubit resource. (alias: asap)
    • 'as_late_as_possible': Schedule instructions late, that is, keeping qubits in the ground state when possible. (alias: alap). This is the default.

Transpiler execution

callback (Callable[[BasePass, DAGCircuit, float, PropertySet, int], Any]) - A callback function is one that is called after each pass execution. This is useful for debugging. Since the transpiler substantially transforms a circuit, the callback mechanism helps you understand what the transpiler is doing after each pass. For example, if you see an unexpected circuit, you can write a callback to draw the circuit and print the pass name after each pass.

The function is called with these keyword arguments:

  • pass_: the pass being run.
  • dag: the dag output of the pass.
  • time: the time to execute the pass.
  • property_set: the property set.
  • count: the index for the pass execution.

The arguments passed expose the internals of the pass manager and are subject to change as the pass manager internals change. If you intend to reuse a callback function over multiple releases, verify that the arguments being passed are the same.

To use the callback feature, define a function that will take in kwargs dict and access the variables. For example:

def callback_func(**kwargs):
    pass_ = kwargs['pass_']
    dag = kwargs['dag']
    time = kwargs['time']
    property_set = kwargs['property_set']
    count = kwargs['count']
transpile(circ, callback=callback_func)
  • seed_transpiler (int) - Sets random seeds for the stochastic parts of the transpiler.
  • output_name (str | List[str]) - A list with strings to identify the output circuits. The length of the list should be the same length as the circuits parameter.

The following default values are used if you don't specify any of the above parameters.

qiskit.compiler.transpile(unitary_synthesis_method='default', translation_method='basis_translator', layout_method='sabre', routing_method='sabre', approximation_degree=1.0, optimization_level=1.0, scheduling_method='as_late_as_possible')

Next steps

Was this page helpful?