version: "1.0.1" name: quantum-fourier-transform description: Use this skill when the user asks for Quantum Fourier Transform (QFT), inverse QFT (IQFT), Fourier-basis state conversion, QFT circuit construction, or implementing/running/debugging QFTAlgorithm in the UnitaryLab algorithm library. Prefer the UnitaryLab QFTAlgorithm and unitarylab.core.Circuit implementation; PennyLane material is reference-only.

Quantum Fourier Transform (QFT)

Purpose

The Quantum Fourier Transform maps computational-basis amplitudes into the Fourier basis. It is the quantum analogue of the discrete Fourier transform and is a core subroutine in phase estimation, Shor-style period finding, quantum arithmetic, and several linear-algebra routines.

Use this skill when you need to:

• Build or run a QFT or inverse QFT circuit in UnitaryLab.
• Verify a QFT simulation against NumPy FFT/iFFT.
• Explain the QFTAlgorithm implementation in unitarylab_algorithms.linear_algebra.qft.algorithm.
• Diagnose phase-ordering, inverse-transform, or bit-reversal issues.

Overview

For an $n$-qubit register, QFT acts on basis state $|x\rangle$ as:

$$

$$

The UnitaryLab implementation constructs the transform with:

• Hadamard gates h(i) to create local Fourier superpositions.
• Multi-controlled phase gates mcp(theta, control, target) to encode relative phases.
• Final swap(i, n-1-i) gates to restore output bit order.
• qft.dagger() for inverse QFT.

The algorithm then appends this QFT/IQFT block to an optional initialized state and verifies the simulator output against NumPy's FFT routines.

Prerequisites

• Qubit indexing and computational-basis states.
• Hadamard, controlled phase rotation, and SWAP gates.
• Python: numpy, numpy.fft, unitarylab.core.Circuit, unitarylab_algorithms.

Using the Provided Implementation

import numpy as np
from unitarylab_algorithms.linear_algebra.qft.algorithm import QFTAlgorithm
algo = QFTAlgorithm(text_mode="plain")
state = np.zeros(8, dtype=complex)
state[1] = 1.0
result = algo.run(
    n=3,
    state=state,
    inverse=False,
    backend="torch",
    device="cpu",
)
print(result["status"])
print(result["Verification error"])
print(result["Final state"])
print(result["Expected state"])
print(result["circuit_path"])

For inverse QFT:

result = algo.run(n=3, state=state, inverse=True, backend="torch")

Core Parameters Explained

Common misunderstandings:

• state must have length 2**n. The helper test() validates this before calling run().
• The implementation normalizes state internally. Pass amplitudes, not probabilities.
• inverse=True does not rebuild a separate circuit by hand; it calls qft.dagger() and renames the circuit to IQFT.
• The NumPy check uses ifft(state) * sqrt(2**n) for QFT and fft(state) / sqrt(2**n) for IQFT, matching the implemented sign and normalization convention.

Return Fields

Implementation Architecture

QFTAlgorithm in algorithm.py extends BaseAlgorithm and follows three computational stages plus export.

QFT construction loop:

qft = Circuit(n, name="QFT")
for i in range(n - 1, -1, -1):
    qft.h(i)
    for j in range(i - 1, -1, -1):
        qft.mcp(np.pi / 2 ** (i - j), j, i)
for i in range(n // 2):
    qft.swap(i, n - 1 - i)

For n=3, the forward circuit structure is:

H(2)
MCP(pi/2, 1 -> 2)
MCP(pi/4, 0 -> 2)
H(1)
MCP(pi/2, 0 -> 1)
H(0)
SWAP(0, 2)

Theory-to-Code Mapping

Minimal Manual Implementation

import numpy as np
from unitarylab.core import Circuit
def build_qft(n: int, inverse: bool = False) -> Circuit:
    qft = Circuit(n, name="QFT")
    for i in range(n - 1, -1, -1):
        qft.h(i)
        for j in range(i - 1, -1, -1):
            qft.mcp(np.pi / 2 ** (i - j), j, i)
    for i in range(n // 2):
        qft.swap(i, n - 1 - i)
    if inverse:
        qft = qft.dagger()
        qft.update_name("IQFT")
        qft.gate_sequence.update_name("IQFT")
    return qft
def run_qft_state(state, inverse: bool = False, backend: str = "torch"):
    state = np.asarray(state, dtype=complex)
    n = int(np.log2(state.size))
    if state.size != 2**n:
        raise ValueError("State length must be a power of two.")
    state = state / np.linalg.norm(state)
    qc = Circuit(n, name="QFT Example")
    qc.initialize(state, range(n))
    qc.append(build_qft(n, inverse=inverse), range(n))
    final = qc.execute(backend=backend).state
    expected = np.fft.fft(state) / np.sqrt(2**n) if inverse else np.fft.ifft(state) * np.sqrt(2**n)
    return final, expected, np.linalg.norm(final - expected)

Debugging Tips

Reference Implementation (PennyLane)

PennyLane's QFT operation is useful as a reference for matrix conventions, decomposition, and resource counts. In this repository, however, the primary implementation path is UnitaryLab through QFTAlgorithm, Circuit, and simulator verification against NumPy.

PennyLane's decomposition uses the same conceptual pieces:

• Hadamard gates.
• Controlled phase shifts with angles $2\pi / 2^k$.
• Final SWAP gates for bit order.
• qml.adjoint(qml.QFT) for inverse QFT.

Minimal PennyLane reference:

import pennylane as qml
import numpy as np
n = 3
dev = qml.device("default.qubit", wires=n)
@qml.qnode(dev)
def circuit():
    qml.BasisState(np.array([1, 0, 0]), wires=range(n))
    qml.QFT(wires=range(n))
    return qml.state()
state = circuit()

Use this reference only for conceptual comparison or cross-framework checks. For this skill, examples, debugging, and production guidance should stay centered on unitarylab_algorithms.linear_algebra.qft.algorithm.QFTAlgorithm.