qamomile.circuit.frontend

Frontend: Python-embedded tracing that turns qkernel functions into IR Blocks.

The qkernel decorator (qkernel.py) first rewrites the user’s function with an AST transform (ast_transform.py) that replaces native if / while / for statements with tracer-visible builder calls, then executes the transformed function under a Tracer (tracer.py) with handle arguments. Every handle method and operation builder appends abstract IR Operations to the active tracer, and func_to_block.py packages the trace into a HIERARCHICAL Block (including the ParamSlot manifest for classical arguments).

Design constraints:

• Handles (handle/) are linear-typed wrappers over IR Values: gates consume their quantum arguments and return fresh handles that must be re-bound (SSA-like versioning). Reuse of a consumed handle raises QubitConsumedError at trace time, before the transpiler’s affine_validate re-checks the same invariant on the IR.

• The frontend owns tracing, the handle type system, and Python-syntax lowering (control-flow rewriting, loop region args). It emits abstract IR only; whole-block validation, IR rewriting, segmentation, and backend concretization belong to qamomile.circuit.transpiler.

• Calls to nested qkernels stay as InvokeOperation boxes carrying a CallPolicy; the frontend never inlines — inline is a transpiler pass.

qamomile.circuit.frontend.ast_transform¶

Overview¶

Functions¶

analyze_region_signatures [source]¶

def analyze_region_signatures(
    definition: ast.FunctionDef | ast.AsyncFunctionDef,
) -> dict[RegionLocation, RegionSignature]

Analyze structured interfaces in one parsed function definition.

Parameters:

Returns:

dict[RegionLocation, RegionSignature] — dict[RegionLocation, RegionSignature]: Source region signatures.

branch_rebind_pre_bindings [source]¶

def branch_rebind_pre_bindings(frame_locals: dict[str, Any], names: tuple) -> dict[str, Any]

Capture pre-branch bindings for if-rebind records.

Called from AST-injected code at the emit_if call site with the caller’s locals(). A name missing from the call site’s locals is resolved through the enclosing emit_if calls’ captured pre-bindings (innermost first): a dead-after variable never enters the generated branch-body scopes, so for a nested if only the enclosing capture still knows its pre-branch handle. The transformer’s candidate analysis is lexical, so a name may genuinely be unbound everywhere (a preceding pure-store if can be dead-store-eliminated from its outputs); such names are silently skipped instead of raising UnboundLocalError at the call site.

Parameters:

Returns:

dict[str, typing.Any] — dict[str, typing.Any]: The resolvable candidate names mapped to their pre-branch handles.

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.

dead_rebind_binding [source]¶

def dead_rebind_binding(frame_locals: dict[str, Any], name: str) -> Any

Probe a branch body’s post-branch binding of a dead-after variable.

Called from AST-injected code as an extra element of a branch body’s return tuple. A variable reassigned in a branch but never read after the if is dead-store-eliminated from the branch outputs, so its post-branch binding is not otherwise observable by emit_if; this probe reads it from the body’s locals(). In the branch that does not store the variable the name is unbound in the body scope, so the probe returns a sentinel instead of raising NameError.

Parameters:

Returns:

typing.Any — typing.Any: The post-branch handle, or the unbound sentinel when the body never bound the name.

emit_if [source]¶

def emit_if(
    cond_func: Callable,
    true_func: Callable,
    false_func: Callable,
    variables: list,
    output_names: tuple = (),
    rebind_pre_bindings: dict | None = None,
    dead_names: tuple = (),
    capture_indices: tuple[int, ...] = (),
) -> Any

Trace an if/else conditional and merge its branch results.

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 — typing.Any: The sole merged value, a tuple of merged values, or None when the branches return no values.

Raises:

• TypeError — If corresponding branch values have incompatible types or divergent values with no Qamomile IR representation.

• ValueError — If branch result lengths or probe-tail lengths disagree.

Example:

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

explicit_loop_bindings [source]¶

def explicit_loop_bindings(bindings: tuple[tuple[str, Callable[[], Any]], ...]) -> dict[str, Any]

Resolve generated lexical loop bindings without frame inspection.

Generated control-flow code passes one lazy zero-argument resolver for each statically analyzed interface name. A name that is not bound on the traced path may still be available from the enclosing branch’s explicit pre-binding stack; genuinely absent names are omitted, matching the old tolerant snapshot behavior.

Parameters:

Returns:

dict[str, typing.Any] — dict[str, typing.Any]: Resolved bindings keyed by source name.

for_items [source]¶

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

Create a traced for-items loop in the 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[typing.Any, typing.Any]: Key handle(s) and the typed scalar value handle used while tracing the loop body.

Raises:

• TypeError — If d is a runtime-parameter Dict (declared via parameters=[...] without bound data), or its key annotation cannot be represented by the loop target. A runtime Dict’s key structure is unknown at compile time, so an items() loop cannot be unrolled; only constant-key subscript lookups (d[key]) are supported for runtime-parameter dicts.

• NotImplementedError — If the Dict value annotation is a container or another type without a scalar frontend handle.

• ValueError — If the constructed loop has inconsistent region-result metadata.

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',
    *,
    captures: tuple[tuple[str, Any], ...] = (),
) -> Generator[UInt, None, None]

Create a traced for loop in the Qamomile frontend.

Parameters:

Yields:

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

Raises:

• TypeError — If a bound cannot be represented as a scalar IR value.

• ValueError — If the constructed loop has inconsistent region-result metadata.

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

Classical scalar updates (total = total + i) become explicit RegionArg records on the ForOperation: the loop enters with the initializer, each iteration reads the previous iteration’s value, and post-loop code reads the loop result.

loop_rebind_snapshot [source]¶

def loop_rebind_snapshot(frame_locals: dict[str, Any], names: tuple[str, ...]) -> dict[str, Any]

Snapshot pre-loop variable handles for rebind detection.

Called from AST-injected probe code as the first statement of a traced loop body. The snapshot records which handle each candidate variable name pointed at before the body ran, so record_loop_rebinds can detect rebinds by comparing IR value identity afterwards.

Candidates are resolved through :func:branch_rebind_pre_bindings: the caller’s frame locals first, then the enclosing if-branch pre-binding stack. The fallback matters inside an if branch — a variable the branch only stores (via the loop) is not a branch input parameter, so it is unbound in the branch’s frame at loop entry, yet its pre-branch handle is exactly the state a loop-body rebind would discard. Names bound nowhere are silently omitted.

Parameters:

Returns:

dict[str, typing.Any] — dict[str, typing.Any]: The resolvable candidate names mapped to their pre-loop-body handles (or plain Python values).

loop_region_enter [source]¶

def loop_region_enter(snapshot: dict[str, Any], name: str, allow_array: bool = False) -> Any

Bind loop-carried classical state to a fresh region argument.

Called from AST-injected code at the top of a structured loop body (immediately after loop_rebind_snapshot) for each read-before-write classical candidate: total = loop_region_enter(_qm_rebind_snap_N, "total"). When the pre-loop binding is a classical UInt / Float scalar (or a plain Python int / float), the body is given a fresh region-argument handle so its reads become explicit loop-carried reads instead of stale pre-loop reads — the MLIR iter_args model. The loop builder later converts the pending entry into a RegionArg on the loop operation.

Classical arrays are also promoted so persistent element stores thread the current array version through the loop. Quantum values, dicts, Qubit, Bit, opaque Python objects, and bool are returned unchanged; quantum rebinds keep feeding the discard check and measurement-backed Bit carries keep their targeted rejection.

Parameters:

Returns:

typing.Any — typing.Any: A fresh region-argument handle for supported scalar or array bindings, or the original binding unchanged.

Raises:

• NameError — If name resolves nowhere — mirroring the NameError the body’s first read would have raised.

loop_region_result [source]¶

def loop_region_result(name: str, current: Any) -> Any

Rebind a loop-carried variable to its post-loop result handle.

Called from AST-injected code immediately after a structured loop’s with block: total = loop_region_result("total", total). Consumes the result handle the loop builder published for name (if any) so post-loop reads reference the loop operation’s result value instead of the body’s final yielded value.

Parameters:

Returns:

typing.Any — typing.Any: The published result handle, or current.

record_loop_rebinds [source]¶

def record_loop_rebinds(
    snapshot: dict[str, Any],
    frame_locals: dict[str, Any],
    names: tuple[str, ...],
    classical_names: tuple[str, ...],
) -> None

Record classical and quantum rebinds on the current loop-body tracer.

Called from AST-injected probe code as the last statement of a traced loop body. Two families of rebinds are recorded as :class:LoopCarriedRebind entries on the active body tracer (the loop builders copy them onto the loop operation, where the transpiler’s rejection passes read them):

• Quantum (any candidate name): the variable’s pre-body value is quantum and its post-body value denotes a different resource — a fresh allocation or another register rather than a gate self-update or exact full reslice. These feed the transpiler’s loop-body quantum discard check.

• Classical values (only names in classical_names): supported same-type UInt / Float values that were region-bound at body entry complete their pending RegionArg instead of producing a record. Every other representable rebind produces a residual record, including measurement-backed Bit values and containers. The transpiler rejects shapes that need unsupported routing; a store-only scalar Bit is accepted only for a statically non-empty unrolled loop, where reusing the measurement-result UUID correctly selects the last iteration and no zero-trip initializer must be routed. classical_names includes both read-before-write carries and store-only values that are live after the loop.

No IR operations are emitted; this only annotates the tracer.

Parameters:

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.

should_trace_items_loop [source]¶

def should_trace_items_loop(mapping: Any) -> bool

Decide whether a qmc.items body must be traced.

The frontend executes loop bodies once to capture a ForItemsOperation. When the mapping is a Dict handle whose bound contents are compile-time-known and EMPTY, Python’s iteration would execute zero times, so tracing the body would incorrectly leak bindings (and rebind records) into the enclosing scope — the qmc.range zero-trip guard’s exact analogue (:func:should_trace_for_loop). Symbolic or unbound mappings stay conservative and trace the body so the normal compiler validation path reports any errors.

Parameters:

Returns:

bool — False only for a mapping with present-and-empty bound bool — dict contents; True otherwise.

transform_control_flow [source]¶

def transform_control_flow(
    func: Callable[..., Any],
    *,
    region_signatures: dict[RegionLocation, RegionSignature] | None = None,
) -> Callable[..., Any]

Rewrite Python control flow into tracer-visible region builders.

Parameters:

Returns:

Callable[..., Any] — Callable[..., Any]: Transformed function executed by the tracer.

Raises:

• SyntaxError — If source retrieval or parsing fails.

• NotImplementedError — If a referenced closure value is unavailable.

while_loop [source]¶

def while_loop(
    cond: Callable,
    *,
    captures: tuple[tuple[str, Any], ...] = (),
) -> 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.

Raises:

• TypeError — If either condition evaluation cannot be represented as a scalar IR value.

• ValueError — If the constructed loop has inconsistent region-result metadata.

Example::

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

The body register is a body-local name (q2), not a rebind of the pre-loop q: rebinding a pre-existing quantum variable to a register allocated in the body is rejected by the transpiler’s control-flow discard check, because the runtime loop re-executes its body on one persistent register without reset and cannot realize “fresh per iteration” semantics for the rebound name.

Classical scalar updates (count = count + 1) are represented as explicit region arguments and yields. Target validation may still reject a carry when the selected backend cannot thread that classical type through a runtime measurement-controlled loop.

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,
    region_signatures: dict[RegionLocation, RegionSignature] | None = None,
) -> None

Initialize source tracking and explicit region interfaces.

Parameters:

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

Transform a supported qkernel for loop and attach rebind probes.

Parameters:

Returns:

Any — Guarded AST statement implementing the range or items loop.

Raises:

• SyntaxError — If the loop form, target, shadowing, or escaping bindings violate qkernel loop rules.

• AssertionError — If validated dispatch reaches an unknown loop kind.

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

Transform a qkernel while loop into a traced context-manager body.

Parameters:

Returns:

Any — Replacement ast.With node invoking while_loop.

Raises:

• SyntaxError — If the loop has an else clause, its condition performs a quantum operation, or a body-local value escapes.

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. Runtime-branch and loop-body discards are instead rejected at the IR layer by reject_control_flow_quantum_discard (in qamomile.circuit.transpiler.passes.analyze), which can tell compile-time branches from runtime ones.

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

RegionLocation [source]¶

class RegionLocation

Identify one source-level structured control-flow region.

Parameters:

Constructor¶

def __init__(self, kind: str, lineno: int, col_offset: int) -> None

Attributes¶

• col_offset: int

• kind: str

• lineno: int

RegionSignature [source]¶

class RegionSignature

Describe values crossing one structured region boundary.

Parameters:

Constructor¶

def __init__(
    self,
    inputs: tuple[str, ...],
    carried: tuple[str, ...],
    captures: tuple[str, ...],
    results: tuple[str, ...],
) -> None

Attributes¶

• captures: tuple[str, ...]

• carried: tuple[str, ...]

• inputs: tuple[str, ...]

• results: tuple[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)

Initialize an empty variable/dataflow collector.

Parameters:

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_order: tuple[str, ...] Return assigned variable names in first-source-store order.

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

• vars

Methods¶

visit_AnnAssign¶

def visit_AnnAssign(self, node: ast.AnnAssign)

Visit the RHS first, like visit_Assign.

total: qmc.UInt = total + i reads the RHS before storing, so the generic (target-first) traversal would misclassify the first context as “Store” and drop the read-before-write evidence the loop-carry candidate analysis needs. The annotation itself is type syntax, not dataflow, and is skipped.

Parameters:

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

Parameters:

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 a non-excluded variable name and its access context.

Parameters:

visit_NamedExpr¶

def visit_NamedExpr(self, node: ast.NamedExpr)

Visit a named expression in Python evaluation order.

A walrus assignment such as total := total + i evaluates the value before storing the target. Preserving that order keeps the read-before-write evidence used to identify loop-carry candidates.

Parameters:

qamomile.circuit.frontend.callable_signature¶

Frontend signature helpers for callable-style operations.

Overview¶

Functions¶

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.

Classes¶

CallableSignature [source]¶

class CallableSignature

Describe frontend input and output handle types for an opaque callable.

This class is intentionally a small frontend helper. It lets users write signature-shaped APIs such as opaque(name, signature=...) without exposing the compiler-facing CallableDef model.

Parameters:

Constructor¶

def __init__(self, inputs: list[Any], outputs: list[Any]) -> None

Attributes¶

• inputs: list[Any]

• outputs: list[Any]

Methods¶

accepts_single_qubit_vector¶

def accepts_single_qubit_vector(self) -> bool

Return whether this signature is a one-vector quantum callable.

Returns:

bool — True when both input and output are exactly one bool — Vector[Qubit]-style annotation.

scalar_qubit_input_count¶

def scalar_qubit_input_count(self) -> int | None

Return scalar-qubit arity when the signature is scalar-only.

Returns:

int | None — int | None: Number of scalar Qubit inputs, or None when int | None — the signature contains a vector register.

to_ir_signature¶

def to_ir_signature(self) -> Signature

Convert the frontend signature into an IR operation signature.

Returns:

Signature — Best-effort IR signature using operation parameter Signature — hints.

Raises:

• TypeError — If a frontend type cannot map to an IR value type.

ParamHint [source]¶

class ParamHint

Constructor¶

def __init__(self, name: str, type: ValueType) -> None

Attributes¶

• name: str

• type: ValueType

Signature [source]¶

class Signature

Constructor¶

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

Attributes¶

• operands: list[ParamHint | None]

• results: list[ParamHint]

qamomile.circuit.frontend.composite_gate¶

Define named composite qkernels without a parallel frontend hierarchy.

Overview¶

Functions¶

composite_gate [source]¶

def composite_gate(
    func: Callable[..., Any] | None = None,
    *,
    name: str = '',
    implementations: Sequence[CallableImplementation] | None = None,
) -> QKernel[..., Any] | Callable[[Callable[..., Any]], QKernel[..., Any]]

Define a named composite using the normal qkernel programming model.

The decorated object is a QKernel. Calls keep their named box in the IR, while build(), draw(), estimate_resources(), control(), and inverse() use the same interface as every other qkernel.

Parameters:

Returns:

QKernel[..., Any] | Callable[[Callable[..., Any]], QKernel[..., Any]] — QKernel[..., Any] | Callable[[Callable[..., Any]], QKernel[..., Any]]: Configured qkernel or decorator.

Raises:

• TypeError — If the decorator target is not callable.

Example:

>>> import qamomile.circuit as qmc
>>> @qmc.composite_gate(name="bell_pair")
... def bell_pair(
...     a: qmc.Qubit, b: qmc.Qubit
... ) -> tuple[qmc.Qubit, qmc.Qubit]:
...     a = qmc.h(a)
...     return qmc.cx(a, b)

configure_composite [source]¶

def configure_composite(
    kernel: QKernel[..., Any],
    *,
    name: str | None = None,
    namespace: str | None = None,
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
    policy: CallPolicy = CallPolicy.PRESERVE_BOX,
    implementations: Sequence[CallableImplementation] | None = None,
    semantic_arguments: Mapping[str, Any] | None = None,
) -> QKernel[..., Any]

Configure a QKernel to remain visible as a named composite call.

This mutates and returns the same QKernel object. No wrapper class or alternate call protocol is introduced.

Parameters:

Returns:

QKernel[..., Any] — QKernel[..., Any]: The same configured kernel instance.

qkernel [source]¶

def qkernel(func: Callable[P, R]) -> QKernel[P, R]

Decorator to define a Qamomile quantum kernel.

Parameters:

Returns:

QKernel[P, R] — QKernel[P, R]: QKernel wrapping the function.

Classes¶

CallPolicy [source]¶

class CallPolicy(enum.Enum)

Describe the default lowering policy for a callable call.

Attributes¶

• INLINE

• NATIVE_FIRST

• PRESERVE_BOX

CallableImplementation [source]¶

class CallableImplementation

Describe one implementation candidate for a callable.

Parameters:

Constructor¶

def __init__(
    self,
    transform: CallTransform = CallTransform.DIRECT,
    backend: str | None = None,
    strategy: str | None = None,
    body: Block | None = None,
    body_ref: CallableBodyRef | None = None,
    emitter: Any = None,
    attrs: dict[str, Any] = dict(),
) -> None

Attributes¶

• attrs: dict[str, Any]

• backend: str | None

• body: Block | None

• body_ref: CallableBodyRef | None

• emitter: Any

• strategy: str | None

• transform: CallTransform

CompositeGateType [source]¶

class CompositeGateType(enum.Enum)

Classify standard boxed quantum callables.

Attributes¶

• CUSTOM

• IQFT

• QFT

• QPE

QKernel [source]¶

class QKernel(QKernelBuildMixin, QKernelVisualizationMixin, Generic[P, R])

Decorator class for Qamomile quantum kernels.

Constructor¶

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

Attributes¶

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

• effects: KernelEffect Return cached semantic effects of this qkernel.

• func

• input_types: dict[str, Any] Return resolved and frozen frontend input annotations.

• name

• output_types: list[Any] Return the resolved frontend annotation for every output slot.

• raw_func

• return_type: Any Return the resolved and frozen complete return annotation.

• signature

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.

bit_array [source]¶

def bit_array(shape: UInt | int | tuple[UInt | int, ...], name: str = 'bits') -> Vector[Bit]

Create a fixed-length classical bit vector initialized to zero.

The vector is represented as an initialized IR constant array, so it can receive measured Bit values through ordinary element assignment and can be returned from a qkernel. Its length must be known while tracing; the emitted classical initializer materializes contents, not a dynamic array shape.

Parameters:

Returns:

Vector[Bit] — Vector[Bit]: A fixed-length vector whose elements are initialized to False.

Raises:

• TypeError — If shape or name has the wrong type.

• ValueError — If the shape is empty, negative, or not known at trace time.

• NotImplementedError — If a shape with more than one dimension is requested.

Example:

>>> import qamomile.circuit as qmc
>>>
>>> @qmc.qkernel
... def readout() -> qmc.Vector[qmc.Bit]:
...     qubits = qmc.qubit_array(2, "qubits")
...     measured = qmc.measure(qubits)
...     bits = qmc.bit_array(2)
...     bits[0] = measured[0]
...     bits[1] = measured[1]
...     return bits

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]

Create a new 1-D qubit register and emit its QInitOperation.

Parameters:

Returns:

Vector[Qubit] — Vector[Qubit]: A 1-D quantum register handle of the requested size.

Raises:

• TypeError — If shape or name has the wrong type.

• ValueError — If shape is an empty tuple.

• NotImplementedError — If shape has more than one dimension. The quantum addressing path is rank-1, so a higher-rank register would silently alias distinct elements onto the same physical qubit. Allocate a 1-D Vector[Qubit] of the total size and compute flat indices explicitly instead (e.g. q[i * ncols + j]).

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, ValueBase, 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). Compiler-internal identity and writes use UUIDs or explicit parameter metadata. Compatibility readers may consult a non-empty label only after those identity channels, so anonymous temporaries cannot collide through a shared display key.

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¶

Configuration for compiler implementation-strategy selection.

Overview¶

Classes¶

DecompositionConfig [source]¶

class DecompositionConfig

Configure named implementation strategies for callable lowering.

Implementations live on each callable definition. This object only records user selection; it is intentionally not a second global strategy registry.

Parameters:

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

Return the selected strategy name for a callable.

Parameters:

Returns:

str — Explicit override or the configured default.

get_strategy_params¶

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

Return parameters for one strategy.

Parameters:

Returns:

dict[str, Any] — dict[str, Any]: Copy of the configured parameter mapping.

qamomile.circuit.frontend.func_to_block¶

Overview¶

Constants¶

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

• ValueLike: TypeAlias = 'Value | ArrayValue | TupleValue | DictValue'

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_build.create_traced_block so the resulting slot list reflects the same decisions that drive symbolic-vs-bound input creation. Classical scalar / array arguments are always included; a Dict argument is included only when it is a runtime parameter (its slot carries a DictType). Pure-quantum arguments, Tuple arguments, and compile-time-bound Dict arguments are excluded and 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.

Raises:

• TypeError — If a non-static classical annotation cannot be represented by an IR parameter type.

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

• NotImplementedError — If param_type is a rank>1 quantum array annotation (Matrix[Qubit] / Tensor[Qubit]). The quantum addressing path is rank-1, so a higher-rank register would silently alias distinct elements onto the same physical qubit. This path constructs the handle via object.__new__ (bypassing ArrayBase.__post_init__), so it needs its own guard.

create_static_binding_proxy [source]¶

def create_static_binding_proxy(annotation: Any, name: str) -> StaticBindingProxy

Create an unbound tracing proxy for a registered annotation.

Parameters:

Returns:

StaticBindingProxy — Closed symbolic adapter surface.

Raises:

• TypeError — If annotation is not registered.

func_to_block [source]¶

def func_to_block(func: Callable) -> Block

Convert a typed frontend function to a hierarchical block.

Parameters:

Returns:

Block — Hierarchical trace containing ordinary inputs and any deferred static binding slots.

Raises:

• TypeError — If an input or return annotation is missing or unsupported, a static binding parameter declares a default, or the traced return value does not match its annotation.

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_static_binding_annotation [source]¶

def is_static_binding_annotation(annotation: Any) -> bool

Return whether an annotation denotes a registered static binding.

Parameters:

Returns:

bool — Whether the annotation is registered.

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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    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[ValueLike] = list(),
    output_values: list[ValueLike] = list(),
    output_names: list[str] = list(),
    operations: list['Operation'] = list(),
    kind: BlockKind = BlockKind.HIERARCHICAL,
    parameters: dict[str, Value] = dict(),
    param_slots: tuple[ParamSlot, ...] = tuple(),
    static_bindings: tuple[StaticBindingSlot, ...] = tuple(),
) -> None

Attributes¶

• effects: ‘KernelEffect’ Return lazily cached semantic effects for this block.

• input_values: list[ValueLike]

• kind: BlockKind

• label_args: list[str]

• measurement_result_indices: frozenset[int] Return public output positions derived from measurement.

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[ValueLike]

• param_slots: tuple[ParamSlot, ...]

• parameters: dict[str, Value]

• static_bindings: tuple[StaticBindingSlot, ...]

Methods¶

call¶

def call(self, **kwargs: ValueLike = {}) -> 'InvokeOperation'

Create an inline callable invocation against this block.

Parameters:

Returns:

'InvokeOperation' — Inline-policy invocation whose callable definition points at this block.

Raises:

• KeyError — If a required label in self.label_args is missing from kwargs.

is_affine¶

def is_affine(self) -> bool

Return whether this block has passed affine validation.

Returns:

bool — True for AFFINE and ANALYZED blocks.

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}. Supports iteration via items() and subscript lookup (d[key]), including indexing one dict with the iteration keys of another.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gammas: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], Jij * gammas[(i, j)])
    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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
    _value_type: type | None = None,
    _runtime_parameter: bool = False,
) -> 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, ValueBase)

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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
) -> 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’

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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
) -> None

Attributes¶

• value: Value[QFixedType]

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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
) -> 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.

StaticBindingProxy [source]¶

class StaticBindingProxy

Expose a registered static object surface during unbound tracing.

Parameters:

Constructor¶

def __init__(self, spec: StaticBindingSpec, name: str) -> None

Create symbolic fields and deferred callable members.

Parameters:

Attributes¶

• slot: StaticBindingSlot Return the IR manifest entry owned by this proxy.

Tracer [source]¶

class Tracer

Collects operations (and loop-rebind records) during tracing.

Constructor¶

def __init__(
    self,
    _operations: list[Operation] = list(),
    loop_carried_rebinds: tuple[LoopCarriedRebind, ...] = (),
    region_entries: dict[str, Any] = dict(),
    loop_region_results: dict[str, Any] = dict(),
) -> None

Attributes¶

• loop_carried_rebinds: tuple[LoopCarriedRebind, ...]

• loop_region_results: dict[str, Any]

• operations: list[Operation]

• region_entries: dict[str, Any]

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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    _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, ValueBase)

A tuple of IR values for structured data.

Constructor¶

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

Attributes¶

• elements: tuple[ValueLike, ...]

• 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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    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, ValueBase, 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). Compiler-internal identity and writes use UUIDs or explicit parameter metadata. Compatibility readers may consult a non-empty label only after those identity channels, so anonymous temporaries cannot collide through a shared display key.

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¶

Handle type system: user-facing typed wrappers around IR Values.

Handles are what qkernel code manipulates: quantum primitives (Qubit, QFixed), classical scalars (UInt, Float, Bit), arrays (Vector, VectorView, Matrix, Tensor), structural containers (Tuple, Dict), and Observable (Hamiltonian). Each handle wraps one IR Value and forwards Python operators (arithmetic, comparison, indexing) to tracer-emitted IR operations, so user code reads as ordinary Python while building IR.

Design constraints:

• Quantum handles are linear: operations consume them and return fresh handles wrapping a new-version Value; reusing a consumed handle raises QubitConsumedError. Classical handles may be read freely.

• Classical arithmetic folds eagerly when both operands are known compile-time constants; otherwise a symbolic BinOp / CompOp is traced for partial_eval to resolve later.

• Handles are trace-time objects only — they never survive into the transpiled program and carry no backend or layout information. The IR Value (with its type and metadata) is the durable representation.

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 emit a deferred callable 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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    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}. Supports iteration via items() and subscript lookup (d[key]), including indexing one dict with the iteration keys of another.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gammas: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], Jij * gammas[(i, j)])
    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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
    _value_type: type | None = None,
    _runtime_parameter: bool = False,
) -> 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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
) -> 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.

Records the user-code source location (file:line) of the consuming call so a later affine violation can point at both the first-use and the reuse site.

Parameters:

Returns:

typing.Self — typing.Self: New handle pointing to the same underlying value.

Raises:

• QubitConsumedError — If this quantum handle was already consumed.

validate_consumable¶

def validate_consumable(self, operation_name: str = 'unknown') -> None

Validate a consume without changing affine ownership state.

Parameters:

Raises:

• QubitConsumedError — If this quantum handle was already consumed.

Matrix [source]¶

class Matrix(ArrayBase[T])

2-dimensional array type for classical element types.

Quantum element types are rejected: constructing a Matrix[Qubit] raises NotImplementedError (see ArrayBase.__post_init__) because the quantum addressing path is rank-1. Use a 1-D Vector[Qubit] with explicit index arithmetic instead.

Example:

import qamomile as qm

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

# Access elements (always requires 2 indices)
x = matrix[0, 1]
matrix[0, 1] = x

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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    _shape: tuple[int | UInt, int | UInt] = (0, 0),
    _borrowed_indices: dict[tuple[str, ...], 'tuple[UInt, ...] | Handle'] = 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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
) -> 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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
) -> 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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
) -> None

Attributes¶

• value: Value[QubitType]

Tensor [source]¶

class Tensor(ArrayBase[T])

N-dimensional array type (3 or more dimensions) for classical element types.

Quantum element types are rejected: constructing a Tensor[Qubit] raises NotImplementedError (see ArrayBase.__post_init__) because the quantum addressing path is rank-1. Use a 1-D Vector[Qubit] with explicit index arithmetic instead.

Example:

import qamomile as qm

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

# Access elements (requires all indices)
x = tensor[0, 1, 2]
tensor[0, 1, 2] = x

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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], 'tuple[UInt, ...] | Handle'] = 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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    _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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], 'tuple[UInt, ...] | Handle'] = 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 an inline callable invocation 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 consume on an overlapping element or view.

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

Initialize an affine-resource violation diagnosis.

Parameters:

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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], 'tuple[UInt, ...] | Handle'] = 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 after validating its affine ownership state.

Parameters:

Returns:

typing.Self — typing.Self: Fresh handle carrying the consumed array value.

Raises:

• QubitConsumedError — If this handle or a covered slot was consumed.

• UnreturnedBorrowError — If a live element or slice borrow remains.

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 scalar or view owners (parked in the dict with _consumed set and _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.

validate_consumable¶

def validate_consumable(self, operation_name: str = 'unknown') -> None

Validate an array consume without changing ownership state.

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 element or view operation (measure(q[0]) or measure(q[1::2]) followed by measure(q)), this raises QubitConsumedError rather than silently re-consuming those slots.

Parameters:

Raises:

• QubitConsumedError — If this handle or any covered slot was already consumed.

• UnreturnedBorrowError — If a live element or slice borrow remains.

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]

BinOp [source]¶

class BinOp(BinaryOperationBase)

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

Constructor¶

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

Attributes¶

• kind: BinOpKind | None

• operation_kind: OperationKind

• signature: Signature

BinOpKind [source]¶

class BinOpKind(enum.Enum)

Attributes¶

• ADD

• DIV

• FLOORDIV

• 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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    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

CompOp [source]¶

class CompOp(BinaryOperationBase)

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

Constructor¶

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

Attributes¶

• kind: CompOpKind | None

• operation_kind: OperationKind

• signature: Signature

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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
    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,
    _consumed_at: '_FrameRef | None' = None,
    _consumed_pre_branch: bool = False,
) -> 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.

Records the user-code source location (file:line) of the consuming call so a later affine violation can point at both the first-use and the reuse site.

Parameters:

Returns:

typing.Self — typing.Self: New handle pointing to the same underlying value.

Raises:

• QubitConsumedError — If this quantum handle was already consumed.

validate_consumable¶

def validate_consumable(self, operation_name: str = 'unknown') -> None

Validate a consume without changing affine ownership state.

Parameters:

Raises:

• QubitConsumedError — If this quantum handle was already consumed.

IfOperation [source]¶

class IfOperation(HasNestedOps, Operation)

Represents an if-else conditional operation.

Example:

if condition:
    true_body
else:
    false_body

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    true_operations: list[Operation] = list(),
    false_operations: list[Operation] = list(),
    true_yields: list[Value] = list(),
    false_yields: list[Value] = list(),
    branch_rebinds: tuple[BranchRebind, ...] = (),
    true_captures: tuple[ValueBase, ...] = (),
    false_captures: tuple[ValueBase, ...] = (),
) -> None

Attributes¶

• branch_rebinds: tuple[BranchRebind, ...]

• condition: Value

• false_captures: tuple[ValueBase, ...]

• false_operations: list[Operation]

• false_yields: list[Value]

• operation_kind: OperationKind

• signature: Signature

• true_captures: tuple[ValueBase, ...]

• true_operations: list[Operation]

• true_yields: list[Value]

Methods¶

add_merge¶

def add_merge(self, true_value: Value, false_value: Value, result: Value) -> None

Append a branch-merge slot to this if-else.

The only sanctioned construction path for merges: it keeps the yield lists and results index-aligned so iter_merges can rely on the invariants it checks.

Parameters:

Raises:

• RuntimeError — If the condition operand has not been attached to this operation yet (operands[0] must exist before merges are added), or the branch / result types do not match.

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Include branch-yield values and rebind records for cloning/substitution.

The yields are subclass-specific Value fields (not operands — see the class docstring), so generic passes reach them through this override, mirroring ForItemsOperation.key_var_values. Branch rebind records follow the loop operations’ rationale: the recorded pre-branch values reference program values by identity, so inline cloning must remap them in lockstep with operands. Read-based checks must not treat the records as reads (see _op_read_uuids in the analyze pass module).

Returns:

list[ValueBase] — list[ValueBase]: Base input values plus the true/false yields and rebind-record values.

iter_merges¶

def iter_merges(self) -> Iterator[IfMerge]

Iterate the branch-merge slots of this if-else.

This is the single read API for merge semantics: passes must consume merges through it (never through the yield lists directly) so the underlying storage can change without touching consumers.

Yields:

IfMerge — One entry per merged output, in result order.

Raises:

• RuntimeError — If the stored merge data is internally inconsistent (the yield-list lengths differ from the result count, or the condition operand is missing while merges are attached). This indicates IR corruption, not a user error. The per-merge corruption modes of the old embedded-operation storage (a foreign entry, a malformed or mismatched condition, a result copy diverging from results[i]) cannot be represented in the yield-list storage and need no checks.

nested_op_lists¶

def nested_op_lists(self) -> list[list[Operation]]

Return the two branch bodies (merge yields are not operations).

Returns:

list[list[Operation]] — list[list[Operation]]: [true_operations, false_operations]. The branch-merge yields are values, not operations, so they are intentionally absent here.

nested_regions¶

def nested_regions(self) -> tuple[Region, ...]

Return the true and false branch interfaces.

Returns:

tuple[Region, ...] — tuple[Region, ...]: True and false regions in that order, with branch-local captures and merge yields.

rebuild_nested¶

def rebuild_nested(self, new_lists: list[list[Operation]]) -> Operation

Return a copy with the true and false branch bodies replaced.

Parameters:

Returns:

Operation — A copy of this if-else with the branch bodies swapped and all other fields (yields, rebinds) preserved.

rebuild_regions¶

def rebuild_regions(self, regions: Sequence[Region]) -> Operation

Rebuild both branches and their complete boundary interfaces.

Parameters:

Returns:

Operation — Rebuilt conditional operation.

Raises:

• ValueError — If region count, block arguments, or yield signatures are inconsistent.

replace_values¶

def replace_values(self, mapping: dict[str, ValueBase]) -> Operation

Substitute operand, result, branch-yield, and rebind-record values.

Parameters:

Returns: