uniqc.algorithms.core.circuits.qft module

Quantum Fourier Transform (QFT) circuit fragment.

This module follows the circuit fragment design (see the design notes in the project README):

• qft_circuit(n_qubits, qubits=None, swaps=True) -> Circuit is the canonical fragment-style API and returns a fresh uniqc.circuit_builder.qcircuit.Circuit.

• qft_circuit(circuit, qubits=...) is kept as a deprecated in-place shim that emits DeprecationWarning.

uniqc.algorithms.core.circuits.qft.qft_circuit(first_arg=None, qubits=None, swaps=True)

Build (or apply) a Quantum Fourier Transform fragment.

Two calling conventions are supported:

# Fragment style (recommended):
qft = qft_circuit(n_qubits=3)              # returns a fresh Circuit
qft = qft_circuit(3, qubits=[2, 3, 4])     # explicit qubit layout

# Legacy in-place style (deprecated, emits DeprecationWarning):
c = Circuit(3)
qft_circuit(c, qubits=[0, 1, 2])           # mutates c, returns None

The QFT maps \(|j\rangle\) to \(\frac{1}{\sqrt{N}} \sum_{k=0}^{N-1} e^{2\pi i jk / N} |k\rangle\).

Parameters:

• first_arg – Either an integer n_qubits (fragment mode) or a Circuit (deprecated in-place mode). May be None if qubits is given.

• qubits (list[int] | None) – Qubit indices to operate on. None defaults to range(n_qubits).

• swaps (bool) – Whether to append the SWAP layer that reverses qubit order so the output follows the standard big-endian convention.

Returns:

A fresh Circuit in fragment mode; None in legacy mode.

Raises:

ValueError – Fewer than 1 qubit specified.

uniqc.algorithms.core.circuits.qft.qft_example()

Return a 3-qubit QFT circuit, used by docs and tests as a smoke example.

Return type:

Circuit