Install and use transpiler plugins

qiskit[all]~=1.2.4
qiskit-ibm-runtime~=0.33.2
qiskit-aer~=0.15.1
qiskit-serverless~=0.18.0
qiskit-ibm-catalog~=0.2
qiskit-addon-sqd~=0.8.0
qiskit-addon-utils~=0.1.0
qiskit-addon-aqc-tensor~=0.1.2
qiskit-addon-obp~=0.1.0
scipy~=1.14.1
pyscf~=2.7.0

To facilitate the development and reuse of custom transpilation code by the wider community of Qiskit users, the Qiskit SDK supports a plugin interface that enables third-party Python packages to declare that they provide extended transpilation functionality accessible via Qiskit.

Currently, third-party plugins can provide extended transpilation functionality in three ways:

• A transpiler stage plugin provides a pass manager that can be used in place of one of the 6 stages of a preset staged pass manager: init, layout, routing, translation, optimization, and scheduling.
• A unitary synthesis plugin provides extended functionality for unitary gate synthesis.
• A high-level synthesis plugin provides extended functionality for synthesizing "high-level objects" such as linear functions or Clifford operators. High-level objects are represented by subclasses of the Operation class.

The rest of the page describes how to list available plugins, install new ones, and use them.

List available plugins and install new ones

Qiskit already includes some built-in plugins for transpilation. To install more, you can use your Python package manager. For example, you might run pip install qiskit-toqm to install the Qiskit TOQM routing stage plugin. A number of third-party plugins are part of the Qiskit ecosystem.

List available transpiler stage plugins

Use the list_stage_plugins function, passing the name of the stage whose plugins you want to list.

from qiskit.transpiler.preset_passmanagers.plugin import list_stage_plugins
 
list_stage_plugins("layout")

Output:

['default', 'dense', 'sabre', 'trivial']

list_stage_plugins("routing")

Output:

['basic', 'lookahead', 'none', 'sabre', 'stochastic']

If qiskit-toqm were installed, then toqm would appear in the list of routing plugins.

List available unitary synthesis plugins

Use the unitary_synthesis_plugin_names function.

from qiskit.transpiler.passes.synthesis import unitary_synthesis_plugin_names
 
unitary_synthesis_plugin_names()

Output:

['aqc', 'default', 'sk']

List available high-level synthesis plugins

Use the high_level_synthesis_plugin_names function, passing the name of the type of "high-level object" to be synthesized. The name corresponds to the name attribute of the Operation class representing the type of object being synthesized.

from qiskit.transpiler.passes.synthesis import (
    high_level_synthesis_plugin_names,
)
 
high_level_synthesis_plugin_names("clifford")

Output:

['ag', 'bm', 'default', 'greedy', 'layers', 'lnn']

You can use the HighLevelSynthesisPluginManager class to list the names of all high-level synthesis plugins:

from qiskit.transpiler.passes.synthesis.plugin import (
    HighLevelSynthesisPluginManager,
)
 
HighLevelSynthesisPluginManager().plugins.names()

Output:

['clifford.ag',
 'clifford.bm',
 'clifford.default',
 'clifford.greedy',
 'clifford.layers',
 'clifford.lnn',
 'linear_function.default',
 'linear_function.kms',
 'linear_function.pmh',
 'permutation.acg',
 'permutation.basic',
 'permutation.default',
 'permutation.kms',
 'permutation.token_swapper',
 'qft.default',
 'qft.full',
 'qft.line']

Use a plugin

In this section, we show how to use transpiler plugins. In the code examples, we use plugins that come with Qiskit, but plugins installed from third-party packages are used the same way.

Use a transpiler stage plugin

To use a transpiler stage plugin, specify its name with the appropriate argument to generate_preset_pass_manager or transpile. The argument is formed by appending _method to the name of the transpilation stage. For example, to use the stochastic routing plugin, we would specify stochastic for the routing_method argument:

from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit_ibm_runtime import QiskitRuntimeService
 
service = QiskitRuntimeService()
backend = service.backend("ibm_brisbane")
 
pass_manager = generate_preset_pass_manager(
    optimization_level=3, backend=backend, routing_method="stochastic"
)

Use a unitary synthesis plugin

To use a unitary synthesis plugin, specify its name as the unitary_synthesis_method argument to generate_preset_pass_manager or transpile:

pass_manager = generate_preset_pass_manager(
    optimization_level=3,
    backend=backend,
    unitary_synthesis_method="sk",
    unitary_synthesis_plugin_config=dict(
        basis_gates=["cz", "id", "rz", "sx", "x"]
    ),
)

Unitary synthesis is used in the init, translation, and optimization stages of the staged pass manager returned by generate_preset_pass_manager or used in transpile. See Transpiler stages for a description of these stages.

Use the unitary_synthesis_plugin_config argument, a free-form dictionary, to pass options for the unitary synthesis method. The documentation of the synthesis method should explain the options it supports. See this list for links to the documentation of the built-in unitary synthesis plugins.

Use a high-level synthesis plugin

First, create an HLSConfig to store the names of the plugins to use for various high-level objects. For example:

from qiskit.transpiler.passes import HLSConfig
 
hls_config = HLSConfig(clifford=["layers"], linear_function=["pmh"])

This code cell creates a high-level synthesis configuration that uses the layers plugin for synthesizing Clifford objects and the pmh plugin for synthesizing LinearFunction objects. The names of the keyword arguments correspond to the name attribute of the Operation class representing the type of object being synthesized. For each high-level object, the list of given plugins are tried in sequence until one of them succeeds (in the example above, each list only contains a single plugin).

In addition to specifying a plugin by its name, you can instead pass a (name, options) tuple, where the second element of the tuple is a dictionary containing options for the plugin. The documentation of the synthesis method should explain the options it supports. See this list for links to the documentation of the built-in high-level synthesis plugins.

Once you have created the HLSConfig object, pass it as the hls_config argument to generate_preset_pass_manager or transpile:

pass_manager = generate_preset_pass_manager(
    optimization_level=3, backend=backend, hls_config=hls_config
)

High-level synthesis is used in the init, translation, and optimization stages of the staged pass manager returned by generate_preset_pass_manager or used in transpile. See Transpiler stages for a description of these stages.

Next steps