Skip to main contentIBM Quantum Documentation

Preset Passmanagers

qiskit.transpiler.preset_passmanagers

This module contains functions for generating the preset pass managers for the transpiler. The preset pass managers are instances of StagedPassManager which are used to execute the circuit transformations as part of Qiskit’s compiler inside the transpile() function at the different optimization levels. The functionality here is divided into two parts, the first includes the functions used generate the entire pass manager which is used by transpile() (Preset Pass Manager Generation) and the second includes functions which are used to build (either entirely or in part) the stages which the preset pass managers are composed of (Stage Generator Functions).


Preset Pass Manager Generation

generate_preset_pass_manager

qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager(optimization_level, backend=None, target=None, basis_gates=None, inst_map=None, coupling_map=None, instruction_durations=None, backend_properties=None, timing_constraints=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, approximation_degree=1.0, seed_transpiler=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None, init_method=None, optimization_method=None, *, _skip_target=False) GitHub(opens in a new tab)

Generate a preset PassManager

This function is used to quickly generate a preset pass manager. A preset pass manager are the default pass managers used by the transpile() function. This function provides a convenient and simple method to construct a standalone PassManager object that mirrors what the transpile

Parameters

  • optimization_level (int(opens in a new tab)) –

    The optimization level to generate a PassManager for. This can be 0, 1, 2, or 3. 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
  • backend (Backend) – An optional backend object which can be used as the source of the default values for the basis_gates, inst_map, couplig_map, backend_properties, instruction_durations, timing_constraints, and target. If any of those other arguments are specified in addition to backend they will take precedence over the value contained in the backend.

  • target (Target) – The Target representing a backend compilation target. The following attributes will be inferred from this argument if they are not set: coupling_map, basis_gates, instruction_durations, inst_map, timing_constraints and backend_properties.

  • basis_gates (list(opens in a new tab)) – List of basis gate names to unroll to (e.g: ['u1', 'u2', 'u3', 'cx']).

  • inst_map (InstructionScheduleMap) – Mapping object that maps gate to schedules. If any user defined calibration is found in the map and this is used in a circuit, transpiler attaches the custom gate definition to the circuit. This enables one to flexibly override the low-level instruction implementation.

  • coupling_map (CouplingMap orlist(opens in a new tab)) – Directed graph represented a coupling map.

  • instruction_durations (InstructionDurations) – Dictionary of duration (in dt) for each instruction.

  • timing_constraints (TimingConstraints) – Hardware time alignment restrictions.

  • initial_layout (Layout) – Initial position of virtual qubits on physical qubits.

  • layout_method (str(opens in a new tab)) – The Pass to use for choosing initial qubit placement. Valid choices are 'trivial', 'dense', and 'sabre', representing TrivialLayout, DenseLayout and SabreLayout respectively. This can also be the external plugin name to use for the layout stage of the output StagedPassManager. You can see a list of installed plugins by using list_stage_plugins() with "layout" for the stage_name argument.

  • routing_method (str(opens in a new tab)) – The pass to use for routing qubits on the architecture. Valid choices are 'basic', 'lookahead', 'stochastic', 'sabre', and 'none' representing BasicSwap, LookaheadSwap, StochasticSwap, SabreSwap, and erroring if routing is required respectively. This can also be the external plugin name to use for the routing stage of the output StagedPassManager. You can see a list of installed plugins by using list_stage_plugins() with "routing" for the stage_name argument.

  • translation_method (str(opens in a new tab)) – The method to use for translating gates to basis gates. Valid choices 'translator', 'synthesis' representing BasisTranslator, and UnitarySynthesis respectively. This can also be the external plugin name to use for the translation stage of the output StagedPassManager. You can see a list of installed plugins by using list_stage_plugins() with "translation" for the stage_name argument.

  • scheduling_method (str(opens in a new tab)) – The pass to use for scheduling instructions. Valid choices are 'alap' and 'asap'. This can also be the external plugin name to use for the scheduling stage of the output StagedPassManager. You can see a list of installed plugins by using list_stage_plugins() with "scheduling" for the stage_name argument.

  • backend_properties (BackendProperties) – Properties returned by a backend, including information on gate errors, readout errors, qubit coherence times, etc.

  • approximation_degree (float(opens in a new tab)) – Heuristic dial used for circuit approximation (1.0=no approximation, 0.0=maximal approximation).

  • seed_transpiler (int(opens in a new tab)) – Sets random seed for the stochastic parts of the transpiler.

  • unitary_synthesis_method (str(opens in a new tab)) – The name of the unitary synthesis method to use. By default 'default' is used. You can see a list of installed plugins with unitary_synthesis_plugin_names().

  • unitary_synthesis_plugin_config (dict(opens in a new tab)) – An optional configuration dictionary that will be passed directly to the unitary synthesis plugin. By default this setting will have no effect as the default unitary synthesis method does not take custom configuration. This should only be necessary when a unitary synthesis plugin is specified with the unitary_synthesis_method argument. As this is custom for each unitary synthesis plugin refer to the plugin documentation for how to use this option.

  • hls_config (HLSConfig) – An optional configuration class HLSConfig that will be passed directly to HighLevelSynthesis transformation pass. This configuration class allows to specify for various high-level objects the lists of synthesis algorithms and their parameters.

  • init_method (str(opens in a new tab)) – The plugin name to use for the init stage of the output StagedPassManager. By default an external plugin is not used. You can see a list of installed plugins by using list_stage_plugins() with "init" for the stage name argument.

  • optimization_method (str(opens in a new tab)) – The plugin name to use for the optimization stage of the output StagedPassManager. By default an external plugin is not used. You can see a list of installed plugins by using list_stage_plugins() with "optimization" for the stage_name argument.

Returns

The preset pass manager for the given options

Return type

StagedPassManager

Raises

ValueError(opens in a new tab) – if an invalid value for optimization_level is passed in.

level_0_pass_manager

qiskit.transpiler.preset_passmanagers.level_0_pass_manager(pass_manager_config) GitHub(opens in a new tab)

Level 0 pass manager: no explicit optimization other than mapping to backend.

This pass manager applies the user-given initial layout. If none is given, a trivial layout consisting of mapping the i-th virtual qubit to the i-th physical qubit is used. Any unused physical qubit is allocated as ancilla space.

The pass manager then unrolls the circuit to the desired basis, and transforms the circuit to match the coupling map.

Parameters

pass_manager_config (PassManagerConfig) – configuration of the pass manager.

Returns

a level 0 pass manager.

Raises

TranspilerError – if the passmanager config is invalid.

Return type

StagedPassManager

level_1_pass_manager

qiskit.transpiler.preset_passmanagers.level_1_pass_manager(pass_manager_config) GitHub(opens in a new tab)

Level 1 pass manager: light optimization by simple adjacent gate collapsing.

This pass manager applies the user-given initial layout. If none is given, and a trivial layout (i-th virtual -> i-th physical) makes the circuit fit the coupling map, that is used. Otherwise, the circuit is mapped to the most densely connected coupling subgraph, and swaps are inserted to map. Any unused physical qubit is allocated as ancilla space. The pass manager then unrolls the circuit to the desired basis, and transforms the circuit to match the coupling map. Finally, optimizations in the form of adjacent gate collapse and redundant reset removal are performed.

Parameters

pass_manager_config (PassManagerConfig) – configuration of the pass manager.

Returns

a level 1 pass manager.

Raises

TranspilerError – if the passmanager config is invalid.

Return type

StagedPassManager

level_2_pass_manager

qiskit.transpiler.preset_passmanagers.level_2_pass_manager(pass_manager_config) GitHub(opens in a new tab)

Level 2 pass manager: medium optimization by initial layout selection and gate cancellation using commutativity rules.

This pass manager applies the user-given initial layout. If none is given, a search for a perfect layout (i.e. one that satisfies all 2-qubit interactions) is conducted. If no such layout is found, qubits are laid out on the most densely connected subset which also exhibits the best gate fidelities.

The pass manager then transforms the circuit to match the coupling constraints. It is then unrolled to the basis, and any flipped cx directions are fixed. Finally, optimizations in the form of commutative gate cancellation and redundant reset removal are performed.

Parameters

pass_manager_config (PassManagerConfig) – configuration of the pass manager.

Returns

a level 2 pass manager.

Raises

TranspilerError – if the passmanager config is invalid.

Return type

StagedPassManager

level_3_pass_manager

qiskit.transpiler.preset_passmanagers.level_3_pass_manager(pass_manager_config) GitHub(opens in a new tab)

Level 3 pass manager: heavy optimization by noise adaptive qubit mapping and gate cancellation using commutativity rules and unitary synthesis.

This pass manager applies the user-given initial layout. If none is given, a search for a perfect layout (i.e. one that satisfies all 2-qubit interactions) is conducted. If no such layout is found, and device calibration information is available, the circuit is mapped to the qubits with best readouts and to CX gates with highest fidelity.

The pass manager then transforms the circuit to match the coupling constraints. It is then unrolled to the basis, and any flipped cx directions are fixed. Finally, optimizations in the form of commutative gate cancellation, resynthesis of two-qubit unitary blocks, and redundant reset removal are performed.

Parameters

pass_manager_config (PassManagerConfig) – configuration of the pass manager.

Returns

a level 3 pass manager.

Raises

TranspilerError – if the passmanager config is invalid.

Return type

StagedPassManager


Stage Generator Functions

generate_control_flow_options_check

qiskit.transpiler.preset_passmanagers.common.generate_control_flow_options_check(layout_method=None, routing_method=None, translation_method=None, optimization_method=None, scheduling_method=None, basis_gates=(), target=None) GitHub(opens in a new tab)

Generate a pass manager that, when run on a DAG that contains control flow, fails with an error message explaining the invalid options, and what could be used instead.

Returns

a pass manager that populates the contains_x properties for each of the control-flow operations, and raises an error if any of the given options do not support control flow, but a circuit with control flow is given.

Return type

PassManager

generate_error_on_control_flow

qiskit.transpiler.preset_passmanagers.common.generate_error_on_control_flow(message) GitHub(opens in a new tab)

Get a pass manager that always raises an error if control flow is present in a given circuit.

generate_unroll_3q

qiskit.transpiler.preset_passmanagers.common.generate_unroll_3q(target, basis_gates=None, approximation_degree=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None) GitHub(opens in a new tab)

Generate an unroll >3q PassManager

Parameters

Returns

The unroll 3q or more pass manager

Return type

PassManager

generate_embed_passmanager

qiskit.transpiler.preset_passmanagers.common.generate_embed_passmanager(coupling_map) GitHub(opens in a new tab)

Generate a layout embedding PassManager

This is used to generate a PassManager object that can be used to expand and apply an initial layout to a circuit

Parameters

coupling_map (Union[CouplingMap, Target) – The coupling map for the backend to embed the circuit to.

Returns

The embedding passmanager that assumes the layout property

set has been set in earlier stages

Return type

PassManager

generate_routing_passmanager

qiskit.transpiler.preset_passmanagers.common.generate_routing_passmanager(routing_pass, target, coupling_map=None, vf2_call_limit=None, backend_properties=None, seed_transpiler=None, check_trivial=False, use_barrier_before_measurement=True, vf2_max_trials=None) GitHub(opens in a new tab)

Generate a routing PassManager

Parameters

  • routing_pass (TransformationPass) – The pass which will perform the routing
  • target (Target) – the Target object representing the backend
  • coupling_map (CouplingMap) – The coupling map of the backend to route for
  • vf2_call_limit (int(opens in a new tab)) – The internal call limit for the vf2 post layout pass. If this is None or 0 the vf2 post layout will not be run.
  • backend_properties (BackendProperties) – Properties of a backend to synthesize for (e.g. gate fidelities).
  • seed_transpiler (int(opens in a new tab)) – Sets random seed for the stochastic parts of the transpiler.
  • check_trivial (bool(opens in a new tab)) – If set to true this will condition running the VF2PostLayout pass after routing on whether a trivial layout was tried and was found to not be perfect. This is only needed if the constructed pass manager runs TrivialLayout as a first layout attempt and uses it if it’s a perfect layout (as is the case with preset pass manager level 1).
  • use_barrier_before_measurement (bool(opens in a new tab)) – If true (the default) the BarrierBeforeFinalMeasurements transpiler pass will be run prior to the specified pass in the routing_pass argument.
  • vf2_max_trials (int(opens in a new tab)) – The maximum number of trials to run VF2 when evaluating the vf2 post layout pass. If this is None or 0 the vf2 post layout will not be run.

Returns

The routing pass manager

Return type

PassManager

generate_pre_op_passmanager

qiskit.transpiler.preset_passmanagers.common.generate_pre_op_passmanager(target=None, coupling_map=None, remove_reset_in_zero=False) GitHub(opens in a new tab)

Generate a pre-optimization loop PassManager

This pass manager will check to ensure that directionality from the coupling map is respected

Parameters

  • target (Target) – the Target object representing the backend
  • coupling_map (CouplingMap) – The coupling map to use
  • remove_reset_in_zero (bool(opens in a new tab)) – If True include the remove reset in zero pass in the generated PassManager

Returns

The pass manager

Return type

PassManager

generate_translation_passmanager

qiskit.transpiler.preset_passmanagers.common.generate_translation_passmanager(target, basis_gates=None, method='translator', approximation_degree=None, coupling_map=None, backend_props=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None) GitHub(opens in a new tab)

Generate a basis translation PassManager

Parameters

  • target (Target) – the Target object representing the backend
  • basis_gates (list(opens in a new tab)) – A list of str gate names that represent the basis gates on the backend target
  • method (str(opens in a new tab)) – The basis translation method to use
  • approximation_degree (Optional[float(opens in a new tab)]) – The heuristic approximation degree to use. Can be between 0 and 1.
  • coupling_map (CouplingMap) – the coupling map of the backend in case synthesis is done on a physical circuit. The directionality of the coupling_map will be taken into account if pulse_optimize is True/None and natural_direction is True/None.
  • unitary_synthesis_plugin_config (dict(opens in a new tab)) – The optional dictionary plugin configuration, this is plugin specific refer to the specified plugin’s documentation for how to use.
  • backend_props (BackendProperties) – Properties of a backend to synthesize for (e.g. gate fidelities).
  • unitary_synthesis_method (str(opens in a new tab)) – The unitary synthesis method to use. You can see a list of installed plugins with unitary_synthesis_plugin_names().
  • hls_config (HLSConfig) – An optional configuration class to use for HighLevelSynthesis pass. Specifies how to synthesize various high-level objects.

Returns

The basis translation pass manager

Return type

PassManager

Raises

TranspilerError – If the method kwarg is not a valid value

generate_scheduling

qiskit.transpiler.preset_passmanagers.common.generate_scheduling(instruction_durations, scheduling_method, timing_constraints, inst_map, target=None) GitHub(opens in a new tab)

Generate a post optimization scheduling PassManager

Parameters

  • instruction_durations (dict(opens in a new tab)) – The dictionary of instruction durations
  • scheduling_method (str(opens in a new tab)) – The scheduling method to use, can either be 'asap'/'as_soon_as_possible' or 'alap'/'as_late_as_possible'
  • timing_constraints (TimingConstraints) – Hardware time alignment restrictions.
  • inst_map (InstructionScheduleMap) – Mapping object that maps gate to schedule.
  • target (Target) – The Target object representing the backend

Returns

The scheduling pass manager

Return type

PassManager

Raises

TranspilerError – If the scheduling_method kwarg is not a valid value

Was this page helpful?