# qiskit.compiler.transpile¶

transpile(circuits, backend=None, basis_gates=None, coupling_map=None, backend_properties=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, instruction_durations=None, dt=None, approximation_degree=None, timing_constraints=None, seed_transpiler=None, optimization_level=None, pass_manager=None, callback=None, output_name=None)[source]

Transpile one or more circuits, according to some desired transpilation targets.

All arguments may be given as either a singleton or list. In case of a list, the length must be equal to the number of circuits being transpiled.

Transpilation is done in parallel using multiprocessing.

Parameters
• circuits (Union[QuantumCircuit, List[QuantumCircuit]]) -- Circuit(s) to transpile

• backend (Union[Backend, BaseBackend, None]) --

If set, transpiler options are automatically grabbed from backend.configuration() and backend.properties(). If any other option is explicitly set (e.g., coupling_map), it will override the backend's.

Note

The backend arg is purely for convenience. The resulting circuit may be run on any backend as long as it is compatible.

• basis_gates (Optional[List[str]]) -- List of basis gate names to unroll to (e.g: ['u1', 'u2', 'u3', 'cx']). If None, do not unroll.

• coupling_map (Union[CouplingMap, List[List[int]], None]) --

Coupling map (perhaps custom) to target in mapping. Multiple formats are supported:

1. CouplingMap instance

2. List, must be given as an adjacency matrix, where each entry specifies all two-qubit interactions supported by backend, e.g: [[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]]

• backend_properties (Optional[BackendProperties]) -- properties returned by a backend, including information on gate errors, readout errors, qubit coherence times, etc. Find a backend that provides this information with: backend.properties()

• initial_layout (Union[Layout, Dict, List, None]) --

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 may permute qubits through swaps or other means. Multiple formats are supported:

1. Layout instance

2. Dict * virtual to physical:

{qr[0]: 0,
qr[1]: 3,
qr[2]: 5}

• physical to virtual:

{0: qr[0],
3: qr[1],
5: qr[2]}

3. List

• virtual to physical:

[0, 3, 5]  # virtual qubits are ordered (in addition to named)

• physical to virtual:

[qr[0], None, None, qr[1], None, qr[2]]


• layout_method (Optional[str]) -- Name of layout selection pass ('trivial', 'dense', 'noise_adaptive', 'sabre')

• routing_method (Optional[str]) -- Name of routing pass ('basic', 'lookahead', 'stochastic', 'sabre', 'none')

• translation_method (Optional[str]) -- Name of translation pass ('unroller', 'translator', 'synthesis')

• scheduling_method (Optional[str]) -- Name of scheduling pass. * 'as_soon_as_possible': Schedule instructions greedily, as early as possible on a qubit resource. (alias: 'asap') * 'as_late_as_possible': Schedule instructions late, i.e. keeping qubits in the ground state when possible. (alias: 'alap') If None, no scheduling will be done.

• instruction_durations (Union[List[Tuple[str, Optional[Iterable[int]], float, str]], List[Tuple[str, Optional[Iterable[int]], float]], InstructionDurations, None]) -- Durations of instructions. The gate lengths defined in backend.properties are used as default. They are overwritten if this instruction_durations is specified. The format of instruction_durations 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 backend. If the time unit is 'dt', the duration must be an integer.

• dt (Optional[float]) -- Backend sample time (resolution) in seconds. If None (default), backend.configuration().dt is used.

• approximation_degree (float) -- heuristic dial used for circuit approximation (1.0=no approximation, 0.0=maximal approximation)

• timing_constraints (Optional[Dict[str, int]]) --

An optional control hardware restriction on instruction time resolution. A quantum computer backend may report a set of restrictions, namely:

• granularity: An integer value representing minimum pulse gate resolution in units of dt. A user-defined pulse gate should have duration of a multiple of this granularity value.

• min_length: An integer value representing 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 instruction should start at time which is a multiple of the alignment value.

• acquire_alignment: An integer value representing a time resolution of measure instruction starting time. Measure instruction should start at time which is a multiple of the alignment value.

This information will be provided by the backend configuration. If the backend doesn't have any restriction on the instruction time allocation, then timing_constraints is None and no adjustment will be performed.

• seed_transpiler (Optional[int]) -- Sets random seed for the stochastic parts of the transpiler

• optimization_level (Optional[int]) -- How much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer transpilation time. * 0: no optimization * 1: light optimization * 2: heavy optimization * 3: even heavier optimization If None, level 1 will be chosen as default.

• pass_manager (Optional[PassManager]) -- The pass manager to use for a custom pipeline of transpiler passes. If this arg is present, all other args will be ignored and the pass manager will be used directly (Qiskit will not attempt to auto-select a pass manager based on transpile options).

• callback (Optional[Callable[[BasePass, DAGCircuit, float, PropertySet, int], Any]]) --

A callback function that will be called after each pass execution. The function will be called with 5 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 exact 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, be sure to check 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)


• output_name (Union[str, List[str], None]) -- A list with strings to identify the output circuits. The length of the list should be exactly the length of the circuits parameter.

Return type

Union[QuantumCircuit, List[QuantumCircuit]]

Returns

The transpiled circuit(s).

Raises

TranspilerError -- in case of bad inputs to transpiler (like conflicting parameters) or errors in passes