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, but can also be used in a standalone manner. The functionality here is divided into two parts. The first includes the functions used to generate the entire pass manager, which is used by transpile() (Low-level preset pass manager generation), and the second includes functions that are used to build (either entirely or in part) the stages that comprise the preset pass managers (Stage generator functions).
Low-level preset pass manager generation
level_0_pass_manager
qiskit.transpiler.preset_passmanagers.level_0_pass_manager(pass_manager_config)
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
level_1_pass_manager
qiskit.transpiler.preset_passmanagers.level_1_pass_manager(pass_manager_config)
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
level_2_pass_manager
qiskit.transpiler.preset_passmanagers.level_2_pass_manager(pass_manager_config)
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
level_3_pass_manager
qiskit.transpiler.preset_passmanagers.level_3_pass_manager(pass_manager_config)
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
Stage generator functions
generate_control_flow_options_check
qiskit.transpiler.preset_passmanagers.generate_control_flow_options_check(layout_method=None, routing_method=None, translation_method=None, optimization_method=None, scheduling_method=None, basis_gates=(), target=None)
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
generate_error_on_control_flow
qiskit.transpiler.preset_passmanagers.generate_error_on_control_flow(message)
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.generate_unroll_3q(target, basis_gates=None, approximation_degree=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, hls_config=None, qubits_initially_zero=True)
Generate an unroll >3q PassManager
Parameters
- target (Target) – the
Targetobject representing the backend - basis_gates (list) – A list of str gate names that represent the basis gates on the backend target
- approximation_degree (Optional[float]) – The heuristic approximation degree to use. Can be between 0 and 1.
- unitary_synthesis_method (str) – The unitary synthesis method to use. You can see a list of installed plugins with
unitary_synthesis_plugin_names(). - unitary_synthesis_plugin_config (dict) – The optional dictionary plugin configuration, this is plugin specific refer to the specified plugin’s documentation for how to use.
- hls_config (HLSConfig) – An optional configuration class to use for
HighLevelSynthesispass. Specifies how to synthesize various high-level objects. - qubits_initially_zero (bool) – Indicates whether the input circuit is zero-initialized.
Returns
The unroll 3q or more pass manager
Return type
generate_embed_passmanager
qiskit.transpiler.preset_passmanagers.generate_embed_passmanager(coupling_map)
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
generate_routing_passmanager
qiskit.transpiler.preset_passmanagers.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)
Generate a routing PassManager
qiskit.transpiler.preset_passmanagers.common.generate_routing_passmanager()’s argument backend_properties is deprecated as of Qiskit 1.4. It will be removed in Qiskit 2.0. The BackendProperties data structure has been deprecated and will be removed in Qiskit 2.0. The required target input argument should be used instead. You can use Target.from_configuration() to build the target from the properties object, but in 2.0 you will need to generate a target directly.
Parameters
- routing_pass (TransformationPass) – The pass which will perform the routing
- target (Target) – the
Targetobject representing the backend - coupling_map (CouplingMap) – The coupling map of the backend to route for
- vf2_call_limit (int) – The internal call limit for the vf2 post layout pass. If this is
Noneor0the vf2 post layout will not be run. - backend_properties (BackendProperties) – Properties of a backend to synthesize for (e.g. gate fidelities).
- seed_transpiler (int) – Sets random seed for the stochastic parts of the transpiler.
- check_trivial (bool) – If set to true this will condition running the
VF2PostLayoutpass 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 runsTrivialLayoutas 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) – If true (the default) the
BarrierBeforeFinalMeasurementstranspiler pass will be run prior to the specified pass in therouting_passargument. - vf2_max_trials (int) – The maximum number of trials to run VF2 when evaluating the vf2 post layout pass. If this is
Noneor0the vf2 post layout will not be run.
Returns
The routing pass manager
Return type
generate_pre_op_passmanager
qiskit.transpiler.preset_passmanagers.generate_pre_op_passmanager(target=None, coupling_map=None, remove_reset_in_zero=False)
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
Targetobject representing the backend - coupling_map (CouplingMap) – The coupling map to use
- remove_reset_in_zero (bool) – If
Trueinclude the remove reset in zero pass in the generated PassManager
Returns
The pass manager
Return type
generate_translation_passmanager
qiskit.transpiler.preset_passmanagers.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, qubits_initially_zero=True)
Generate a basis translation PassManager
qiskit.transpiler.preset_passmanagers.common.generate_translation_passmanager()’s argument backend_properties is deprecated as of Qiskit 1.4. It will be removed in Qiskit 2.0. The BackendProperties data structure has been deprecated and will be removed in Qiskit 2.0. The required target input argument should be used instead. You can use Target.from_configuration() to build the target from the properties object, but in 2.0 you will need to generate a target directly.
Parameters
- target (Target) – the
Targetobject representing the backend - basis_gates (list) – A list of str gate names that represent the basis gates on the backend target
- method (str) – The basis translation method to use
- approximation_degree (Optional[float]) – 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) – 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) – 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
HighLevelSynthesispass. Specifies how to synthesize various high-level objects. - qubits_initially_zero (bool) – Indicates whether the input circuit is zero-initialized.
Returns
The basis translation pass manager
Return type
Raises
TranspilerError – If the method kwarg is not a valid value
generate_scheduling
qiskit.transpiler.preset_passmanagers.generate_scheduling(instruction_durations, scheduling_method, timing_constraints, inst_map, target=None)
Generate a post optimization scheduling PassManager
qiskit.transpiler.preset_passmanagers.common.generate_scheduling()’s argument inst_map is deprecated as of Qiskit 1.3. It will be removed in Qiskit 2.0. The entire Qiskit Pulse package is being deprecated and this argument uses a dependency on the package.
Parameters
- instruction_durations (dict) – The dictionary of instruction durations
- scheduling_method (str) – 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) – DEPRECATED. Mapping object that maps gate to schedule.
- target (Target) – The
Targetobject representing the backend
Returns
The scheduling pass manager
Return type
Raises
TranspilerError – If the scheduling_method kwarg is not a valid value