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.

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

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.

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

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 depends on has_implementation:

• If has_implementation=True:

  • operands[0]: BlockValue (the implementation)

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

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

  • operands[1+num_control_qubits+num_target_qubits:]: Parameters

• If has_implementation=False (stub):

  • 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,
    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: ‘BlockValue | None’ Get the implementation BlockValue, if any.

• 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: BlockValue Compiles the function to a BlockValue (IR) 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 = {}) -> Graph

Build the computation graph by tracing this kernel.

Parameters:

Returns:

Graph — The traced computation graph ready for transpilation.

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
graph = circuit.build()

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

# theta bound to concrete value
graph = 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(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

def get_const(self) -> int | float | None

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.