Transpiler Stage Plugin Interface

qiskit.transpiler.preset_passmanagers.plugin

This module defines the plugin interface for providing custom stage implementations for the preset pass managers and the transpile() function. This enables external Python packages to provide PassManager objects that can be used for each named stage.

The plugin interfaces are built using setuptools entry points which enable packages external to Qiskit to advertise they include a transpiler stage(s).

For details on how to instead write plugins for transpiler synthesis methods, see qiskit.transpiler.passes.synthesis.plugin.

Plugin Stages

There are six stages in the preset pass managers, all of which actively load external plugins using corresponding entry points. The following table summarizes each stage. For more details on the description and expectations of each stage, follow the link in the stages’ names to the full documentation.

Writing Plugins

To write a pass manager stage plugin there are 2 main steps. The first step is to create a subclass of the abstract plugin class PassManagerStagePlugin which is used to define how the PassManager for the stage will be constructed. For example, to create a layout stage plugin that just runs VF2Layout (with increasing amount of trials, depending on the optimization level) and falls back to using TrivialLayout if VF2Layout is unable to find a perfect layout:

from qiskit.transpiler.preset_passmanagers.plugin import PassManagerStagePlugin
from qiskit.transpiler.preset_passmanagers import common
from qiskit.transpiler import PassManager
from qiskit.transpiler.passes import VF2Layout, TrivialLayout
from qiskit.transpiler.passes.layout.vf2_layout import VF2LayoutStopReason
 
 
def _vf2_match_not_found(property_set):
    return property_set["layout"] is None or (
        property_set["VF2Layout_stop_reason"] is not None
        and property_set["VF2Layout_stop_reason"] is not VF2LayoutStopReason.SOLUTION_FOUND
 
 
class VF2LayoutPlugin(PassManagerStagePlugin):
 
    def pass_manager(self, pass_manager_config, optimization_level):
        layout_pm = PassManager(
            [
                VF2Layout(
                    coupling_map=pass_manager_config.coupling_map,
                    properties=pass_manager_config.backend_properties,
                    max_trials=optimization_level * 10 + 1
                    target=pass_manager_config.target
                )
            ]
        )
        layout_pm.append(
            TrivialLayout(pass_manager_config.coupling_map),
            condition=_vf2_match_not_found,
        )
        layout_pm += common.generate_embed_passmanager(pass_manager_config.coupling_map)
        return layout_pm

The second step is to expose the PassManagerStagePlugin subclass as a setuptools entry point in the package metadata. This can be done an entry-points table in pyproject.toml for the plugin package with the necessary entry points under the appropriate namespace for the stage your plugin is for. You can see the list of stages, entry points, and expectations from the stage in Plugin Stages. For example, continuing from the example plugin above:

[project.entry-points."qiskit.transpiler.layout"]
"vf2" = "qiskit_plugin_pkg.module.plugin:VF2LayoutPlugin"

There isn’t a limit to the number of plugins a single package can include as long as each plugin has a unique name. So a single package can expose multiple plugins if necessary. Refer to Plugin Stages for a list of reserved names for each stage.

Plugin API

list_stage_plugins

passmanager_stage_plugins

from qiskit.transpiler.preset_passmanagers.plugin import passmanager_stage_plugins
routing_plugins = passmanager_stage_plugins('routing')
basic_plugin = routing_plugins['basic']
help(basic_plugin)

Help on BasicSwapPassManager in module ...preset_passmanagers.builtin_plugins object:

class BasicSwapPassManager(...preset_passmanagers.plugin.PassManagerStagePlugin)
 |  Plugin class for routing stage with :class:`~.BasicSwap`
 |
 |  Method resolution order:
 |      BasicSwapPassManager
 |      ...preset_passmanagers.plugin.PassManagerStagePlugin
 |      abc.ABC
 |      builtins.object
 ...