qamomile.circuit.qft

Quantum Fourier Transform implementation using CompositeGate.

This module provides QFT and IQFT as CompositeGate classes, serving as a reference for implementing custom composite gates using the frontend API.

Multiple decomposition strategies are available:

• “standard”: Full precision QFT with O(n^2) gates

• “approximate”: Truncated rotations with O(n*k) gates (default k=3)

• “approximate_k2”: Truncated rotations with k=2

Example:

from qamomile.circuit.stdlib.qft import QFT, IQFT, qft, iqft

@qmc.qkernel
def my_algorithm(qubits: Vector[Qubit]) -> Vector[Qubit]:
    # Using factory function
    qubits = qft(qubits)
    # ... some operations ...
    qubits = iqft(qubits)
    return qubits

# Or using class directly with strategy selection
qft_gate = QFT(3)
result = qft_gate(q0, q1, q2, strategy="approximate")

# Compare resources
standard_resources = qft_gate.get_resources_for_strategy("standard")
approx_resources = qft_gate.get_resources_for_strategy("approximate")

Overview¶

Functions¶

iqft [source]¶

def iqft(qubits: Vector[Qubit]) -> Vector[Qubit]

Apply Inverse Quantum Fourier Transform to a vector of qubits.

This is a convenience factory function that creates an IQFT gate and applies it to the qubits.

Parameters:

Returns:

Vector[Qubit] — Transformed qubits (same vector, modified in place)

Example:

@qmc.qkernel
def my_algorithm(qubits: Vector[Qubit]) -> Vector[Qubit]:
    qubits = iqft(qubits)
    return qubits

qft [source]¶

def qft(qubits: Vector[Qubit]) -> Vector[Qubit]

Apply Quantum Fourier Transform to a vector of qubits.

This is a convenience factory function that creates a QFT gate and applies it to the qubits.

Parameters:

Returns:

Vector[Qubit] — Transformed qubits (same vector, modified in place)

Example:

@qmc.qkernel
def my_algorithm(qubits: Vector[Qubit]) -> Vector[Qubit]:
    qubits = qft(qubits)
    return qubits

Classes¶

ApproximateIQFTStrategy [source]¶

class ApproximateIQFTStrategy

Approximate inverse QFT decomposition with truncated rotations.

This strategy truncates small-angle rotations in the IQFT, mirroring the ApproximateQFTStrategy.

Constructor¶

def __init__(self, truncation_depth: int = 3) -> None

Attributes¶

• name: str Return strategy identifier.

• truncation_depth: int

Methods¶

decompose¶

def decompose(self, qubits: tuple['Qubit', ...]) -> tuple['Qubit', ...]

Decompose IQFT with truncated rotations.

Parameters:

Returns:

tuple['Qubit', ...] — Output qubits after approximate IQFT transformation

resources¶

def resources(self, num_qubits: int) -> ResourceMetadata

Return resource estimates for approximate IQFT.

Parameters:

Returns:

ResourceMetadata — ResourceMetadata with gate counts

ApproximateQFTStrategy [source]¶

class ApproximateQFTStrategy

Approximate QFT decomposition with truncated rotations.

This strategy truncates small-angle rotations to reduce gate count while maintaining acceptable precision for many applications.

For a given truncation_depth k:

• Only controlled phases with angle >= pi/2^k are applied

• Gate count is O(n*k) instead of O(n^2)

• Error scales as O(n/2^k)

Constructor¶

def __init__(self, truncation_depth: int = 3) -> None

Attributes¶

• name: str Return strategy identifier.

• truncation_depth: int

Methods¶

decompose¶

def decompose(self, qubits: tuple['Qubit', ...]) -> tuple['Qubit', ...]

Decompose QFT with truncated rotations.

Parameters:

Returns:

tuple['Qubit', ...] — Output qubits after approximate QFT transformation

resources¶

def resources(self, num_qubits: int) -> ResourceMetadata

Return resource estimates for approximate QFT.

Parameters:

Returns:

ResourceMetadata — ResourceMetadata with gate counts

CompositeGate [source]¶

class CompositeGate(abc.ABC)

Base class for user-facing composite gate definitions.

Subclasses can define composite gates in two ways:

1. Using _decompose() (recommended for users): Define the gate decomposition using frontend syntax (same as qkernel [source]).

   class QFT(CompositeGate):
       def __init__(self, num_qubits: int):
           self._num_qubits = num_qubits
   
       @property
       def num_target_qubits(self) -> int:
           return self._num_qubits
   
       def _decompose(self, qubits: Vector[Qubit]) -> Vector[Qubit]:
           # Use frontend syntax: qm.h(), qm.cp(), qm.range(), etc.
           n = self._num_qubits
           for j in qmc.range(n - 1, -1, -1):
               qubits[j] = qmc.h(qubits[j])
               for k in qmc.range(j - 1, -1, -1):
                   angle = math.pi / (2 ** (j - k))
                   qubits[j], qubits[k] = qmc.cp(qubits[j], qubits[k], angle)
           return qubits
   
       def _resources(self) -> ResourceMetadata:
           return ResourceMetadata(t_gates=0)

2. Using get_implementation() (advanced): Return a pre-built BlockValue directly.

Example usage:

# Factory function pattern
def qft(qubits: Vector[Qubit]) -> Vector[Qubit]:
    n = _get_size(qubits)
    return QFT(n)(qubits)

# Direct class usage
result = QFT(3)(*qubit_list)

Attributes¶

• custom_name: str

• gate_type: CompositeGateType

• num_control_qubits: int Number of control qubits (default: 0).

• num_target_qubits: int Number of target qubits this gate operates on.

Methods¶

build_decomposition¶

def build_decomposition(self, *qubits: Qubit = (), **params: Any = {}) -> 'BlockValue | None'

Build the decomposition circuit dynamically.

Override this method to provide a decomposition that depends on runtime arguments (e.g., QPE needs the unitary BlockValue).

This method is called by InlinePass when inlining composite gates that have dynamic implementations.

Parameters:

Returns:

'BlockValue | None' — BlockValue containing the decomposition, or None if not available.

Example:

class QPE(CompositeGate):
    def build_decomposition(self, *qubits, **params):
        unitary = params.get("unitary")
        # Build QPE circuit using the unitary
        return self._build_qpe_impl(qubits, unitary)

get_implementation¶

def get_implementation(self) -> 'BlockValue | None'

Get the implementation BlockValue, if any.

Return None for stub gates (used in resource estimation). Override in subclasses to provide implementation.

Note: If _decompose() is defined, it takes precedence over this method.

get_resource_metadata¶

def get_resource_metadata(self) -> ResourceMetadata | None

Get resource estimation metadata.

Returns _resources() if defined, otherwise None. Override _resources() to provide resource hints.

get_resources_for_strategy¶

def get_resources_for_strategy(self, strategy_name: str | None = None) -> ResourceMetadata | None

Get resource metadata for a specific strategy.

Parameters:

Returns:

ResourceMetadata | None — ResourceMetadata for the strategy, or None if not available

get_strategy¶

@classmethod
def get_strategy(cls, name: str | None = None) -> 'DecompositionStrategy | None'

Get a registered decomposition strategy.

Parameters:

Returns:

'DecompositionStrategy | None' — DecompositionStrategy instance, or None if not found

list_strategies¶

@classmethod
def list_strategies(cls) -> list[str]

List all registered strategy names.

Returns:

list[str] — List of strategy names

register_strategy¶

@classmethod
def register_strategy(cls, name: str, strategy: 'DecompositionStrategy') -> None

Register a decomposition strategy for this gate type.

Parameters:

Example:

QFT.register_strategy("approximate", ApproximateQFTStrategy(k=3))

set_default_strategy¶

@classmethod
def set_default_strategy(cls, name: str) -> None

Set the default decomposition strategy.

Parameters:

Raises:

• ValueError — If strategy is not registered

CompositeGateType [source]¶

class CompositeGateType(enum.Enum)

Registry of known composite gate types.

Attributes¶

• CUSTOM

• IQFT

• QFT

• QPE

IQFT [source]¶

class IQFT(CompositeGate)

Inverse Quantum Fourier Transform composite gate.

The IQFT is the inverse of the QFT. It’s a key component of:

• Quantum Phase Estimation (QPE)

• Shor’s algorithm

• Quantum counting

Available strategies:

• “standard”: Full precision IQFT (default)

• “approximate”: Truncated rotations (k=3)

• “approximate_k2”: Truncated rotations (k=2)

Example:

# Create IQFT for 3 qubits
iqft_gate = IQFT(3)

# Apply to qubits
result = iqft_gate(q0, q1, q2)

# Apply with specific strategy
result = iqft_gate(q0, q1, q2, strategy="approximate")

# Or use the factory function
qubits = iqft(qubit_vector)

Constructor¶

def __init__(self, num_qubits: int)

Initialize IQFT gate.

Parameters:

Attributes¶

• custom_name

• gate_type

• num_target_qubits: int Return the number of target qubits.

QFT [source]¶

class QFT(CompositeGate)

Quantum Fourier Transform composite gate.

The QFT is the quantum analog of the discrete Fourier transform. It’s a key component of many quantum algorithms.

Available strategies:

• “standard”: Full precision QFT (default)

• “approximate”: Truncated rotations (k=3)

• “approximate_k2”: Truncated rotations (k=2)

Example:

# Create QFT for 3 qubits
qft_gate = QFT(3)

# Apply to qubits (uses default strategy)
result = qft_gate(q0, q1, q2)

# Apply with specific strategy
result = qft_gate(q0, q1, q2, strategy="approximate")

# Compare resources between strategies
standard = qft_gate.get_resources_for_strategy("standard")
approx = qft_gate.get_resources_for_strategy("approximate")

# Or use the factory function
qubits = qft(qubit_vector)

Constructor¶

def __init__(self, num_qubits: int)

Initialize QFT gate.

Parameters:

Attributes¶

• custom_name

• gate_type

• num_target_qubits: int Return the number of target qubits.

ResourceMetadata [source]¶

class ResourceMetadata

Resource estimation metadata for composite gates.

Gate count fields mirror GateCount categories.

None semantics:

Fields left as None mean “unknown/unspecified”. During extraction, gate_counter treats None as 0, which may undercount resources if the true value is nonzero. To ensure accurate resource estimates, set all relevant fields explicitly.

When total_gates is set but some of single_qubit_gates, two_qubit_gates, or multi_qubit_gates are None, the extractor emits a UserWarning if the known sub-total is less than total_gates, indicating potentially missing gate category data.

Constructor¶

def __init__(
    self,
    query_complexity: int | None = None,
    t_gates: int | None = None,
    ancilla_qubits: int = 0,
    total_gates: int | None = None,
    single_qubit_gates: int | None = None,
    two_qubit_gates: int | None = None,
    multi_qubit_gates: int | None = None,
    clifford_gates: int | None = None,
    rotation_gates: int | None = None,
    custom_metadata: dict[str, Any] = dict(),
) -> None

Attributes¶

• ancilla_qubits: int

• clifford_gates: int | None

• custom_metadata: dict[str, Any]

• multi_qubit_gates: int | None

• query_complexity: int | None

• rotation_gates: int | None

• single_qubit_gates: int | None

• t_gates: int | None

• total_gates: int | None

• two_qubit_gates: int | None

StandardIQFTStrategy [source]¶

class StandardIQFTStrategy

Standard inverse QFT decomposition (full precision).

This strategy implements the standard IQFT decomposition, which is the inverse of the standard QFT.

Constructor¶

def __init__(self) -> None

Attributes¶

• name: str Return strategy identifier.

Methods¶

decompose¶

def decompose(self, qubits: tuple['Qubit', ...]) -> tuple['Qubit', ...]

Decompose IQFT into elementary gates.

Parameters:

Returns:

tuple['Qubit', ...] — Output qubits after IQFT transformation

resources¶

def resources(self, num_qubits: int) -> ResourceMetadata

Return resource estimates for standard IQFT.

Parameters:

Returns:

ResourceMetadata — ResourceMetadata with gate counts

StandardQFTStrategy [source]¶

class StandardQFTStrategy

Standard QFT decomposition: H + CP + SWAP (full precision).

This strategy implements the standard QFT decomposition with:

• n Hadamard gates

• n(n-1)/2 controlled phase gates

• n/2 SWAP gates for bit reversal

Total gate count: O(n^2)

Constructor¶

def __init__(self) -> None

Attributes¶

• name: str Return strategy identifier.

Methods¶

decompose¶

def decompose(self, qubits: tuple['Qubit', ...]) -> tuple['Qubit', ...]

Decompose QFT into elementary gates.

Parameters:

Returns:

tuple['Qubit', ...] — Output qubits after QFT transformation

resources¶

def resources(self, num_qubits: int) -> ResourceMetadata

Return resource estimates for standard QFT.

Parameters:

Returns:

ResourceMetadata — ResourceMetadata with gate counts