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

should_trace_for_loop [source]¶

def should_trace_for_loop(start: Any, stop: Any, step: Any) -> bool

Decide whether a qmc.range body must be traced.

The frontend executes loop bodies once to capture a ForOperation. When all bounds are concrete and Python’s range would execute zero times, tracing the body would incorrectly leak borrow / destructive-consume state into the enclosing scope. Symbolic or invalid bounds stay conservative and trace the body so the normal compiler validation path reports any errors.

Parameters:

Returns:

bool — False only for statically-known zero-trip loops; True bool — otherwise.

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

• a = qm.qubit("...") silently discarding a

• a = some_opaque_call() where the call has no known quantum source

• a = b = expr chained assignment touching a quantum name

• a: qm.Qubit = ... (annotated form of the above)

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)

• a, b = f(a, b) / a, b = (g(b), h(a)) (1-to-1 quantum permutation)

The analyzer is a single-pass ast.NodeVisitor and does not model Python control flow precisely. To keep compile-time-if dead-branch rebinds — which the IR’s CompileTimeIfLoweringPass will later resolve by selecting one branch and discarding the other — from being rejected at decoration time, visit_If / visit_For / visit_While route every branch through :meth:_visit_branch_scope, which snapshots quantum_vars before and restores it after each body / orelse, AND truncates any violations recorded inside the branch back to the pre-branch length. Top-level (non-branch-internal) rebinds are flagged as usual; branch-internal rebinds are deliberately not reported at decoration time. The companion gap on the IR side (AffineValidationPass does not detect silent-discard patterns) is tracked in LIMITATIONS.md.

Constructor¶

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

Initialize the analyzer with the kernel’s quantum parameter names.

Parameters:

Attributes¶

• quantum_vars: dict[str, str]

• violations: list[RebindViolation]

Methods¶

visit_AnnAssign¶

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

Dispatch q: qm.Qubit = expr through the single-assign path.

Parameters:

visit_Assign¶

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

Dispatch a = expr / a, b = expr / a = b = expr.

Parameters:

visit_Call¶

def visit_Call(self, node: ast.Call) -> None

Apply consume effects when a classical-returning call is seen.

_check_single_assign / _check_tuple_assign already invoke :meth:_consume_quantum_args when a classical-returning call appears on the RHS of an assignment. This visitor handles the cases where the same call appears outside an assignment: as a bare expression statement (qm.measure(q)), inside an if / while condition, inside a for iterable, or nested inside any other expression visited via generic_visit. Without this hook, those forms would leave q in quantum_vars and trip a false-positive FRESH_ALLOCATION violation on a later rebind of q.

Re-visiting from inside a covered assignment path is benign: _consume_quantum_args is idempotent — by the time visit_Call runs as part of generic_visit after the assignment dispatch, the relevant origins are already gone from quantum_vars and the second call is a no-op.

Parameters:

visit_For¶

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

Visit a for loop’s body and else with branch-local scope.

node.iter is walked first (before the branch-scope snapshot) so that any consume effect inside the iterable expression is reflected in the outer analyzer state. The loop target itself is not modeled — Qamomile’s frontend rewrites qmc.range(...) loops via the control-flow transformer, so the iterator variable is a classical index and never quantum.

Parameters:

visit_If¶

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

Visit if/else body with branch-local scope.

node.test is walked first (before the branch-scope snapshot) so that any consume effect inside the condition (e.g. if qm.measure(q):) is reflected in the outer analyzer state, not silently rolled back when the branch scope restores. See :meth:_visit_branch_scope for the snapshot-restore protocol applied to body and orelse.

Parameters:

visit_While¶

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

Visit a while loop’s body and else with branch-local scope.

Same protocol as :meth:visit_If. node.test is walked before the branch-scope snapshot.

Parameters:

RebindSourceKind [source]¶

class RebindSourceKind(enum.StrEnum)

Discriminator for the source of a detected rebind violation.

Each value classifies why the analyzer believes an existing quantum binding is being silently discarded, and lets downstream error-message formatting render a domain-appropriate explanation instead of forcing a generic “different quantum variable” sentence onto, e.g., a fresh allocation.

Members:

DIRECT_ALIAS: q = other_q or q = qs[i]. QUANTUM_ARG: q = f(other_q, ...) where other_q has a different origin than q. FRESH_ALLOCATION: q = qm.qubit(...) / qm.qubit_array(...) — the original quantum state is silently discarded in favor of a freshly allocated one. UNKNOWN_CALL: q = some_func(...) where the call references no known quantum variable and is not a recognized quantum constructor; conservatively treated as a rebind because the original q is not threaded through the RHS. CHAINED_ASSIGNMENT: q1 = q2 = expr where at least one target is an existing quantum variable; chained binding semantics are too ambiguous to verify self-update.

Attributes¶

• CHAINED_ASSIGNMENT

• DIRECT_ALIAS

• FRESH_ALLOCATION

• QUANTUM_ARG

• UNKNOWN_CALL

RebindViolation [source]¶

class RebindViolation

A detected forbidden quantum variable rebinding.

Constructor¶

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

Attributes¶

• func_name: str | None

• lineno: int

• source_expr: str | None

• source_kind: RebindSourceKind

• source_name: str | None

• 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(),
    param_slots: tuple[ParamSlot, ...] = tuple(),
) -> 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]

• param_slots: tuple[ParamSlot, ...]

• 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])

# Slicing returns a VectorView over a subset of the parent vector.
# The view shares borrow tracking with the parent; element access
# on the view transparently indexes the parent.
evens = qubits[0::2]
for i in qmc.range(evens.shape[0]):
    evens[i] = qmc.h(evens[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, ...] | ArrayBase[T]'] = 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 a named parameter.

Parameters:

Returns:

UInt — A constant-valued handle for an int argument, or a named symbolic handle for a str argument.

Raises:

• TypeError — If arg is neither a plain int nor a str (in particular, if it is a bool).

Classes¶

ArrayValue [source]¶

class ArrayValue(Value[T])

An array of typed IR values.

When slice_of is set, this array is a strided view over another array. Element accesses on a sliced ArrayValue resolve to physical slots on the root parent via the affine map parent_index = slice_start + slice_step * view_local_index, applied recursively along slice_of chains. The emit-time resolver walks this chain to produce the final qubit index; passes that substitute or clone values must treat slice_of / slice_start / slice_step as Value references that need to track through the same mapping as parent_array.

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(),
    slice_of: 'ArrayValue | None' = None,
    slice_start: 'Value | None' = None,
    slice_step: 'Value | None' = None,
) -> None

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• shape: tuple[Value, ...]

• slice_of: ‘ArrayValue | None’

• slice_start: ‘Value | None’

• slice_step: ‘Value | None’

• type: T

• uuid: str

Methods¶

is_slice¶

def is_slice(self) -> bool

Return True if this array is a strided view of another array.

Returns:

bool — True iff slice_of is non-None.

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¶

build_param_slots [source]¶

def build_param_slots(
    signature: inspect.Signature,
    input_types: dict[str, Any],
    *,
    parameters: list[str] | None = None,
    kwargs: dict[str, Any] | None = None,
    qubit_sizes: dict[str, int] | None = None,
    bind_defaults: bool,
) -> tuple[ParamSlot, ...]

Build a ParamSlot tuple for the classical arguments of a kernel.

Mirrors the argument-classification logic in QKernel._create_traced_block so the resulting slot list reflects the same decisions that drive symbolic-vs-bound input creation. Only classical (non-quantum, non-Tuple, non-Dict) arguments are included; pure-quantum arguments live in Block.input_values instead.

Parameters:

Returns:

tuple[ParamSlot, ...] — tuple[ParamSlot, ...]: One slot per classical argument, in the order they appear in signature.parameters.

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,
    *,
    shape: tuple[int, ...] | None = None,
) -> Handle

Create a dummy input based on parameter type annotation.

Parameters:

Returns:

Handle — A frontend Handle wrapping a dummy Value or ArrayValue suitable for use as a function-parameter input during tracing.

Raises:

• TypeError — If param_type is not a supported parameter type, or if a Tuple/array annotation is missing its element type(s).

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.

When slice_of is set, this array is a strided view over another array. Element accesses on a sliced ArrayValue resolve to physical slots on the root parent via the affine map parent_index = slice_start + slice_step * view_local_index, applied recursively along slice_of chains. The emit-time resolver walks this chain to produce the final qubit index; passes that substitute or clone values must treat slice_of / slice_start / slice_step as Value references that need to track through the same mapping as parent_array.

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(),
    slice_of: 'ArrayValue | None' = None,
    slice_start: 'Value | None' = None,
    slice_step: 'Value | None' = None,
) -> None

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• shape: tuple[Value, ...]

• slice_of: ‘ArrayValue | None’

• slice_start: ‘Value | None’

• slice_step: ‘Value | None’

• type: T

• uuid: str

Methods¶

is_slice¶

def is_slice(self) -> bool

Return True if this array is a strided view of another array.

Returns:

bool — True iff slice_of is non-None.

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(),
    param_slots: tuple[ParamSlot, ...] = tuple(),
) -> 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]

• param_slots: tuple[ParamSlot, ...]

• 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

ParamKind [source]¶

class ParamKind(enum.Enum)

Lifecycle classification for a classical kernel argument.

Values:

RUNTIME_PARAMETER: The argument is intended to be bound at execution time by the backend (or, more generally, by the outer caller in a hybrid loop). It survives the compilation pipeline as a symbolic parameter. COMPILE_TIME_BOUND: The argument was provided as a binding (or via a Python default) and is folded into the IR by resolve_parameter_shapes / partial_eval. No symbolic counterpart remains in the emitted circuit.

Attributes¶

• COMPILE_TIME_BOUND

• RUNTIME_PARAMETER

ParamSlot [source]¶

class ParamSlot

Metadata for a single classical kernel argument.

A ParamSlot describes one position in the kernel’s classical parameter contract — its declared type, whether it is a runtime parameter or a compile-time-bound value, the Python default (if any), the actually-bound value (when kind is COMPILE_TIME_BOUND), and any outer-DSL hints. Slots are immutable; pipeline passes that need to update a slot must clone via dataclasses.replace.

The slot is identified by name, which matches the kernel’s Python parameter name and the corresponding entry in Block.label_args. A slot’s name MUST never overlap between RUNTIME_PARAMETER and COMPILE_TIME_BOUND instances within one Block (this mirrors the project-level bindings / parameters disjointness rule).

Constructor¶

def __init__(
    self,
    name: str,
    type: 'ValueType',
    kind: ParamKind,
    ndim: int = 0,
    default: Any = None,
    bound_value: Any = None,
    differentiable: bool = False,
) -> None

Attributes¶

• bound_value: Any

• default: Any

• differentiable: bool

• kind: ParamKind

• name: str

• ndim: int

• type: ‘ValueType’

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:

• TypeError — If arr is not a 1-D Vector handle (Vector or its VectorView subclass) — e.g., a scalar Qubit was passed where a Vector is required, a higher-rank Matrix / Tensor was passed (this helper only resolves a 1-D first-axis size), or an unrelated shape-bearing object such as a numpy array. This is a clearer signal than the bare AttributeError that arr.shape would otherwise raise, and it guards the stdlib / composite callers that resolve a register size through this helper.

• 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, ...] | ArrayBase[T]'] = 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, ...] | ArrayBase[T]'] = 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])

# Slicing returns a VectorView over a subset of the parent vector.
# The view shares borrow tracking with the parent; element access
# on the view transparently indexes the parent.
evens = qubits[0::2]
for i in qmc.range(evens.shape[0]):
    evens[i] = qmc.h(evens[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, ...] | ArrayBase[T]'] = dict(),
) -> None

Attributes¶

• value: ArrayValue

VectorView [source]¶

class VectorView(Vector[T])

Strided view over a parent Vector, backed by a sliced ArrayValue.

A VectorView is produced by slicing a Vector (q[1::2], q[a:b], etc.). It is a thin Vector subclass whose value is a fresh ArrayValue with slice_of / slice_start / slice_step metadata pointing back to the parent’s ArrayValue. Element accesses go through Vector._get_element unchanged — the IR element carries parent_array = sliced_av, and the emit-time resolver walks the slice_of chain to produce the physical qubit index. No affine translation happens in the view itself.

Because the sliced ArrayValue is a first-class IR Value, the view can be passed as an operand of CallBlockOperation to another @qkernel without the inline-trace special-case path that earlier iterations required. Passing views through expval / measure likewise operates on the sliced qubit subset, not the root parent as a whole.

Linearity:

Slicing bulk-borrows the covered parent slots whenever start, step and length are compile-time int constants. While the view is live, accessing the corresponding parent slot directly (q[0] after evens = q[0::2]) raises QubitConsumedError. Under the strict-return policy the view’s ownership is cleared only by two operations:

• slice-assigning it back into the parent (parent[a:b:c] = view) — this is the only path that fully releases the borrow without destroying the qubits;

• destructively consuming it (measure(view) / cast(view, ...) / expval(view, H)) — the physical slots become consumed markers, no return needed.

Every other consume (broadcast gates h(view), pauli_evolve(view, H, gamma), sub-kernel calls f(view), controlled-U index_spec) only transfers ownership to a freshly-wrapped VectorView and that new view still must be returned via slice assignment. A view left bulk-borrowing at the parent’s consume point raises UnreturnedBorrowError.

Symbolic slices (q[lo:hi] with lo/hi UInt) cannot enumerate their covered slots at trace time and therefore skip the bulk-borrow here; SliceBorrowCheckPass picks them up post-fold after bindings resolve the bounds to concrete values.

Example:

@qmc.qkernel
def alternating_h(q: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]:
    evens = q[0::2]
    for i in qmc.range(evens.shape[0]):
        evens[i] = qmc.h(evens[i])
    q[0::2] = evens  # explicit return before the parent is used
    return q

Methods¶

consume¶

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

Consume the view and release its parent slice-borrows.

Validates that every view-local borrow has been returned, then dispatches on operation_name to keep the parent’s slice-borrow record consistent with the new strict-return semantics:

• Destructive (measure / cast): leave self parked in the parent’s borrow table as a destroyed-slot breadcrumb. super().consume() flips self._consumed = True and self._consumed_by = operation_name, which is what :func:_is_destroyed_slot_owner reads to reject subsequent access at the same slot.

• Releasing (slice assignment): drop every parent entry that self currently owns. The caller (the slice- assignment frontend path) also emits a ReleaseSliceViewOperation so the IR-level checker sees the release. This branch is reserved for explicit borrow- return paths.

• Transfer (every other op — broadcast gates, rotation, phase, ControlledU, sub-kernel call argument consumption, etc.): rebind the parent’s borrow entry from self to the new view handle returned here. The new view inherits self._slice_covered_indices so it can be slice-assigned back to the parent later — strict-return requires that eventual parent[a:b:c] = new_view.

Operations that produce a fresh sliced ArrayValue (e.g. :func:qamomile.circuit.frontend.operation.pauli_evolve.pauli_evolve, :class:QKernel.__call__ for callees that return a sliced array) cannot simply use the auto-returned new_view because the new view they build wraps a different Value than this consume’s return. Those op implementations call :meth:_transfer_borrow_to after building their result so the parent’s borrow table tracks the right handle.

Parameters:

Returns:

typing.Self — A fresh view handle with the same backing state; under typing.Self — transfer the parent’s borrow table now points at this typing.Self — handle, under release / destruction the parent’s record typing.Self — for the covered slots is finalised.

Raises:

• QubitConsumedError — If any covered slot was already destroyed by a prior destructive view consume on an overlapping view that has since gone out of scope.

qamomile.circuit.frontend.handle.array¶

Overview¶

Functions¶

get_current_tracer [source]¶

def get_current_tracer() -> Tracer

is_plain_int [source]¶

def is_plain_int(value: object) -> bool

Return True if value is a Python int but not a bool.

bool is a subclass of int in Python, so isinstance(True, int) is True. This helper distinguishes a genuine integer from a boolean, which matters wherever a boolean must be rejected in an integer slot — for example, validating decoded wire data or a register width.

Parameters:

Returns:

bool — True when value is an int and not a bool.

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, ...] | ArrayBase[T]'] = 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.

When any slot of the array has already been physically consumed by an earlier destructive view operation (measure(q[1::2]) then measure(q)), this raises QubitConsumedError rather than silently re-consuming those slots.

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.

Strict-return policy: an active slice view that is still registered as the owner of any parent slot is treated as an unreturned borrow even if the view itself has no outstanding element borrows. The caller must perform an explicit slice assignment (parent[a:b:c] = view) to release the view’s bulk-borrow before consuming the parent. Destructively consumed views (parked in the dict with view._consumed set and view._consumed_by classified as :attr:ConsumeMode.DESTRUCTIVE) record physically-destroyed slots and are not outstanding borrows; they survive end-of-block so a later whole-array consume can detect and reject the destroyed slots.

Raises:

• UnreturnedBorrowError — If any elements are still borrowed, either directly or by a slice view that has not been explicitly returned via slice assignment.

ArrayValue [source]¶

class ArrayValue(Value[T])

An array of typed IR values.

When slice_of is set, this array is a strided view over another array. Element accesses on a sliced ArrayValue resolve to physical slots on the root parent via the affine map parent_index = slice_start + slice_step * view_local_index, applied recursively along slice_of chains. The emit-time resolver walks this chain to produce the final qubit index; passes that substitute or clone values must treat slice_of / slice_start / slice_step as Value references that need to track through the same mapping as parent_array.

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(),
    slice_of: 'ArrayValue | None' = None,
    slice_start: 'Value | None' = None,
    slice_step: 'Value | None' = None,
) -> None

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• shape: tuple[Value, ...]

• slice_of: ‘ArrayValue | None’

• slice_start: ‘Value | None’

• slice_step: ‘Value | None’

• type: T

• uuid: str

Methods¶

is_slice¶

def is_slice(self) -> bool

Return True if this array is a strided view of another array.

Returns:

bool — True iff slice_of is non-None.

next_version¶

def next_version(self) -> ArrayValue[T]

BinOpKind [source]¶

class BinOpKind(enum.Enum)

Attributes¶

• ADD

• DIV

• FLOORDIV

• MIN

• MOD

• 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.

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

ConsumeMode [source]¶

class ConsumeMode(enum.Enum)

Classify how a VectorView.consume call resolves slice borrows.

ArrayBase.consume and VectorView.consume accept a free-form operation_name string used both for error messages and for dispatching how the parent’s bulk-borrow table is updated. The string itself is purely cosmetic; the dispatch logic only cares about which of three resolution modes applies, captured by this enum:

• DESTRUCTIVE: the consume physically destroys the qubits (measure / cast). The consumed view stays parked in the parent’s borrow table so any later access to the same slot is surfaced as a use-after-destroy.

• RELEASING: the consume returns the borrow to the parent cleanly (slice assignment) — the entries are dropped and the parent regains free access to the covered slots.

• TRANSFER: the consume hands ownership forward to a freshly built VectorView (broadcast gates, pauli_evolve, QKernel.__call__, controlled-U index_spec). The covered slots stay borrowed under the new handle.

Attributes¶

• DESTRUCTIVE

• RELEASING

• TRANSFER

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, ...] | ArrayBase[T]'] = 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]

QubitBorrowConflictError [source]¶

class QubitBorrowConflictError(AffineTypeError)

Qubit slot inaccessible because another live handle borrows it.

Raised when a qubit slot cannot be accessed because another live handle currently borrows it — a slice view that has not been returned, an outstanding element borrow, or any future borrow form Qamomile may add. Unlike :class:QubitConsumedError, the slot is not destroyed: releasing the borrowing handle (slice assignment, element write-back, etc.) restores access.

Example of incorrect code (overlapping slice views)::

a = q[0:3]      # q[0..2] now borrowed by ``a``
b = q[2:5]      # ERROR: q[2] is still borrowed by ``a``

Correct code::

a = q[0:3]
q[0:3] = a      # return ``a`` first
b = q[2:5]      # now safe

Example of incorrect code (element borrow not returned before borrowing a neighbour)::

q0 = qubits[0]
q0 = qmc.h(q0)
q1 = qubits[1]  # ERROR: q0 is still borrowed

Correct code::

q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0  # return the element first
q1 = qubits[1]  # now safe

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).

ReleaseSliceViewOperation [source]¶

class ReleaseSliceViewOperation(Operation)

Mark a slice view’s borrow as explicitly returned to its parent.

Emitted by :meth:Vector.__setitem__ when used with a slice index (qs[a:b] = qmc.h(qs[a:b])). This op tells the post-fold linearity checker (:class:~qamomile.circuit.transpiler.passes.slice_borrow_check.SliceBorrowCheckPass) that the view referenced in operands[0] no longer owns its covered parent slots, mirroring the frontend’s VectorView.consume(operation_name="slice assignment") borrow release.

Like :class:SliceArrayOperation, this op is a declarative classical-side marker that does not survive into the emit stream: :class:~qamomile.circuit.transpiler.passes.strip_slice_ops.StripSliceArrayOpsPass removes both :class:SliceArrayOperation and :class:ReleaseSliceViewOperation after :class:SliceBorrowCheckPass has observed them. Reaching emit is a compiler-internal invariant violation and is rejected with a RuntimeError from :mod:standard_emit.

Within a control-flow body (ForOperation / WhileOperation / IfOperation), this op only releases view borrows that were created within the same body. Releasing a borrow that the enclosing block has registered (an “outer-snapshot” borrow) is rejected by SliceBorrowCheckPass with SliceBorrowViolationError — the loop-merge semantics of the pass cannot propagate entry deletions out of the body, so the only way to keep the static check consistent is to forbid that pattern.

Example:

``qs[1:3] = qmc.h(qs[1:3])`` emits, after the broadcast loop::

    ReleaseSliceViewOperation(
        operands=[qmc_h_result_view],  # slice_of=qs_value
        results=[],
    )

Constructor¶

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

Attributes¶

• operation_kind: OperationKind Release is classical — it updates borrow tracking metadata only.

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

SliceArrayOperation [source]¶

class SliceArrayOperation(Operation)

Construct a strided view of an ArrayValue.

The op itself performs no quantum action — it records that the result ArrayValue is a strided view of the operand parent with the given start / step. The result’s slice_of / slice_start / slice_step fields carry the affine map used by the emit-time resolver.

SliceArrayOperation is classified as :attr:OperationKind.CLASSICAL because slicing is pure index selection — no new quantum operation is introduced. The pipeline keeps this op through PartialEvaluationPass (which invokes ConstantFoldingPass(..., strip_slice_ops=False)) so the post-fold :class:~qamomile.circuit.transpiler.passes.slice_borrow_check.SliceBorrowCheckPass can use it as a view-declaration marker; once that check has run, StripSliceArrayOpsPass removes every SliceArrayOperation / ReleaseSliceViewOperation so segmentation (:mod:~qamomile.circuit.transpiler.passes.separate) and the downstream emit stage only see a pure quantum-op stream. By the time :mod:~qamomile.circuit.transpiler.passes.separate runs the op has therefore been stripped — reaching emit is a compiler- internal invariant violation.

Example:

``q[1::2]`` on a ``Vector[Qubit]`` emits::

    SliceArrayOperation(
        operands=[q_value, uint_1, uint_2],
        results=[sliced_value],  # slice_of=q_value, slice_start=uint_1, slice_step=uint_2
    )

Constructor¶

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

Attributes¶

• operation_kind: OperationKind Slice is classical — it selects indices without quantum action.

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

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, ...] | ArrayBase[T]'] = 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 = qmc.h(q0) q1 = qubits[1] # ERROR: q0 not returned yet

Correct code:

q0 = qubits[0] q0 = qmc.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])

# Slicing returns a VectorView over a subset of the parent vector.
# The view shares borrow tracking with the parent; element access
# on the view transparently indexes the parent.
evens = qubits[0::2]
for i in qmc.range(evens.shape[0]):
    evens[i] = qmc.h(evens[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, ...] | ArrayBase[T]'] = dict(),
) -> None

Attributes¶

• value: ArrayValue

VectorView [source]¶

class VectorView(Vector[T])

Strided view over a parent Vector, backed by a sliced ArrayValue.

A VectorView is produced by slicing a Vector (q[1::2], q[a:b], etc.). It is a thin Vector subclass whose value is a fresh ArrayValue with slice_of / slice_start / slice_step metadata pointing back to the parent’s ArrayValue. Element accesses go through Vector._get_element unchanged — the IR element carries parent_array = sliced_av, and the emit-time resolver walks the slice_of chain to produce the physical qubit index. No affine translation happens in the view itself.

Because the sliced ArrayValue is a first-class IR Value, the view can be passed as an operand of CallBlockOperation to another @qkernel without the inline-trace special-case path that earlier iterations required. Passing views through expval / measure likewise operates on the sliced qubit subset, not the root parent as a whole.

Linearity:

Slicing bulk-borrows the covered parent slots whenever start, step and length are compile-time int constants. While the view is live, accessing the corresponding parent slot directly (q[0] after evens = q[0::2]) raises QubitConsumedError. Under the strict-return policy the view’s ownership is cleared only by two operations:

• slice-assigning it back into the parent (parent[a:b:c] = view) — this is the only path that fully releases the borrow without destroying the qubits;

• destructively consuming it (measure(view) / cast(view, ...) / expval(view, H)) — the physical slots become consumed markers, no return needed.

Every other consume (broadcast gates h(view), pauli_evolve(view, H, gamma), sub-kernel calls f(view), controlled-U index_spec) only transfers ownership to a freshly-wrapped VectorView and that new view still must be returned via slice assignment. A view left bulk-borrowing at the parent’s consume point raises UnreturnedBorrowError.

Symbolic slices (q[lo:hi] with lo/hi UInt) cannot enumerate their covered slots at trace time and therefore skip the bulk-borrow here; SliceBorrowCheckPass picks them up post-fold after bindings resolve the bounds to concrete values.

Example:

@qmc.qkernel
def alternating_h(q: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]:
    evens = q[0::2]
    for i in qmc.range(evens.shape[0]):
        evens[i] = qmc.h(evens[i])
    q[0::2] = evens  # explicit return before the parent is used
    return q

Methods¶

consume¶

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

Consume the view and release its parent slice-borrows.

Validates that every view-local borrow has been returned, then dispatches on operation_name to keep the parent’s slice-borrow record consistent with the new strict-return semantics:

• Destructive (measure / cast): leave self parked in the parent’s borrow table as a destroyed-slot breadcrumb. super().consume() flips self._consumed = True and self._consumed_by = operation_name, which is what :func:_is_destroyed_slot_owner reads to reject subsequent access at the same slot.

• Releasing (slice assignment): drop every parent entry that self currently owns. The caller (the slice- assignment frontend path) also emits a ReleaseSliceViewOperation so the IR-level checker sees the release. This branch is reserved for explicit borrow- return paths.

• Transfer (every other op — broadcast gates, rotation, phase, ControlledU, sub-kernel call argument consumption, etc.): rebind the parent’s borrow entry from self to the new view handle returned here. The new view inherits self._slice_covered_indices so it can be slice-assigned back to the parent later — strict-return requires that eventual parent[a:b:c] = new_view.

Operations that produce a fresh sliced ArrayValue (e.g. :func:qamomile.circuit.frontend.operation.pauli_evolve.pauli_evolve, :class:QKernel.__call__ for callees that return a sliced array) cannot simply use the auto-returned new_view because the new view they build wraps a different Value than this consume’s return. Those op implementations call :meth:_transfer_borrow_to after building their result so the parent’s borrow table tracks the right handle.

Parameters:

Returns:

typing.Self — A fresh view handle with the same backing state; under typing.Self — transfer the parent’s borrow table now points at this typing.Self — handle, under release / destruction the parent’s record typing.Self — for the covered slots is finalised.

Raises:

• QubitConsumedError — If any covered slot was already destroyed by a prior destructive view consume on an overlapping view that has since gone out of scope.

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