qpe_toolbox.estimation.qft
==========================

.. py:module:: qpe_toolbox.estimation.qft


Functions
---------

.. autoapisummary::

   qpe_toolbox.estimation.qft.qft_swapped
   qpe_toolbox.estimation.qft.iqft_swapped
   qpe_toolbox.estimation.qft.qft
   qpe_toolbox.estimation.qft.iqft
   qpe_toolbox.estimation.qft.count_gates_qft_swapped


Module Contents
---------------

.. py:function:: qft_swapped(wires)

   Generate the sequence of gates for a recursive QFT with reversed ordering.

   The QFT is implemented recursively without final swaps.
   This routine is suitable for constructing circuits with qubit indices
   in reversed order.

   :param wires: List of qubit indices on which to apply the QFT.
   :type wires: list[int]

   :returns: List of gate instructions in the form
             ``(gate_label, *params, qubits...)``, where single-qubit gates are
             ``('H', q)``, and controlled-phase gates are
             ``('CPHASE', angle, target, control)``.
   :rtype: list[tuple]

   .. rubric:: Notes

   - Recursive implementation.
   - No final SWAP gates are included.
   - Use ``qft`` for standard bit ordering with swaps.


.. py:function:: iqft_swapped(wires)

   Generate the inverse QFT gate sequence with reversed bit ordering.

   :param wires: List of qubit indices on which to apply the inverse QFT.
   :type wires: list[int]

   :returns: Gate instructions for the inverse QFT, in the same format as ``qft_sw``.
   :rtype: list[tuple]

   .. rubric:: Notes

   - Controlled-phase gates have their angles negated relative to ``qft_sw``.
   - No final SWAP gates are included.


.. py:function:: qft(wires)

   Generate the full Quantum Fourier Transform (QFT) gate sequence.

   :param wires: List of qubit indices on which to apply the QFT.
   :type wires: list[int]

   :returns: Gate instructions including Hadamard, controlled-phase, and final
             SWAP gates for normal bit ordering.
   :rtype: list[tuple]

   .. rubric:: Notes

   - Combines ``qft_sw`` with SWAP gates to reorder qubits to standard output order.


.. py:function:: iqft(wires)

   Generate the inverse Quantum Fourier Transform (IQFT) gate sequence.

   :param wires: List of qubit indices on which to apply the IQFT.
   :type wires: list[int]

   :returns: Gate instructions for the inverse QFT, including SWAPs.
   :rtype: list[tuple]

   .. rubric:: Notes

   - The angles of controlled-phase gates are negated relative to the QFT.
   - Bit ordering should be checked if interfacing with other routines.


.. py:function:: count_gates_qft_swapped(m)

   Compute the number of gates in the recursive QFT (reversed bit ordering).

   :param m: Number of qubits in the QFT.
   :type m: int

   :returns: Dictionary with keys:
             - ``'H'`` : number of Hadamard gates
             - ``'CPHASE'`` : number of controlled-phase gates
   :rtype: dict[str, int]

   .. rubric:: Notes

   - SWAP gates are **not** counted.
   - Gate count corresponds to the reversed-output QFT.