qamomile.circuit.frontend

qamomile.circuit.frontend.ast_transform¶

Overview¶

Functions¶

collect_quantum_rebind_violations [source]¶

def collect_quantum_rebind_violations(func: Callable, quantum_param_names: set[str]) -> list[RebindViolation]

Analyze func for forbidden quantum rebind patterns.

Returns a (possibly empty) list of violations. Never raises on analysis failure – returns [] instead.

emit_if [source]¶

def emit_if(
    cond_func: Callable,
    true_func: Callable,
    false_func: Callable,
    variables: list,
) -> Any

Builder function for if-else conditional with Phi function merging.

This function is called from AST-transformed code. The AST transformer converts: if condition: true_body else: false_body

Into:

def _cond_N(vars): return condition def _body_N(vars): true_body; return vars def _body_N+1(vars): false_body; return vars result = emit_if(_cond_N, _body_N, _body_N+1, [var_list])

Parameters:

Returns:

typing.Any — Merged variable values after conditional execution (using Phi functions)

Example:

@qkernel
def my_kernel(q: Qubit) -> Qubit:
    result = measure(q)
    if result:
        q = z(q)
    return q

for_items [source]¶

def for_items(
    d: Dict,
    key_var_names: list[str],
    value_var_name: str,
) -> Generator[tuple[Any, Any], None, None]

Builder function to create a for-items loop in Qamomile frontend.

This context manager creates a ForItemsOperation that iterates over dictionary (key, value) pairs. The operation is always unrolled at transpile time since quantum backends cannot natively iterate over classical data structures.

Parameters:

Yields:

tuple[typing.Any, typing.Any] — Tuple of (key_handles, value_handle) for use in loop body

Example:

@qkernel
def ising_cost(
    q: Vector[Qubit],
    ising: Dict[Tuple[UInt, UInt], Float],
    gamma: Float,
) -> Vector[Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

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

transform_control_flow [source]¶

def transform_control_flow(func: Callable)

while_loop [source]¶

def while_loop(cond: Callable) -> Generator[WhileLoop, None, None]

Create a while loop whose condition is a measurement result.

The condition must be a Bit produced by qmc.measure(). Non-measurement conditions (classical variables, constants, comparisons) are accepted at build time but will be rejected by ValidateWhileContractPass during transpilation.

Parameters:

Yields:

WhileLoop — A marker object for the while loop context.

Example::

@qm.qkernel
def repeat_until_zero() -> qm.Bit:
    q = qm.qubit("q")
    q = qm.h(q)
    bit = qm.measure(q)
    while bit:
        q = qm.qubit("q2")
        q = qm.h(q)
        bit = qm.measure(q)
    return bit

Classes¶

ControlFlowTransformer [source]¶

class ControlFlowTransformer(ast.NodeTransformer)

Constructor¶

def __init__(
    self,
    global_names: set[str] | None = None,
    param_names: set[str] | None = None,
    namespace: dict[str, Any] | None = None,
) -> None

Attributes¶

• counter: int

• for_func_name

• if_func_name

• type_registry: dict[str, ast.AST]

• while_func_name

Methods¶

visit_AnnAssign¶

def visit_AnnAssign(self, node: ast.AnnAssign) -> Any

Detect annotated assignments such as a: int = 0 and register the type information.

visit_For¶

def visit_For(self, node: ast.For) -> Any

visit_FunctionDef¶

def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef

Process the function body with definition tracking.

Collects parameter names as the initial set of defined variables and delegates to _visit_body_with_tracking for sequential statement processing.

visit_If¶

def visit_If(self, node: ast.If) -> Any

visit_While¶

def visit_While(self, node: ast.While) -> Any

QuantumRebindAnalyzer [source]¶

class QuantumRebindAnalyzer(ast.NodeVisitor)

Detects forbidden quantum variable reassignment at the AST level.

Forbidden patterns (target is an existing quantum variable):

• a = b where b is quantum with a different origin

• a = f(b, ...) where b is quantum with a different origin

Allowed patterns:

• a = f(a, ...) (self-update)

• new = f(b, ...) (new binding – target was not quantum before)

• alias = q (new alias – target was not quantum before)

Constructor¶

def __init__(self, quantum_param_names: set[str]) -> None

Attributes¶

• quantum_vars: dict[str, str]

• violations: list[RebindViolation]

Methods¶

visit_Assign¶

def visit_Assign(self, node: ast.Assign) -> None

RebindViolation [source]¶

class RebindViolation

A detected forbidden quantum variable rebinding.

Constructor¶

def __init__(
    self,
    target_name: str,
    source_name: str,
    func_name: str | None,
    lineno: int,
) -> None

Attributes¶

• func_name: str | None

• lineno: int

• source_name: str

• target_name: str

VariableCollector [source]¶

class VariableCollector(ast.NodeVisitor)

Collect variables used and mutated within a block.

Excludes:

• Function names in calls (func in Call)

• Global base objects in attribute accesses (value in Attribute)

• Global variables (modules, builtins, etc.)

Constructor¶

def __init__(self, global_names: set[str] | None = None)

Attributes¶

• incoming_vars: set[str] Variables that must come from an outer scope (first use is Load).

• load_vars: set[str] Variables referenced in Load context (actually read).

• locally_defined_vars: set[str] Variables first defined (Store) within this scope.

• store_vars: set[str] Variables assigned in Store context.

• vars

Methods¶

visit_Assign¶

def visit_Assign(self, node: ast.Assign)

Visit the RHS first to match Python’s evaluation order.

q1 = qm.h(q1) → RHS q1 (Load) is first → first_context is “Load” cond2 = qm.measure(q2) → RHS q2 (Load) first, LHS cond2 (Store) after

visit_Attribute¶

def visit_Attribute(self, node: ast.Attribute)

Record the base name of an attribute access.

Global names such as module names (qm.h) are excluded as before, while user variables (qs.shape) are treated as Load.

visit_AugAssign¶

def visit_AugAssign(self, node: ast.AugAssign)

AugAssign (e.g. x += 1) is an implicit Read-before-Write.

Visit the RHS first and record Name targets as both Load and Store. first_context is “Load” (the existing value is read first).

visit_Call¶

def visit_Call(self, node: ast.Call)

Exclude the function name of a call.

visit_FunctionDef¶

def visit_FunctionDef(self, node: ast.FunctionDef)

Skip traversal of inner function definitions.

visit_Name¶

def visit_Name(self, node: ast.Name)

Collect variable names (only those not in the exclude list).

qamomile.circuit.frontend.composite_gate¶

Frontend interface for composite gates.

Overview¶

Functions¶

composite_gate [source]¶

def composite_gate(
    func: Callable | None = None,
    *,
    stub: bool = False,
    name: str = '',
    num_qubits: int | None = None,
    num_controls: int = 0,
    resource_metadata: ResourceMetadata | None = None,
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
) -> _WrappedCompositeGate | _StubCompositeGate | Callable[[Callable], _WrappedCompositeGate | _StubCompositeGate]

Decorator to create a CompositeGate from a qkernel function or as a stub.

Usage with qkernel (implementation provided): composite_gate [source](name=“my_qft”) qkernel [source] def my_qft(q0: Qubit, q1: Qubit) -> tuple[Qubit, Qubit]: q0 = h(q0) q0, q1 = cp(q0, q1, pi/2) q1 = h(q1) return q0, q1

# Usage:
q0, q1 = my_qft(q0, q1)

Usage as stub (no implementation, for resource estimation): composite_gate [source]( stub=True, name=“oracle”, num_qubits=5, resource_metadata=ResourceMetadata(query_complexity=100, t_gates=10), ) def oracle(): pass

# Usage:
results = oracle(*qubits)
metadata = oracle.get_resource_metadata()

Parameters:

Returns:

_WrappedCompositeGate | _StubCompositeGate | Callable[[Callable], _WrappedCompositeGate | _StubCompositeGate] — A CompositeGate instance that can be called like a gate function.

get_current_tracer [source]¶

def get_current_tracer() -> Tracer

trace [source]¶

def trace(tracer: Tracer | None = None) -> Generator[Tracer, None, None]

Context manager to set the current tracer.

Classes¶

Block [source]¶

class Block

Unified block representation for all pipeline stages.

Replaces the older traced and callable IR wrappers with a single structure. The kind field indicates which pipeline stage this block is at.

Constructor¶

def __init__(
    self,
    name: str = '',
    label_args: list[str] = list(),
    input_values: list[Value] = list(),
    output_values: list[Value] = list(),
    output_names: list[str] = list(),
    operations: list['Operation'] = list(),
    kind: BlockKind = BlockKind.HIERARCHICAL,
    parameters: dict[str, Value] = dict(),
) -> None

Attributes¶

• input_values: list[Value]

• kind: BlockKind

• label_args: list[str]

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[Value]

• parameters: dict[str, Value]

Methods¶

call¶

def call(self, **kwargs: Value = {}) -> 'CallBlockOperation'

Create a CallBlockOperation against this block.

is_affine¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

BlockKind [source]¶

class BlockKind(Enum)

Classification of block structure for pipeline stages.

Attributes¶

• AFFINE

• ANALYZED

• HIERARCHICAL

• TRACED

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

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

DecompositionStrategy [source]¶

class DecompositionStrategy(Protocol)

Protocol for defining decomposition strategies.

A decomposition strategy provides:

1. A unique name for identification

2. A decompose method that performs the actual decomposition

3. Resource estimation for the decomposition

Strategies allow the same composite gate to have multiple implementations with different trade-offs (e.g., precision vs. gate count).

Attributes¶

• name: str Unique identifier for this strategy.

Methods¶

decompose¶

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

Perform the decomposition.

Parameters:

Returns:

tuple['Qubit', ...] — Output qubits after decomposition

resources¶

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

Return resource estimates for this decomposition.

Parameters:

Returns:

'ResourceMetadata' — ResourceMetadata with gate counts, depth estimates, etc.

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

Tracer [source]¶

class Tracer

Constructor¶

def __init__(self, _operations: list[Operation] = list()) -> None

Attributes¶

• operations: list[Operation]

Methods¶

add_operation¶

def add_operation(self, op) -> 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.

Vector [source]¶

class Vector(ArrayBase[T])

1-dimensional array type.

Example:

import qamomile.circuit as qmc

# Create a vector of 3 qubits
qubits: qmc.Vector[qmc.Qubit] = qmc.qubit_array(3, name="qubits")

# Access elements
q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0

# Apply H gate to all qubits (CORRECT)
n = qubits.shape[0]
for i in qmc.range(n):
    qubits[i] = qmc.h(qubits[i])

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    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,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

• value: ArrayValue

qamomile.circuit.frontend.constructors¶

Overview¶

Functions¶

bit [source]¶

def bit(arg: bool | str | int) -> Bit

Create a Bit handle from a boolean/int literal or declare a named Bit parameter.

float_ [source]¶

def float_(arg: float | str) -> Float

Create a Float handle from a float literal or declare a named Float parameter.

get_current_tracer [source]¶

def get_current_tracer() -> Tracer

qubit [source]¶

def qubit(name: str) -> Qubit

Create a new qubit and emit a QInitOperation.

qubit_array [source]¶

def qubit_array(
    shape: UInt | int | tuple[UInt | int, ...],
    name: str,
) -> Vector[Qubit] | Matrix[Qubit] | Tensor[Qubit]

Create a new qubit array (vector/matrix/tensor) and emit QInitOperations.

uint [source]¶

def uint(arg: int | str) -> UInt

Create a UInt handle from an integer literal or declare a named UInt parameter.

Classes¶

ArrayValue [source]¶

class ArrayValue(Value[T])

An array of typed IR values.

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• shape: tuple[Value, ...]

• type: T

• uuid: str

Methods¶

next_version¶

def next_version(self) -> ArrayValue[T]

QInitOperation [source]¶

class QInitOperation(Operation)

Initialize the qubit

Constructor¶

def __init__(self, operands: list[Value] = list(), results: list[Value] = list()) -> None

Attributes¶

• operation_kind: OperationKind

• signature: Signature

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.

qamomile.circuit.frontend.decomposition¶

Decomposition strategy framework for composite gates.

This module provides the infrastructure for defining multiple decomposition patterns for composite gates, enabling flexible gate synthesis strategies.

Example:

class StandardQFTStrategy:
    @property
    def name(self) -> str:
        return "standard"

    def decompose(self, qubits: tuple[Qubit, ...]) -> tuple[Qubit, ...]:
        # Full precision QFT implementation
        ...

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

class ApproximateQFTStrategy:
    def __init__(self, truncation_depth: int = 3):
        self._k = truncation_depth

    @property
    def name(self) -> str:
        return f"approximate_k{self._k}"

    def decompose(self, qubits: tuple[Qubit, ...]) -> tuple[Qubit, ...]:
        # Truncated rotations QFT
        ...

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

Overview¶

Functions¶

get_global_registry [source]¶

def get_global_registry() -> StrategyRegistry

Get the global strategy registry.

Returns:

StrategyRegistry — The global StrategyRegistry instance

get_strategy [source]¶

def get_strategy(
    gate_name: str,
    strategy_name: str | None = None,
) -> DecompositionStrategy | None

Get a strategy from the global registry.

Parameters:

Returns:

DecompositionStrategy | None — The strategy instance, or None if not found

register_strategy [source]¶

def register_strategy(gate_name: str, strategy_name: str, strategy: DecompositionStrategy) -> None

Register a strategy in the global registry.

Parameters:

Classes¶

DecompositionConfig [source]¶

class DecompositionConfig

Configuration for decomposition strategy selection.

This configuration is passed to the transpiler to control which decomposition strategies are used for composite gates.

Constructor¶

def __init__(
    self,
    strategy_overrides: dict[str, str] = dict(),
    strategy_params: dict[str, dict[str, Any]] = dict(),
    default_strategy: str = 'standard',
) -> None

Attributes¶

• default_strategy: str

• strategy_overrides: dict[str, str]

• strategy_params: dict[str, dict[str, Any]]

Methods¶

get_strategy_for_gate¶

def get_strategy_for_gate(self, gate_name: str) -> str

Get the strategy name for a specific gate.

Parameters:

Returns:

str — Strategy name to use

get_strategy_params¶

def get_strategy_params(self, strategy_name: str) -> dict[str, Any]

Get parameters for a specific strategy.

Parameters:

Returns:

dict[str, Any] — Dictionary of parameters

DecompositionStrategy [source]¶

class DecompositionStrategy(Protocol)

Protocol for defining decomposition strategies.

A decomposition strategy provides:

1. A unique name for identification

2. A decompose method that performs the actual decomposition

3. Resource estimation for the decomposition

Strategies allow the same composite gate to have multiple implementations with different trade-offs (e.g., precision vs. gate count).

Attributes¶

• name: str Unique identifier for this strategy.

Methods¶

decompose¶

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

Perform the decomposition.

Parameters:

Returns:

tuple['Qubit', ...] — Output qubits after decomposition

resources¶

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

Return resource estimates for this decomposition.

Parameters:

Returns:

'ResourceMetadata' — ResourceMetadata with gate counts, depth estimates, etc.

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

StrategyRegistry [source]¶

class StrategyRegistry

Registry for managing decomposition strategies.

This class provides a centralized registry for strategies, allowing them to be looked up by name across the transpiler pipeline.

Example:

registry = StrategyRegistry()
registry.register("qft", "standard", StandardQFTStrategy())
registry.register("qft", "approximate", ApproximateQFTStrategy())

strategy = registry.get("qft", "standard")

Constructor¶

def __init__(self) -> None

Initialize empty registry.

Methods¶

get¶

def get(
    self,
    gate_name: str,
    strategy_name: str | None = None,
) -> DecompositionStrategy | None

Get a strategy for a gate.

Parameters:

Returns:

DecompositionStrategy | None — The strategy instance, or None if not found

list_gates¶

def list_gates(self) -> list[str]

List all gates with registered strategies.

Returns:

list[str] — List of gate names

list_strategies¶

def list_strategies(self, gate_name: str) -> list[str]

List available strategies for a gate.

Parameters:

Returns:

list[str] — List of strategy names

register¶

def register(
    self,
    gate_name: str,
    strategy_name: str,
    strategy: DecompositionStrategy,
) -> None

Register a strategy for a gate.

Parameters:

qamomile.circuit.frontend.func_to_block¶

Overview¶

Constants¶

• TYPE_MAPPING: dict[Any, Any] = {int: UIntType, float: FloatType, bool: BitType}

Functions¶

create_dummy_handle [source]¶

def create_dummy_handle(value_type: ValueType, name: str = 'dummy', emit_init: bool = True) -> Handle

Create a dummy Handle instance based on ValueType.

Parameters:

Used for creating input parameters during tracing.

create_dummy_input [source]¶

def create_dummy_input(param_type: Any, name: str = 'param', emit_init: bool = True) -> Handle

Create a dummy input based on parameter type annotation.

Parameters:

This creates input Handles for function parameters.

func_to_block [source]¶

def func_to_block(func: Callable) -> Block

Convert a function to a hierarchical Block.

Example:

def my_func(a: UInt, b: UInt) -> tuple[UInt]:
    c = a + b
    return (c, )

block = func_to_block(my_func)

get_current_tracer [source]¶

def get_current_tracer() -> Tracer

handle_type_map [source]¶

def handle_type_map(handle_type: type[Handle] | type) -> ValueType

Map Handle type to ValueType.

is_array_type [source]¶

def is_array_type(t: Any) -> bool

Check if type is a Vector, Matrix, or Tensor subclass.

is_dict_type [source]¶

def is_dict_type(t: Any) -> bool

Check if type is a Dict handle type.

is_tuple_type [source]¶

def is_tuple_type(t: Any) -> bool

Check if type is a Tuple handle type.

trace [source]¶

def trace(tracer: Tracer | None = None) -> Generator[Tracer, None, None]

Context manager to set the current tracer.

Classes¶

ArrayValue [source]¶

class ArrayValue(Value[T])

An array of typed IR values.

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• shape: tuple[Value, ...]

• type: T

• uuid: str

Methods¶

next_version¶

def next_version(self) -> ArrayValue[T]

Bit [source]¶

class Bit(Handle)

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: bool = False,
) -> None

Attributes¶

• init_value: bool

BitType [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

Block [source]¶

class Block

Unified block representation for all pipeline stages.

Replaces the older traced and callable IR wrappers with a single structure. The kind field indicates which pipeline stage this block is at.

Constructor¶

def __init__(
    self,
    name: str = '',
    label_args: list[str] = list(),
    input_values: list[Value] = list(),
    output_values: list[Value] = list(),
    output_names: list[str] = list(),
    operations: list['Operation'] = list(),
    kind: BlockKind = BlockKind.HIERARCHICAL,
    parameters: dict[str, Value] = dict(),
) -> None

Attributes¶

• input_values: list[Value]

• kind: BlockKind

• label_args: list[str]

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[Value]

• parameters: dict[str, Value]

Methods¶

call¶

def call(self, **kwargs: Value = {}) -> 'CallBlockOperation'

Create a CallBlockOperation against this block.

is_affine¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

BlockKind [source]¶

class BlockKind(Enum)

Classification of block structure for pipeline stages.

Attributes¶

• AFFINE

• ANALYZED

• HIERARCHICAL

• TRACED

Dict [source]¶

class Dict(Handle, Generic[K, V])

Dict handle for qkernel functions.

Represents a dictionary mapping keys to values, commonly used for Ising coefficients like {(i, j): Jij}.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

Constructor¶

def __init__(
    self,
    value: DictValue,
    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,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
) -> None

Attributes¶

• size: UInt Return the number of entries as a UInt handle.

• value: DictValue

Methods¶

items¶

def items(self) -> DictItemsIterator[K, V]

Return an iterator over (key, value) pairs.

DictType [source]¶

class DictType(ValueType)

Type representing a dictionary mapping keys to values.

Unlike simple types, DictType stores the key and value types, so equality and hashing depend on those types. When key_type and value_type are None, represents a generic Dict type.

Quantum/classical classification is derived from key/value types.

Constructor¶

def __init__(
    self,
    key_type: ValueType | None = None,
    value_type: ValueType | None = None,
) -> None

Attributes¶

• key_type: ValueType | None

• value_type: ValueType | None

Methods¶

is_classical¶

def is_classical(self) -> bool

is_quantum¶

def is_quantum(self) -> bool

label¶

def label(self) -> str

DictValue [source]¶

class DictValue(_MetadataValueMixin)

A dictionary value stored as stable ordered entries.

Constructor¶

def __init__(
    self,
    name: str,
    entries: tuple[tuple[TupleValue | Value, Value], ...] = tuple(),
    metadata: ValueMetadata = ValueMetadata(),
    uuid: str = (lambda: str(uuid.uuid4()))(),
    logical_id: str = (lambda: str(uuid.uuid4()))(),
) -> None

Attributes¶

• entries: tuple[tuple[TupleValue | Value, Value], ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: DictType

• uuid: str

Methods¶

is_constant¶

def is_constant(self) -> bool

next_version¶

def next_version(self) -> DictValue

Float [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: float = 0.0,
) -> None

Attributes¶

• init_value: float

FloatType [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

Observable [source]¶

class Observable(Handle)

Handle representing a Hamiltonian observable parameter.

This is a reference type - the actual qamomile.observable.Hamiltonian is provided via bindings during transpilation. It cannot be constructed or manipulated within qkernels.

Example:

import qamomile.circuit as qm
import qamomile.observable as qm_o

# Build Hamiltonian in Python
H = qm_o.Z(0) * qm_o.Z(1) + 0.5 * qm_o.X(0)

@qm.qkernel
def vqe(q: qm.Vector[qm.Qubit], H: qm.Observable) -> qm.Float:
    # Use Hamiltonian from bindings
    return qm.expval(q, H)

# Pass via bindings
executable = transpiler.transpile(vqe, bindings={"H": H})

Constructor¶

def __init__(
    self,
    value: Value,
    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

ObservableType [source]¶

class ObservableType(ObjectTypeMixin, ValueType)

Type representing a Hamiltonian observable parameter.

This is a reference type - the actual qamomile.observable.Hamiltonian is provided via bindings during transpilation. It cannot be constructed or manipulated within qkernels.

Example usage:

import qamomile.circuit as qm
import qamomile.observable as qm_o

# Build Hamiltonian in Python
H = qm_o.Z(0) * qm_o.Z(1)

@qm.qkernel
def vqe(q: qm.Vector[qm.Qubit], H: qm.Observable) -> qm.Float:
    return qm.expval(q, H)

# H is passed as binding
executable = transpiler.transpile(vqe, bindings={"H": H})

Constructor¶

def __init__(self) -> None

QInitOperation [source]¶

class QInitOperation(Operation)

Initialize the qubit

Constructor¶

def __init__(self, operands: list[Value] = list(), results: list[Value] = list()) -> None

Attributes¶

• operation_kind: OperationKind

• signature: Signature

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]

ReturnOperation [source]¶

class ReturnOperation(Operation)

Explicit return operation marking the end of a block with return values.

This operation represents an explicit return statement in the IR. It takes the values to be returned as operands and produces no results (it is a terminal operation that transfers control flow back to the caller).

operands: [Value, ...] - The values to return (may be empty for void returns) results: [] - Always empty (terminal operation)

Example:

A function that returns two values (a UInt and a Float):

ReturnOperation(
    operands=[uint_value, float_value],
    results=[],
)

The signature would be:
    operands=[ParamHint("return_0", UIntType()), ParamHint("return_1", FloatType())]
    results=[]

Constructor¶

def __init__(self, operands: list[Value] = list(), results: list[Value] = list()) -> None

Attributes¶

• operation_kind: OperationKind Return CLASSICAL as this is a control flow operation without quantum effects.

• signature: Signature Return the signature with operands for each return value and no results.

Tracer [source]¶

class Tracer

Constructor¶

def __init__(self, _operations: list[Operation] = list()) -> None

Attributes¶

• operations: list[Operation]

Methods¶

add_operation¶

def add_operation(self, op) -> None

Tuple [source]¶

class Tuple(Handle, Generic[K, V])

Tuple handle for qkernel functions.

Represents a tuple of values, commonly used for multi-index keys like (i, j) in Ising models.

Example:

@qmc.qkernel
def my_kernel(idx: qmc.Tuple[qmc.UInt, qmc.UInt]) -> qmc.UInt:
    i, j = idx
    return i + j

Constructor¶

def __init__(
    self,
    value: TupleValue,
    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,
    _elements: tuple[Handle, ...] = tuple(),
) -> None

Attributes¶

• value: TupleValue

TupleType [source]¶

class TupleType(ValueType)

Type representing a tuple of values.

Unlike simple types, TupleType stores the types of its elements, so equality and hashing depend on the element types.

Quantum/classical classification is derived from element types: quantum if any element is quantum, classical if all are classical.

Constructor¶

def __init__(self, element_types: tuple[ValueType, ...]) -> None

Attributes¶

• element_types: tuple[ValueType, ...]

Methods¶

is_classical¶

def is_classical(self) -> bool

is_quantum¶

def is_quantum(self) -> bool

label¶

def label(self) -> str

TupleValue [source]¶

class TupleValue(_MetadataValueMixin)

A tuple of IR values for structured data.

Constructor¶

def __init__(
    self,
    name: str,
    elements: tuple[Value, ...] = tuple(),
    metadata: ValueMetadata = ValueMetadata(),
    uuid: str = (lambda: str(uuid.uuid4()))(),
    logical_id: str = (lambda: str(uuid.uuid4()))(),
) -> None

Attributes¶

• elements: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: ‘TupleType’

• uuid: str

Methods¶

is_constant¶

def is_constant(self) -> bool

next_version¶

def next_version(self) -> TupleValue

UInt [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: int = 0,
) -> None

Attributes¶

• init_value: int

UIntType [source]¶

class UIntType(ClassicalTypeMixin, ValueType)

Type representing an unsigned integer.

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.

ValueType [source]¶

class ValueType(abc.ABC)

Base class for all value types in the IR.

Type instances are compared by class - all instances of the same type class are considered equal. This allows using type instances as dictionary keys where all QubitType() instances match.

Methods¶

is_classical¶

def is_classical(self) -> bool

is_object¶

def is_object(self) -> bool

is_quantum¶

def is_quantum(self) -> bool

label¶

def label(self) -> str

qamomile.circuit.frontend.handle¶

Overview¶

Functions¶

get_size [source]¶

def get_size(arr: Vector[_H]) -> int

Return the size of a Vector handle as a Python integer.

Resolves the leading axis of arr.shape through two forms a Vector shape entry can take:

1. A plain Python int (built-in bound shape; this is what you get from qmc.qubit_array(N, ...) for literal N).

2. A UInt handle whose underlying Value carries a compile-time constant (set by uint(literal), _create_bound_input, or partial evaluation).

A UInt handle whose underlying Value is not a constant is treated as an unresolved symbolic dimension and raises ValueError even when the handle has the dataclass-default init_value=0. Falling back to init_value for that case would silently turn a runtime-symbolic Vector[Float] parameter into a “size 0” array, hiding programming errors. Callers that need to handle symbolic shapes (e.g., to gracefully no-op when the size is unknown) must catch the ValueError themselves.

Parameters:

Returns:

int — The first-axis size as a plain Python int.

Raises:

• ValueError — If the shape cannot be resolved to a concrete integer — e.g., the Vector is a runtime-parametric handle without compile-time bindings, or carries a UInt dimension whose underlying Value has not been promoted to a constant.

Classes¶

Bit [source]¶

class Bit(Handle)

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: bool = False,
) -> None

Attributes¶

• init_value: bool

Dict [source]¶

class Dict(Handle, Generic[K, V])

Dict handle for qkernel functions.

Represents a dictionary mapping keys to values, commonly used for Ising coefficients like {(i, j): Jij}.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

Constructor¶

def __init__(
    self,
    value: DictValue,
    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,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
) -> None

Attributes¶

• size: UInt Return the number of entries as a UInt handle.

• value: DictValue

Methods¶

items¶

def items(self) -> DictItemsIterator[K, V]

Return an iterator over (key, value) pairs.

Float [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: float = 0.0,
) -> None

Attributes¶

• init_value: float

Handle [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    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¶

• id: str

• indices: tuple[‘UInt’, ...]

• name: str | None

• parent: ‘ArrayBase | None’

• value: Value

Methods¶

consume¶

def consume(self, operation_name: str = 'unknown') -> Self

Mark this handle as consumed and return a fresh handle.

Parameters:

Returns:

typing.Self — A new handle pointing to the same underlying value.

Raises:

• QubitConsumedError — If this handle was already consumed and is a quantum type.

Matrix [source]¶

class Matrix(ArrayBase[T])

2-dimensional array type.

Example:

import qamomile as qm

# Create a 3x4 matrix of qubits
matrix: qm.Matrix[qm.Qubit] = qm.Matrix(shape=(3, 4))

# Access elements (always requires 2 indices)
q = matrix[0, 1]
q = qm.h(q)
matrix[0, 1] = q

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    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,
    _shape: tuple[int | UInt, int | UInt] = (0, 0),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

• value: ArrayValue

Observable [source]¶

class Observable(Handle)

Handle representing a Hamiltonian observable parameter.

This is a reference type - the actual qamomile.observable.Hamiltonian is provided via bindings during transpilation. It cannot be constructed or manipulated within qkernels.

Example:

import qamomile.circuit as qm
import qamomile.observable as qm_o

# Build Hamiltonian in Python
H = qm_o.Z(0) * qm_o.Z(1) + 0.5 * qm_o.X(0)

@qm.qkernel
def vqe(q: qm.Vector[qm.Qubit], H: qm.Observable) -> qm.Float:
    # Use Hamiltonian from bindings
    return qm.expval(q, H)

# Pass via bindings
executable = transpiler.transpile(vqe, bindings={"H": H})

Constructor¶

def __init__(
    self,
    value: Value,
    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

QFixed [source]¶

class QFixed(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QFixedType],
    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[QFixedType]

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]

Tensor [source]¶

class Tensor(ArrayBase[T])

N-dimensional array type (3 or more dimensions).

Example:

import qamomile as qm

# Create a 2x3x4 tensor of qubits
tensor: qm.Tensor[qm.Qubit] = qm.Tensor(shape=(2, 3, 4))

# Access elements (requires all indices)
q = tensor[0, 1, 2]
q = qm.h(q)
tensor[0, 1, 2] = q

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    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,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

• value: ArrayValue

Tuple [source]¶

class Tuple(Handle, Generic[K, V])

Tuple handle for qkernel functions.

Represents a tuple of values, commonly used for multi-index keys like (i, j) in Ising models.

Example:

@qmc.qkernel
def my_kernel(idx: qmc.Tuple[qmc.UInt, qmc.UInt]) -> qmc.UInt:
    i, j = idx
    return i + j

Constructor¶

def __init__(
    self,
    value: TupleValue,
    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,
    _elements: tuple[Handle, ...] = tuple(),
) -> None

Attributes¶

• value: TupleValue

UInt [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: int = 0,
) -> None

Attributes¶

• init_value: int

Vector [source]¶

class Vector(ArrayBase[T])

1-dimensional array type.

Example:

import qamomile.circuit as qmc

# Create a vector of 3 qubits
qubits: qmc.Vector[qmc.Qubit] = qmc.qubit_array(3, name="qubits")

# Access elements
q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0

# Apply H gate to all qubits (CORRECT)
n = qubits.shape[0]
for i in qmc.range(n):
    qubits[i] = qmc.h(qubits[i])

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    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,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

• value: ArrayValue

qamomile.circuit.frontend.handle.array¶

Overview¶

Functions¶

get_current_tracer [source]¶

def get_current_tracer() -> Tracer

Classes¶

AffineTypeError [source]¶

class AffineTypeError(QamomileCompileError)

Base class for affine type violations.

Affine types enforce that quantum resources (qubits) are used at most once. This prevents common errors such as reusing a consumed qubit or aliasing.

Constructor¶

def __init__(
    self,
    message: str,
    handle_name: str | None = None,
    operation_name: str | None = None,
    first_use_location: str | None = None,
)

Attributes¶

• first_use_location

• handle_name

• operation_name

ArrayBase [source]¶

class ArrayBase(Handle, Generic[T])

Base class for array types (Vector, Matrix, Tensor).

Provides common functionality for array indexing and element access.

Constructor¶

def __init__(
    self,
    value: ArrayValue,
    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,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

• element_type: Type[T]

• shape: tuple[int | UInt, ...] Return the shape of the array.

• value: ArrayValue

Methods¶

consume¶

def consume(self, operation_name: str = 'unknown') -> Self

Consume the array, enforcing borrow-return contract for quantum arrays.

For quantum arrays, all borrowed elements must be returned before the array can be consumed. This ensures that no unreturned borrows are silently discarded by operations like qkernel calls or controlled gates.

create¶

@classmethod
def create(
    cls,
    shape: tuple[int | UInt, ...],
    name: str,
    el_type: Type[T],
) -> 'ArrayBase[T]'

Create an ArrayValue for the given shape and name.

validate_all_returned¶

def validate_all_returned(self) -> None

Validate all borrowed elements have been returned.

This method is useful for ensuring that all borrowed elements have been properly written back before using the array in operations that require the entire array.

Raises:

• UnreturnedBorrowError — If any elements are still borrowed.

ArrayValue [source]¶

class ArrayValue(Value[T])

An array of typed IR values.

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• shape: tuple[Value, ...]

• type: T

• uuid: str

Methods¶

next_version¶

def next_version(self) -> ArrayValue[T]

Bit [source]¶

class Bit(Handle)

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: bool = False,
) -> None

Attributes¶

• init_value: bool

BitType [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

CInitOperation [source]¶

class CInitOperation(Operation)

Initialize the classical values (const, arguments etc)

Constructor¶

def __init__(self, operands: list[Value] = list(), results: list[Value] = list()) -> None

Attributes¶

• operation_kind: OperationKind

• signature: Signature

Float [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: float = 0.0,
) -> None

Attributes¶

• init_value: float

FloatType [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

Handle [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    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¶

• id: str

• indices: tuple[‘UInt’, ...]

• name: str | None

• parent: ‘ArrayBase | None’

• value: Value

Methods¶

consume¶

def consume(self, operation_name: str = 'unknown') -> Self

Mark this handle as consumed and return a fresh handle.

Parameters:

Returns:

typing.Self — A new handle pointing to the same underlying value.

Raises:

• QubitConsumedError — If this handle was already consumed and is a quantum type.

Matrix [source]¶

class Matrix(ArrayBase[T])

2-dimensional array type.

Example:

import qamomile as qm

# Create a 3x4 matrix of qubits
matrix: qm.Matrix[qm.Qubit] = qm.Matrix(shape=(3, 4))

# Access elements (always requires 2 indices)
q = matrix[0, 1]
q = qm.h(q)
matrix[0, 1] = q

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    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,
    _shape: tuple[int | UInt, int | UInt] = (0, 0),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

• value: ArrayValue

QInitOperation [source]¶

class QInitOperation(Operation)

Initialize the qubit

Constructor¶

def __init__(self, operands: list[Value] = list(), results: list[Value] = list()) -> None

Attributes¶

• operation_kind: OperationKind

• signature: Signature

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]

QubitConsumedError [source]¶

class QubitConsumedError(AffineTypeError)

Qubit handle used after being consumed by a previous operation.

Each qubit handle can only be used once. After a gate operation, you must reassign the result to use the new handle.

Example of incorrect code:

q1 = qm.h(q) q2 = qm.x(q) # ERROR: q was already consumed by h()

Correct code:

q = qm.h(q) # Reassign to capture new handle q = qm.x(q) # Use the reassigned handle

QubitType [source]¶

class QubitType(QuantumTypeMixin, ValueType)

Type representing a quantum bit (qubit).

Tensor [source]¶

class Tensor(ArrayBase[T])

N-dimensional array type (3 or more dimensions).

Example:

import qamomile as qm

# Create a 2x3x4 tensor of qubits
tensor: qm.Tensor[qm.Qubit] = qm.Tensor(shape=(2, 3, 4))

# Access elements (requires all indices)
q = tensor[0, 1, 2]
q = qm.h(q)
tensor[0, 1, 2] = q

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    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,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

• value: ArrayValue

UInt [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: int = 0,
) -> None

Attributes¶

• init_value: int

UIntType [source]¶

class UIntType(ClassicalTypeMixin, ValueType)

Type representing an unsigned integer.

UnreturnedBorrowError [source]¶

class UnreturnedBorrowError(AffineTypeError)

Borrowed array element not returned before array use.

When you borrow an element from a qubit array, you must return it (write it back) before using other elements or the array itself.

Example of incorrect code:

q0 = qubits[0] q0 = qm.h(q0) q1 = qubits[1] # ERROR: q0 not returned yet

Correct code:

q0 = qubits[0] q0 = qm.h(q0) qubits[0] = q0 # Return the borrowed element q1 = qubits[1] # Now safe to borrow another

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.

Vector [source]¶

class Vector(ArrayBase[T])

1-dimensional array type.

Example:

import qamomile.circuit as qmc

# Create a vector of 3 qubits
qubits: qmc.Vector[qmc.Qubit] = qmc.qubit_array(3, name="qubits")

# Access elements
q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0

# Apply H gate to all qubits (CORRECT)
n = qubits.shape[0]
for i in qmc.range(n):
    qubits[i] = qmc.h(qubits[i])

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    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,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

• value: ArrayValue

qamomile.circuit.frontend.handle.containers¶

Container types for qkernel: Tuple and Dict handles.

Overview¶

Classes¶

Dict [source]¶

class Dict(Handle, Generic[K, V])

Dict handle for qkernel functions.

Represents a dictionary mapping keys to values, commonly used for Ising coefficients like {(i, j): Jij}.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

Constructor¶

def __init__(
    self,
    value: DictValue,
    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,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
) -> None

Attributes¶

• size: UInt Return the number of entries as a UInt handle.

• value: DictValue

Methods¶

items¶

def items(self) -> DictItemsIterator[K, V]

Return an iterator over (key, value) pairs.

DictItemsIterator [source]¶

class DictItemsIterator(Generic[K, V])

Iterator for Dict.items() that yields (key, value) pairs.

This is used internally for iterating over Dict entries in qkernel.

Constructor¶

def __init__(self, dict_handle: 'Dict[K, V]', _index: int = 0) -> None

Attributes¶

• dict_handle: ‘Dict[K, V]’

DictValue [source]¶

class DictValue(_MetadataValueMixin)

A dictionary value stored as stable ordered entries.

Constructor¶

def __init__(
    self,
    name: str,
    entries: tuple[tuple[TupleValue | Value, Value], ...] = tuple(),
    metadata: ValueMetadata = ValueMetadata(),
    uuid: str = (lambda: str(uuid.uuid4()))(),
    logical_id: str = (lambda: str(uuid.uuid4()))(),
) -> None

Attributes¶

• entries: tuple[tuple[TupleValue | Value, Value], ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: DictType

• uuid: str

Methods¶

is_constant¶

def is_constant(self) -> bool

next_version¶

def next_version(self) -> DictValue

Handle [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    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¶

• id: str

• indices: tuple[‘UInt’, ...]

• name: str | None

• parent: ‘ArrayBase | None’

• value: Value

Methods¶

consume¶

def consume(self, operation_name: str = 'unknown') -> Self

Mark this handle as consumed and return a fresh handle.

Parameters:

Returns:

typing.Self — A new handle pointing to the same underlying value.

Raises:

• QubitConsumedError — If this handle was already consumed and is a quantum type.

Tuple [source]¶

class Tuple(Handle, Generic[K, V])

Tuple handle for qkernel functions.

Represents a tuple of values, commonly used for multi-index keys like (i, j) in Ising models.

Example:

@qmc.qkernel
def my_kernel(idx: qmc.Tuple[qmc.UInt, qmc.UInt]) -> qmc.UInt:
    i, j = idx
    return i + j

Constructor¶

def __init__(
    self,
    value: TupleValue,
    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,
    _elements: tuple[Handle, ...] = tuple(),
) -> None

Attributes¶

• value: TupleValue

TupleValue [source]¶

class TupleValue(_MetadataValueMixin)

A tuple of IR values for structured data.

Constructor¶

def __init__(
    self,
    name: str,
    elements: tuple[Value, ...] = tuple(),
    metadata: ValueMetadata = ValueMetadata(),
    uuid: str = (lambda: str(uuid.uuid4()))(),
    logical_id: str = (lambda: str(uuid.uuid4()))(),
) -> None

Attributes¶

• elements: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: ‘TupleType’

• uuid: str

Methods¶

is_constant¶

def is_constant(self) -> bool

next_version¶

def next_version(self) -> TupleValue

UInt [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: int = 0,
) -> None

Attributes¶

• init_value: int

UIntType [source]¶

class UIntType(ClassicalTypeMixin, ValueType)

Type representing an unsigned integer.

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.

qamomile.circuit.frontend.handle.hamiltonian¶

Observable handle for Hamiltonian parameters.

This module provides the Observable handle class that represents a reference to a Hamiltonian observable provided via bindings during transpilation. Unlike HamiltonianExpr in previous versions, this is a pure parameter handle with no arithmetic operations.

Overview¶

Classes¶

Handle [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    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¶

• id: str

• indices: tuple[‘UInt’, ...]

• name: str | None

• parent: ‘ArrayBase | None’

• value: Value

Methods¶

consume¶

def consume(self, operation_name: str = 'unknown') -> Self

Mark this handle as consumed and return a fresh handle.

Parameters:

Returns:

typing.Self — A new handle pointing to the same underlying value.

Raises:

• QubitConsumedError — If this handle was already consumed and is a quantum type.

Observable [source]¶

class Observable(Handle)

Handle representing a Hamiltonian observable parameter.

This is a reference type - the actual qamomile.observable.Hamiltonian is provided via bindings during transpilation. It cannot be constructed or manipulated within qkernels.

Example:

import qamomile.circuit as qm
import qamomile.observable as qm_o

# Build Hamiltonian in Python
H = qm_o.Z(0) * qm_o.Z(1) + 0.5 * qm_o.X(0)

@qm.qkernel
def vqe(q: qm.Vector[qm.Qubit], H: qm.Observable) -> qm.Float:
    # Use Hamiltonian from bindings
    return qm.expval(q, H)

# Pass via bindings
executable = transpiler.transpile(vqe, bindings={"H": H})

Constructor¶

def __init__(
    self,
    value: Value,
    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

qamomile.circuit.frontend.handle.handle¶

Overview¶

Functions¶

get_current_tracer [source]¶

def get_current_tracer() -> Tracer

Classes¶

ArithmeticMixin [source]¶

class ArithmeticMixin

Mixin providing arithmetic operations for numeric Handle types.

Requires:

• value: Value attribute

• _make_result(): Method to create result Handle of same type

• _coerce(): Method to convert Python literals to Handle

Attributes¶

• value: Value

ArrayBase [source]¶

class ArrayBase(Handle, Generic[T])

Base class for array types (Vector, Matrix, Tensor).

Provides common functionality for array indexing and element access.

Constructor¶

def __init__(
    self,
    value: ArrayValue,
    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,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

• element_type: Type[T]

• shape: tuple[int | UInt, ...] Return the shape of the array.

• value: ArrayValue

Methods¶

consume¶

def consume(self, operation_name: str = 'unknown') -> Self

Consume the array, enforcing borrow-return contract for quantum arrays.

For quantum arrays, all borrowed elements must be returned before the array can be consumed. This ensures that no unreturned borrows are silently discarded by operations like qkernel calls or controlled gates.

create¶

@classmethod
def create(
    cls,
    shape: tuple[int | UInt, ...],
    name: str,
    el_type: Type[T],
) -> 'ArrayBase[T]'

Create an ArrayValue for the given shape and name.

validate_all_returned¶

def validate_all_returned(self) -> None

Validate all borrowed elements have been returned.

This method is useful for ensuring that all borrowed elements have been properly written back before using the array in operations that require the entire array.

Raises:

• UnreturnedBorrowError — If any elements are still borrowed.

BinOp [source]¶

class BinOp(BinaryOperationBase)

Binary arithmetic operation (ADD, SUB, MUL, DIV, FLOORDIV, POW).

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    kind: BinOpKind | None = None,
) -> None

Attributes¶

• kind: BinOpKind | None

• operation_kind: OperationKind

• signature: Signature

BinOpKind [source]¶

class BinOpKind(enum.Enum)

Attributes¶

• ADD

• DIV

• FLOORDIV

• MUL

• POW

• SUB

CompOp [source]¶

class CompOp(BinaryOperationBase)

Comparison operation (EQ, NEQ, LT, LE, GT, GE).

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    kind: CompOpKind | None = None,
) -> None

Attributes¶

• kind: CompOpKind | None

• operation_kind: OperationKind

• signature: Signature

CompOpKind [source]¶

class CompOpKind(enum.Enum)

Attributes¶

• EQ

• GE

• GT

• LE

• LT

• NEQ

CondOp [source]¶

class CondOp(BinaryOperationBase)

Conditional logical operation (AND, OR).

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    kind: CondOpKind | None = None,
) -> None

Attributes¶

• kind: CondOpKind | None

• operation_kind: OperationKind

• signature: Signature

CondOpKind [source]¶

class CondOpKind(enum.Enum)

Attributes¶

• AND

• OR

Handle [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    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¶

• id: str

• indices: tuple[‘UInt’, ...]

• name: str | None

• parent: ‘ArrayBase | None’

• value: Value

Methods¶

consume¶

def consume(self, operation_name: str = 'unknown') -> Self

Mark this handle as consumed and return a fresh handle.

Parameters:

Returns:

typing.Self — A new handle pointing to the same underlying value.

Raises:

• QubitConsumedError — If this handle was already consumed and is a quantum type.

NotOp [source]¶

class NotOp(Operation)

Constructor¶

def __init__(self, operands: list[Value] = list(), results: list[Value] = list()) -> None

Attributes¶

• input: Value

• operation_kind: OperationKind

• output: Value

• signature: Signature

QubitConsumedError [source]¶

class QubitConsumedError(AffineTypeError)

Qubit handle used after being consumed by a previous operation.

Each qubit handle can only be used once. After a gate operation, you must reassign the result to use the new handle.

Example of incorrect code:

q1 = qm.h(q) q2 = qm.x(q) # ERROR: q was already consumed by h()

Correct code:

q = qm.h(q) # Reassign to capture new handle q = qm.x(q) # Use the reassigned handle

UInt [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: int = 0,
) -> None

Attributes¶

• init_value: int

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.

qamomile.circuit.frontend.handle.primitives¶

Overview¶

Classes¶

ArithmeticMixin [source]¶

class ArithmeticMixin

Mixin providing arithmetic operations for numeric Handle types.

Requires:

• value: Value attribute

• _make_result(): Method to create result Handle of same type

• _coerce(): Method to convert Python literals to Handle

Attributes¶

• value: Value

BinOpKind [source]¶

class BinOpKind(enum.Enum)

Attributes¶

• ADD

• DIV

• FLOORDIV

• MUL

• POW

• SUB

Bit [source]¶

class Bit(Handle)

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: bool = False,
) -> None

Attributes¶

• init_value: bool

BitType [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

CompOpKind [source]¶

class CompOpKind(enum.Enum)

Attributes¶

• EQ

• GE

• GT

• LE

• LT

• NEQ

CondOpKind [source]¶

class CondOpKind(enum.Enum)

Attributes¶

• AND

• OR

Float [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    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,
    init_value: float = 0.0,
) -> None

Attributes¶

• init_value: float

FloatType [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

Handle [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    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¶

• id: str

• indices: tuple[‘UInt’, ...]

• name: str | None

• parent: ‘ArrayBase | None’

• value: Value

Methods¶

consume¶

def consume(self, operation_name: str = 'unknown') -> Self

Mark this handle as consumed and return a fresh handle.