feat: integrate compute_output_permutation into _optimize_unitary

Extract with `up_to_perm=True` so that basic_optimization runs on a
SWAP-free circuit, then prepend the output permutation as SWAP gate
objects (1 gate each instead of 3 CNOTs).

Author: dlyongemallo

benchmarking/Depth_compression_ratio.png

@@ -19,9 +19,9 @@ Depth - original: 12, optimized: 12 (1.00), zx: 12 (1.00)
 Number of non-local gates - original: 8, optimized: 8, zx: 8, ratio: 1.00
 
 Circuit name: dnn_n2
-Size - original: 228, optimized: 13 (17.54), zx: 148 (1.54)
-Depth - original: 155, optimized: 8 (19.38), zx: 97 (1.60)
-Number of non-local gates - original: 42, optimized: 3, zx: 24, ratio: 0.12
+Size - original: 228, optimized: 13 (17.54), zx: 146 (1.56)
+Depth - original: 155, optimized: 8 (19.38), zx: 95 (1.63)
+Number of non-local gates - original: 42, optimized: 3, zx: 22, ratio: 0.14
 
 Circuit name: qrng_n4
 Size - original: 8, optimized: 8 (1.00), zx: 8 (1.00)
@@ -44,29 +44,29 @@ Depth - original: 5, optimized: 5 (1.00), zx: 5 (1.00)
 Number of non-local gates - original: 3, optimized: 3, zx: 3, ratio: 1.00
 
 Circuit name: basis_trotter_n4
-Size - original: 1510, optimized: 545 (2.77), zx: 395 (3.82)
-Depth - original: 815, optimized: 248 (3.29), zx: 297 (2.74)
-Number of non-local gates - original: 462, optimized: 179, zx: 177, ratio: 1.01
+Size - original: 1510, optimized: 545 (2.77), zx: 391 (3.86)
+Depth - original: 815, optimized: 248 (3.29), zx: 293 (2.78)
+Number of non-local gates - original: 462, optimized: 179, zx: 173, ratio: 1.03
 
 Circuit name: qec_en_n5
-Size - original: 30, optimized: 27 (1.11), zx: 20 (1.50)
-Depth - original: 18, optimized: 15 (1.20), zx: 16 (1.12)
-Number of non-local gates - original: 10, optimized: 10, zx: 12, ratio: 0.83
+Size - original: 30, optimized: 27 (1.11), zx: 18 (1.67)
+Depth - original: 18, optimized: 15 (1.20), zx: 11 (1.64)
+Number of non-local gates - original: 10, optimized: 10, zx: 10, ratio: 1.00
 
 Circuit name: toffoli_n3
 Size - original: 21, optimized: 18 (1.17), zx: 21 (1.00)
 Depth - original: 13, optimized: 12 (1.08), zx: 13 (1.00)
 Number of non-local gates - original: 6, optimized: 6, zx: 6, ratio: 1.00
 
 Circuit name: grover_n2
-Size - original: 18, optimized: 9 (2.00), zx: 10 (1.80)
-Depth - original: 12, optimized: 6 (2.00), zx: 8 (1.50)
-Number of non-local gates - original: 2, optimized: 2, zx: 3, ratio: 0.67
+Size - original: 18, optimized: 9 (2.00), zx: 6 (3.00)
+Depth - original: 12, optimized: 6 (2.00), zx: 4 (3.00)
+Number of non-local gates - original: 2, optimized: 2, zx: 2, ratio: 1.00
 
 Circuit name: hs4_n4
-Size - original: 32, optimized: 16 (2.00), zx: 21 (1.52)
+Size - original: 32, optimized: 16 (2.00), zx: 18 (1.78)
 Depth - original: 10, optimized: 6 (1.67), zx: 7 (1.43)
-Number of non-local gates - original: 4, optimized: 4, zx: 5, ratio: 0.80
+Number of non-local gates - original: 4, optimized: 4, zx: 4, ratio: 1.00
 
 Circuit name: qaoa_n3
 Size - original: 18, optimized: 17 (1.06), zx: 18 (1.00)
@@ -84,9 +84,9 @@ Depth - original: 5, optimized: 5 (1.00), zx: 4 (1.25)
 Number of non-local gates - original: 2, optimized: 2, zx: 2, ratio: 1.00
 
 Circuit name: vqe_uccsd_n4
-Size - original: 224, optimized: 147 (1.52), zx: 79 (2.84)
-Depth - original: 146, optimized: 111 (1.32), zx: 55 (2.65)
-Number of non-local gates - original: 88, optimized: 71, zx: 40, ratio: 1.77
+Size - original: 224, optimized: 147 (1.52), zx: 76 (2.95)
+Depth - original: 146, optimized: 111 (1.32), zx: 53 (2.75)
+Number of non-local gates - original: 88, optimized: 71, zx: 37, ratio: 1.92
 
 Circuit name: quantumwalks_n2
 Size - original: 13, optimized: 13 (1.00), zx: 13 (1.00)
@@ -119,14 +119,14 @@ Depth - original: 22, optimized: 22 (1.00), zx: 22 (1.00)
 Number of non-local gates - original: 10, optimized: 10, zx: 10, ratio: 1.00
 
 Circuit name: vqe_uccsd_n6
-Size - original: 2288, optimized: 1615 (1.42), zx: 339 (6.75)
-Depth - original: 1487, optimized: 1298 (1.15), zx: 204 (7.29)
-Number of non-local gates - original: 1052, optimized: 923, zx: 188, ratio: 4.91
+Size - original: 2288, optimized: 1615 (1.42), zx: 331 (6.91)
+Depth - original: 1487, optimized: 1298 (1.15), zx: 200 (7.43)
+Number of non-local gates - original: 1052, optimized: 923, zx: 180, ratio: 5.13
 
 Circuit name: ising_n10
-Size - original: 490, optimized: 220 (2.23), zx: 388 (1.26)
-Depth - original: 71, optimized: 42 (1.69), zx: 114 (0.62)
-Number of non-local gates - original: 90, optimized: 90, zx: 158, ratio: 0.57
+Size - original: 490, optimized: 220 (2.23), zx: 380 (1.29)
+Depth - original: 71, optimized: 42 (1.69), zx: 109 (0.65)
+Number of non-local gates - original: 90, optimized: 90, zx: 150, ratio: 0.60
 
 Circuit name: simon_n6
 Size - original: 22, optimized: 46 (0.48), zx: 21 (1.05)
@@ -139,29 +139,29 @@ Depth - original: 21, optimized: 85 (0.25), zx: 21 (1.00)
 Number of non-local gates - original: 18, optimized: 43, zx: 18, ratio: 2.39
 
 Circuit name: qaoa_n6
-Size - original: 276, optimized: 120 (2.30), zx: 135 (2.04)
-Depth - original: 110, optimized: 46 (2.39), zx: 68 (1.62)
-Number of non-local gates - original: 54, optimized: 36, zx: 71, ratio: 0.51
+Size - original: 276, optimized: 120 (2.30), zx: 127 (2.17)
+Depth - original: 110, optimized: 46 (2.39), zx: 60 (1.83)
+Number of non-local gates - original: 54, optimized: 36, zx: 63, ratio: 0.57
 
 Circuit name: bb84_n8
 Size - original: 43, optimized: 27 (1.59), zx: 31 (1.39)
 Depth - original: 7, optimized: 4 (1.75), zx: 5 (1.40)
 Number of non-local gates - original: 0, optimized: 0, zx: 0
 
 Circuit name: vqe_uccsd_n8
-Size - original: 10816, optimized: 7771 (1.39), zx: 1226 (8.82)
-Depth - original: 7253, optimized: 6424 (1.13), zx: 795 (9.12)
-Number of non-local gates - original: 5488, optimized: 4815, zx: 712, ratio: 6.76
+Size - original: 10816, optimized: 7771 (1.39), zx: 1214 (8.91)
+Depth - original: 7253, optimized: 6424 (1.13), zx: 788 (9.20)
+Number of non-local gates - original: 5488, optimized: 4815, zx: 701, ratio: 6.87
 
 Circuit name: adder_n10
 Size - original: 19, optimized: 139 (0.14), zx: 19 (1.00)
 Depth - original: 11, optimized: 96 (0.11), zx: 11 (1.00)
 Number of non-local gates - original: 9, optimized: 65, zx: 9, ratio: 7.22
 
 Circuit name: dnn_n8
-Size - original: 1016, optimized: 208 (4.88), zx: 650 (1.56)
-Depth - original: 173, optimized: 34 (5.09), zx: 146 (1.18)
-Number of non-local gates - original: 192, optimized: 64, zx: 144, ratio: 0.44
+Size - original: 1016, optimized: 208 (4.88), zx: 638 (1.59)
+Depth - original: 173, optimized: 34 (5.09), zx: 143 (1.21)
+Number of non-local gates - original: 192, optimized: 64, zx: 132, ratio: 0.48
 
 Circuit name: bv_n14
 Size - original: 54, optimized: 53 (1.02), zx: 54 (1.00)
@@ -179,7 +179,7 @@ Depth - original: 51, optimized: 388 (0.13), zx: 51 (1.00)
 Number of non-local gates - original: 42, optimized: 252, zx: 42, ratio: 6.00
 
 Circuit name: qft_n18
-Size - original: 801, optimized: 665 (1.20), zx: 752 (1.07)
-Depth - original: 134, optimized: 118 (1.14), zx: 372 (0.36)
-Number of non-local gates - original: 306, optimized: 306, zx: 518, ratio: 0.59
+Size - original: 801, optimized: 665 (1.20), zx: 722 (1.11)
+Depth - original: 134, optimized: 118 (1.14), zx: 362 (0.37)
+Number of non-local gates - original: 306, optimized: 306, zx: 488, ratio: 0.63
 

benchmarking/Ratio_of_non-local_gates.png

@@ -20,7 +20,7 @@
 from typing import Any, Callable, Optional
 import pyzx as zx
 from pyzx.circuit.gates import Measurement as PyzxMeasurement, Reset as PyzxReset
-from pyzx.circuit.gates import ConditionalGate
+from pyzx.circuit.gates import ConditionalGate, SWAP
 import numpy as np
 import pytest
 
@@ -694,6 +694,121 @@ def test_compute_output_permutation_non_bijective() -> None:
         compute_output_permutation(g)
 
 
+def test_permutation_swaps_in_pipeline() -> None:
+    """Test that _optimize_unitary prepends SWAP gates for the output permutation.
+
+    After extraction with up_to_perm=True, the output permutation should be
+    prepended as SWAP gate objects.  Each SWAP counts as one gate instead of
+    three CNOTs, improving the gate-count comparison.
+    """
+    # pylint: disable=import-outside-toplevel
+    from fractions import Fraction
+    from zxpass.zxpass import (
+        _optimize_unitary,
+        _permutation_to_swaps,
+        compute_output_permutation,
+    )
+
+    # Build a circuit that produces a non-trivial output permutation and is
+    # large enough that the gate-count fallback does not trigger.
+    c = zx.Circuit(4)
+    for j in range(4):
+        c.add_gate("HAD", j)
+    for _ in range(3):
+        for i in range(3):
+            c.add_gate("CNOT", i, i + 1)
+        for j in range(4):
+            c.add_gate("ZPhase", j, phase=Fraction(1, 2 + j))
+        for i in range(3):
+            c.add_gate("CNOT", i, i + 1)
+
+    # Replay the same extraction path to compute the SWAP prefix that
+    # ``_optimize_unitary`` should prepend.
+    g = c.to_graph()
+    zx.simplify.full_reduce(g)
+    zx.extract.extract_circuit(g, up_to_perm=True)
+    expected_swaps = _permutation_to_swaps(compute_output_permutation(g))
+    # Sanity-check that this circuit exercises the SWAP-prefix path, so the
+    # test does not silently degenerate into a trivial no-op assertion.
+    assert expected_swaps, "Test circuit should produce a non-trivial permutation."
+
+    optimized = _optimize_unitary(c)
+
+    # Confirm the fallback did not trigger for this circuit; otherwise the
+    # SWAP-prefix assertions below would be vacuously skipped.
+    assert list(optimized.gates) != list(c.gates), (
+        "Test circuit unexpectedly hit the gate-count fallback."
+    )
+
+    # The optimized circuit should begin with exactly the expected SWAP prefix.
+    assert len(optimized.gates) >= len(expected_swaps)
+    for k, (i, j) in enumerate(expected_swaps):
+        gate = optimized.gates[k]
+        assert isinstance(gate, SWAP), (
+            f"Expected SWAP at position {k}, got {type(gate).__name__}."
+        )
+        assert {gate.control, gate.target} == {i, j}, (
+            f"SWAP at position {k} acts on {{{gate.control}, {gate.target}}}, "
+            f"expected {{{i}, {j}}}."
+        )
+    # No SWAPs should appear after the prefix.
+    for gate in optimized.gates[len(expected_swaps):]:
+        assert not isinstance(gate, SWAP), (
+            "SWAP gates should only appear at the beginning of the circuit."
+        )
+
+
+def test_permutation_to_swaps_correctness() -> None:
+    """Test that _permutation_to_swaps produces a correct SWAP sequence."""
+    from zxpass.zxpass import _permutation_to_swaps  # pylint: disable=import-outside-toplevel
+
+    # Identity permutation: no SWAPs needed.
+    assert not _permutation_to_swaps({0: 0, 1: 1, 2: 2})
+
+    # Simple transposition.
+    swaps = _permutation_to_swaps({0: 1, 1: 0})
+    assert len(swaps) == 1
+    assert set(swaps[0]) == {0, 1}
+
+    # 3-cycle: needs 2 transpositions.
+    perm = {0: 1, 1: 2, 2: 0}
+    swaps = _permutation_to_swaps(perm)
+    # Verify the SWAPs implement the permutation.
+    state = list(range(3))
+    for i, j in swaps:
+        state[i], state[j] = state[j], state[i]
+    assert state == [perm[k] for k in range(3)]
+
+    # Larger permutation with multiple cycles.
+    perm = {0: 2, 1: 0, 2: 1, 3: 4, 4: 3}
+    swaps = _permutation_to_swaps(perm)
+    state = list(range(5))
+    for i, j in swaps:
+        state[i], state[j] = state[j], state[i]
+    assert state == [perm[k] for k in range(5)]
+
+
+def test_permutation_to_swaps_invalid_input() -> None:
+    """Test that _permutation_to_swaps rejects non-bijective input."""
+    from zxpass.zxpass import _permutation_to_swaps  # pylint: disable=import-outside-toplevel
+
+    # Non-contiguous keys (missing 1).
+    with pytest.raises(ValueError, match="keys to be range"):
+        _permutation_to_swaps({0: 0, 2: 2})
+
+    # Out-of-range keys (shifted by 1).
+    with pytest.raises(ValueError, match="keys to be range"):
+        _permutation_to_swaps({1: 1, 2: 2})
+
+    # Values outside range.
+    with pytest.raises(ValueError, match="values to be a permutation"):
+        _permutation_to_swaps({0: 5, 1: 1})
+
+    # Repeated values (not a permutation).
+    with pytest.raises(ValueError, match="values to be a permutation"):
+        _permutation_to_swaps({0: 1, 1: 1})
+
+
 def test_post_extraction_cleanup() -> None:
     """Test that ``_optimize_unitary`` applies ``basic_optimization`` after extraction.
 
@@ -738,32 +853,35 @@ def test_post_extraction_cleanup() -> None:
 
 
 def test_post_extraction_cleanup_equivalence() -> None:
-    """Test that the post-extraction cleanup preserves circuit equivalence.
-
-    Runs multiple circuits through the full ZXPass pipeline and verifies
-    statevector equivalence after the basic_optimization post-pass.
-    """
-    circuits = []
-
-    # Bell state preparation with extra gates.
+    """Test that post-extraction cleanup and permutation integration preserve equivalence."""
     qc1 = QuantumCircuit(3)
     qc1.h(0)
     qc1.cx(0, 1)
     qc1.cx(1, 2)
     qc1.h(2)
     qc1.cx(2, 0)
-    circuits.append(qc1)
 
-    # Multi-CX circuit.
-    qc2 = QuantumCircuit(4)
-    for i in range(3):
+    qc2 = QuantumCircuit(5)
+    for i in range(5):
+        qc2.h(i)
+    for i in range(4):
         qc2.cx(i, i + 1)
-    qc2.h(0)
-    qc2.cx(3, 0)
-    qc2.h(1)
-    circuits.append(qc2)
-
-    for qc in circuits:
+    qc2.cx(4, 0)
+    for i in range(5):
+        qc2.rz(0.3 * (i + 1), i)
+
+    qc3 = QuantumCircuit(4)
+    qc3.h(0)
+    qc3.cx(0, 1)
+    qc3.h(1)
+    qc3.cx(1, 2)
+    qc3.h(2)
+    qc3.cx(2, 3)
+    qc3.cx(3, 0)
+    qc3.cx(2, 1)
+    qc3.cx(1, 0)
+
+    for qc in [qc1, qc2, qc3]:
         assert _run_zxpass(qc), f"Equivalence failed for circuit:\n{qc}"
 
 

benchmarking/benchmarks_output.txt

@@ -177,21 +177,67 @@ def compute_output_permutation(g: Any) -> Dict[int, int]:
     return perm
 
 
+def _permutation_to_swaps(perm: Dict[int, int]) -> List[Tuple[int, int]]:
+    """Decompose a permutation into transpositions (SWAP pairs).
+
+    Uses cycle decomposition.  The returned list, applied left to right,
+    implements the forward permutation (wire *j* ends up holding the state
+    of input qubit ``perm[j]``).
+
+    Raises ``ValueError`` if ``perm`` is not a bijection on
+    ``range(len(perm))`` (i.e. if its keys or values are not exactly the
+    set of integers ``{0, 1, ..., len(perm) - 1}``).
+    """
+    n = len(perm)
+    expected = set(range(n))
+    if set(perm.keys()) != expected:
+        raise ValueError(
+            f"Expected permutation keys to be range({n}), "
+            f"got {sorted(perm.keys())}."
+        )
+    if set(perm.values()) != expected:
+        raise ValueError(
+            f"Expected permutation values to be a permutation of range({n}), "
+            f"got {sorted(perm.values())}."
+        )
+    current = [perm[i] for i in range(n)]
+    swaps: List[Tuple[int, int]] = []
+    for i in range(n):
+        while current[i] != i:
+            j = current[i]
+            swaps.append((i, j))
+            current[i], current[j] = current[j], current[i]
+    swaps.reverse()
+    return swaps
+
+
 def _optimize_unitary(c: zx.Circuit) -> zx.Circuit:
     """Optimise a purely unitary PyZX circuit using full_reduce and extraction.
 
-    After extraction, ``basic_optimization`` converts HAD-CZ-HAD sequences to
-    CNOTs and cancels redundant single-qubit gates.  If the result still has at
-    least as many gates as the original circuit, the original is returned
-    unchanged to avoid regressions on small circuits with compact multi-qubit
-    gates (e.g. Toffoli, Fredkin). The comparison counts PyZX gate objects
-    directly; since ``_recover_dag`` emits one Qiskit op per PyZX gate, this
-    matches the Qiskit-side ``size()`` that downstream passes see.
+    Extracts with ``up_to_perm=True`` so that ``basic_optimization`` runs on a
+    circuit free of SWAP-decomposition clutter.  The output permutation is then
+    prepended as SWAP gates (each counting as one gate rather than three CNOTs),
+    giving a fairer gate-count comparison against the original circuit.  If the
+    result still has at least as many gates as the original, the original is
+    returned unchanged to avoid regressions on small circuits with compact
+    multi-qubit gates (e.g. Toffoli, Fredkin). The comparison counts PyZX gate
+    objects directly; since ``_recover_dag`` emits one Qiskit op per PyZX gate,
+    this matches the Qiskit-side ``size()`` that downstream passes see.
     """
     g = c.to_graph()
     zx.simplify.full_reduce(g)
-    optimized = zx.extract.extract_circuit(g)
+    optimized = zx.extract.extract_circuit(g, up_to_perm=True)
+    perm = compute_output_permutation(g)
     optimized = basic_optimization(optimized.to_basic_gates(), do_swaps=False)
+    # Prepend SWAP gates for the output permutation.
+    swap_pairs = _permutation_to_swaps(perm)
+    if swap_pairs:
+        with_perm = zx.Circuit(c.qubits)
+        for i, j in swap_pairs:
+            with_perm.add_gate(SWAP(i, j))
+        for gate in optimized.gates:
+            with_perm.add_gate(gate)
+        optimized = with_perm
     # TODO: Consider a two-axis comparison keyed primarily on 2-qubit gate
     # count (``twoqubitcount()``), with total gate count as a tiebreaker. The
     # 2-qubit count is the dominant hardware cost and is naturally apples-to-