Add stage plugin interface for transpile

docs/apidocs/terra.rst

@@ -36,6 +36,7 @@ Qiskit Terra API Reference
    transpiler_passes
    transpiler_preset
    transpiler_plugins
+   transpiler_synthesis_plugins
    transpiler_builtin_plugins
    utils
    utils_mitigation

docs/apidocs/transpiler_plugins.rst

@@ -1,6 +1,6 @@
 .. _qiskit-transpiler-plugins:
 
-.. automodule:: qiskit.transpiler.passes.synthesis.plugin
+.. automodule:: qiskit.transpiler.preset_passmanagers.plugin
    :no-members:
    :no-inherited-members:
    :no-special-members:

docs/apidocs/transpiler_synthesis_plugins.rst

@@ -0,0 +1,6 @@
+.. _qiskit-transpiler-synthesis-plugins:
+
+.. automodule:: qiskit.transpiler.passes.synthesis.plugin
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

qiskit/compiler/transpiler.py

@@ -80,6 +80,8 @@ def transpile(
     unitary_synthesis_method: str = "default",
     unitary_synthesis_plugin_config: dict = None,
     target: Target = None,
+    init_method: str = None,
+    optimization_method: str = None,
 ) -> Union[QuantumCircuit, List[QuantumCircuit]]:
     """Transpile one or more circuits, according to some desired transpilation targets.
 
@@ -150,17 +152,29 @@ def transpile(
 
                     [qr[0], None, None, qr[1], None, qr[2]]
 
-        layout_method: Name of layout selection pass ('trivial', 'dense', 'noise_adaptive', 'sabre')
+        layout_method: Name of layout selection pass ('trivial', 'dense', 'noise_adaptive', 'sabre').
+            This can also be the external plugin name to use for the ``layout`` stage.
+            You can see a list of installed plugins by using :func:`~.list_stage_plugins` with
+            ``"layout"`` for the ``stage_name`` argument.
         routing_method: Name of routing pass
             ('basic', 'lookahead', 'stochastic', 'sabre', 'toqm', 'none'). Note
             that to use method 'toqm', package 'qiskit-toqm' must be installed.
+            This can also be the external plugin name to use for the ``routing`` stage.
+            You can see a list of installed plugins by using :func:`~.list_stage_plugins` with
+            ``"routing"`` for the ``stage_name`` argument.
         translation_method: Name of translation pass ('unroller', 'translator', 'synthesis')
+            This can also be the external plugin name to use for the ``translation`` stage.
+            You can see a list of installed plugins by using :func:`~.list_stage_plugins` with
+            ``"translation"`` for the ``stage_name`` argument.
         scheduling_method: Name of scheduling pass.
             * ``'as_soon_as_possible'``: Schedule instructions greedily, as early as possible
             on a qubit resource. (alias: ``'asap'``)
             * ``'as_late_as_possible'``: Schedule instructions late, i.e. keeping qubits
             in the ground state when possible. (alias: ``'alap'``)
-            If ``None``, no scheduling will be done.
+            If ``None``, no scheduling will be done. This can also be the external plugin name
+            to use for the ``scheduling`` stage. You can see a list of installed plugins by
+            using :func:`~.list_stage_plugins` with ``"scheduling"`` for the ``stage_name``
+            argument.
         instruction_durations: Durations of instructions.
             Applicable only if scheduling_method is specified.
             The gate lengths defined in ``backend.properties`` are used as default.
@@ -246,6 +260,16 @@ def callback_func(**kwargs):
             the ``backend`` argument, but if you have manually constructed a
             :class:`~qiskit.transpiler.Target` object you can specify it manually here.
             This will override the target from ``backend``.
+        init_method: The plugin name to use for the ``init`` stage. By default an external
+            plugin is not used. You can see a list of installed plugins by
+            using :func:`~.list_stage_plugins` with ``"init"`` for the stage
+            name argument.
+        optimization_method: The plugin name to use for the
+            ``optimization`` stage. By default an external
+            plugin is not used. You can see a list of installed plugins by
+            using :func:`~.list_stage_plugins` with ``"optimization"`` for the
+            ``stage_name`` argument.
+
     Returns:
         The transpiled circuit(s).
 
@@ -310,6 +334,8 @@ def callback_func(**kwargs):
         unitary_synthesis_method,
         unitary_synthesis_plugin_config,
         target,
+        init_method,
+        optimization_method,
     )
     # Get transpile_args to configure the circuit transpilation job(s)
     if coupling_map in unique_transpile_args:
@@ -392,7 +418,7 @@ def _log_transpile_time(start_time, end_time):
 def _combine_args(shared_transpiler_args, unique_config):
     # Pop optimization_level to exclude it from the kwargs when building a
     # PassManagerConfig
-    level = shared_transpiler_args.pop("optimization_level")
+    level = shared_transpiler_args.get("optimization_level")
     pass_manager_config = shared_transpiler_args
     pass_manager_config.update(unique_config.pop("pass_manager_config"))
     pass_manager_config = PassManagerConfig(**pass_manager_config)
@@ -560,6 +586,8 @@ def _parse_transpile_args(
     unitary_synthesis_method,
     unitary_synthesis_plugin_config,
     target,
+    init_method,
+    optimization_method,
 ) -> Tuple[List[Dict], Dict]:
     """Resolve the various types of args allowed to the transpile() function through
     duck typing, overriding args, etc. Refer to the transpile() docstring for details on
@@ -627,6 +655,8 @@ def _parse_transpile_args(
     shared_dict = {
         "optimization_level": optimization_level,
         "basis_gates": basis_gates,
+        "init_method": init_method,
+        "optimization_method": optimization_method,
     }
 
     list_transpile_args = []

qiskit/transpiler/passes/synthesis/plugin.py

@@ -27,6 +27,10 @@
 which enable packages external to qiskit to advertise they include a synthesis
 plugin.
 
+See :mod:`qiskit.transpiler.preset_passmanagers.plugin` for details on how
+to write plugins for transpiler stages.
+
+
 Writing Plugins
 ===============
 

qiskit/transpiler/passmanager_config.py

@@ -39,6 +39,9 @@ def __init__(
         unitary_synthesis_method="default",
         unitary_synthesis_plugin_config=None,
         target=None,
+        init_method=None,
+        optimization_method=None,
+        optimization_level=None,
     ):
         """Initialize a PassManagerConfig object
 
@@ -50,12 +53,16 @@ def __init__(
             coupling_map (CouplingMap): Directed graph represented a coupling
                 map.
             layout_method (str): the pass to use for choosing initial qubit
-                placement.
+                placement. This will be the plugin name if an external layout stage
+                plugin is being used
             routing_method (str): the pass to use for routing qubits on the
-                architecture.
+                architecture. This will be a plugin name if an external routing stage
+                plugin is being used
             translation_method (str): the pass to use for translating gates to
-                basis_gates.
-            scheduling_method (str): the pass to use for scheduling instructions.
+                basis_gates. This will be a plugin name if an external translation stage
+                plugin is being used.
+            scheduling_method (str): the pass to use for scheduling instructions. This will
+                be a plugin name if an external scheduling stage plugin is being used.
             instruction_durations (InstructionDurations): Dictionary of duration
                 (in dt) for each instruction.
             backend_properties (BackendProperties): Properties returned by a
@@ -70,6 +77,10 @@ def __init__(
                 :class:`~qiskit.transpiler.passes.UnitarySynthesis` pass. Will
                 search installed plugins for a valid method.
             target (Target): The backend target
+            init_method (str): The plugin name for the init stage plugin to use
+            optimization_method (str): The plugin name for the optimization stage plugin
+                to use
+            optimization_level (int): The optimization level being used for compilation
         """
         self.initial_layout = initial_layout
         self.basis_gates = basis_gates
@@ -87,6 +98,9 @@ def __init__(
         self.unitary_synthesis_method = unitary_synthesis_method
         self.unitary_synthesis_plugin_config = unitary_synthesis_plugin_config
         self.target = target
+        self.init_method = init_method
+        self.optimization_method = optimization_method
+        self.optimization_level = optimization_level
 
     @classmethod
     def from_backend(cls, backend, **pass_manager_options):

qiskit/transpiler/preset_passmanagers/__init__.py

@@ -55,6 +55,8 @@ def generate_preset_pass_manager(
     seed_transpiler=None,
     unitary_synthesis_method="default",
     unitary_synthesis_plugin_config=None,
+    init_method=None,
+    optimization_method=None,
 ):
     """Generate a preset :class:`~.PassManager`
 
@@ -103,18 +105,30 @@ def generate_preset_pass_manager(
         layout_method (str): The :class:`~.Pass` to use for choosing initial qubit
             placement. Valid choices are ``'trivial'``, ``'dense'``, ``'noise_adaptive'``,
             and, ``'sabre'`` repsenting :class:`~.TrivialLayout`, :class:`~DenseLayout`,
-            :class:`~.NoiseAdaptiveLayout`, :class:`~.SabreLayout` respectively.
+            :class:`~.NoiseAdaptiveLayout`, :class:`~.SabreLayout` respectively. This can also
+            be the external plugin name to use for the ``layout`` stage of the output
+            :class:`~.StagedPassManager`. You can see a list of installed plugins by using
+            :func:`~.list_stage_plugins` with ``"layout"`` for the ``stage_name`` argument.
         routing_method (str): The pass to use for routing qubits on the
             architecture. Valid choices are ``'basic'``, ``'lookahead'``, ``'stochastic'``,
             ``'sabre'``, and ``'none'`` representing :class:`~.BasicSwap`,
             :class:`~.LookaheadSwap`, :class:`~.StochasticSwap`, :class:`~.SabreSwap`, and
-            erroring if routing is required respectively.
+            erroring if routing is required respectively. This can also be the external plugin
+            name to use for the ``routing`` stage of the output :class:`~.StagedPassManager`.
+            You can see a list of installed plugins by using :func:`~.list_stage_plugins` with
+            ``"routing"`` for the ``stage_name`` argument.
         translation_method (str): The method to use for translating gates to
             basis gates. Valid choices ``'unroller'``, ``'translator'``, ``'synthesis'``
             representing :class:`~.Unroller`, :class:`~.BasisTranslator`, and
-            :class:`~.UnitarySynthesis` respectively.
+            :class:`~.UnitarySynthesis` respectively. This can also be the external plugin
+            name to use for the ``translation`` stage of the output :class:`~.StagedPassManager`.
+            You can see a list of installed plugins by using :func:`~.list_stage_plugins` with
+            ``"translation"`` for the ``stage_name`` argument.
         scheduling_method (str): The pass to use for scheduling instructions. Valid choices
-            are ``'alap'`` and ``'asap'``.
+            are ``'alap'`` and ``'asap'``. This can also be the external plugin name to use
+            for the ``scheduling`` stage of the output :class:`~.StagedPassManager`. You can
+            see a list of installed plugins by using :func:`~.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.
@@ -134,6 +148,17 @@ def generate_preset_pass_manager(
             the ``unitary_synthesis`` argument. As this is custom for each
             unitary synthesis plugin refer to the plugin documentation for how
             to use this option.
+        init_method (str): The plugin name to use for the ``init`` stage of
+            the output :class:`~.StagedPassManager`. By default an external
+            plugin is not used. You can see a list of installed plugins by
+            using :func:`~.list_stage_plugins` with ``"init"`` for the stage
+            name argument.
+        optimization_method (str): The plugin name to use for the
+            ``optimization`` stage of the output
+            :class:`~.StagedPassManager`. By default an external
+            plugin is not used. You can see a list of installed plugins by
+            using :func:`~.list_stage_plugins` with ``"optimization"`` for the
+            ``stage_name`` argument.
 
     Returns:
         StagedPassManager: The preset pass manager for the given options
@@ -172,6 +197,9 @@ def generate_preset_pass_manager(
         unitary_synthesis_method=unitary_synthesis_method,
         unitary_synthesis_plugin_config=unitary_synthesis_plugin_config,
         initial_layout=initial_layout,
+        init_method=init_method,
+        optimization_method=optimization_method,
+        optimization_level=optimization_level,
     )
 
     if backend is not None: