qiskit 1.1.1__cp38-abi3-macosx_10_9_universal2.whl → 1.2.0__cp38-abi3-macosx_10_9_universal2.whl

qiskit/synthesis/linear/linear_depth_lnn.py

@@ -28,15 +28,15 @@ from qiskit.circuit import QuantumCircuit
 from qiskit.synthesis.linear.linear_matrix_utils import (
     calc_inverse_matrix,
     check_invertible_binary_matrix,
-    _col_op,
-    _row_op,
+    col_op,
+    row_op,
 )
 
 
 def _row_op_update_instructions(cx_instructions, mat, a, b):
     # Add a cx gate to the instructions and update the matrix mat
     cx_instructions.append((a, b))
-    _row_op(mat, a, b)
+    row_op(mat, a, b)
 
 
 def _get_lower_triangular(n, mat, mat_inv):
@@ -62,7 +62,7 @@ def _get_lower_triangular(n, mat, mat_inv):
                     first_j = j
                 else:
                     # cx_instructions_cols (L instructions) are not needed
-                    _col_op(mat, j, first_j)
+                    col_op(mat, j, first_j)
         # Use row operations directed upwards to zero out all "1"s above the remaining "1" in row i
         for k in reversed(range(0, i)):
             if mat[k, first_j]:
@@ -70,8 +70,8 @@ def _get_lower_triangular(n, mat, mat_inv):
 
     # Apply only U instructions to get the permuted L
     for inst in cx_instructions_rows:
-        _row_op(mat_t, inst[0], inst[1])
-        _col_op(mat_inv_t, inst[0], inst[1])
+        row_op(mat_t, inst[0], inst[1])
+        col_op(mat_inv_t, inst[0], inst[1])
     return mat_t, mat_inv_t
 
 
@@ -210,7 +210,7 @@ def _north_west_to_identity(n, mat):
 def _optimize_cx_circ_depth_5n_line(mat):
     # Optimize CX circuit in depth bounded by 5n for LNN connectivity.
     # The algorithm [1] has two steps:
-    # a) transform the originl matrix to a north-west matrix (m2nw),
+    # a) transform the original matrix to a north-west matrix (m2nw),
     # b) transform the north-west matrix to identity (nw2id).
     #
     # A square n-by-n matrix A is called north-west if A[i][j]=0 for all i+j>=n
@@ -222,7 +222,7 @@ def _optimize_cx_circ_depth_5n_line(mat):
 
     # According to [1] the synthesis is done on the inverse matrix
     # so the matrix mat is inverted at this step
-    mat_inv = mat.copy()
+    mat_inv = mat.astype(bool, copy=True)
     mat_cpy = calc_inverse_matrix(mat_inv)
 
     n = len(mat_cpy)

qiskit/synthesis/linear/linear_matrix_utils.py

@@ -12,164 +12,16 @@
 
 """Utility functions for handling binary matrices."""
 
-from typing import Optional, Union
-import numpy as np
-from qiskit.exceptions import QiskitError
-
-
-def check_invertible_binary_matrix(mat: np.ndarray):
-    """Check that a binary matrix is invertible.
-
-    Args:
-        mat: a binary matrix.
-
-    Returns:
-        bool: True if mat in invertible and False otherwise.
-    """
-    if len(mat.shape) != 2 or mat.shape[0] != mat.shape[1]:
-        return False
-
-    rank = _compute_rank(mat)
-    return rank == mat.shape[0]
-
-
-def random_invertible_binary_matrix(
-    num_qubits: int, seed: Optional[Union[np.random.Generator, int]] = None
-):
-    """Generates a random invertible n x n binary matrix.
-
-    Args:
-        num_qubits: the matrix size.
-        seed: a random seed.
-
-    Returns:
-        np.ndarray: A random invertible binary matrix of size num_qubits.
-    """
-    if isinstance(seed, np.random.Generator):
-        rng = seed
-    else:
-        rng = np.random.default_rng(seed)
-
-    rank = 0
-    while rank != num_qubits:
-        mat = rng.integers(2, size=(num_qubits, num_qubits))
-        rank = _compute_rank(mat)
-    return mat
-
-
-def _gauss_elimination(mat, ncols=None, full_elim=False):
-    """Gauss elimination of a matrix mat with m rows and n columns.
-    If full_elim = True, it allows full elimination of mat[:, 0 : ncols]
-    Returns the matrix mat."""
-
-    mat, _ = _gauss_elimination_with_perm(mat, ncols, full_elim)
-    return mat
-
-
-def _gauss_elimination_with_perm(mat, ncols=None, full_elim=False):
-    """Gauss elimination of a matrix mat with m rows and n columns.
-    If full_elim = True, it allows full elimination of mat[:, 0 : ncols]
-    Returns the matrix mat, and the permutation perm that was done on the rows during the process.
-    perm[0 : rank] represents the indices of linearly independent rows in the original matrix."""
-
-    # Treat the matrix A as containing integer values
-    mat = np.array(mat, dtype=int, copy=True)
-
-    m = mat.shape[0]  # no. of rows
-    n = mat.shape[1]  # no. of columns
-    if ncols is not None:
-        n = min(n, ncols)  # no. of active columns
-
-    perm = np.array(range(m))  # permutation on the rows
-
-    r = 0  # current rank
-    k = 0  # current pivot column
-    while (r < m) and (k < n):
-        is_non_zero = False
-        new_r = r
-        for j in range(k, n):
-            for i in range(r, m):
-                if mat[i][j]:
-                    is_non_zero = True
-                    k = j
-                    new_r = i
-                    break
-            if is_non_zero:
-                break
-        if not is_non_zero:
-            return mat, perm  # A is in the canonical form
-
-        if new_r != r:
-            mat[[r, new_r]] = mat[[new_r, r]]
-            perm[r], perm[new_r] = perm[new_r], perm[r]
-
-        if full_elim:
-            for i in range(0, r):
-                if mat[i][k]:
-                    mat[i] = mat[i] ^ mat[r]
-
-        for i in range(r + 1, m):
-            if mat[i][k]:
-                mat[i] = mat[i] ^ mat[r]
-        r += 1
-
-    return mat, perm
-
-
-def calc_inverse_matrix(mat: np.ndarray, verify: bool = False):
-    """Given a square numpy(dtype=int) matrix mat, tries to compute its inverse.
-
-    Args:
-        mat: a boolean square matrix.
-        verify: if True asserts that the multiplication of mat and its inverse is the identity matrix.
-
-    Returns:
-        np.ndarray: the inverse matrix.
-
-    Raises:
-         QiskitError: if the matrix is not square.
-         QiskitError: if the matrix is not invertible.
-    """
-
-    if mat.shape[0] != mat.shape[1]:
-        raise QiskitError("Matrix to invert is a non-square matrix.")
-
-    n = mat.shape[0]
-    # concatenate the matrix and identity
-    mat1 = np.concatenate((mat, np.eye(n, dtype=int)), axis=1)
-    mat1 = _gauss_elimination(mat1, None, full_elim=True)
-
-    r = _compute_rank_after_gauss_elim(mat1[:, 0:n])
-
-    if r < n:
-        raise QiskitError("The matrix is not invertible.")
-
-    matinv = mat1[:, n : 2 * n]
-
-    if verify:
-        mat2 = np.dot(mat, matinv) % 2
-        assert np.array_equal(mat2, np.eye(n))
-
-    return matinv
-
-
-def _compute_rank_after_gauss_elim(mat):
-    """Given a matrix A after Gaussian elimination, computes its rank
-    (i.e. simply the number of nonzero rows)"""
-    return np.sum(mat.any(axis=1))
-
-
-def _compute_rank(mat):
-    """Given a matrix A computes its rank"""
-    mat = _gauss_elimination(mat)
-    return np.sum(mat.any(axis=1))
-
-
-def _row_op(mat, ctrl, trgt):
-    # Perform ROW operation on a matrix mat
-    mat[trgt] = mat[trgt] ^ mat[ctrl]
-
-
-def _col_op(mat, ctrl, trgt):
-    # Perform COL operation on a matrix mat
-    mat[:, ctrl] = mat[:, trgt] ^ mat[:, ctrl]
+# pylint: disable=unused-import
+from qiskit._accelerate.synthesis.linear import (
+    gauss_elimination,
+    gauss_elimination_with_perm,
+    compute_rank_after_gauss_elim,
+    compute_rank,
+    calc_inverse_matrix,
+    binary_matmul,
+    random_invertible_binary_matrix,
+    check_invertible_binary_matrix,
+    row_op,
+    col_op,
+)

qiskit/synthesis/linear_phase/cnot_phase_synth.py

@@ -123,7 +123,7 @@ def synth_cnot_phase_aam(
 
     # Implementation of the pseudo-code (Algorithm 1) in the aforementioned paper
     sta.append([cnots, range_list, epsilon])
-    while sta != []:
+    while sta:
         [cnots, ilist, qubit] = sta.pop()
         if cnots == []:
             continue

qiskit/synthesis/linear_phase/cx_cz_depth_lnn.py

@@ -39,7 +39,7 @@ from qiskit.synthesis.linear.linear_depth_lnn import _optimize_cx_circ_depth_5n_
 def _initialize_phase_schedule(mat_z):
     """
     Given a CZ layer (represented as an n*n CZ matrix Mz)
-    Return a scheudle of phase gates implementing Mz in a SWAP-only netwrok
+    Return a schedule of phase gates implementing Mz in a SWAP-only netwrok
     (c.f. Alg 1, [2])
     """
     n = len(mat_z)
@@ -173,7 +173,7 @@ def _apply_phase_to_nw_circuit(n, phase_schedule, seq, swap_plus):
                 of exactly n layers of boxes, each being either a SWAP or a SWAP+. That is,
                 each northwest diagonalization circuit can be uniquely represented by which
                 of its n(n-1)/2 boxes are SWAP+ and which are SWAP.
-    Return a QuantumCircuit that computes the phase scheudle S inside CX
+    Return a QuantumCircuit that computes the phase schedule S inside CX
     """
     cir = QuantumCircuit(n)
 
@@ -217,7 +217,7 @@ def _apply_phase_to_nw_circuit(n, phase_schedule, seq, swap_plus):
 
 def synth_cx_cz_depth_line_my(mat_x: np.ndarray, mat_z: np.ndarray) -> QuantumCircuit:
     """
-    Joint synthesis of a -CZ-CX- circuit for linear nearest neighbour (LNN) connectivity,
+    Joint synthesis of a -CZ-CX- circuit for linear nearest neighbor (LNN) connectivity,
     with 2-qubit depth at most 5n, based on Maslov and Yang.
     This method computes the CZ circuit inside the CX circuit via phase gate insertions.
 

qiskit/synthesis/linear_phase/cz_depth_lnn.py

@@ -119,7 +119,7 @@ def _create_patterns(n):
 
 
 def synth_cz_depth_line_mr(mat: np.ndarray) -> QuantumCircuit:
-    r"""Synthesis of a CZ circuit for linear nearest neighbour (LNN) connectivity,
+    r"""Synthesis of a CZ circuit for linear nearest neighbor (LNN) connectivity,
     based on Maslov and Roetteler.
 
     Note that this method *reverts* the order of qubits in the circuit,

qiskit/synthesis/one_qubit/one_qubit_decompose.py

@@ -14,6 +14,7 @@
 Decompose a single-qubit unitary via Euler angles.
 """
 from __future__ import annotations
+from typing import TYPE_CHECKING
 import numpy as np
 
 from qiskit._accelerate import euler_one_qubit_decomposer
@@ -37,6 +38,9 @@ from qiskit.quantum_info.operators.predicates import is_unitary_matrix
 from qiskit.circuit.gate import Gate
 from qiskit.quantum_info.operators.operator import Operator
 
+if TYPE_CHECKING:
+    from qiskit.dagcircuit import DAGCircuit
+
 DEFAULT_ATOL = 1e-12
 
 ONE_QUBIT_EULER_BASIS_GATES = {
@@ -150,43 +154,33 @@ class OneQubitEulerDecomposer:
         self.basis = basis  # sets: self._basis, self._params, self._circuit
         self.use_dag = use_dag
 
-    def build_circuit(self, gates, global_phase):
+    def build_circuit(self, gates, global_phase) -> QuantumCircuit | DAGCircuit:
         """Return the circuit or dag object from a list of gates."""
         qr = [Qubit()]
         lookup_gate = False
         if len(gates) > 0 and isinstance(gates[0], tuple):
             lookup_gate = True
 
-        if self.use_dag:
-            from qiskit.dagcircuit import dagcircuit
-
-            dag = dagcircuit.DAGCircuit()
-            dag.global_phase = global_phase
-            dag.add_qubits(qr)
-            for gate_entry in gates:
-                if lookup_gate:
-                    gate = NAME_MAP[gate_entry[0]](*gate_entry[1])
-                else:
-                    gate = gate_entry
-
-                dag.apply_operation_back(gate, (qr[0],), check=False)
-            return dag
-        else:
-            circuit = QuantumCircuit(qr, global_phase=global_phase)
-            for gate_entry in gates:
-                if lookup_gate:
-                    gate = NAME_MAP[gate_entry[0]](*gate_entry[1])
-                else:
-                    gate = gate_entry
-                circuit._append(gate, [qr[0]], [])
-            return circuit
+        from qiskit.dagcircuit import dagcircuit
+
+        dag = dagcircuit.DAGCircuit()
+        dag.global_phase = global_phase
+        dag.add_qubits(qr)
+        for gate_entry in gates:
+            if lookup_gate:
+                gate = NAME_MAP[gate_entry[0].name](*gate_entry[1])
+            else:
+                gate = gate_entry.name
+
+            dag.apply_operation_back(gate, (qr[0],), check=False)
+        return dag
 
     def __call__(
         self,
         unitary: Operator | Gate | np.ndarray,
         simplify: bool = True,
         atol: float = DEFAULT_ATOL,
-    ) -> QuantumCircuit:
+    ) -> QuantumCircuit | DAGCircuit:
         """Decompose single qubit gate into a circuit.
 
         Args:
@@ -221,11 +215,17 @@ class OneQubitEulerDecomposer:
         return self._decompose(unitary, simplify=simplify, atol=atol)
 
     def _decompose(self, unitary, simplify=True, atol=DEFAULT_ATOL):
-        circuit_sequence = euler_one_qubit_decomposer.unitary_to_gate_sequence(
-            unitary, [self.basis], 0, None, simplify, atol
+        if self.use_dag:
+            circuit_sequence = euler_one_qubit_decomposer.unitary_to_gate_sequence(
+                unitary, [self.basis], 0, None, simplify, atol
+            )
+            circuit = self.build_circuit(circuit_sequence, circuit_sequence.global_phase)
+            return circuit
+        return QuantumCircuit._from_circuit_data(
+            euler_one_qubit_decomposer.unitary_to_circuit(
+                unitary, [self.basis], 0, None, simplify, atol
+            )
         )
-        circuit = self.build_circuit(circuit_sequence, circuit_sequence.global_phase)
-        return circuit
 
     @property
     def basis(self):

qiskit/synthesis/permutation/permutation_full.py

@@ -16,11 +16,9 @@ from __future__ import annotations
 
 import numpy as np
 from qiskit.circuit.quantumcircuit import QuantumCircuit
-from .permutation_utils import (
-    _get_ordered_swap,
-    _inverse_pattern,
-    _pattern_to_cycles,
-    _decompose_cycles,
+from qiskit._accelerate.synthesis.permutation import (
+    _synth_permutation_basic,
+    _synth_permutation_acg,
 )
 
 
@@ -44,17 +42,7 @@ def synth_permutation_basic(pattern: list[int] | np.ndarray[int]) -> QuantumCirc
     Returns:
         The synthesized quantum circuit.
     """
-    # This is the very original Qiskit algorithm for synthesizing permutations.
-
-    num_qubits = len(pattern)
-    qc = QuantumCircuit(num_qubits)
-
-    swaps = _get_ordered_swap(pattern)
-
-    for swap in swaps:
-        qc.swap(swap[0], swap[1])
-
-    return qc
+    return QuantumCircuit._from_circuit_data(_synth_permutation_basic(pattern))
 
 
 def synth_permutation_acg(pattern: list[int] | np.ndarray[int]) -> QuantumCircuit:
@@ -87,16 +75,4 @@ def synth_permutation_acg(pattern: list[int] | np.ndarray[int]) -> QuantumCircui
            *Routing Permutations on Graphs Via Matchings.*,
            `(Full paper) <https://www.cs.tau.ac.il/~nogaa/PDFS/r.pdf>`_
     """
-
-    num_qubits = len(pattern)
-    qc = QuantumCircuit(num_qubits)
-
-    # invert pattern (Qiskit notation is opposite)
-    cur_pattern = _inverse_pattern(pattern)
-    cycles = _pattern_to_cycles(cur_pattern)
-    swaps = _decompose_cycles(cycles)
-
-    for swap in swaps:
-        qc.swap(swap[0], swap[1])
-
-    return qc
+    return QuantumCircuit._from_circuit_data(_synth_permutation_acg(pattern))

qiskit/synthesis/permutation/permutation_lnn.py

@@ -15,7 +15,7 @@
 from __future__ import annotations
 import numpy as np
 from qiskit.circuit.quantumcircuit import QuantumCircuit
-from .permutation_utils import _inverse_pattern
+from qiskit._accelerate.synthesis.permutation import _synth_permutation_depth_lnn_kms
 
 
 def synth_permutation_depth_lnn_kms(pattern: list[int] | np.ndarray[int]) -> QuantumCircuit:
@@ -49,26 +49,4 @@ def synth_permutation_depth_lnn_kms(pattern: list[int] | np.ndarray[int]) -> Qua
     # In the permutation synthesis code below the notation is opposite:
     # [2, 4, 3, 0, 1] means that 0 maps to 2, 1 to 3, 2 to 3, 3 to 0, and 4 to 1.
     # This is why we invert the pattern.
-    cur_pattern = _inverse_pattern(pattern)
-
-    num_qubits = len(cur_pattern)
-    qc = QuantumCircuit(num_qubits)
-
-    # add conditional odd-even swap layers
-    for i in range(num_qubits):
-        _create_swap_layer(qc, cur_pattern, i % 2)
-
-    return qc
-
-
-def _create_swap_layer(qc, pattern, starting_point):
-    """Implements a single swap layer, consisting of conditional swaps between each
-    neighboring couple. The starting_point is the first qubit to use (either 0 or 1
-    for even or odd layers respectively). Mutates both the quantum circuit ``qc``
-    and the permutation pattern ``pattern``.
-    """
-    num_qubits = len(pattern)
-    for j in range(starting_point, num_qubits - 1, 2):
-        if pattern[j] > pattern[j + 1]:
-            qc.swap(j, j + 1)
-            pattern[j], pattern[j + 1] = pattern[j + 1], pattern[j]
+    return QuantumCircuit._from_circuit_data(_synth_permutation_depth_lnn_kms(pattern))

qiskit/synthesis/permutation/permutation_utils.py

@@ -12,62 +12,5 @@
 
 """Utility functions for handling permutations."""
 
-
-def _get_ordered_swap(permutation_in):
-    """Sorts the input permutation by iterating through the permutation list
-    and putting each element to its correct position via a SWAP (if it's not
-    at the correct position already). If ``n`` is the length of the input
-    permutation, this requires at most ``n`` SWAPs.
-
-    More precisely, if the input permutation is a cycle of length ``m``,
-    then this creates a quantum circuit with ``m-1`` SWAPs (and of depth ``m-1``);
-    if the input  permutation consists of several disjoint cycles, then each cycle
-    is essentially treated independently.
-    """
-    permutation = list(permutation_in[:])
-    swap_list = []
-    index_map = _inverse_pattern(permutation_in)
-    for i, val in enumerate(permutation):
-        if val != i:
-            j = index_map[i]
-            swap_list.append((i, j))
-            permutation[i], permutation[j] = permutation[j], permutation[i]
-            index_map[val] = j
-            index_map[i] = i
-    swap_list.reverse()
-    return swap_list
-
-
-def _inverse_pattern(pattern):
-    """Finds inverse of a permutation pattern."""
-    b_map = {pos: idx for idx, pos in enumerate(pattern)}
-    return [b_map[pos] for pos in range(len(pattern))]
-
-
-def _pattern_to_cycles(pattern):
-    """Given a permutation pattern, creates its disjoint cycle decomposition."""
-    nq = len(pattern)
-    explored = [False] * nq
-    cycles = []
-    for i in pattern:
-        cycle = []
-        while not explored[i]:
-            cycle.append(i)
-            explored[i] = True
-            i = pattern[i]
-        if len(cycle) >= 2:
-            cycles.append(cycle)
-    return cycles
-
-
-def _decompose_cycles(cycles):
-    """Given a disjoint cycle decomposition, decomposes every cycle into a SWAP
-    circuit of depth 2."""
-    swap_list = []
-    for cycle in cycles:
-        m = len(cycle)
-        for i in range((m - 1) // 2):
-            swap_list.append((cycle[i - 1], cycle[m - 3 - i]))
-        for i in range(m // 2):
-            swap_list.append((cycle[i - 1], cycle[m - 2 - i]))
-    return swap_list
+# pylint: disable=unused-import
+from qiskit._accelerate.synthesis.permutation import _inverse_pattern, _validate_permutation

qiskit/synthesis/qft/__init__.py

@@ -13,3 +13,4 @@
 """Module containing stabilizer QFT circuit synthesis."""
 
 from .qft_decompose_lnn import synth_qft_line
+from .qft_decompose_full import synth_qft_full

qiskit/synthesis/qft/qft_decompose_full.py

@@ -0,0 +1,79 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2024.
+#
+# 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.
+"""
+Circuit synthesis for a QFT circuit.
+"""
+
+from __future__ import annotations
+import numpy as np
+from qiskit.circuit.quantumcircuit import QuantumCircuit
+
+
+def synth_qft_full(
+    num_qubits: int,
+    do_swaps: bool = True,
+    approximation_degree: int = 0,
+    insert_barriers: bool = False,
+    inverse: bool = False,
+    name: str | None = None,
+) -> QuantumCircuit:
+    """Construct a circuit for the Quantum Fourier Transform using all-to-all connectivity.
+
+    .. note::
+
+        With the default value of ``do_swaps = True``, this synthesis algorithm creates a
+        circuit that faithfully implements the QFT operation. This circuit contains a sequence
+        of swap gates at the end, corresponding to reversing the order of its output qubits.
+        In some applications this reversal permutation can be avoided. Setting ``do_swaps = False``
+        creates a circuit without this reversal permutation, at the expense that this circuit
+        implements the "QFT-with-reversal" instead of QFT. Alternatively, the
+        :class:`~.ElidePermutations` transpiler pass is able to remove these swap gates.
+
+    Args:
+        num_qubits: The number of qubits on which the Quantum Fourier Transform acts.
+        do_swaps: Whether to synthesize the "QFT" or the "QFT-with-reversal" operation.
+        approximation_degree: The degree of approximation (0 for no approximation).
+            It is possible to implement the QFT approximately by ignoring
+            controlled-phase rotations with the angle beneath a threshold. This is discussed
+            in more detail in https://arxiv.org/abs/quant-ph/9601018 or
+            https://arxiv.org/abs/quant-ph/0403071.
+        insert_barriers: If ``True``, barriers are inserted for improved visualization.
+        inverse: If ``True``, the inverse Quantum Fourier Transform is constructed.
+        name: The name of the circuit.
+
+    Returns:
+        A circuit implementing the QFT operation.
+
+    """
+
+    circuit = QuantumCircuit(num_qubits, name=name)
+
+    for j in reversed(range(num_qubits)):
+        circuit.h(j)
+        num_entanglements = max(0, j - max(0, approximation_degree - (num_qubits - j - 1)))
+        for k in reversed(range(j - num_entanglements, j)):
+            # Use negative exponents so that the angle safely underflows to zero, rather than
+            # using a temporary variable that overflows to infinity in the worst case.
+            lam = np.pi * (2.0 ** (k - j))
+            circuit.cp(lam, j, k)
+
+        if insert_barriers:
+            circuit.barrier()
+
+    if do_swaps:
+        for i in range(num_qubits // 2):
+            circuit.swap(i, num_qubits - i - 1)
+
+    if inverse:
+        circuit = circuit.inverse()
+
+    return circuit

qiskit/synthesis/qft/qft_decompose_lnn.py

@@ -21,21 +21,29 @@ from qiskit.synthesis.permutation.permutation_reverse_lnn import _append_reverse
 def synth_qft_line(
     num_qubits: int, do_swaps: bool = True, approximation_degree: int = 0
 ) -> QuantumCircuit:
-    """Synthesis of a QFT circuit for a linear nearest neighbor connectivity.
-    Based on Fig 2.b in Fowler et al. [1].
+    """Construct a circuit for the Quantum Fourier Transform using linear
+    neighbor connectivity.
 
-    Note that this method *reverts* the order of qubits in the circuit,
-    compared to the original :class:`.QFT` code.
-    Hence, the default value of the ``do_swaps`` parameter is ``True``
-    since it produces a circuit with fewer CX gates.
+    The construction is based on Fig 2.b in Fowler et al. [1].
+
+    .. note::
+
+        With the default value of ``do_swaps = True``, this synthesis algorithm creates a
+        circuit that faithfully implements the QFT operation. When ``do_swaps = False``,
+        this synthesis algorithm creates a circuit that corresponds to "QFT-with-reversal":
+        applying the QFT and reversing the order of its output qubits.
 
     Args:
-        num_qubits: The number of qubits on which the QFT acts.
+        num_qubits: The number of qubits on which the Quantum Fourier Transform acts.
         approximation_degree: The degree of approximation (0 for no approximation).
-        do_swaps: Whether to include the final swaps in the QFT.
+            It is possible to implement the QFT approximately by ignoring
+            controlled-phase rotations with the angle beneath a threshold. This is discussed
+            in more detail in https://arxiv.org/abs/quant-ph/9601018 or
+            https://arxiv.org/abs/quant-ph/0403071.
+        do_swaps: Whether to synthesize the "QFT" or the "QFT-with-reversal" operation.
 
     Returns:
-        A circuit implementation of the QFT circuit.
+        A circuit implementing the QFT operation.
 
     References:
         1. A. G. Fowler, S. J. Devitt, and L. C. L. Hollenberg,