qiskit 2.0.3__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/transpiler/passes/layout/sabre_pre_layout.py

@@ -0,0 +1,225 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 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.
+
+"""Creating Sabre starting layouts."""
+
+import itertools
+
+from qiskit.transpiler.basepasses import AnalysisPass
+from qiskit.transpiler.coupling import CouplingMap
+from qiskit.transpiler.exceptions import TranspilerError
+from qiskit.transpiler.passes.layout.vf2_layout import VF2Layout
+from qiskit.transpiler.target import Target
+from qiskit._accelerate.error_map import ErrorMap
+
+
+class SabrePreLayout(AnalysisPass):
+    """Choose a starting layout to use for additional Sabre layout trials.
+
+    Property Set Values Written
+    ---------------------------
+
+    ``sabre_starting_layouts`` (``list[Layout]``)
+        An optional list of :class:`~.Layout` objects to use for additional Sabre layout trials.
+
+    **References:**
+
+    [1] Henry Zou and Matthew Treinish and Kevin Hartman and Alexander Ivrii and Jake Lishman.
+    "LightSABRE: A Lightweight and Enhanced SABRE Algorithm"
+    `arXiv:2409.08368 <https://doi.org/10.48550/arXiv.2409.08368>`__
+    """
+
+    def __init__(
+        self,
+        coupling_map,
+        max_distance=2,
+        error_rate=0.1,
+        max_trials_vf2=100,
+        call_limit_vf2=None,
+        improve_layout=True,
+    ):
+        """SabrePreLayout initializer.
+
+        The pass works by augmenting the coupling map with more and more "extra" edges
+        until VF2 succeeds to find a perfect graph isomorphism. More precisely, the
+        augmented coupling map contains edges between nodes that are within a given
+        distance ``d`` in the original coupling map, and the value of ``d`` is increased
+        until an isomorphism is found.
+
+        Intuitively, a better layout involves fewer extra edges. The pass also optionally
+        minimizes the number of extra edges involved in the layout until a local minimum
+        is found. This involves removing extra edges and running VF2 to see if an
+        isomorphism still exists.
+
+        Args:
+            coupling_map (Union[CouplingMap, Target]): directed graph representing the
+                original coupling map or a target modelling the backend (including its
+                connectivity).
+            max_distance (int): the maximum distance to consider for augmented coupling maps.
+            error_rate (float): the error rate to assign to the "extra" edges. A non-zero
+                error rate prioritizes VF2 to choose original edges over extra edges.
+            max_trials_vf2 (int): specifies the maximum number of VF2 trials. A larger number
+                allows VF2 to explore more layouts, eventually choosing the one with the smallest
+                error rate.
+            call_limit_vf2 (int): limits each call to VF2 by bounding the number of VF2 state visits.
+            improve_layout (bool): whether to improve the layout by minimizing the number of
+                extra edges involved. This might be time-consuming as this requires additional
+                VF2 calls.
+
+        Raises:
+            TranspilerError: At runtime, if neither ``coupling_map`` or ``target`` are provided.
+        """
+
+        self.max_distance = max_distance
+        self.error_rate = error_rate
+        self.max_trials_vf2 = max_trials_vf2
+        self.call_limit_vf2 = call_limit_vf2
+        self.improve_layout = improve_layout
+
+        if isinstance(coupling_map, Target):
+            self.target = coupling_map
+            self.coupling_map = self.target.build_coupling_map()
+        else:
+            self.target = None
+            self.coupling_map = coupling_map
+
+        super().__init__()
+
+    def run(self, dag):
+        """Run the SabrePreLayout pass on `dag`.
+
+        The discovered starting layout is written to the property set
+        value ``sabre_starting_layouts``.
+
+        Args:
+            dag (DAGCircuit): DAG to create starting layout for.
+        """
+
+        if self.coupling_map is None:
+            raise TranspilerError(
+                "SabrePreLayout requires coupling_map to be used with either"
+                "CouplingMap or a Target."
+            )
+
+        starting_layout = None
+        cur_distance = 1
+        while cur_distance <= self.max_distance:
+            augmented_map, augmented_error_map = self._add_extra_edges(cur_distance)
+            pass_ = VF2Layout(
+                augmented_map,
+                seed=0,
+                max_trials=self.max_trials_vf2,
+                call_limit=self.call_limit_vf2,
+            )
+            pass_.property_set["vf2_avg_error_map"] = augmented_error_map
+            pass_.run(dag)
+
+            if "layout" in pass_.property_set:
+                starting_layout = pass_.property_set["layout"]
+                break
+
+            cur_distance += 1
+
+        if cur_distance > 1 and starting_layout is not None:
+            # optionally improve starting layout
+            if self.improve_layout:
+                starting_layout = self._minimize_extra_edges(dag, starting_layout)
+            # write discovered layout into the property set
+            if "sabre_starting_layouts" not in self.property_set:
+                self.property_set["sabre_starting_layouts"] = [starting_layout]
+            else:
+                self.property_set["sabre_starting_layouts"].append(starting_layout)
+
+    def _add_extra_edges(self, distance):
+        """Augments the coupling map with extra edges that connect nodes ``distance``
+        apart in the original graph. The extra edges are assigned errors allowing VF2
+        to prioritize real edges over extra edges.
+        """
+        nq = len(self.coupling_map.graph)
+        augmented_coupling_map = CouplingMap()
+        augmented_coupling_map.graph = self.coupling_map.graph.copy()
+        augmented_error_map = ErrorMap(nq)
+
+        for x, y in itertools.combinations(self.coupling_map.graph.node_indices(), 2):
+            d = self.coupling_map.distance(x, y)
+            if 1 < d <= distance:
+                error_rate = 1 - ((1 - self.error_rate) ** d)
+                augmented_coupling_map.add_edge(x, y)
+                augmented_error_map.add_error((x, y), error_rate)
+                augmented_coupling_map.add_edge(y, x)
+                augmented_error_map.add_error((y, x), error_rate)
+
+        return augmented_coupling_map, augmented_error_map
+
+    def _get_extra_edges_used(self, dag, layout):
+        """Returns the set of extra edges involved in the layout."""
+        extra_edges_used = set()
+        virtual_bits = layout.get_virtual_bits()
+        for node in dag.two_qubit_ops():
+            p0 = virtual_bits[node.qargs[0]]
+            p1 = virtual_bits[node.qargs[1]]
+            if self.coupling_map.distance(p0, p1) > 1:
+                extra_edge = (p0, p1) if p0 < p1 else (p1, p0)
+                extra_edges_used.add(extra_edge)
+        return extra_edges_used
+
+    def _find_layout(self, dag, edges):
+        """Checks if there is a layout for a given set of edges."""
+        cm = CouplingMap(edges)
+        pass_ = VF2Layout(cm, seed=0, max_trials=1, call_limit=self.call_limit_vf2)
+        pass_.run(dag)
+        return pass_.property_set.get("layout", None)
+
+    def _minimize_extra_edges(self, dag, starting_layout):
+        """Minimizes the set of extra edges involved in the layout. This iteratively
+        removes extra edges from the coupling map and uses VF2 to check if a layout
+        still exists. This is reasonably efficiently as it only looks for a local
+        minimum.
+        """
+        # compute the set of edges in the original coupling map
+        real_edges = []
+        for x, y in itertools.combinations(self.coupling_map.graph.node_indices(), 2):
+            d = self.coupling_map.distance(x, y)
+            if d == 1:
+                real_edges.append((x, y))
+
+        best_layout = starting_layout
+
+        # keeps the set of "necessary" extra edges: without a necessary edge
+        # a layout no longer exists
+        extra_edges_necessary = []
+
+        extra_edges_unprocessed_set = self._get_extra_edges_used(dag, starting_layout)
+
+        while extra_edges_unprocessed_set:
+            # choose some unprocessed edge
+            edge_chosen = next(iter(extra_edges_unprocessed_set))
+            extra_edges_unprocessed_set.remove(edge_chosen)
+
+            # check if a layout still exists without this edge
+            layout = self._find_layout(
+                dag, real_edges + extra_edges_necessary + list(extra_edges_unprocessed_set)
+            )
+
+            if layout is None:
+                # without this edge the layout either does not exist or is too hard to find
+                extra_edges_necessary.append(edge_chosen)
+
+            else:
+                # this edge is not necessary, furthermore we can trim the set of edges to examine based
+                # in the edges involved in the layout.
+                extra_edges_unprocessed_set = self._get_extra_edges_used(dag, layout).difference(
+                    set(extra_edges_necessary)
+                )
+                best_layout = layout
+
+        return best_layout

qiskit/transpiler/passes/layout/set_layout.py

@@ -0,0 +1,69 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2019
+#
+# 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.
+
+"""Set the ``layout`` property to the given layout."""
+from qiskit.transpiler.basepasses import AnalysisPass
+from qiskit.transpiler.exceptions import InvalidLayoutError
+from qiskit.transpiler.layout import Layout
+
+
+class SetLayout(AnalysisPass):
+    """Set the ``layout`` property to the given layout.
+
+    This pass associates a physical qubit (int) to each virtual qubit
+    of the circuit (Qubit) in increasing order.
+    """
+
+    def __init__(self, layout):
+        """SetLayout initializer.
+
+        Args:
+            layout (Layout or List[int]): the layout to set. It can be:
+
+                * a :class:`Layout` instance: sets that layout.
+                * a list of integers: takes the index in the list as the physical position in which the
+                  virtual qubit is going to be mapped.
+
+        """
+        super().__init__()
+        self.layout = layout
+
+    def run(self, dag):
+        """Run the SetLayout pass on ``dag``.
+
+        Args:
+            dag (DAGCircuit): DAG to map.
+
+        Returns:
+            DAGCircuit: the original DAG.
+        """
+        if isinstance(self.layout, list):
+            if len(self.layout) != len(dag.qubits):
+                raise InvalidLayoutError(
+                    "The length of the layout is different than the size of the "
+                    f"circuit: {len(self.layout)} <> {len(dag.qubits)}"
+                )
+            if len(set(self.layout)) != len(self.layout):
+                raise InvalidLayoutError(
+                    f"The provided layout {self.layout} contains duplicate qubits"
+                )
+            layout = Layout({phys: dag.qubits[i] for i, phys in enumerate(self.layout)})
+        elif isinstance(self.layout, Layout):
+            layout = self.layout.copy()
+        elif self.layout is None:
+            layout = None
+        else:
+            raise InvalidLayoutError(
+                f"SetLayout was initialized with the layout type: {type(self.layout)}"
+            )
+        self.property_set["layout"] = layout
+        return dag

qiskit/transpiler/passes/layout/trivial_layout.py

@@ -0,0 +1,66 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2018.
+#
+# 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.
+
+"""Choose a Layout by assigning ``n`` circuit qubits to device qubits ``0, .., n-1``."""
+
+from qiskit.transpiler.layout import Layout
+from qiskit.transpiler.basepasses import AnalysisPass
+from qiskit.transpiler.exceptions import TranspilerError
+from qiskit.transpiler.target import Target
+
+
+class TrivialLayout(AnalysisPass):
+    """Choose a Layout by assigning ``n`` circuit qubits to device qubits ``0, .., n-1``.
+
+    A pass for choosing a Layout of a circuit onto a Coupling graph, using a simple
+    round-robin order.
+
+    This pass associates a physical qubit (int) to each virtual qubit
+    of the circuit (Qubit) in increasing order.
+
+    Does not assume any ancilla.
+    """
+
+    def __init__(self, coupling_map):
+        """TrivialLayout initializer.
+
+        Args:
+            coupling_map (Union[CouplingMap, Target]): directed graph representing a coupling map.
+
+        Raises:
+            TranspilerError: if invalid options
+        """
+        super().__init__()
+        if isinstance(coupling_map, Target):
+            self.target = coupling_map
+            self.coupling_map = self.target.build_coupling_map()
+        else:
+            self.target = None
+            self.coupling_map = coupling_map
+
+    def run(self, dag):
+        """Run the TrivialLayout pass on `dag`.
+
+        Args:
+            dag (DAGCircuit): DAG to find layout for.
+
+        Raises:
+            TranspilerError: if dag wider than the target backend
+        """
+        if self.target is not None:
+            if dag.num_qubits() > self.target.num_qubits:
+                raise TranspilerError("Number of qubits greater than device.")
+        elif dag.num_qubits() > self.coupling_map.size():
+            raise TranspilerError("Number of qubits greater than device.")
+        self.property_set["layout"] = Layout.generate_trivial_layout(
+            *(dag.qubits + list(dag.qregs.values()))
+        )

qiskit/transpiler/passes/layout/vf2_layout.py

@@ -0,0 +1,256 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# 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.
+
+
+"""VF2Layout pass to find a layout using subgraph isomorphism"""
+from enum import Enum
+import itertools
+import logging
+import time
+
+from rustworkx import vf2_mapping
+
+from qiskit.transpiler.layout import Layout
+from qiskit.transpiler.basepasses import AnalysisPass
+from qiskit.transpiler.exceptions import TranspilerError
+from qiskit.transpiler.passes.layout import vf2_utils
+
+
+logger = logging.getLogger(__name__)
+
+
+class VF2LayoutStopReason(Enum):
+    """Stop reasons for VF2Layout pass."""
+
+    SOLUTION_FOUND = "solution found"
+    NO_SOLUTION_FOUND = "nonexistent solution"
+    MORE_THAN_2Q = ">2q gates in basis"
+
+
+class VF2Layout(AnalysisPass):
+    """A pass for choosing a Layout of a circuit onto a Coupling graph, as
+    a subgraph isomorphism problem, solved by VF2++.
+
+    If a solution is found that means there is a "perfect layout" and that no
+    further swap mapping or routing is needed. If a solution is found the layout
+    will be set in the property set as ``property_set['layout']``. However, if no
+    solution is found, no ``property_set['layout']`` is set. The stopping reason is
+    set in ``property_set['VF2Layout_stop_reason']`` in all the cases and will be
+    one of the values enumerated in ``VF2LayoutStopReason`` which has the
+    following values:
+
+        * ``"solution found"``: If a perfect layout was found.
+        * ``"nonexistent solution"``: If no perfect layout was found.
+        * ``">2q gates in basis"``: If VF2Layout can't work with basis
+
+    By default, this pass will construct a heuristic scoring map based on
+    the error rates in the provided ``target`` (or ``properties`` if ``target``
+    is not provided). However, analysis passes can be run prior to this pass
+    and set ``vf2_avg_error_map`` in the property set with a :class:`~.ErrorMap`
+    instance. If a value is ``NaN`` that is treated as an ideal edge
+    For example if an error map is created as::
+
+        from qiskit.transpiler.passes.layout.vf2_utils import ErrorMap
+
+        error_map = ErrorMap(3)
+        error_map.add_error((0, 0), 0.0024)
+        error_map.add_error((0, 1), 0.01)
+        error_map.add_error((1, 1), 0.0032)
+
+    that represents the error map for a 2 qubit target, where the avg 1q error
+    rate is ``0.0024`` on qubit 0 and ``0.0032`` on qubit 1. Then the avg 2q
+    error rate for gates that operate on (0, 1) is 0.01 and (1, 0) is not
+    supported by the target. This will be used for scoring if it's set as the
+    ``vf2_avg_error_map`` key in the property set when :class:`~.VF2Layout` is run.
+    """
+
+    def __init__(
+        self,
+        coupling_map=None,
+        strict_direction=False,
+        seed=None,
+        call_limit=None,
+        time_limit=None,
+        max_trials=None,
+        target=None,
+    ):
+        """Initialize a ``VF2Layout`` pass instance
+
+        Args:
+            coupling_map (CouplingMap): Directed graph representing a coupling map.
+            strict_direction (bool): If True, considers the direction of the coupling map.
+                                     Default is False.
+            seed (int): Sets the seed of the PRNG. -1 Means no node shuffling.
+            call_limit (int): The number of state visits to attempt in each execution of
+                VF2.
+            time_limit (float): The total time limit in seconds to run ``VF2Layout``
+            max_trials (int): The maximum number of trials to run VF2 to find
+                a layout. If this is not specified the number of trials will be limited
+                based on the number of edges in the interaction graph or the coupling graph
+                (whichever is larger) if no other limits are set. If set to a value <= 0 no
+                limit on the number of trials will be set.
+            target (Target): A target representing the backend device to run ``VF2Layout`` on.
+                If specified it will supersede a set value for
+                ``coupling_map`` if the :class:`.Target` contains connectivity constraints. If the value
+                of ``target`` models an ideal backend without any constraints then the value of
+                ``coupling_map``
+                will be used.
+
+        Raises:
+            TypeError: At runtime, if neither ``coupling_map`` or ``target`` are provided.
+        """
+        super().__init__()
+        self.target = target
+        if (
+            target is not None
+            and (target_coupling_map := self.target.build_coupling_map()) is not None
+        ):
+            self.coupling_map = target_coupling_map
+        else:
+            self.coupling_map = coupling_map
+        self.strict_direction = strict_direction
+        self.seed = seed
+        self.call_limit = call_limit
+        self.time_limit = time_limit
+        self.max_trials = max_trials
+        self.avg_error_map = None
+
+    def run(self, dag):
+        """run the layout method"""
+        if self.coupling_map is None:
+            raise TranspilerError("coupling_map or target must be specified.")
+        self.avg_error_map = self.property_set["vf2_avg_error_map"]
+        if self.avg_error_map is None:
+            self.avg_error_map = vf2_utils.build_average_error_map(self.target, self.coupling_map)
+
+        result = vf2_utils.build_interaction_graph(dag, self.strict_direction)
+        if result is None:
+            self.property_set["VF2Layout_stop_reason"] = VF2LayoutStopReason.MORE_THAN_2Q
+            return
+        im_graph, im_graph_node_map, reverse_im_graph_node_map, free_nodes = result
+        scoring_edge_list = vf2_utils.build_edge_list(im_graph)
+        scoring_bit_list = vf2_utils.build_bit_list(im_graph, im_graph_node_map)
+        cm_graph, cm_nodes = vf2_utils.shuffle_coupling_graph(
+            self.coupling_map, self.seed, self.strict_direction
+        )
+        # Filter qubits without any supported operations. If they don't support any operations
+        # They're not valid for layout selection
+        if self.target is not None and self.target.qargs is not None:
+            has_operations = set(itertools.chain.from_iterable(self.target.qargs))
+            to_remove = set(range(len(cm_nodes))).difference(has_operations)
+            if to_remove:
+                cm_graph.remove_nodes_from([cm_nodes[i] for i in to_remove])
+
+        # To avoid trying to over optimize the result by default limit the number
+        # of trials based on the size of the graphs. For circuits with simple layouts
+        # like an all 1q circuit we don't want to sit forever trying every possible
+        # mapping in the search space if no other limits are set
+        if self.max_trials is None and self.call_limit is None and self.time_limit is None:
+            im_graph_edge_count = len(im_graph.edge_list())
+            cm_graph_edge_count = len(self.coupling_map.graph.edge_list())
+            self.max_trials = max(im_graph_edge_count, cm_graph_edge_count) + 15
+
+        logger.debug("Running VF2 to find mappings")
+        mappings = vf2_mapping(
+            cm_graph,
+            im_graph,
+            subgraph=True,
+            id_order=False,
+            induced=False,
+            call_limit=self.call_limit,
+        )
+        chosen_layout = None
+        chosen_layout_score = None
+        start_time = time.time()
+        trials = 0
+
+        def mapping_to_layout(layout_mapping):
+            return Layout({reverse_im_graph_node_map[k]: v for k, v in layout_mapping.items()})
+
+        for mapping in mappings:
+            trials += 1
+            logger.debug("Running trial: %s", trials)
+            stop_reason = VF2LayoutStopReason.SOLUTION_FOUND
+            layout_mapping = {im_i: cm_nodes[cm_i] for cm_i, im_i in mapping.items()}
+
+            # If the graphs have the same number of nodes we don't need to score or do multiple
+            # trials as the score heuristic currently doesn't weigh nodes based on gates on a
+            # qubit so the scores will always all be the same
+            if len(cm_graph) == len(im_graph):
+                chosen_layout = mapping_to_layout(layout_mapping)
+                break
+            # If there is no error map available we can just skip the scoring stage as there
+            # is nothing to score with, so any match is the best we can find.
+            if self.avg_error_map is None:
+                chosen_layout = mapping_to_layout(layout_mapping)
+                break
+            layout_score = vf2_utils.score_layout(
+                self.avg_error_map,
+                layout_mapping,
+                im_graph_node_map,
+                reverse_im_graph_node_map,
+                im_graph,
+                self.strict_direction,
+                edge_list=scoring_edge_list,
+                bit_list=scoring_bit_list,
+            )
+            # If the layout score is 0 we can't do any better and we'll just
+            # waste time finding additional mappings that will at best match
+            # the performance, so exit early in this case
+            if layout_score == 0.0:
+                chosen_layout = mapping_to_layout(layout_mapping)
+                break
+            logger.debug("Trial %s has score %s", trials, layout_score)
+            if chosen_layout is None:
+                chosen_layout = mapping_to_layout(layout_mapping)
+                chosen_layout_score = layout_score
+            elif layout_score < chosen_layout_score:
+                layout = mapping_to_layout(layout_mapping)
+                logger.debug(
+                    "Found layout %s has a lower score (%s) than previous best %s (%s)",
+                    layout,
+                    layout_score,
+                    chosen_layout,
+                    chosen_layout_score,
+                )
+                chosen_layout = layout
+                chosen_layout_score = layout_score
+            if self.max_trials is not None and self.max_trials > 0 and trials >= self.max_trials:
+                logger.debug("Trial %s is >= configured max trials %s", trials, self.max_trials)
+                break
+            elapsed_time = time.time() - start_time
+            if self.time_limit is not None and elapsed_time >= self.time_limit:
+                logger.debug(
+                    "VF2Layout has taken %s which exceeds configured max time: %s",
+                    elapsed_time,
+                    self.time_limit,
+                )
+                break
+        if chosen_layout is None:
+            stop_reason = VF2LayoutStopReason.NO_SOLUTION_FOUND
+        else:
+            chosen_layout = vf2_utils.map_free_qubits(
+                free_nodes,
+                chosen_layout,
+                cm_graph.num_nodes(),
+                reverse_im_graph_node_map,
+                self.avg_error_map,
+            )
+            # No free qubits for free qubit mapping
+            if chosen_layout is None:
+                self.property_set["VF2Layout_stop_reason"] = VF2LayoutStopReason.NO_SOLUTION_FOUND
+                return
+            self.property_set["layout"] = chosen_layout
+            for reg in dag.qregs.values():
+                self.property_set["layout"].add_register(reg)
+
+        self.property_set["VF2Layout_stop_reason"] = stop_reason