scnc
/
qiskit-documentation
mirror of https://github.com/Qiskit/documentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
qiskit-documentation/docs/api/qiskit/dev/transpiler_plugins.mdx

164 lines
12 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: plugin (dev version)
description: API reference for qiskit.transpiler.preset_passmanagers.plugin in the dev version of qiskit
in_page_toc_min_heading_level: 2
python_api_type: module
python_api_name: qiskit.transpiler.preset_passmanagers.plugin
---
<span id="module-qiskit.transpiler.preset_passmanagers.plugin" />
<span id="qiskit-transpiler-plugins" />
<span id="transpiler-stage-plugin-interface-qiskit-transpiler-preset-passmanagers-plugin" />
<span id="transpiler-preset-stage-plugins" />
# 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()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function. This enables external Python packages to provide [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") objects that can be used for each named stage.
The plugin interfaces are built using setuptools [entry points](https://setuptools.readthedocs.io/en/latest/userguide/entry_point.html) 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`](transpiler_synthesis_plugins#module-qiskit.transpiler.passes.synthesis.plugin "qiskit.transpiler.passes.synthesis.plugin").
<span id="stage-table" />
## 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.
| Stage Name | Entry Point | Reserved Names | Summary |
| --------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [init](transpiler#transpiler-preset-stage-init) | `qiskit.transpiler.init` | `default` | High-level, logical optimizations on abstract circuits, and reduction of multi-qubit operations to one- and two-qubit operations. |
| [layout](transpiler#transpiler-preset-stage-layout) | `qiskit.transpiler.layout` | `trivial`, `dense`, `sabre`, `default` | Choose an initial mapping of virtual qubits to physical qubits, including expansion of the circuit to include explicit ancillas. This stage is sometimes combined with `routing`. |
| [routing](transpiler#transpiler-preset-stage-routing) | `qiskit.transpiler.routing` | `default`, `basic`, `stochastic`, `lookahead`, `sabre` | Insert gates into the circuit to ensure it matches the connectivity constraints of the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"). The inserted gates do not need to be in the target ISA yet, so are often just output as `swap` instructions. This stage is sometimes subsumed by `layout`. |
| [translation](transpiler#transpiler-preset-stage-translation) | `qiskit.transpiler.translation` | `default`, `translator`, `synthesis` | Rewrite all gates outside the target ISA to use only gates within the ISA. |
| [optimization](transpiler#transpiler-preset-stage-optimization) | `qiskit.transpiler.optimization` | `default` | Low-level, physical-circuit-aware optimizations. Unlike `init`, the `optimization` stage acts at the level of a physical circuit. |
| [scheduling](transpiler#transpiler-preset-stage-scheduling) | `qiskit.transpiler.scheduling` | `alap`, `asap`, `default` | Insert [`Delay`](circuit#qiskit.circuit.Delay "qiskit.circuit.Delay") instructions to make the wall-clock timing of the circuit fully explicit. |
## 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`](qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin "qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin") which is used to define how the [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") for the stage will be constructed. For example, to create a `layout` stage plugin that just runs [`VF2Layout`](qiskit.transpiler.passes.VF2Layout "qiskit.transpiler.passes.VF2Layout") (with increasing amount of trials, depending on the optimization level) and falls back to using [`TrivialLayout`](qiskit.transpiler.passes.TrivialLayout "qiskit.transpiler.passes.TrivialLayout") if `VF2Layout` is unable to find a perfect layout:
```python
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`](qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin "qiskit.transpiler.preset_passmanagers.plugin.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](#stage-table). For example, continuing from the example plugin above:
```toml
[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](#stage-table) for a list of reserved names for each stage.
## Plugin API
| | |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`PassManagerStagePlugin`](qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin "qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePlugin")() | A `PassManagerStagePlugin` is a plugin interface object for using custom stages in [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile"). |
| [`PassManagerStagePluginManager`](qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager "qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager")() | Manager class for preset pass manager stage plugins. |
### list\_stage\_plugins
<Function id="qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins" github="https://github.com/Qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/plugin.py#L274-L300" signature="qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins(stage_name)">
Get a list of installed plugins for a stage.
**Parameters**
**stage\_name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – The stage name to get the plugin names for
**Returns**
The list of installed plugin names for the specified stages
**Return type**
plugins
**Raises**
[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If an invalid stage name is specified.
</Function>
### passmanager\_stage\_plugins
<Function id="qiskit.transpiler.preset_passmanagers.plugin.passmanager_stage_plugins" github="https://github.com/Qiskit/qiskit/tree/main/qiskit/transpiler/preset_passmanagers/plugin.py#L303-L346" signature="qiskit.transpiler.preset_passmanagers.plugin.passmanager_stage_plugins(stage)">
Return a dict with, for each stage name, the class type of the plugin.
This function is useful for getting more information about a plugin:
```python
from qiskit.transpiler.preset_passmanagers.plugin import passmanager_stage_plugins
routing_plugins = passmanager_stage_plugins('routing')
basic_plugin = routing_plugins['basic']
help(basic_plugin)
```
```text
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
...
```
**Parameters**
**stage** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – The stage name to get
**Returns**
the key is the name of the plugin and the value is the class type for each.
**Return type**
[dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")
**Raises**
[**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – If an invalid stage name is specified.
</Function>
Reference in New Issue View Git Blame Copy Permalink