qiskit 1.3.0__cp39-abi3-macosx_11_0_arm64.whl

qiskit/transpiler/passes/synthesis/high_level_synthesis.py

@@ -0,0 +1,854 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022, 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+High-level-synthesis transpiler pass.
+"""
+
+from __future__ import annotations
+
+import typing
+from functools import partial
+from collections.abc import Callable
+
+import numpy as np
+
+from qiskit.circuit.annotated_operation import Modifier
+from qiskit.circuit.operation import Operation
+from qiskit.circuit.instruction import Instruction
+from qiskit.converters import circuit_to_dag, dag_to_circuit
+from qiskit.transpiler.basepasses import TransformationPass
+from qiskit.circuit.quantumcircuit import QuantumCircuit
+from qiskit.circuit import ControlledGate, EquivalenceLibrary, equivalence, Qubit
+from qiskit.transpiler.passes.utils import control_flow
+from qiskit.transpiler.target import Target
+from qiskit.transpiler.coupling import CouplingMap
+from qiskit.dagcircuit.dagcircuit import DAGCircuit
+from qiskit.transpiler.exceptions import TranspilerError
+
+from qiskit.circuit.annotated_operation import (
+    AnnotatedOperation,
+    InverseModifier,
+    ControlModifier,
+    PowerModifier,
+)
+
+from qiskit._accelerate.high_level_synthesis import QubitTracker, QubitContext
+from .plugin import HighLevelSynthesisPluginManager
+
+if typing.TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGOpNode
+
+
+class HLSConfig:
+    """The high-level-synthesis config allows to specify a list of "methods" used by
+    :class:`~.HighLevelSynthesis` transformation pass to synthesize different types
+    of higher-level objects.
+
+    A higher-level object is an object of type :class:`~.Operation` (e.g., :class:`.Clifford` or
+    :class:`.LinearFunction`).  Each object is referred to by its :attr:`~.Operation.name` field
+    (e.g., ``"clifford"`` for :class:`.Clifford` objects), and the applicable synthesis methods are
+    tied to this name.
+
+    In the config, each method is specified in one of several ways:
+
+    1. a tuple consisting of the name of a known synthesis plugin and a dictionary providing
+       additional arguments for the algorithm.
+    2. a tuple consisting of an instance of :class:`.HighLevelSynthesisPlugin` and additional
+       arguments for the algorithm.
+    3. a single string of a known synthesis plugin
+    4. a single instance of :class:`.HighLevelSynthesisPlugin`.
+
+    The following example illustrates different ways how a config file can be created::
+
+        from qiskit.transpiler.passes.synthesis.high_level_synthesis import HLSConfig
+        from qiskit.transpiler.passes.synthesis.high_level_synthesis import ACGSynthesisPermutation
+
+        # All the ways to specify hls_config are equivalent
+        hls_config = HLSConfig(permutation=[("acg", {})])
+        hls_config = HLSConfig(permutation=["acg"])
+        hls_config = HLSConfig(permutation=[(ACGSynthesisPermutation(), {})])
+        hls_config = HLSConfig(permutation=[ACGSynthesisPermutation()])
+
+    The names of the synthesis plugins should be declared in ``entry-points`` table for
+    ``qiskit.synthesis`` in ``pyproject.toml``, in the form
+    <higher-level-object-name>.<synthesis-method-name>.
+
+    The standard higher-level-objects are recommended to have a synthesis method
+    called "default", which would be called automatically when synthesizing these objects,
+    without having to explicitly set these methods in the config.
+
+    To avoid synthesizing a given higher-level-object, one can give it an empty list of methods.
+
+    For an explicit example of using such config files, refer to the documentation for
+    :class:`~.HighLevelSynthesis`.
+
+    For an overview of the complete process of using high-level synthesis, see
+    :ref:`using-high-level-synthesis-plugins`.
+    """
+
+    def __init__(
+        self,
+        use_default_on_unspecified: bool = True,
+        plugin_selection: str = "sequential",
+        plugin_evaluation_fn: Callable[[QuantumCircuit], int] | None = None,
+        **kwargs,
+    ):
+        """Creates a high-level-synthesis config.
+
+        Args:
+            use_default_on_unspecified: if True, every higher-level-object without an
+                explicitly specified list of methods will be synthesized using the "default"
+                algorithm if it exists.
+            plugin_selection: if set to ``"sequential"`` (default), for every higher-level-object
+                the synthesis pass will consider the specified methods sequentially, stopping
+                at the first method that is able to synthesize the object. If set to ``"all"``,
+                all the specified methods will be considered, and the best synthesized circuit,
+                according to ``plugin_evaluation_fn`` will be chosen.
+            plugin_evaluation_fn: a callable that evaluates the quality of the synthesized
+                quantum circuit; a smaller value means a better circuit. If ``None``, the
+                quality of the circuit its size (i.e. the number of gates that it contains).
+            kwargs: a dictionary mapping higher-level-objects to lists of synthesis methods.
+        """
+        self.use_default_on_unspecified = use_default_on_unspecified
+        self.plugin_selection = plugin_selection
+        self.plugin_evaluation_fn = (
+            plugin_evaluation_fn if plugin_evaluation_fn is not None else lambda qc: qc.size()
+        )
+        self.methods = {}
+
+        for key, value in kwargs.items():
+            self.set_methods(key, value)
+
+    def set_methods(self, hls_name, hls_methods):
+        """Sets the list of synthesis methods for a given higher-level-object. This overwrites
+        the lists of methods if also set previously."""
+        self.methods[hls_name] = hls_methods
+
+
+class HighLevelSynthesis(TransformationPass):
+    r"""Synthesize higher-level objects and unroll custom definitions.
+
+    The input to this pass is a DAG that may contain higher-level objects,
+    including abstract mathematical objects (e.g., objects of type :class:`.LinearFunction`),
+    annotated operations (objects of type :class:`.AnnotatedOperation`), and
+    custom gates.
+
+    In the most common use-case when either ``basis_gates`` or ``target`` is specified,
+    all higher-level objects are synthesized, so the output is a :class:`.DAGCircuit`
+    without such objects.
+    More precisely, every gate in the output DAG is either directly supported by the target,
+    or is in ``equivalence_library``.
+
+    The abstract mathematical objects are synthesized using synthesis plugins, applying
+    synthesis methods specified in the high-level-synthesis config (refer to the documentation
+    for :class:`~.HLSConfig`).
+
+    As an example, let us assume that ``op_a`` and ``op_b`` are names of two higher-level objects,
+    that ``op_a``-objects have two synthesis methods ``default`` which does require any additional
+    parameters and ``other`` with two optional integer parameters ``option_1`` and ``option_2``,
+    that ``op_b``-objects have a single synthesis method ``default``, and ``qc`` is a quantum
+    circuit containing ``op_a`` and ``op_b`` objects. The following code snippet::
+
+        hls_config = HLSConfig(op_b=[("other", {"option_1": 7, "option_2": 4})])
+        pm = PassManager([HighLevelSynthesis(hls_config=hls_config)])
+        transpiled_qc = pm.run(qc)
+
+    shows how to run the alternative synthesis method ``other`` for ``op_b``-objects, while using the
+    ``default`` methods for all other high-level objects, including ``op_a``-objects.
+
+    The annotated operations (consisting of a base operation and a list of inverse, control and power
+    modifiers) are synthesizing recursively, first synthesizing the base operation, and then applying
+    synthesis methods for creating inverted, controlled, or powered versions of that).
+
+    The custom gates are synthesized by recursively unrolling their definitions, until every gate
+    is either supported by the target or is in the equivalence library.
+
+    When neither ``basis_gates`` nor ``target`` is specified, the pass synthesizes only the top-level
+    abstract mathematical objects and annotated operations, without descending into the gate
+    ``definitions``. This is consistent with the older behavior of the pass, allowing to synthesize
+    some higher-level objects using plugins and leaving the other gates untouched.
+
+    The high-level-synthesis passes information about available auxiliary qubits, and whether their
+    state is clean (defined as :math:`|0\rangle`) or dirty (unknown state) to the synthesis routine
+    via the respective arguments ``"num_clean_ancillas"`` and ``"num_dirty_ancillas"``.
+    If ``qubits_initially_zero`` is ``True`` (default), the qubits are assumed to be in the
+    :math:`|0\rangle` state. When appending a synthesized block using auxiliary qubits onto the
+    circuit, we first use the clean auxiliary qubits.
+
+    .. note::
+
+        Synthesis methods are assumed to maintain the state of the auxiliary qubits.
+        Concretely this means that clean auxiliary qubits must still be in the :math:`|0\rangle`
+        state after the synthesized block, while dirty auxiliary qubits are re-used only
+        as dirty qubits.
+
+    """
+
+    def __init__(
+        self,
+        hls_config: HLSConfig | None = None,
+        coupling_map: CouplingMap | None = None,
+        target: Target | None = None,
+        use_qubit_indices: bool = False,
+        equivalence_library: EquivalenceLibrary | None = None,
+        basis_gates: list[str] | None = None,
+        min_qubits: int = 0,
+        qubits_initially_zero: bool = True,
+    ):
+        r"""
+        HighLevelSynthesis initializer.
+
+        Args:
+            hls_config: Optional, the high-level-synthesis config that specifies synthesis methods
+                and parameters for various high-level-objects in the circuit. If it is not specified,
+                the default synthesis methods and parameters will be used.
+            coupling_map: Optional, directed graph represented as a coupling map.
+            target: Optional, the backend target to use for this pass. If it is specified,
+                it will be used instead of the coupling map.
+            use_qubit_indices: a flag indicating whether this synthesis pass is running before or after
+                the layout is set, that is, whether the qubit indices of higher-level-objects correspond
+                to qubit indices on the target backend.
+            equivalence_library: The equivalence library used (instructions in this library will not
+                be unrolled by this pass).
+            basis_gates: Optional, target basis names to unroll to, e.g. `['u3', 'cx']`.
+                Ignored if ``target`` is also specified.
+            min_qubits: The minimum number of qubits for operations in the input
+                dag to translate.
+            qubits_initially_zero: Indicates whether the qubits are initially in the state
+                :math:`|0\rangle`. This allows the high-level-synthesis to use clean auxiliary qubits
+                (i.e. in the zero state) to synthesize an operation.
+        """
+        super().__init__()
+
+        if hls_config is not None:
+            self.hls_config = hls_config
+        else:
+            # When the config file is not provided, we will use the "default" method
+            # to synthesize Operations (when available).
+            self.hls_config = HLSConfig(True)
+
+        self.hls_plugin_manager = HighLevelSynthesisPluginManager()
+        self._coupling_map = coupling_map
+        self._target = target
+        self._use_qubit_indices = use_qubit_indices
+        self.qubits_initially_zero = qubits_initially_zero
+        if target is not None:
+            self._coupling_map = self._target.build_coupling_map()
+        self._equiv_lib = equivalence_library
+        self._basis_gates = basis_gates
+        self._min_qubits = min_qubits
+
+        self._top_level_only = self._basis_gates is None and self._target is None
+
+        # include path for when target exists but target.num_qubits is None (BasicSimulator)
+        if not self._top_level_only and (self._target is None or self._target.num_qubits is None):
+            basic_insts = {"measure", "reset", "barrier", "snapshot", "delay", "store"}
+            self._device_insts = basic_insts | set(self._basis_gates)
+        else:
+            self._device_insts = set()
+
+    def run(self, dag: DAGCircuit) -> DAGCircuit:
+        """Run the HighLevelSynthesis pass on `dag`.
+
+        Args:
+            dag: input dag.
+
+        Returns:
+            Output dag with higher-level operations synthesized.
+
+        Raises:
+            TranspilerError: when the transpiler is unable to synthesize the given DAG
+            (for instance, when the specified synthesis method is not available).
+        """
+        qubits = tuple(dag.find_bit(q).index for q in dag.qubits)
+        context = QubitContext(list(range(len(dag.qubits))))
+        tracker = QubitTracker(num_qubits=dag.num_qubits())
+        if self.qubits_initially_zero:
+            tracker.set_clean(context.to_globals(qubits))
+
+        out_dag = self._run(dag, tracker, context, use_ancillas=True, top_level=True)
+        return out_dag
+
+    def _run(
+        self,
+        dag: DAGCircuit,
+        tracker: QubitTracker,
+        context: QubitContext,
+        use_ancillas: bool,
+        top_level: bool,
+    ) -> DAGCircuit:
+        """
+        The main recursive function that synthesizes a DAGCircuit.
+
+        Input:
+            dag: the DAG to be synthesized.
+            tracker: the global tracker, tracking the state of original qubits.
+            context: the correspondence between the dag's qubits and the global qubits.
+            use_ancillas: if True, synthesis algorithms are allowed to use ancillas.
+            top_level: specifies if this is the top-level of the recursion.
+
+        The function returns the synthesized DAG.
+
+        Note that by using the auxiliary qubits to synthesize operations present in the input DAG,
+        the synthesized DAG may be defined over more qubits than the input DAG. In this case,
+        the function update in-place the global qubits tracker and extends the local-to-global
+        context.
+        """
+
+        if dag.num_qubits() != context.num_qubits():
+            raise TranspilerError("HighLevelSynthesis internal error.")
+
+        # STEP 1: Check if HighLevelSynthesis can be skipped altogether. This is only
+        # done at the top-level since this does not update the global qubits tracker.
+        if top_level:
+            for node in dag.op_nodes():
+                qubits = tuple(dag.find_bit(q).index for q in node.qargs)
+                if not self._definitely_skip_node(node, qubits, dag):
+                    break
+            else:
+                # The for-loop terminates without reaching the break statement
+                if dag.num_qubits() != context.num_qubits():
+                    raise TranspilerError("HighLevelSynthesis internal error.")
+                return dag
+
+        # STEP 2: Analyze the nodes in the DAG. For each node in the DAG that needs
+        # to be synthesized, we recursively synthesize it and store the result. For
+        # instance, the result of synthesizing a custom gate is a DAGCircuit corresponding
+        # to the (recursively synthesized) gate's definition. When the result is a
+        # DAG, we also store its context (the mapping of its qubits to global qubits).
+        # In addition, we keep track of the qubit states using the (global) qubits tracker.
+        #
+        # Note: This is a first version of a potentially more elaborate approach to find
+        # good operation/ancilla allocations. The current approach is greedy and just gives
+        # all available ancilla qubits to the current operation ("the-first-takes-all" approach).
+        # It does not distribute ancilla qubits between different operations present in the DAG.
+        synthesized_nodes = {}
+
+        for node in dag.topological_op_nodes():
+            qubits = tuple(dag.find_bit(q).index for q in node.qargs)
+            processed = False
+            synthesized = None
+            synthesized_context = None
+
+            # Start by handling special operations. Other cases can also be
+            # considered: swaps, automatically simplifying control gate (e.g. if
+            # a control is 0).
+            if node.op.name in ["id", "delay", "barrier"]:
+                # tracker not updated, these are no-ops
+                processed = True
+
+            elif node.op.name == "reset":
+                # reset qubits to 0
+                tracker.set_clean(context.to_globals(qubits))
+                processed = True
+
+            # check if synthesis for the operation can be skipped
+            elif self._definitely_skip_node(node, qubits, dag):
+                tracker.set_dirty(context.to_globals(qubits))
+
+            # next check control flow
+            elif node.is_control_flow():
+                inner_context = context.restrict(qubits)
+                synthesized = control_flow.map_blocks(
+                    partial(
+                        self._run,
+                        tracker=tracker,
+                        context=inner_context,
+                        use_ancillas=False,
+                        top_level=False,
+                    ),
+                    node.op,
+                )
+
+            # now we are free to synthesize
+            else:
+                # This returns the synthesized operation and its context (when the result is
+                # a DAG, it's the correspondence between its qubits and the global qubits).
+                # Also note that the DAG may use auxiliary qubits. The qubits tracker and the
+                # current DAG's context are updated in-place.
+                synthesized, synthesized_context = self._synthesize_operation(
+                    node.op, qubits, tracker, context, use_ancillas=use_ancillas
+                )
+
+            # If the synthesis changed the operation (i.e. it is not None), store the result.
+            if synthesized is not None:
+                synthesized_nodes[node._node_id] = (synthesized, synthesized_context)
+
+            # If the synthesis did not change anything, just update the qubit tracker.
+            elif not processed:
+                tracker.set_dirty(context.to_globals(qubits))
+
+        # We did not change anything just return the input.
+        if len(synthesized_nodes) == 0:
+            if dag.num_qubits() != context.num_qubits():
+                raise TranspilerError("HighLevelSynthesis internal error.")
+            return dag
+
+        # STEP 3. We rebuild the DAG with new operations. Note that we could also
+        # check if no operation changed in size and substitute in-place, but rebuilding is
+        # generally as fast or faster, unless very few operations are changed.
+        out = dag.copy_empty_like()
+        num_additional_qubits = context.num_qubits() - out.num_qubits()
+
+        if num_additional_qubits > 0:
+            out.add_qubits([Qubit() for _ in range(num_additional_qubits)])
+
+        index_to_qubit = dict(enumerate(out.qubits))
+        outer_to_local = context.to_local_mapping()
+
+        for node in dag.topological_op_nodes():
+
+            if op_tuple := synthesized_nodes.get(node._node_id, None):
+                op, op_context = op_tuple
+
+                if isinstance(op, Operation):
+                    out.apply_operation_back(op, node.qargs, node.cargs)
+                    continue
+
+                if isinstance(op, QuantumCircuit):
+                    op = circuit_to_dag(op, copy_operations=False)
+
+                inner_to_global = op_context.to_global_mapping()
+                if isinstance(op, DAGCircuit):
+                    qubit_map = {
+                        q: index_to_qubit[outer_to_local[inner_to_global[i]]]
+                        for (i, q) in enumerate(op.qubits)
+                    }
+                    clbit_map = dict(zip(op.clbits, node.cargs))
+
+                    for sub_node in op.op_nodes():
+                        out.apply_operation_back(
+                            sub_node.op,
+                            tuple(qubit_map[qarg] for qarg in sub_node.qargs),
+                            tuple(clbit_map[carg] for carg in sub_node.cargs),
+                        )
+                    out.global_phase += op.global_phase
+
+                else:
+                    raise TranspilerError(f"Unexpected synthesized type: {type(op)}")
+            else:
+                out.apply_operation_back(node.op, node.qargs, node.cargs, check=False)
+
+        if out.num_qubits() != context.num_qubits():
+            raise TranspilerError("HighLevelSynthesis internal error.")
+
+        return out
+
+    def _synthesize_operation(
+        self,
+        operation: Operation,
+        qubits: tuple[int],
+        tracker: QubitTracker,
+        context: QubitContext,
+        use_ancillas: bool,
+    ) -> tuple[QuantumCircuit | Operation | DAGCircuit | None, QubitContext | None]:
+        """
+        Synthesizes an operation. The function receives the qubits on which the operation
+        is defined in the current DAG, the correspondence between the qubits of the current
+        DAG and the global qubits and the global qubits tracker. The function returns the
+        result of synthesizing the operation. The value of `None` means that the operation
+        should remain as it is. When it's a circuit, we also return the context, i.e. the
+        correspondence of its local qubits and the global qubits. The function changes
+        in-place the tracker (state of the global qubits), the qubits (when the synthesized
+        operation is defined over additional ancilla qubits), and the context (to keep track
+        of where these ancilla qubits maps to).
+        """
+
+        synthesized_context = None
+
+        # Try to synthesize the operation. We'll go through the following options:
+        #  (1) Annotations: if the operator is annotated, synthesize the base operation
+        #       and then apply the modifiers. Returns a circuit (e.g. applying a power)
+        #       or operation (e.g adding control on an X gate).
+        #  (2) High-level objects: try running the battery of high-level synthesis plugins (e.g.
+        #       if the operation is a Clifford). Returns a circuit.
+        #  (3) Unrolling custom definitions: try defining the operation if it is not yet
+        #       in the set of supported instructions. Returns a circuit.
+        #
+        # If any of the above were triggered, we will recurse and go again through these steps
+        # until no further change occurred. At this point, we convert circuits to DAGs (the final
+        # possible return type). If there was no change, we just return ``None``.
+        num_original_qubits = len(qubits)
+        qubits = list(qubits)
+
+        synthesized = None
+
+        # Try synthesizing via AnnotatedOperation. This is faster than an isinstance check
+        # but a bit less safe since someone could create operations with a ``modifiers`` attribute.
+        if len(modifiers := getattr(operation, "modifiers", [])) > 0:
+            # Note: the base operation must be synthesized without using potential control qubits
+            # used in the modifiers.
+            num_ctrl = sum(
+                mod.num_ctrl_qubits for mod in modifiers if isinstance(mod, ControlModifier)
+            )
+            baseop_qubits = qubits[num_ctrl:]  # reminder: control qubits are the first ones
+
+            # get qubits of base operation
+            control_qubits = qubits[0:num_ctrl]
+
+            # Do not allow access to control qubits
+            tracker.disable(context.to_globals(control_qubits))
+            synthesized_base_op, _ = self._synthesize_operation(
+                operation.base_op,
+                baseop_qubits,
+                tracker,
+                context,
+                use_ancillas=use_ancillas,
+            )
+
+            if synthesized_base_op is None:
+                synthesized_base_op = operation.base_op
+            elif isinstance(synthesized_base_op, DAGCircuit):
+                synthesized_base_op = dag_to_circuit(synthesized_base_op)
+
+            # Handle the case that synthesizing the base operation introduced
+            # additional qubits (e.g. the base operation is a circuit that includes
+            # an MCX gate).
+            if synthesized_base_op.num_qubits > len(baseop_qubits):
+                global_aux_qubits = tracker.borrow(
+                    synthesized_base_op.num_qubits - len(baseop_qubits),
+                    context.to_globals(baseop_qubits),
+                )
+                global_to_local = context.to_local_mapping()
+                for aq in global_aux_qubits:
+                    if aq in global_to_local:
+                        qubits.append(global_to_local[aq])
+                    else:
+                        new_local_qubit = context.add_qubit(aq)
+                        qubits.append(new_local_qubit)
+            # Restore access to control qubits.
+            tracker.enable(context.to_globals(control_qubits))
+
+            # This step currently does not introduce ancilla qubits.
+            synthesized = self._apply_annotations(synthesized_base_op, operation.modifiers)
+
+        # If it was no AnnotatedOperation, try synthesizing via HLS or by unrolling.
+        else:
+            # Try synthesis via HLS -- which will return ``None`` if unsuccessful.
+            indices = qubits if self._use_qubit_indices else None
+            if len(hls_methods := self._methods_to_try(operation.name)) > 0:
+                if use_ancillas:
+                    num_clean_available = tracker.num_clean(context.to_globals(qubits))
+                    num_dirty_available = tracker.num_dirty(context.to_globals(qubits))
+                else:
+                    num_clean_available = 0
+                    num_dirty_available = 0
+                synthesized = self._synthesize_op_using_plugins(
+                    hls_methods,
+                    operation,
+                    indices,
+                    num_clean_available,
+                    num_dirty_available,
+                )
+
+                # It may happen that the plugin synthesis method uses clean/dirty ancilla qubits
+                if (synthesized is not None) and (synthesized.num_qubits > len(qubits)):
+                    # need to borrow more qubits from tracker
+                    global_aux_qubits = tracker.borrow(
+                        synthesized.num_qubits - len(qubits), context.to_globals(qubits)
+                    )
+                    global_to_local = context.to_local_mapping()
+
+                    for aq in global_aux_qubits:
+                        if aq in global_to_local:
+                            qubits.append(global_to_local[aq])
+                        else:
+                            new_local_qubit = context.add_qubit(aq)
+                            qubits.append(new_local_qubit)
+
+            # If HLS did not apply, or was unsuccessful, try unrolling custom definitions.
+            if synthesized is None and not self._top_level_only:
+                synthesized = self._get_custom_definition(operation, indices)
+
+        if synthesized is None:
+            # if we didn't synthesize, there was nothing to unroll
+            # updating the tracker will be handled upstream
+            pass
+
+        # if it has been synthesized, recurse and finally store the decomposition
+        elif isinstance(synthesized, Operation):
+            resynthesized, resynthesized_context = self._synthesize_operation(
+                synthesized, qubits, tracker, context, use_ancillas=use_ancillas
+            )
+
+            if resynthesized is not None:
+                synthesized = resynthesized
+            else:
+                tracker.set_dirty(context.to_globals(qubits))
+            if isinstance(resynthesized, DAGCircuit):
+                synthesized_context = resynthesized_context
+
+        elif isinstance(synthesized, QuantumCircuit):
+            # Synthesized is a quantum circuit which we want to process recursively.
+            # For example, it's the definition circuit of a custom gate
+            # or a circuit obtained by calling a synthesis method on a high-level-object.
+            # In the second case, synthesized may have more qubits than the original node.
+
+            as_dag = circuit_to_dag(synthesized, copy_operations=False)
+            inner_context = context.restrict(qubits)
+
+            if as_dag.num_qubits() != inner_context.num_qubits():
+                raise TranspilerError("HighLevelSynthesis internal error.")
+
+            # We save the current state of the tracker to be able to return the ancilla
+            # qubits to the current positions. Note that at this point we do not know
+            # which ancilla qubits will be allocated.
+            saved_tracker = tracker.copy()
+            synthesized = self._run(
+                as_dag, tracker, inner_context, use_ancillas=use_ancillas, top_level=False
+            )
+            synthesized_context = inner_context
+
+            if (synthesized is not None) and (synthesized.num_qubits() > len(qubits)):
+                # need to borrow more qubits from tracker
+                global_aux_qubits = tracker.borrow(
+                    synthesized.num_qubits() - len(qubits), context.to_globals(qubits)
+                )
+                global_to_local = context.to_local_mapping()
+
+                for aq in global_aux_qubits:
+                    if aq in global_to_local:
+                        qubits.append(global_to_local[aq])
+                    else:
+                        new_local_qubit = context.add_qubit(aq)
+                        qubits.append(new_local_qubit)
+
+            if len(qubits) > num_original_qubits:
+                tracker.replace_state(
+                    saved_tracker, context.to_globals(qubits[num_original_qubits:])
+                )
+
+        else:
+            raise TranspilerError(f"Unexpected synthesized type: {type(synthesized)}")
+
+        if isinstance(synthesized, DAGCircuit) and synthesized_context is None:
+            raise TranspilerError("HighLevelSynthesis internal error.")
+
+        return synthesized, synthesized_context
+
+    def _get_custom_definition(
+        self, inst: Instruction, qubits: list[int] | None
+    ) -> QuantumCircuit | None:
+        # check if the operation is already supported natively
+        if not (isinstance(inst, ControlledGate) and inst._open_ctrl):
+            # include path for when target exists but target.num_qubits is None (BasicSimulator)
+            inst_supported = self._instruction_supported(inst.name, qubits)
+            if inst_supported or (self._equiv_lib is not None and self._equiv_lib.has_entry(inst)):
+                return None  # we support this operation already
+
+        # if not, try to get the definition
+        try:
+            definition = inst.definition
+        except (TypeError, AttributeError) as err:
+            raise TranspilerError(f"HighLevelSynthesis was unable to define {inst.name}.") from err
+
+        if definition is None:
+            raise TranspilerError(f"HighLevelSynthesis was unable to synthesize {inst}.")
+
+        return definition
+
+    def _methods_to_try(self, name: str):
+        """Get a sequence of methods to try for a given op name."""
+        if (methods := self.hls_config.methods.get(name)) is not None:
+            # the operation's name appears in the user-provided config,
+            # we use the list of methods provided by the user
+            return methods
+        if (
+            self.hls_config.use_default_on_unspecified
+            and "default" in self.hls_plugin_manager.method_names(name)
+        ):
+            # the operation's name does not appear in the user-specified config,
+            # we use the "default" method when instructed to do so and the "default"
+            # method is available
+            return ["default"]
+        return []
+
+    def _synthesize_op_using_plugins(
+        self,
+        hls_methods: list,
+        op: Operation,
+        qubits: list[int] | None,
+        num_clean_ancillas: int = 0,
+        num_dirty_ancillas: int = 0,
+    ) -> QuantumCircuit | None:
+        """
+        Attempts to synthesize op using plugin mechanism.
+
+        The arguments ``num_clean_ancillas`` and ``num_dirty_ancillas`` specify
+        the number of clean and dirty qubits available to synthesize the given
+        operation. A synthesis method does not need to use these additional qubits.
+
+        Returns either the synthesized circuit or None (which may occur
+        when no synthesis methods is available or specified, or when there is
+        an insufficient number of auxiliary qubits).
+        """
+        hls_plugin_manager = self.hls_plugin_manager
+
+        best_decomposition = None
+        best_score = np.inf
+
+        for method in hls_methods:
+            # There are two ways to specify a synthesis method. The more explicit
+            # way is to specify it as a tuple consisting of a synthesis algorithm and a
+            # list of additional arguments, e.g.,
+            #   ("kms", {"all_mats": 1, "max_paths": 100, "orig_circuit": 0}), or
+            #   ("pmh", {}).
+            # When the list of additional arguments is empty, one can also specify
+            # just the synthesis algorithm, e.g.,
+            #   "pmh".
+            if isinstance(method, tuple):
+                plugin_specifier, plugin_args = method
+            else:
+                plugin_specifier = method
+                plugin_args = {}
+
+            # There are two ways to specify a synthesis algorithm being run,
+            # either by name, e.g. "kms" (which then should be specified in entry_points),
+            # or directly as a class inherited from HighLevelSynthesisPlugin (which then
+            # does not need to be specified in entry_points).
+            if isinstance(plugin_specifier, str):
+                if plugin_specifier not in hls_plugin_manager.method_names(op.name):
+                    raise TranspilerError(
+                        f"Specified method: {plugin_specifier} not found in available "
+                        f"plugins for {op.name}"
+                    )
+                plugin_method = hls_plugin_manager.method(op.name, plugin_specifier)
+            else:
+                plugin_method = plugin_specifier
+
+            # Set the number of available clean and dirty auxiliary qubits via plugin args.
+            plugin_args["num_clean_ancillas"] = num_clean_ancillas
+            plugin_args["num_dirty_ancillas"] = num_dirty_ancillas
+
+            decomposition = plugin_method.run(
+                op,
+                coupling_map=self._coupling_map,
+                target=self._target,
+                qubits=qubits,
+                **plugin_args,
+            )
+
+            # The synthesis methods that are not suited for the given higher-level-object
+            # will return None.
+            if decomposition is not None:
+                if self.hls_config.plugin_selection == "sequential":
+                    # In the "sequential" mode the first successful decomposition is
+                    # returned.
+                    best_decomposition = decomposition
+                    break
+
+                # In the "run everything" mode we update the best decomposition
+                # discovered
+                current_score = self.hls_config.plugin_evaluation_fn(decomposition)
+                if current_score < best_score:
+                    best_decomposition = decomposition
+                    best_score = current_score
+
+        return best_decomposition
+
+    def _apply_annotations(
+        self, synthesized: Operation | QuantumCircuit, modifiers: list[Modifier]
+    ) -> QuantumCircuit:
+        """
+        Recursively synthesizes annotated operations.
+        Returns either the synthesized operation or None (which occurs when the operation
+        is not an annotated operation).
+        """
+        for modifier in modifiers:
+            if isinstance(modifier, InverseModifier):
+                # Both QuantumCircuit and Gate have inverse method
+                synthesized = synthesized.inverse()
+
+            elif isinstance(modifier, ControlModifier):
+                # Both QuantumCircuit and Gate have control method, however for circuits
+                # it is more efficient to avoid constructing the controlled quantum circuit.
+                if isinstance(synthesized, QuantumCircuit):
+                    synthesized = synthesized.to_gate()
+
+                synthesized = synthesized.control(
+                    num_ctrl_qubits=modifier.num_ctrl_qubits,
+                    label=None,
+                    ctrl_state=modifier.ctrl_state,
+                    annotated=False,
+                )
+
+                if isinstance(synthesized, AnnotatedOperation):
+                    raise TranspilerError(
+                        "HighLevelSynthesis failed to synthesize the control modifier."
+                    )
+
+            elif isinstance(modifier, PowerModifier):
+                # QuantumCircuit has power method, and Gate needs to be converted
+                # to a quantum circuit.
+                if not isinstance(synthesized, QuantumCircuit):
+                    synthesized = _instruction_to_circuit(synthesized)
+
+                synthesized = synthesized.power(modifier.power)
+
+            else:
+                raise TranspilerError(f"Unknown modifier {modifier}.")
+
+        return synthesized
+
+    def _definitely_skip_node(
+        self, node: DAGOpNode, qubits: tuple[int] | None, dag: DAGCircuit
+    ) -> bool:
+        """Fast-path determination of whether a node can certainly be skipped (i.e. nothing will
+        attempt to synthesise it) without accessing its Python-space `Operation`.
+
+        This is tightly coupled to `_recursively_handle_op`; it exists as a temporary measure to
+        avoid Python-space `Operation` creation from a `DAGOpNode` if we wouldn't do anything to the
+        node (which is _most_ nodes)."""
+
+        if (
+            dag._has_calibration_for(node)
+            or len(node.qargs) < self._min_qubits
+            or node.is_directive()
+            or (self._instruction_supported(node.name, qubits) and not node.is_control_flow())
+        ):
+            return True
+
+        return (
+            # The fast path is just for Rust-space standard gates (which excludes
+            # `AnnotatedOperation`).
+            node.is_standard_gate()
+            # We don't have the fast-path for controlled gates over 3 or more qubits.
+            # However, we most probably want the fast-path for controlled 2-qubit gates
+            # (such as CX, CZ, CY, CH, CRX, and so on), so "_definitely_skip_node" should
+            # not immediately return False when encountering a controlled gate over 2 qubits.
+            and not (node.is_controlled_gate() and node.num_qubits >= 3)
+            # If there are plugins to try, they need to be tried.
+            and not self._methods_to_try(node.name)
+            # If all the above constraints hold, and it's already supported or the basis translator
+            # can handle it, we'll leave it be.
+            and (
+                # This uses unfortunately private details of `EquivalenceLibrary`, but so does the
+                # `BasisTranslator`, and this is supposed to just be temporary til this is moved
+                # into Rust space.
+                self._equiv_lib is not None
+                and equivalence.Key(name=node.name, num_qubits=node.num_qubits)
+                in self._equiv_lib.keys()
+            )
+        )
+
+    def _instruction_supported(self, name: str, qubits: tuple[int] | None) -> bool:
+        # include path for when target exists but target.num_qubits is None (BasicSimulator)
+        if self._target is None or self._target.num_qubits is None:
+            return name in self._device_insts
+        return self._target.instruction_supported(operation_name=name, qargs=qubits)
+
+
+def _instruction_to_circuit(inst: Instruction) -> QuantumCircuit:
+    circuit = QuantumCircuit(inst.num_qubits, inst.num_clbits)
+    circuit.append(inst, circuit.qubits, circuit.clbits)
+    return circuit