qamomile.circuit.stdlib

Standard library of quantum algorithms.

Available:

Classes: - QFT: Quantum Fourier Transform (CompositeGate class) - IQFT: Inverse Quantum Fourier Transform (CompositeGate class)

Strategies: - StandardQFTStrategy: Full precision QFT - ApproximateQFTStrategy: Truncated rotations QFT - StandardIQFTStrategy: Full precision IQFT - ApproximateIQFTStrategy: Truncated rotations IQFT

Functions: - qft: Apply QFT to a vector of qubits - iqft: Apply IQFT to a vector of qubits - qpe: Quantum Phase Estimation

Example:

# Using class-based API (recommended for custom gates)
from qamomile.circuit.stdlib import QFT, IQFT

class MyCustomGate(CompositeGate):
    def _decompose(self, qubits):
        # Use QFT as building block
        ...

# Using function-based API (recommended for kernels)
from qamomile.circuit.stdlib import qft, iqft

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

# Using strategies
qft_gate = QFT(5)
result = qft_gate(q0, q1, q2, q3, q4, 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.

The same symbolic-shape contract as :func:qft applies here: when qubits has no compile-time-known shape (a sub-kernel parameter traced standalone) the function silently returns qubits unchanged, leaving the sub-kernel block empty.

Parameters:

Returns:

Vector[Qubit] — 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

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

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.

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

qamomile.circuit.stdlib.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.

The same symbolic-shape contract as :func:qft applies here: when qubits has no compile-time-known shape (a sub-kernel parameter traced standalone) the function silently returns qubits unchanged, leaving the sub-kernel block empty.

Parameters:

Returns:

Vector[Qubit] — 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.

When qubits has a concrete (compile-time known) shape this emits the standard O(n^2) QFT decomposition. When qubits is a sub-kernel parameter whose shape is still symbolic at trace time (e.g. def apply_qft(qs: Vector[Qubit]): return qft(qs) traced standalone) the function silently returns qubits unchanged: with no concrete n we cannot decide how many controlled-phase gates to emit, so we leave the sub-kernel block empty and let the outer composition layer re-trace once the shape is resolved. This is the only acceptable fallback while get_size is strict and the composition machinery does not yet propagate concrete shapes back into already-built sub-kernel blocks.

Parameters:

Returns:

Vector[Qubit] — 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 Block 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 = {}) -> Block | None

Build the decomposition circuit dynamically.

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

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

Parameters:

Returns:

Block | None — Block 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) -> Block | None

Get the implementation Block, 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

qamomile.circuit.stdlib.qft_strategies¶

Decomposition strategies for QFT and IQFT.

This module provides multiple decomposition strategies for the Quantum Fourier Transform, allowing trade-offs between precision and gate count.

Strategies:

StandardQFTStrategy: Full precision QFT with O(n^2) gates ApproximateQFTStrategy: Truncated rotations with O(n*k) gates

Example:

from qamomile.circuit.stdlib.qft_strategies import (
    StandardQFTStrategy,
    ApproximateQFTStrategy,
)
from qamomile.circuit.stdlib.qft import QFT

# Register strategies
QFT.register_strategy("standard", StandardQFTStrategy())
QFT.register_strategy("approximate", ApproximateQFTStrategy(truncation_depth=3))

# Use approximate strategy
qft_gate = QFT(5)
result = qft_gate(q0, q1, q2, q3, q4, strategy="approximate")

Overview¶

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

Qubit [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

• value: Value[QubitType]

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

qamomile.circuit.stdlib.qpe¶

Quantum Phase Estimation implementation.

Example:

@qmc.qkernel
def p_gate(q: qmc.Qubit, theta: float) -> qmc.Qubit:
    return qmc.p(q, theta)

@qmc.qkernel
def circuit(theta: float) -> qmc.Float:
    counting = qmc.qubit_array(3, name="counting")
    target = qmc.qubit(name="target")
    target = qmc.x(target)

    phase = qmc.qpe(target, counting, p_gate, theta=theta)
    return qmc.measure(phase)

Overview¶

Functions¶

for_loop [source]¶

def for_loop(
    start,
    stop,
    step = 1,
    var_name: str = '_loop_idx',
) -> Generator[UInt, None, None]

Builder function to create a for loop in Qamomile frontend.

Parameters:

Yields:

UInt — The loop iteration variable (can be used as array index)

Example:

@QKernel
def my_kernel(qubits: Array[Qubit, Literal[3]]) -> Array[Qubit, Literal[3]]:
    for i in qm.range(3):
        qubits[i] = h(qubits[i])
    return qubits

@QKernel
def my_kernel2(qubits: Array[Qubit, Literal[5]]) -> Array[Qubit, Literal[5]]:
    for i in qm.range(1, 4):  # i = 1, 2, 3
        qubits[i] = h(qubits[i])
    return qubits

get_current_tracer [source]¶

def get_current_tracer() -> Tracer

qpe [source]¶

def qpe(
    target: Qubit,
    counting: Vector[Qubit],
    unitary: QKernel,
    **params: Any = {},
) -> QFixed

Quantum Phase Estimation.

Estimates the phase φ where U|ψ> = e^{2πiφ}|ψ>.

Parameters:

Returns:

QFixed — Phase register as quantum fixed-point number

Classes¶

CastOperation [source]¶

class CastOperation(Operation)

Type cast operation for creating aliases over the same quantum resources.

This operation does NOT allocate new qubits. It creates a new Value that references the same underlying quantum resources with a different type.

Use cases:

• Vector[Qubit] -> QFixed (after QPE, for phase measurement)

• Vector[Qubit] -> QUInt (for quantum arithmetic)

• QUInt -> QFixed (reinterpret bits with different encoding)

• QFixed -> QUInt (reinterpret bits with different encoding)

operands: [source_value] - The value being cast results: [cast_result] - The new value with target type (same physical qubits)

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    source_type: ValueType | None = None,
    target_type: ValueType | None = None,
    qubit_mapping: list[str] = list(),
) -> None

Attributes¶

• num_qubits: int Number of qubits involved in the cast.

• operation_kind: OperationKind Cast stays in the same segment as its source (QUANTUM for quantum types).

• qubit_mapping: list[str]

• signature: Signature Return the type signature of this cast operation.

• source_type: ValueType | None

• target_type: ValueType | None

CompositeGateOperation [source]¶

class CompositeGateOperation(Operation)

Represents a composite gate (QPE, QFT, etc.) as a single operation.

CompositeGate allows representing complex multi-gate operations as a single atomic operation in the IR. This enables:

• Resource estimation without full implementation

• Backend-native conversion (e.g., Qiskit’s QPE)

• User-defined complex gates

The operands structure is:

• operands[0:num_control_qubits]: Control qubits (if any)

• operands[num_control_qubits:num_control_qubits+num_target_qubits]: Target qubits

• operands[num_control_qubits+num_target_qubits:]: Parameters

The results structure:

• results[0:num_control_qubits]: Control qubits (returned)

• results[num_control_qubits:]: Target qubits (returned)

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
    num_control_qubits: int = 0,
    num_target_qubits: int = 0,
    custom_name: str = '',
    resource_metadata: ResourceMetadata | None = None,
    has_implementation: bool = True,
    implementation_block: Block | None = None,
    composite_gate_instance: Any = None,
    strategy_name: str | None = None,
) -> None

Attributes¶

• composite_gate_instance: Any

• control_qubits: list[‘Value’] Get the control qubit operands.

• custom_name: str

• gate_type: CompositeGateType

• has_implementation: bool

• implementation: Block | None Get the implementation block, if any.

• implementation_block: Block | None

• name: str Human-readable name of this composite gate.

• num_control_qubits: int

• num_target_qubits: int

• operation_kind: OperationKind Return the operation kind (always QUANTUM).

• parameters: list[‘Value’] Get the parameter operands (angles, etc.).

• resource_metadata: ResourceMetadata | None

• signature: Signature Return the operation signature.

• strategy_name: str | None

• target_qubits: list[‘Value’] Get the target qubit operands.

CompositeGateType [source]¶

class CompositeGateType(enum.Enum)

Registry of known composite gate types.

Attributes¶

• CUSTOM

• IQFT

• QFT

• QPE

QKernel [source]¶

class QKernel(Generic[P, R])

Decorator class for Qamomile quantum kernels.

Constructor¶

def __init__(self, func: Callable[P, R]) -> None

Attributes¶

• block: Block Compile the function to a hierarchical Block if not already compiled.

• func

• input_types

• name

• output_types

• raw_func

• signature

Methods¶

build¶

def build(self, parameters: list[str] | None = None, **kwargs: Any = {}) -> Block

Build a traced Block by tracing this kernel.

Parameters:

Returns:

Block — The traced block ready for transpilation, estimation, or visualization.

Raises:

• TypeError — If a non-parameterizable type is specified as parameter.

• ValueError — If required arguments are missing.

Example:

@qm.qkernel
def circuit(q: Qubit, theta: float) -> Qubit:
    q = qm.rx(q, theta)
    return q

# Auto-detect theta as parameter
block = circuit.build()

# Explicit parameter list
block = circuit.build(parameters=["theta"])

# theta bound to concrete value
block = circuit.build(theta=0.5)

# Transpile with binding
transpiler = QiskitTranspiler()
result = transpiler.emit(graph, binding={"theta": 0.5})

draw¶

def draw(
    self,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
    **kwargs: Any = {},
) -> Any

Visualize the circuit using Matplotlib.

This method builds the computation graph and creates a static visualization. Parameters are auto-detected: non-Qubit arguments without concrete values are shown as symbolic parameters.

Parameters:

Returns:

Any — matplotlib.figure.Figure object.

Raises:

• ImportError — If matplotlib is not installed.

Example:

import qamomile.circuit as qm

@qm.qkernel
def inner(q: qm.Qubit) -> qm.Qubit:
    return qm.x(q)

@qm.qkernel
def circuit(q: qm.Qubit, theta: float) -> qm.Qubit:
    q = inner(q)
    q = qm.h(q)
    q = qm.rx(q, theta)
    return q

# Draw with auto-detected symbolic parameter (theta)
fig = circuit.draw()

# Draw with bound parameter
fig = circuit.draw(theta=0.5)

# Draw with blocks as boxes (default)
fig = circuit.draw()

# Draw with blocks expanded (inlined)
fig = circuit.draw(inline=True)

# Draw with loops folded (shown as blocks)
fig = circuit.draw(fold_loops=True)

# Draw with composite gates expanded
fig = circuit.draw(expand_composite=True)

estimate_resources¶

def estimate_resources(self, *, bindings: dict[str, Any] | None = None) -> ResourceEstimate

Estimate all resources for this kernel’s circuit.

Convenience method that delegates to the module-level estimate_resources function, eliminating the need to access .block directly.

Parameters:

Returns:

ResourceEstimate — ResourceEstimate with qubits, gates, and parameters.

Example:

>>> @qm.qkernel
... def bell() -> qm.Vector[qm.Qubit]:
...     q = qm.qubit_array(2)
...     q[0] = qm.h(q[0])
...     q[0], q[1] = qm.cx(q[0], q[1])
...     return q
>>> est = bell.estimate_resources()
>>> print(est.qubits)  # 2

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

Value [source]¶

class Value(_MetadataValueMixin, Generic[T])

A typed SSA value in the IR.

The name field is display-only: it labels the value for visualization and error messages and has no role in identity. Identity is carried by uuid (per-version) and logical_id (across versions).

An empty string (name="") is the anonymous marker used by auto-generated tmp values (arithmetic results, comparison results, coerced constants). Name-based readers must guard with truthiness (if value.name and value.name in bindings: ...) so anonymous values never collide on a shared empty key. User-supplied parameter names and array names continue to be non-empty.

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    metadata: ValueMetadata = ValueMetadata(),
    uuid: str = (lambda: str(uuid.uuid4()))(),
    logical_id: str = (lambda: str(uuid.uuid4()))(),
    parent_array: ArrayValue | None = None,
    element_indices: tuple[Value, ...] = (),
) -> None

Attributes¶

• element_indices: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

is_array_element¶

def is_array_element(self) -> bool

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version and fresh UUID.

Metadata is intentionally preserved across versions so that parameter bindings and constant annotations remain accessible after the value is updated (e.g. by a gate application or a classical operation). The logical_id also stays the same: it identifies the same logical variable across SSA versions, independently of backend resource allocation. This applies to every Value regardless of its type (Qubit, Float, Bit, ...) -- it is not specific to qubits.