Improved Documentation and Error-Signaling of VF2PostLayout

qiskit/transpiler/passes/layout/vf2_post_layout.py

@@ -35,6 +35,7 @@ class VF2PostLayoutStopReason(Enum):
     """Stop reasons for VF2PostLayout pass."""
 
     SOLUTION_FOUND = "solution found"
+    NO_BETTER_SOLUTION_FOUND = "no better solution found"
     NO_SOLUTION_FOUND = "nonexistent solution"
     MORE_THAN_2Q = ">2q gates in basis"
 
@@ -51,7 +52,7 @@ def _target_match(node_a, node_b):
 
 
 class VF2PostLayout(AnalysisPass):
-    """A pass for choosing a Layout after transpilation of a circuit onto a
+    """A pass for improving an existing Layout after transpilation of a circuit onto a
     Coupling graph, as a subgraph isomorphism problem, solved by VF2++.
 
     Unlike the :class:`~.VF2Layout` transpiler pass which is designed to find an
@@ -66,15 +67,16 @@ class VF2PostLayout(AnalysisPass):
 
     If a solution is found that means there is a lower error layout available for the
     circuit. If a solution is found the layout will be set in the property set as
-    ``property_set['post_layout']``. However, if no solution is found, no
+    ``property_set['post_layout']``. However, if no solution or no better solution is found, no
     ``property_set['post_layout']`` is set. The stopping reason is
     set in ``property_set['VF2PostLayout_stop_reason']`` in all the cases and will be
     one of the values enumerated in ``VF2PostLayoutStopReason`` which has the
     following values:
 
         * ``"solution found"``: If a solution was found.
+        * ``"no better solution found"``: If the initial layout of the circuit is the best solution.
         * ``"nonexistent solution"``: If no solution was found.
-        * ``">2q gates in basis"``: If VF2PostLayout can't work with basis
+        * ``">2q gates in basis"``: If VF2PostLayout can't work with the basis of the circuit.
 
     By default this pass will construct a heuristic scoring map based on the
     the error rates in the provided ``target`` (or ``properties`` if ``target``
@@ -339,7 +341,10 @@ def run(self, dag):
                 )
                 break
         if chosen_layout is None:
-            stop_reason = VF2PostLayoutStopReason.NO_SOLUTION_FOUND
+            if initial_layout is not None:
+                stop_reason = VF2PostLayoutStopReason.NO_BETTER_SOLUTION_FOUND
+            else:
+                stop_reason = VF2PostLayoutStopReason.NO_SOLUTION_FOUND
         else:
             chosen_layout = vf2_utils.map_free_qubits(
                 free_nodes,

test/python/transpiler/test_vf2_post_layout.py

@@ -108,7 +108,7 @@ def test_empty_circuit(self):
         vf2_pass.run(circuit_to_dag(qc))
         self.assertEqual(
             vf2_pass.property_set["VF2PostLayout_stop_reason"],
-            VF2PostLayoutStopReason.NO_SOLUTION_FOUND,
+            VF2PostLayoutStopReason.NO_BETTER_SOLUTION_FOUND,
         )
 
     def test_empty_circuit_v2(self):
@@ -119,7 +119,7 @@ def test_empty_circuit_v2(self):
         vf2_pass.run(circuit_to_dag(qc))
         self.assertEqual(
             vf2_pass.property_set["VF2PostLayout_stop_reason"],
-            VF2PostLayoutStopReason.NO_SOLUTION_FOUND,
+            VF2PostLayoutStopReason.NO_BETTER_SOLUTION_FOUND,
         )
 
     def test_skip_3q_circuit(self):
@@ -389,6 +389,46 @@ def test_target_some_error(self):
         # No layout selected because nothing will beat initial layout
         self.assertNotIn("post_layout", vf2_pass.property_set)
 
+    def test_trivial_layout_is_best(self):
+        """Test that vf2postlayout reports no better solution if the trivial layout is the best layout"""
+        n_qubits = 4
+        trivial_target = Target()
+        trivial_target.add_instruction(
+            CXGate(), {(i, i + 1): InstructionProperties(error=0.001) for i in range(n_qubits - 1)}
+        )
+
+        circuit = QuantumCircuit(n_qubits)
+        circuit.cx(0, 1)
+        circuit.cx(1, 2)
+
+        vf2_pass = VF2PostLayout(target=trivial_target, seed=self.seed, strict_direction=False)
+        dag = circuit_to_dag(circuit)
+        vf2_pass.run(dag)
+        self.assertEqual(
+            vf2_pass.property_set["VF2PostLayout_stop_reason"],
+            VF2PostLayoutStopReason.NO_BETTER_SOLUTION_FOUND,
+        )
+
+    def test_last_qubits_best(self):
+        """Test that vf2postlayout determines the best layout when the last qubits have least error"""
+        n_qubits = 4
+        target_last_qubits_best = Target()
+        target_last_qubits_best.add_instruction(
+            CXGate(),
+            {(i, i + 1): InstructionProperties(error=10**-i) for i in range(n_qubits - 1)},
+        )
+
+        circuit = QuantumCircuit(n_qubits)
+        circuit.cx(0, 1)
+        circuit.cx(1, 2)
+
+        vf2_pass = VF2PostLayout(
+            target=target_last_qubits_best, seed=self.seed, strict_direction=False
+        )
+        dag = circuit_to_dag(circuit)
+        vf2_pass.run(dag)
+        self.assertLayout(dag, target_last_qubits_best.build_coupling_map(), vf2_pass.property_set)
+
 
 class TestVF2PostLayoutScoring(QiskitTestCase):
     """Test scoring heuristic function for VF2PostLayout."""
@@ -480,7 +520,7 @@ def test_empty_circuit(self):
         vf2_pass.run(circuit_to_dag(qc))
         self.assertEqual(
             vf2_pass.property_set["VF2PostLayout_stop_reason"],
-            VF2PostLayoutStopReason.NO_SOLUTION_FOUND,
+            VF2PostLayoutStopReason.NO_BETTER_SOLUTION_FOUND,
         )
 
     def test_empty_circuit_v2(self):
@@ -491,7 +531,7 @@ def test_empty_circuit_v2(self):
         vf2_pass.run(circuit_to_dag(qc))
         self.assertEqual(
             vf2_pass.property_set["VF2PostLayout_stop_reason"],
-            VF2PostLayoutStopReason.NO_SOLUTION_FOUND,
+            VF2PostLayoutStopReason.NO_BETTER_SOLUTION_FOUND,
         )
 
     def test_skip_3q_circuit(self):