🐛 Preserve bijective heuristic layouts (#1153)

Replace direct physical-to-logical layout assignments with the existing
swap-based update so moving a logical qubit cannot duplicate it.

Add regression coverage for deferred, static, and fidelity-aware placement.

Assisted-by: GPT-5 via Codex

Author: burgholzer

CHANGELOG.md

@@ -22,6 +22,8 @@ _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#unreleased)._
 
 ### Fixed
 
+- 🐛 Preserve bijective layouts when the heuristic mapper moves logical qubits
+  ([#1153]) ([**@burgholzer**])
 - 🐛 Preserve the input circuit name during mapping ([#1154])
   ([**@burgholzer**])
 - 🐛 Handle Qiskit targets without calibration properties ([#1152])
@@ -307,6 +309,7 @@ _📚 Refer to the [GitHub Release Notes] for previous changelogs._
 <!-- PR links -->
 
 [#1154]: https://github.com/munich-quantum-toolkit/qmap/pull/1154
+[#1153]: https://github.com/munich-quantum-toolkit/qmap/pull/1153
 [#1152]: https://github.com/munich-quantum-toolkit/qmap/pull/1152
 [#1126]: https://github.com/munich-quantum-toolkit/qmap/pull/1126
 [#1116]: https://github.com/munich-quantum-toolkit/qmap/pull/1116

src/sc/heuristic/HeuristicMapper.cpp

@@ -11,6 +11,7 @@
 #include "sc/heuristic/HeuristicMapper.hpp"
 
 #include "ir/Definitions.hpp"
+#include "ir/Permutation.hpp"
 #include "ir/operations/CompoundOperation.hpp"
 #include "ir/operations/OpType.hpp"
 #include "ir/operations/StandardOperation.hpp"
@@ -106,6 +107,20 @@ void HeuristicMapper::map(const Configuration& configuration) {
   }
 }
 
+namespace {
+// search for current position of target value in map and afterward exchange
+// it with the value at new position
+void findAndSWAP(const qc::Qubit targetValue, const qc::Qubit newPosition,
+                 qc::Permutation& map) {
+  for (const auto& q : map) {
+    if (q.second == targetValue) {
+      std::swap(map.at(newPosition), map.at(q.first));
+      break;
+    }
+  }
+}
+} // namespace
+
 void HeuristicMapper::staticInitialMapping() {
   for (const auto& gate : layers.at(0U)) {
     if (gate.singleQubit()) {
@@ -120,11 +135,12 @@ void HeuristicMapper::staticInitialMapping() {
         locations.at(static_cast<std::uint16_t>(gate.control)) =
             static_cast<std::int16_t>(q0);
         locations.at(gate.target) = static_cast<std::int16_t>(q1);
-        qcMapped.initialLayout.at(q0) = static_cast<qc::Qubit>(gate.control);
-        qcMapped.initialLayout.at(q1) = static_cast<qc::Qubit>(gate.target);
-        qcMapped.outputPermutation.at(q0) =
-            static_cast<qc::Qubit>(gate.control);
-        qcMapped.outputPermutation.at(q1) = static_cast<qc::Qubit>(gate.target);
+        findAndSWAP(static_cast<qc::Qubit>(gate.control), q0,
+                    qcMapped.initialLayout);
+        findAndSWAP(gate.target, q1, qcMapped.initialLayout);
+        findAndSWAP(static_cast<qc::Qubit>(gate.control), q0,
+                    qcMapped.outputPermutation);
+        findAndSWAP(gate.target, q1, qcMapped.outputPermutation);
         break;
       }
     }
@@ -137,8 +153,8 @@ void HeuristicMapper::staticInitialMapping() {
         if (qubits.at(j) == DEFAULT_POSITION) {
           locations.at(i) = static_cast<std::int16_t>(j);
           qubits.at(j) = static_cast<std::int16_t>(i);
-          qcMapped.initialLayout.at(j) = i;
-          qcMapped.outputPermutation.at(j) = i;
+          findAndSWAP(i, j, qcMapped.initialLayout);
+          findAndSWAP(i, j, qcMapped.outputPermutation);
           break;
         }
       }
@@ -194,20 +210,6 @@ void HeuristicMapper::createInitialMapping() {
   }
 }
 
-namespace {
-// search for current position of target value in map and afterward exchange
-// it with the value at new position
-void findAndSWAP(const qc::Qubit targetValue, const qc::Qubit newPosition,
-                 qc::Permutation& map) {
-  for (const auto& q : map) {
-    if (q.second == targetValue) {
-      std::swap(map.at(newPosition), map.at(q.first));
-      break;
-    }
-  }
-}
-} // namespace
-
 void HeuristicMapper::mapUnmappedGates(std::size_t layer) {
   if (fidelityAwareHeur) {
     for (std::size_t q = 0; q < singleQubitMultiplicities.at(layer).size();
@@ -223,6 +225,10 @@ void HeuristicMapper::mapUnmappedGates(std::size_t layer) {
           if (qubits.at(physQbit) == -1) {
             locations.at(q) = static_cast<std::int16_t>(physQbit);
             qubits.at(physQbit) = static_cast<std::int16_t>(q);
+            findAndSWAP(static_cast<qc::Qubit>(q), physQbit,
+                        qcMapped.initialLayout);
+            findAndSWAP(static_cast<qc::Qubit>(q), physQbit,
+                        qcMapped.outputPermutation);
             break;
           }
         }
@@ -498,7 +504,7 @@ void HeuristicMapper::routeCircuit() {
           locations.at(target) = static_cast<std::int16_t>(loc);
           qubits.at(loc) = static_cast<std::int16_t>(target);
           op->setTargets({static_cast<qc::Qubit>(loc)});
-          qcMapped.initialLayout.at(loc) = target;
+          findAndSWAP(target, loc, qcMapped.initialLayout);
           qcMapped.outputPermutation[static_cast<qc::Qubit>(loc)] = target;
         } else {
           op->setTargets({static_cast<qc::Qubit>(targetLocation)});

test/python/sc/test_heuristic_mapper.py

@@ -16,6 +16,7 @@
 from qiskit.providers.fake_provider import GenericBackendV2
 
 from mqt.qmap.plugins.qiskit.sc import compile_
+from mqt.qmap.sc import Heuristic, InitialLayout, Layering
 
 
 @pytest.fixture
@@ -79,3 +80,50 @@ def test_heuristic_non_trivial_swaps(backend: GenericBackendV2) -> None:
     print(result)
 
     assert result.considered_equivalent() is True
+
+
+def test_heuristic_layout_with_deferred_single_qubit() -> None:
+    """Verify that placing a single-only qubit preserves a bijective layout."""
+    qc = QuantumCircuit(4)
+    qc.h(3)
+    qc.cx(0, 1)
+    qc.cx(1, 2)
+    qc.measure_all()
+    backend = GenericBackendV2(num_qubits=5, coupling_map=[[0, 1], [1, 4], [4, 3], [3, 2]])
+
+    qc_mapped, _ = compile_(qc, arch=backend)
+
+    assert verify(qc, qc_mapped).considered_equivalent() is True
+
+
+def test_heuristic_static_layout_is_bijective() -> None:
+    """Verify that static placement preserves a bijective layout."""
+    qc = QuantumCircuit(4)
+    qc.h(0)
+    qc.h(1)
+    qc.cx(2, 3)
+    qc.measure_all()
+    backend = GenericBackendV2(num_qubits=5, coupling_map=[[0, 4], [4, 3], [3, 2], [2, 1]])
+
+    qc_mapped, _ = compile_(qc, arch=backend, initial_layout=InitialLayout.static, layering=Layering.disjoint_qubits)
+
+    assert verify(qc, qc_mapped).considered_equivalent() is True
+
+
+def test_fidelity_aware_layout_is_bijective() -> None:
+    """Verify that fidelity-aware single-qubit placement preserves a bijective layout."""
+    qc = QuantumCircuit(4)
+    qc.h(3)
+    qc.cx(0, 1)
+    qc.cx(1, 2)
+    qc.measure_all()
+    backend = GenericBackendV2(num_qubits=5, coupling_map=[[0, 1], [1, 4], [4, 3], [3, 2]], seed=1)
+
+    qc_mapped, _ = compile_(
+        qc,
+        arch=backend,
+        heuristic=Heuristic.fidelity_best_location,
+        lookahead_heuristic=None,
+    )
+
+    assert verify(qc, qc_mapped).considered_equivalent() is True