qamomile.circuit.transpiler

qamomile.circuit.transpiler.capabilities¶

Backend capability definitions for transpiler optimization.

Overview¶

Classes¶

BackendCapability [source]¶

class BackendCapability(enum.Flag)

Capabilities that a backend may support natively.

Use these flags to indicate which composite gates and features a backend supports, allowing the transpiler to use native implementations when available.

Attributes¶

• BASIC_COMPOSITE

• CLASSICAL_FEEDFORWARD

• DYNAMIC_CIRCUITS

• FOR_LOOP

• FULL_COMPOSITE

• FULL_CONTROL_FLOW

• NATIVE_IQFT

• NATIVE_QFT

• NATIVE_QPE

• NONE

• WHILE_LOOP

CapableBackend [source]¶

class CapableBackend(Protocol)

Protocol for backends that declare their capabilities.

Implement this protocol in backend-specific EmitPass classes to enable capability-based optimizations.

Attributes¶

• capabilities: BackendCapability Return the capabilities this backend supports.

Methods¶

has_capability¶

def has_capability(self, cap: BackendCapability) -> bool

Check if this backend has a specific capability.

Parameters:

Returns:

bool — True if the backend has the capability, False otherwise.

qamomile.circuit.transpiler.classical_executor¶

Classical segment executor for Python-based classical operations.

Overview¶

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]

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

ClassicalExecutor [source]¶

class ClassicalExecutor

Executes classical segments in Python.

Methods¶

execute¶

def execute(self, segment: ClassicalSegment, context: ExecutionContext) -> dict[str, Any]

Execute classical operations and return outputs.

Interprets the operations list directly using Python.

ClassicalSegment [source]¶

class ClassicalSegment(Segment)

A segment of pure classical operations.

Contains arithmetic, comparisons, and control flow. Will be executed directly in Python.

Constructor¶

def __init__(
    self,
    operations: list[Operation] = list(),
    input_refs: list[str] = list(),
    output_refs: list[str] = list(),
) -> None

Attributes¶

• kind: SegmentKind

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

CondOp [source]¶

class CondOp(BinaryOperationBase)

Conditional logical operation (AND, OR).

Constructor¶

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

Attributes¶

• kind: CondOpKind | None

• operation_kind: OperationKind

• signature: Signature

DecodeQFixedOperation [source]¶

class DecodeQFixedOperation(Operation)

Decode measured bits to float (classical operation).

This operation converts a sequence of classical bits from qubit measurements into a floating-point number using fixed-point encoding.

The decoding formula:

float_value = Σ bit[i] * 2^(int_bits - 1 - i)

For QPE phase (int_bits=0): float_value = 0.b0b1b2... = b00.5 + b10.25 + b2*0.125 + ...

Example:

bits = [1, 0, 1] with int_bits=0
→ 0.101 (binary) = 0.5 + 0.125 = 0.625

operands: [ArrayValue of bits (vec[bit])] results: [Float value]

Constructor¶

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

Attributes¶

• int_bits: int

• num_bits: int

• operation_kind: OperationKind

• signature: Signature

DictValue [source]¶

class DictValue(_MetadataValueMixin)

A dictionary value stored as stable ordered entries.

Constructor¶

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

Attributes¶

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

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: DictType

• uuid: str

Methods¶

is_constant¶

def is_constant(self) -> bool

next_version¶

def next_version(self) -> DictValue

ExecutionContext [source]¶

class ExecutionContext

Holds global state during program execution.

Constructor¶

def __init__(self, initial_bindings: dict[str, Any] | None = None)

Methods¶

copy¶

def copy(self) -> 'ExecutionContext'

Clone the execution context.

get¶

def get(self, key: str) -> Any

get_many¶

def get_many(self, keys: list[str]) -> dict[str, Any]

has¶

def has(self, key: str) -> bool

set¶

def set(self, key: str, value: Any) -> None

update¶

def update(self, values: dict[str, Any]) -> None

ExecutionError [source]¶

class ExecutionError(QamomileCompileError)

Error during program execution.

ForItemsOperation [source]¶

class ForItemsOperation(HasNestedOps, Operation)

Represents iteration over dict/iterable items.

Example:

for (i, j), Jij in qmc.items(ising):
    body

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    key_vars: list[str] = list(),
    value_var: str = '',
    key_is_vector: bool = False,
    key_var_values: tuple[Value, ...] | None = None,
    value_var_value: Value | None = None,
    operations: list[Operation] = list(),
) -> None

Attributes¶

• key_is_vector: bool

• key_var_values: tuple[Value, ...] | None

• key_vars: list[str]

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

• value_var: str

• value_var_value: Value | None

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Include the per-key/value Value fields for cloning/substitution.

Same rationale as ForOperation.all_input_values: keep the IR identity fields in lockstep with body references so UUID-keyed lookups stay valid after inline cloning.

nested_op_lists¶

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

rebuild_nested¶

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

replace_values¶

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

ForOperation [source]¶

class ForOperation(HasNestedOps, Operation)

Represents a for loop operation.

Example:

for i in range(start, stop, step):
    body

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    loop_var: str = '',
    loop_var_value: Value | None = None,
    operations: list[Operation] = list(),
) -> None

Attributes¶

• loop_var: str

• loop_var_value: Value | None

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Include loop_var_value so cloning/substitution stays consistent.

Without this override, UUIDRemapper would clone every body reference to the loop variable to a fresh UUID, but leave loop_var_value pointing at the un-cloned original — emit-time UUID-keyed lookups for the loop variable would then miss.

nested_op_lists¶

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

rebuild_nested¶

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

replace_values¶

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

HasNestedOps [source]¶

class HasNestedOps

Mixin for operations that contain nested operation lists.

Subclasses implement nested_op_lists() and rebuild_nested() so that generic passes can recurse into control flow without isinstance chains.

Methods¶

nested_op_lists¶

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

Return all nested operation lists in this control flow op.

rebuild_nested¶

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

Return a copy with nested operation lists replaced.

new_lists must have the same length/order as nested_op_lists().

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(),
    phi_ops: list[PhiOp] = list(),
) -> None

Attributes¶

• condition: Value

• false_operations: list[Operation]

• operation_kind: OperationKind

• phi_ops: list[PhiOp]

• signature: Signature

• true_operations: list[Operation]

Methods¶

nested_op_lists¶

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

rebuild_nested¶

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

NotOp [source]¶

class NotOp(Operation)

Constructor¶

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

Attributes¶

• input: Value

• operation_kind: OperationKind

• output: Value

• signature: Signature

PhiOp [source]¶

class PhiOp(Operation)

SSA Phi function: merge point after conditional branch.

This operation selects one of two values based on a condition. Used to merge values from different branches of an if-else statement.

Example:

if condition:
    x = x + 1  # true_value
else:
    x = x + 2  # false_value
# x is now PhiOp(condition, true_value, false_value)

Constructor¶

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

Attributes¶

• condition: Value

• false_value: Value

• operation_kind: OperationKind

• output: Value

• signature: Signature

• true_value: Value

TupleValue [source]¶

class TupleValue(_MetadataValueMixin)

A tuple of IR values for structured data.

Constructor¶

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

Attributes¶

• elements: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: ‘TupleType’

• uuid: str

Methods¶

is_constant¶

def is_constant(self) -> bool

next_version¶

def next_version(self) -> TupleValue

Value [source]¶

class Value(_MetadataValueMixin, Generic[T])

A typed SSA value in the IR.

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

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

Constructor¶

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

Attributes¶

• element_indices: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

is_array_element¶

def is_array_element(self) -> bool

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version and fresh UUID.

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

WhileOperation [source]¶

class WhileOperation(HasNestedOps, Operation)

Represents a while loop operation.

Only measurement-backed conditions are supported: the condition must be a Bit value produced by qmc.measure(). Non-measurement conditions (classical variables, constants, comparisons) are rejected by ValidateWhileContractPass before reaching backend emit.

Example::

bit = qmc.measure(q)
while bit:
    q = qmc.h(q)
    bit = qmc.measure(q)

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    operations: list[Operation] = list(),
    max_iterations: int | None = None,
) -> None

Attributes¶

• max_iterations: int | None

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

Methods¶

nested_op_lists¶

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

rebuild_nested¶

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

qamomile.circuit.transpiler.compile_check¶

Overview¶

Functions¶

is_block_compilable [source]¶

def is_block_compilable(block: Block) -> bool

Check if a Block is compilable.

A Block is considered compilable if all its operations are compilable. This function checks each operation in the block’s operations list.

Parameters:

Returns: bool: True if the block is compilable, False otherwise.

Classes¶

Block [source]¶

class Block

Unified block representation for all pipeline stages.

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

Constructor¶

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

Attributes¶

• input_values: list[Value]

• kind: BlockKind

• label_args: list[str]

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[Value]

• param_slots: tuple[ParamSlot, ...]

• parameters: dict[str, Value]

Methods¶

call¶

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

Create a CallBlockOperation against this block.

is_affine¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

qamomile.circuit.transpiler.compiled_segments¶

Compiled segment structures for transpiled quantum circuits.

Overview¶

Classes¶

ClassicalSegment [source]¶

class ClassicalSegment(Segment)

A segment of pure classical operations.

Contains arithmetic, comparisons, and control flow. Will be executed directly in Python.

Constructor¶

def __init__(
    self,
    operations: list[Operation] = list(),
    input_refs: list[str] = list(),
    output_refs: list[str] = list(),
) -> None

Attributes¶

• kind: SegmentKind

CompiledClassicalSegment [source]¶

class CompiledClassicalSegment

A classical segment ready for Python execution.

Constructor¶

def __init__(self, segment: ClassicalSegment) -> None

Attributes¶

• segment: ClassicalSegment

CompiledExpvalSegment [source]¶

class CompiledExpvalSegment

A compiled expectation value segment with concrete Hamiltonian.

This segment computes <psi|H|psi> where psi is the quantum state from a quantum circuit and H is a qamomile.observable.Hamiltonian.

Constructor¶

def __init__(
    self,
    segment: ExpvalSegment,
    hamiltonian: 'qm_o.Hamiltonian',
    quantum_segment_index: int = 0,
    result_ref: str = '',
    qubit_map: dict[int, int] = dict(),
) -> None

Attributes¶

• hamiltonian: ‘qm_o.Hamiltonian’

• quantum_segment_index: int

• qubit_map: dict[int, int]

• result_ref: str

• segment: ExpvalSegment

CompiledQuantumSegment [source]¶

class CompiledQuantumSegment(Generic[T])

A quantum segment with emitted backend circuit.

Constructor¶

def __init__(
    self,
    segment: QuantumSegment,
    circuit: T,
    qubit_map: QubitMap = dict(),
    clbit_map: ClbitMap = dict(),
    measurement_qubit_map: dict[int, int] = dict(),
    parameter_metadata: ParameterMetadata = ParameterMetadata(),
) -> None

Attributes¶

• circuit: T

• clbit_map: ClbitMap

• measurement_qubit_map: dict[int, int]

• parameter_metadata: ParameterMetadata

• qubit_map: QubitMap

• segment: QuantumSegment

ExpvalSegment [source]¶

class ExpvalSegment(Segment)

A segment for expectation value computation.

Represents computing <psi|H|psi> where psi is the quantum state and H is a Hamiltonian observable.

This segment bridges a quantum circuit (state preparation) to a classical expectation value.

Constructor¶

def __init__(
    self,
    operations: list[Operation] = list(),
    input_refs: list[str] = list(),
    output_refs: list[str] = list(),
    hamiltonian_value: Value | None = None,
    qubits_value: Value | None = None,
    result_ref: str = '',
) -> None

Attributes¶

• hamiltonian_value: Value | None

• kind: SegmentKind

• qubits_value: Value | None

• result_ref: str

ParameterMetadata [source]¶

class ParameterMetadata

Metadata for all parameters in a compiled segment.

Tracks parameter information for runtime binding.

Constructor¶

def __init__(self, parameters: list[ParameterInfo] = list()) -> None

Attributes¶

• parameters: list[ParameterInfo]

Methods¶

get_array_names¶

def get_array_names(self) -> set[str]

Get unique array/scalar parameter names.

get_ordered_params¶

def get_ordered_params(self) -> list[Any]

Get backend parameter objects in definition order.

Useful for backends that require positional parameter binding (e.g., QURI Parts).

Returns:

list[Any] — List of backend_param objects in the order they were defined.

Example:

# For QURI Parts that uses positional binding:
param_values = [bindings[p.name] for p in metadata.parameters]
bound_circuit = circuit.bind_parameters(param_values)

get_param_by_name¶

def get_param_by_name(self, name: str) -> ParameterInfo | None

Get parameter info by full name.

to_binding_dict¶

def to_binding_dict(self, bindings: dict[str, Any]) -> dict[Any, Any]

Convert indexed bindings to backend parameter bindings.

Transforms user-provided bindings (with indexed names like “gammas[0]”) into a dictionary mapping backend parameter objects to values. Useful for backends that use dict-based parameter binding (e.g., Qiskit).

Parameters:

Returns:

dict[Any, Any] — Dictionary mapping backend_param objects to values.

Example:

# For Qiskit that uses dict-based binding:
qiskit_bindings = metadata.to_binding_dict(bindings)
bound_circuit = circuit.assign_parameters(qiskit_bindings)

QuantumSegment [source]¶

class QuantumSegment(Segment)

A segment of pure quantum operations.

Contains quantum gates and qubit allocations. Will be emitted to a quantum circuit.

Constructor¶

def __init__(
    self,
    operations: list[Operation] = list(),
    input_refs: list[str] = list(),
    output_refs: list[str] = list(),
    qubit_values: list[Value] = list(),
    num_qubits: int = 0,
) -> None

Attributes¶

• kind: SegmentKind

• num_qubits: int

• qubit_values: list[Value]

qamomile.circuit.transpiler.decompositions¶

Shared gate decomposition recipes for backend emitters.

This module defines the canonical decomposition of controlled gates (CH, CY, CP, CRY, CRZ) into primitive operations (RY, RZ, CNOT, S, SDG). Each recipe is a frozen sequence of :class:DecompStep instances that encode:

• Which primitive gate to apply,

• Which qubit role receives the gate ("control" or "target"),

• An optional angle expression (e.g. "theta/2", "-pi/4").

The recipes are the single source of truth for how Qamomile decomposes controlled gates when a backend cannot use a native controlled-U operation.

Why data-only (no shared execution helper)¶

Each backend has its own emission dialect:

• Qiskit uses native circuit.ch() / circuit.cy() and never needs this decomposition.

• QURI Parts represents angles as parametric dicts (name -> coefficient); primitive emit_* methods take those dicts, not plain floats, so a generic “loop over the recipe and call emitter.emit_ry(angle)” helper does not compose.

• CUDA-Q emits Python source as strings. A generic helper that calls self.emit_ry interacts poorly with the tracing test emitter, which wraps every emit_* method and would double-record each call.

Because no single helper absorbs all three styles cleanly, backends inline their decomposition using their own idiomatic emission, and reference the recipe constants below from the emit_ch / emit_cy / ... docstrings to document equivalence. When changing a recipe, update the constant here and ensure every backend’s inline implementation matches.

Overview¶

Constants¶

• CH_DECOMPOSITION: list[DecompStep]

• CP_DECOMPOSITION: list[DecompStep]

• CRY_DECOMPOSITION: list[DecompStep]

• CRZ_DECOMPOSITION: list[DecompStep]

• CY_DECOMPOSITION: list[DecompStep]

Classes¶

DecompStep [source]¶

class DecompStep

A single step in a decomposition recipe.

Constructor¶

def __init__(self, gate: PrimitiveGate, target: str, angle: str | None = None) -> None

Attributes¶

• angle: str | None

• gate: PrimitiveGate

• target: str

PrimitiveGate [source]¶

class PrimitiveGate(Enum)

Gate primitives used in decomposition recipes.

Attributes¶

• CNOT

• RY

• RZ

• S

• SDG

qamomile.circuit.transpiler.emit_context¶

Typed bindings container for the emit pipeline.

Background — what was wrong with the bare dict[str, Any]:

The pre-EmitContext design used a single bindings: dict[str, Any] threaded through every emit-pipeline function. That dict served at least seven distinct semantic purposes simultaneously:

1. User-supplied kernel parameters (keyed by parameter name).

2. Loop iteration variables (keyed by loop_var name; pushed on entry, restored on exit).

3. Emit-time-computed intermediates — BinOp / CompOp / CondOp / NotOp results (keyed by Value UUID after Fix B; originally also keyed by Value name, which collided across tmps).

4. Phi-output aliases (keyed by phi-output UUID; written by register_classical_phi_aliases).

5. Backend runtime expressions (e.g. qiskit.circuit.classical.expr.Expr for compound runtime if-conditions).

6. Array data (keyed by array name; bound iterables passed by user).

7. Dict data (keyed by dict name; bound iterables passed by user).

8. Pauli observables (keyed by observable name).

This overloading was the structural cause of every name-collision bug class seen in this codebase: "bit_tmp" chained predicates, j_phi_4 phi aliases, the inline-pass DictValue drop, and the type-blind bool(...) coercion in resolve_operand. Each was patched locally; the structural overloading remained.

What EmitContext does (root-cause fix):

EmitContext is a dict subclass — flat [key] access still works for migration compatibility. On top of dict semantics, every binding kind has a separate, semantically-typed slot with the appropriate identity key:

• _params — user parameters, keyed by name (user-facing).

• _loop_vars — loop iteration variables, keyed by Value UUID.

• _values — emit-time intermediates, keyed by UUID.

• _runtime_exprs — backend Expr objects, keyed by UUID.

• _array_data — array bindings, keyed by ArrayValue.uuid.

• _dict_data — dict bindings, keyed by DictValue.uuid.

• _observables — Pauli observables, keyed by Value.uuid.

The key invariant: after the migration, the dict-baseclass writes disappear. All writers go through typed setters (push_loop_var, set_array_data, etc.); all readers go through typed getters. EmitContext retains dict-protocol read-compat for legacy callers during migration, but new code should never touch ctx[key].

Identity policy:

• UUID: everything compiler-internal (loop vars, intermediates, runtime exprs, array/dict/observable bindings).

• Name: only at the user-API boundary (parameter names supplied by transpile(bindings={...})).

This eliminates the name-collision bug class entirely: empty/duplicate names cannot resolve to anything because lookups never go through the name path.

Overview¶

Classes¶

EmitContext [source]¶

class EmitContext(dict)

Bindings container with semantic slots, dict-compatible.

All emit-pipeline functions that take bindings: dict[str, Any] accept an EmitContext unchanged because it inherits from dict.

Use the typed methods (bind_param, set_value, etc.) when writing new code so the slot tracking stays accurate; existing ctx[key] = value writes still work but bypass the slots.

Slots:

_params: User-supplied kernel parameters, keyed by parameter name. Stable across the run. Name-keyed because the user supplies parameters by name at the public API boundary. _loop_vars: Currently-bound loop iteration variables, keyed by ForOperation.loop_var_value.uuid / ForItemsOperation.value_var_value.uuid etc. Pushed on loop entry, restored on exit. UUID-keyed so identical user-chosen variable names in nested or sibling loops never collide. _values: Emit-time-computed intermediate values (BinOp results, CompOp/CondOp/NotOp results, phi aliases), keyed by Value UUID. _runtime_exprs: Backend runtime-expression objects (e.g. Qiskit expr.Expr for compound classical conditions), keyed by Value UUID. _array_data: Bound array data (e.g. Vector[Float] parameter values), keyed by ArrayValue.uuid. _dict_data: Bound dict data (e.g. Dict[Tuple[UInt, UInt], Float] ising coefficients), keyed by DictValue.uuid. _observables: Bound Pauli observables (used by PauliEvolveOp and gate counting), keyed by observable Value UUID.

Example:

>>> ctx = EmitContext.from_user_bindings({"theta": 0.5, "n": 3})
>>> ctx["theta"]  # dict-style read still works
0.5
>>> ctx.bind_param("phi", 1.5)
>>> "phi" in ctx and ctx["phi"] == 1.5
True
>>> ctx.set_value(some_uuid, 42)
>>> ctx[some_uuid] == 42 and some_uuid in ctx._values
True

Constructor¶

def __init__(self, *args: Any = (), **kwargs: Any = {}) -> None

Methods¶

bind_param¶

def bind_param(self, name: str, value: Any) -> None

Register a kernel parameter binding (by name).

bind_params¶

def bind_params(self, params: dict[str, Any]) -> None

Register multiple kernel parameter bindings.

copy¶

def copy(self) -> 'EmitContext'

Return a shallow copy preserving all semantic slots.

The dict baseclass copy() returns a plain dict, dropping the slot-tracking metadata. Loop unrollers call bindings.copy() to make a per-iteration child scope; without this override the child would lose the params/loop_vars/values/runtime_exprs partitioning and become a flat dict, defeating the whole point of EmitContext. We override to return an EmitContext with slot dicts independently copied so child mutations (e.g. pushing a new loop var) don’t bleed back to the parent.

describe¶

def describe(self) -> str

Return a multi-line summary suitable for debug printing.

from_user_bindings¶

@classmethod
def from_user_bindings(cls, user_bindings: dict[str, Any] | None) -> 'EmitContext'

Build an EmitContext seeded with user-supplied parameters.

Parameters:

Returns:

'EmitContext' — A fresh EmitContext with all entries registered as parameters.

get_array_data¶

def get_array_data(self, uuid: str) -> Any

Get array data by ArrayValue.uuid, or None.

get_dict_data¶

def get_dict_data(self, uuid: str) -> Any

Get dict data by DictValue.uuid, or None.

get_loop_var¶

def get_loop_var(self, uuid: str) -> Any

Get a loop variable binding by Value UUID, or None if absent.

get_observable¶

def get_observable(self, uuid: str) -> Any

Get a Pauli observable by Value UUID, or None.

get_runtime_expr¶

def get_runtime_expr(self, uuid: str) -> Any

Get a backend runtime expression by Value UUID, or None.

iter_values¶

def iter_values(self) -> Iterator[tuple[str, Any]]

Iterate over UUID-keyed emit-time intermediates only.

push_loop_var¶

def push_loop_var(self, uuid: str, value: Any, display_name: str | None = None) -> None

Bind a loop iteration variable, keyed by Value UUID.

Parameters:

Note: this adds a binding to the existing context. Loop unrollers typically copy the parent context first so the binding is local to one iteration; this method does not copy.

set_array_data¶

def set_array_data(self, uuid: str, data: Any, display_name: str | None = None) -> None

Bind array data by ArrayValue.uuid.

Parameters:

set_dict_data¶

def set_dict_data(self, uuid: str, data: Any, display_name: str | None = None) -> None

Bind dict data by DictValue.uuid.

Parameters:

set_observable¶

def set_observable(self, uuid: str, observable: Any, display_name: str | None = None) -> None

Bind a Pauli observable by Value UUID.

Parameters:

set_runtime_expr¶

def set_runtime_expr(self, uuid: str, expr: Any) -> None

Bind a backend runtime expression by Value UUID.

Backends (e.g. Qiskit) call this when they construct a runtime-evaluable expression for a classical predicate that wasn’t compile-time-foldable. _emit_if / _emit_while consult the runtime-expr slot first when resolving conditions.

set_value¶

def set_value(self, uuid: str, value: Any) -> None

Bind an emit-time-computed intermediate by Value UUID.

Use for BinOp / CompOp / CondOp / NotOp results, phi aliases, and other UUID-identified intermediates.

qamomile.circuit.transpiler.errors¶

Compilation error classes for Qamomile transpiler.

Overview¶

Classes¶

AffineTypeError [source]¶

class AffineTypeError(QamomileCompileError)

Base class for affine type violations.

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

Constructor¶

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

Attributes¶

• first_use_location

• handle_name

• operation_name

DependencyError [source]¶

class DependencyError(QamomileCompileError)

Error when quantum operation depends on non-parameter classical value.

This error indicates that the program requires JIT compilation which is not yet supported.

Constructor¶

def __init__(
    self,
    message: str,
    quantum_op: str | None = None,
    classical_value: str | None = None,
)

Attributes¶

• classical_value

• quantum_op

EmitError [source]¶

class EmitError(QamomileCompileError)

Error during backend code emission.

Constructor¶

def __init__(self, message: str, operation: str | None = None)

Attributes¶

• operation

EntrypointValidationError [source]¶

class EntrypointValidationError(ValidationError)

Error when a top-level transpilation entrypoint has unsupported I/O.

ExecutionError [source]¶

class ExecutionError(QamomileCompileError)

Error during program execution.

FrontendTransformError [source]¶

class FrontendTransformError(QamomileCompileError)

Error during frontend AST-to-builder lowering.

InliningError [source]¶

class InliningError(QamomileCompileError)

Error during inline pass (inlining CallBlockOperations).

OperandResolutionInfo [source]¶

class OperandResolutionInfo

Detailed information about a single operand that failed to resolve.

Constructor¶

def __init__(
    self,
    operand_name: str,
    operand_uuid: str,
    is_array_element: bool,
    parent_array_name: str | None,
    element_indices_names: list[str],
    failure_reason: ResolutionFailureReason,
    failure_details: str,
) -> None

Attributes¶

• element_indices_names: list[str]

• failure_details: str

• failure_reason: ResolutionFailureReason

• is_array_element: bool

• operand_name: str

• operand_uuid: str

• parent_array_name: str | None

QamomileCompileError [source]¶

class QamomileCompileError(Exception)

Base class for all Qamomile compilation errors.

QubitAliasError [source]¶

class QubitAliasError(AffineTypeError)

Same qubit used multiple times in one operation.

Operations like cx() require distinct qubits for control and target. Using the same qubit in both positions is physically impossible and indicates a programming error.

Example of incorrect code:

q1, q2 = qm.cx(q, q) # ERROR: same qubit as control and target

Correct code:

q1, q2 = qm.cx(control, target) # Use distinct qubits

QubitBorrowConflictError [source]¶

class QubitBorrowConflictError(AffineTypeError)

Qubit slot inaccessible because another live handle borrows it.

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

Example of incorrect code (overlapping slice views)::

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

Correct code::

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

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

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

Correct code::

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

QubitConsumedError [source]¶

class QubitConsumedError(AffineTypeError)

Qubit handle used after being consumed by a previous operation.

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

Example of incorrect code:

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

Correct code:

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

QubitIndexResolutionError [source]¶

class QubitIndexResolutionError(EmitError)

Error when qubit indices cannot be resolved during emission.

This error provides detailed diagnostic information about why qubit index resolution failed and suggests remediation steps.

Constructor¶

def __init__(
    self,
    gate_type: str,
    operand_infos: list[OperandResolutionInfo],
    available_bindings_keys: list[str],
    available_qubit_map_keys: list[str],
)

Attributes¶

• available_bindings_keys

• available_qubit_map_keys

• gate_type

• operand_infos

QubitRebindError [source]¶

class QubitRebindError(AffineTypeError)

Quantum variable reassigned from a different quantum source.

When a quantum variable is reassigned, the RHS must consume the same variable (self-update pattern). Reassigning from a different quantum variable would silently discard the original quantum state.

The check runs at qkernel decoration time as a static AST analysis (see qamomile.circuit.frontend.ast_transform.collect_quantum_rebind_violations) and raises immediately — the wrapped QKernel object is never constructed when a violation is present. The check is run unconditionally for every decorated kernel: kernel-level quantum parameters (Qubit / Vector[Qubit]) seed origins from the signature, and the analyzer’s recognition of internal quantum constructors (qubit(...) / qubit_array(...)) seeds further origins from inside the body so kernels that derive all of their quantum state from internal allocations are also covered.

Branch-internal rebinds (assignments inside an if / for / while body) are NOT flagged at decoration time: compile-time conditional branches legitimately rebind quantum names (the compile-time-if lowering pass selects one branch and discards the other), and the single-pass AST analyzer cannot distinguish compile-time from runtime branches. To keep those compile-time patterns working, branch-internal violations are suppressed.

This is a known coverage gap. AffineValidationPass in the IR layer only enforces “consumed at most once” and does NOT detect “never consumed” / “silent discard” patterns, so a genuine runtime if cond: q = qm.qubit("fresh") that discards a parameter is currently not raised by either layer. A dedicated IR-level silent-discard pass (or a flow-sensitive frontend analyzer) would be needed to close it; this is tracked as follow-up. Top-level (non-branch-internal) bypasses continue to raise at decoration time.

Example of incorrect code:

a = qm.h(b) # ERROR: ‘a’ was quantum, now overwritten from ‘b’ a = b # ERROR: ‘a’ was quantum, now overwritten from ‘b’

Correct patterns:

a = qm.h(a) # Self-update (OK) new = qm.h(b) # New binding (OK, ‘new’ wasn’t quantum before)

ResolutionFailureReason [source]¶

class ResolutionFailureReason(Enum)

Categorizes why qubit index resolution failed.

Attributes¶

• ARRAY_ELEMENT_NOT_IN_QUBIT_MAP

• DIRECT_UUID_NOT_FOUND

• INDEX_NOT_NUMERIC

• NEGATIVE_INDEX

• NESTED_ARRAY_RESOLUTION_FAILED

• SYMBOLIC_INDEX_NOT_BOUND

• UNKNOWN

SeparationError [source]¶

class SeparationError(QamomileCompileError)

Error during quantum/classical separation.

SliceBorrowViolationError [source]¶

class SliceBorrowViolationError(AffineTypeError)

Aliasing detected between a slice view and a direct parent access.

Raised by :class:SliceBorrowCheckPass at transpile time when a parent array slot is simultaneously held by a VectorView and accessed directly, or when two overlapping views cover the same slot. For slices with constant bounds this is normally caught at trace time; this error covers the post-fold case when slice bounds were symbolic UInt parameters resolved by bindings.

Example of incorrect code (detected only after bindings resolve lo/hi to concrete values)::

region = q[lo:hi]     # bindings give lo=0, hi=4 → covers {0,1,2,3}
qa = region[0]        # borrows parent slot 0 via the view
qb = q[0]             # borrows parent slot 0 directly
# SliceBorrowViolationError: slot 0 is held by a slice view

UnreturnedBorrowError [source]¶

class UnreturnedBorrowError(AffineTypeError)

Borrowed array element not returned before array use.

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

Example of incorrect code:

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

Correct code:

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

ValidationError [source]¶

class ValidationError(QamomileCompileError)

Error during validation (e.g., non-classical I/O).

Constructor¶

def __init__(self, message: str, value_name: str | None = None)

Attributes¶

• value_name

qamomile.circuit.transpiler.executable¶

Executable program structure for compiled quantum-classical programs.

Overview¶

Classes¶

ClassicalExecutor [source]¶

class ClassicalExecutor

Executes classical segments in Python.

Methods¶

execute¶

def execute(self, segment: ClassicalSegment, context: ExecutionContext) -> dict[str, Any]

Execute classical operations and return outputs.

Interprets the operations list directly using Python.

CompiledClassicalSegment [source]¶

class CompiledClassicalSegment

A classical segment ready for Python execution.

Constructor¶

def __init__(self, segment: ClassicalSegment) -> None

Attributes¶

• segment: ClassicalSegment

CompiledExpvalSegment [source]¶

class CompiledExpvalSegment

A compiled expectation value segment with concrete Hamiltonian.

This segment computes <psi|H|psi> where psi is the quantum state from a quantum circuit and H is a qamomile.observable.Hamiltonian.

Constructor¶

def __init__(
    self,
    segment: ExpvalSegment,
    hamiltonian: 'qm_o.Hamiltonian',
    quantum_segment_index: int = 0,
    result_ref: str = '',
    qubit_map: dict[int, int] = dict(),
) -> None

Attributes¶

• hamiltonian: ‘qm_o.Hamiltonian’

• quantum_segment_index: int

• qubit_map: dict[int, int]

• result_ref: str

• segment: ExpvalSegment

CompiledQuantumSegment [source]¶

class CompiledQuantumSegment(Generic[T])

A quantum segment with emitted backend circuit.

Constructor¶

def __init__(
    self,
    segment: QuantumSegment,
    circuit: T,
    qubit_map: QubitMap = dict(),
    clbit_map: ClbitMap = dict(),
    measurement_qubit_map: dict[int, int] = dict(),
    parameter_metadata: ParameterMetadata = ParameterMetadata(),
) -> None

Attributes¶

• circuit: T

• clbit_map: ClbitMap

• measurement_qubit_map: dict[int, int]

• parameter_metadata: ParameterMetadata

• qubit_map: QubitMap

• segment: QuantumSegment

ExecutableProgram [source]¶

class ExecutableProgram(Generic[T])

A fully compiled program ready for execution.

Contains compiled quantum, classical, and expectation-value segments. Use sample() for multi-shot execution or run() for single execution.

Example:

executable = transpiler.compile(kernel)

# Sample: multiple shots, returns counts
job = executable.sample(executor, shots=1000)
result = job.result()  # SampleResult with counts

# Run: single shot, returns typed result
job = executable.run(executor)
result = job.result()  # Returns kernel's return type

Constructor¶

def __init__(
    self,
    plan: ProgramPlan | None = None,
    compiled_quantum: list[CompiledQuantumSegment[T]] = list(),
    compiled_classical: list[CompiledClassicalSegment] = list(),
    compiled_expval: list[CompiledExpvalSegment] = list(),
    output_refs: list[str] = list(),
    num_output_bits: int = 0,
) -> None

Attributes¶

• compiled_classical: list[CompiledClassicalSegment]

• compiled_expval: list[CompiledExpvalSegment]

• compiled_quantum: list[CompiledQuantumSegment[T]]

• has_parameters: bool Check if this program has unbound parameters.

• num_output_bits: int

• output_refs: list[str]

• parameter_names: list[str] Get list of parameter names that need binding.

• plan: ProgramPlan | None

• quantum_circuit: T Get the single quantum circuit.

Methods¶

get_circuits¶

def get_circuits(self) -> list[T]

Get all quantum circuits in execution order.

get_first_circuit¶

def get_first_circuit(self) -> T | None

Get the first quantum circuit, or None if no quantum segments.

run¶

def run(
    self,
    executor: QuantumExecutor[T],
    bindings: dict[str, Any] | None = None,
) -> RunJob[Any] | ExpvalJob

Execute once and return single result.

Parameters:

Returns:

RunJob[Any] | ExpvalJob — RunJob that resolves to the kernel’s return type, or RunJob[Any] | ExpvalJob — ExpvalJob if the program contains expectation value computation.

Raises:

• ExecutionError — If no quantum circuit to execute

• ValueError — If required parameters are missing

Example:

job = executable.run(executor, bindings={"gamma": [0.5]})
result = job.result()
print(result)  # 0.25 (for QFixed) or (0, 1) (for bits)

sample¶

def sample(
    self,
    executor: QuantumExecutor[T],
    shots: int = 1024,
    bindings: dict[str, Any] | None = None,
) -> SampleJob[Any]

Execute with multiple shots and return counts.

Parameters:

Returns:

SampleJob[Any] — SampleJob that resolves to SampleResult with results.

Raises:

• ExecutionError — If no quantum circuit to execute

• ValueError — If required parameters are missing

Example:

job = executable.sample(executor, shots=1000, bindings={"gamma": [0.5]})
result = job.result()
print(result.results)  # [(0.25, 500), (0.75, 500)]

ExecutionContext [source]¶

class ExecutionContext

Holds global state during program execution.

Constructor¶

def __init__(self, initial_bindings: dict[str, Any] | None = None)

Methods¶

copy¶

def copy(self) -> 'ExecutionContext'

Clone the execution context.

get¶

def get(self, key: str) -> Any

get_many¶

def get_many(self, keys: list[str]) -> dict[str, Any]

has¶

def has(self, key: str) -> bool

set¶

def set(self, key: str, value: Any) -> None

update¶

def update(self, values: dict[str, Any]) -> None

ExecutionError [source]¶

class ExecutionError(QamomileCompileError)

Error during program execution.

ExpvalJob [source]¶

class ExpvalJob(Job[float])

Job for expectation value computation.

Returns a single float representing <psi|H|psi>.

Constructor¶

def __init__(self, exp_val: float)

Initialize expval job.

Parameters:

Methods¶

result¶

def result(self) -> float

Return the expectation value.

status¶

def status(self) -> JobStatus

Return job status.

ParameterInfo [source]¶

class ParameterInfo

Information about a single unbound parameter in the circuit.

Constructor¶

def __init__(
    self,
    name: str,
    array_name: str,
    index: int | None,
    backend_param: Any,
    source_ref: str | None = None,
) -> None

Attributes¶

• array_name: str

• backend_param: Any

• index: int | None

• name: str

• source_ref: str | None

ParameterMetadata [source]¶

class ParameterMetadata

Metadata for all parameters in a compiled segment.

Tracks parameter information for runtime binding.

Constructor¶

def __init__(self, parameters: list[ParameterInfo] = list()) -> None

Attributes¶

• parameters: list[ParameterInfo]

Methods¶

get_array_names¶

def get_array_names(self) -> set[str]

Get unique array/scalar parameter names.

get_ordered_params¶

def get_ordered_params(self) -> list[Any]

Get backend parameter objects in definition order.

Useful for backends that require positional parameter binding (e.g., QURI Parts).

Returns:

list[Any] — List of backend_param objects in the order they were defined.

Example:

# For QURI Parts that uses positional binding:
param_values = [bindings[p.name] for p in metadata.parameters]
bound_circuit = circuit.bind_parameters(param_values)

get_param_by_name¶

def get_param_by_name(self, name: str) -> ParameterInfo | None

Get parameter info by full name.

to_binding_dict¶

def to_binding_dict(self, bindings: dict[str, Any]) -> dict[Any, Any]

Convert indexed bindings to backend parameter bindings.

Transforms user-provided bindings (with indexed names like “gammas[0]”) into a dictionary mapping backend parameter objects to values. Useful for backends that use dict-based parameter binding (e.g., Qiskit).

Parameters:

Returns:

dict[Any, Any] — Dictionary mapping backend_param objects to values.

Example:

# For Qiskit that uses dict-based binding:
qiskit_bindings = metadata.to_binding_dict(bindings)
bound_circuit = circuit.assign_parameters(qiskit_bindings)

ProgramPlan [source]¶

class ProgramPlan

Execution plan for a hybrid quantum/classical program.

Structure:

• [Optional] Classical preprocessing (parameter computation, etc.)

• Single quantum segment (REQUIRED)

• [Optional] Expval segment OR classical postprocessing

This plan enforces Qamomile’s current execution model: all quantum operations must be in a single quantum circuit.

Constructor¶

def __init__(
    self,
    steps: list[ProgramStep] = list(),
    abi: ProgramABI = ProgramABI(),
    boundaries: list[HybridBoundary] = list(),
    parameters: dict[str, Value] = dict(),
) -> None

Attributes¶

• abi: ProgramABI

• boundaries: list[HybridBoundary]

• parameters: dict[str, Value]

• steps: list[ProgramStep]

QuantumExecutor [source]¶

class QuantumExecutor(ABC, Generic[T])

Abstract base class for quantum backend execution.

To implement a custom executor:

1. execute() [Required] Execute circuit and return bitstring counts as dict[str, int]. Keys are bitstrings in big-endian format (e.g., “011” means q2=0, q1=1, q0=1).

2. bind_parameters() [Optional] Bind parameter values to parametric circuits. Override if your executor supports parametric circuits (e.g., QAOA variational circuits). Use ParameterMetadata.to_binding_dict() for easy conversion.

3. estimate() [Optional] Compute expectation values <psi|H|psi>. Override if your executor supports estimation primitives (e.g., Qiskit Estimator, QURI Parts).

Example (Minimal): class MyExecutor(QuantumExecutor[QuantumCircuit]): def init(self): from qiskit_aer import AerSimulator self.backend = AerSimulator()

    def execute(self, circuit, shots):
        from qiskit import transpile
        if circuit.num_clbits == 0:
            circuit = circuit.copy()
            circuit.measure_all()
        transpiled = transpile(circuit, self.backend)
        return self.backend.run(transpiled, shots=shots).result().get_counts()

Example (With Parameter Binding): def bind_parameters(self, circuit, bindings, metadata): # metadata.to_binding_dict() converts indexed names to backend params return circuit.assign_parameters(metadata.to_binding_dict(bindings))

Methods¶

bind_parameters¶

def bind_parameters(
    self,
    circuit: T,
    bindings: dict[str, Any],
    parameter_metadata: ParameterMetadata,
) -> T

Bind parameter values to the circuit.

Default implementation returns the circuit unchanged. Override for backends that support parametric circuits.

Parameters:

Returns:

T — New circuit with parameters bound

estimate¶

def estimate(
    self,
    circuit: T,
    hamiltonian: 'qm_o.Hamiltonian',
    params: Sequence[float] | None = None,
) -> float

Estimate the expectation value of a Hamiltonian.

This method computes <psi|H|psi> where psi is the quantum state prepared by the circuit and H is the Hamiltonian.

Backends can override this method to provide optimized implementations using their native estimator primitives.

Parameters:

Returns:

float — The estimated expectation value

Raises:

• NotImplementedError — If the executor does not support estimation

execute¶

def execute(self, circuit: T, shots: int) -> dict[str, int]

Execute the circuit and return bitstring counts.

Parameters:

Returns:

dict[str, int] — Dictionary mapping bitstrings to counts. dict[str, int] — {“00”: 512, “11”: 512}

RunJob [source]¶

class RunJob(Job[T], Generic[T])

Job for single execution.

Returns a single result value matching the kernel’s return type.

Constructor¶

def __init__(self, raw_counts: dict[str, int], result_converter: Callable[[str], T])

Initialize run job.

Parameters:

Methods¶

result¶

def result(self) -> T

Return the single result.

status¶

def status(self) -> JobStatus

Return job status.

SampleJob [source]¶

class SampleJob(Job[SampleResult[T]], Generic[T])

Job for sampling execution (multiple shots).

Returns a SampleResult containing counts for each unique result.

Constructor¶

def __init__(
    self,
    raw_counts: dict[str, int],
    result_converter: Callable[[dict[str, int]], list[tuple[T, int]]],
    shots: int,
)

Initialize sample job.

Parameters:

Methods¶

result¶

def result(self) -> SampleResult[T]

Return the sample result.

status¶

def status(self) -> JobStatus

Return job status.

qamomile.circuit.transpiler.execution_context¶

Execution context for quantum-classical program execution.

Overview¶

Classes¶

ExecutionContext [source]¶

class ExecutionContext

Holds global state during program execution.

Constructor¶

def __init__(self, initial_bindings: dict[str, Any] | None = None)

Methods¶

copy¶

def copy(self) -> 'ExecutionContext'

Clone the execution context.

get¶

def get(self, key: str) -> Any

get_many¶

def get_many(self, keys: list[str]) -> dict[str, Any]

has¶

def has(self, key: str) -> bool

set¶

def set(self, key: str, value: Any) -> None

update¶

def update(self, values: dict[str, Any]) -> None

qamomile.circuit.transpiler.gate_emitter¶

GateEmitter protocol for backend-agnostic gate emission.

This module defines the GateEmitter protocol that backends implement to emit individual quantum gates. The StandardEmitPass uses this protocol to orchestrate circuit generation without backend-specific code.

Overview¶

Constants¶

• GATE_SPECS: dict[GateKind, GateSpec]

Functions¶

default_combine_symbolic [source]¶

def default_combine_symbolic(kind: 'BinOpKind', lhs: Any, rhs: Any) -> Any

Default combine_symbolic for backends with arithmetic-capable Parameters.

Performs Python operator dispatch on the operands. Used by evaluate_binop whenever the active emitter does not define its own combine_symbolic method — the typical case for Qiskit (ParameterExpression overloads __add__ etc.) and CUDA-Q parameters. Backends whose Parameter type lacks Python operators (e.g. QURI Parts) define their own combine_symbolic on the emitter class to return a backend-native symbolic representation instead.

Parameters:

Returns:

Any — lhs OP rhs for the matching operator. 0.0 / 0 for Any — division-by-zero in the symbolic path so the caller can finish Any — emission without aborting on a numerically degenerate case. Any — None for unrecognised kind values, which the caller Any — treats as a no-op.

Classes¶

BinOpKind [source]¶

class BinOpKind(enum.Enum)

Attributes¶

• ADD

• DIV

• FLOORDIV

• MIN

• MOD

• MUL

• POW

• SUB

GateEmitter [source]¶

class GateEmitter(Protocol[T])

Protocol for backend-specific gate emission.

Each backend implements this protocol to emit individual gates to their circuit representation.

Type parameter T is the backend’s circuit type (e.g., QuantumCircuit).

Attributes¶

• measurement_mode: MeasurementMode Return the measurement mode for this backend.

Methods¶

append_gate¶

def append_gate(self, circuit: T, gate: Any, qubits: list[int]) -> None

Append a gate to the circuit.

Parameters:

circuit_to_gate¶

def circuit_to_gate(self, circuit: T, name: str = 'U') -> Any

Convert a circuit to a reusable gate.

Parameters:

Returns:

Any — Backend-specific gate object, or None if not supported

create_circuit¶

def create_circuit(self, num_qubits: int, num_clbits: int) -> T

Create a new empty circuit.

Parameters:

Returns:

T — A new backend-specific circuit object

create_parameter¶

def create_parameter(self, name: str) -> Any

Create a symbolic parameter for the backend.

Parameters:

Returns:

Any — Backend-specific parameter object

emit_barrier¶

def emit_barrier(self, circuit: T, qubits: list[int]) -> None

Emit barrier on specified qubits.

emit_ch¶

def emit_ch(self, circuit: T, control: int, target: int) -> None

Emit controlled-Hadamard gate.

emit_cp¶

def emit_cp(self, circuit: T, control: int, target: int, angle: float | Any) -> None

Emit controlled-Phase gate.

emit_crx¶

def emit_crx(self, circuit: T, control: int, target: int, angle: float | Any) -> None

Emit controlled-RX gate.

emit_cry¶

def emit_cry(self, circuit: T, control: int, target: int, angle: float | Any) -> None

Emit controlled-RY gate.

emit_crz¶

def emit_crz(self, circuit: T, control: int, target: int, angle: float | Any) -> None

Emit controlled-RZ gate.

emit_cx¶

def emit_cx(self, circuit: T, control: int, target: int) -> None

Emit CNOT gate.

emit_cy¶

def emit_cy(self, circuit: T, control: int, target: int) -> None

Emit controlled-Y gate.

emit_cz¶

def emit_cz(self, circuit: T, control: int, target: int) -> None

Emit CZ gate.

emit_else_start¶

def emit_else_start(self, circuit: T, context: Any) -> None

Start the else branch.

emit_for_loop_end¶

def emit_for_loop_end(self, circuit: T, context: Any) -> None

End a native for loop context.

emit_for_loop_start¶

def emit_for_loop_start(self, circuit: T, indexset: range) -> Any

Start a native for loop context.

Returns a context manager or loop parameter, depending on backend.

emit_h¶

def emit_h(self, circuit: T, qubit: int) -> None

Emit Hadamard gate.

emit_if_end¶

def emit_if_end(self, circuit: T, context: Any) -> None

End the if/else block.

emit_if_start¶

def emit_if_start(self, circuit: T, clbit: int, value: int = 1) -> Any

Start a native if context.

Returns context for the if/else block.

emit_measure¶

def emit_measure(self, circuit: T, qubit: int, clbit: int) -> None

Emit measurement operation.

emit_p¶

def emit_p(self, circuit: T, qubit: int, angle: float | Any) -> None

Emit Phase gate (P(θ) = diag(1, e^(iθ))).

emit_rx¶

def emit_rx(self, circuit: T, qubit: int, angle: float | Any) -> None

Emit RX rotation gate.

Parameters:

emit_ry¶

def emit_ry(self, circuit: T, qubit: int, angle: float | Any) -> None

Emit RY rotation gate.

emit_rz¶

def emit_rz(self, circuit: T, qubit: int, angle: float | Any) -> None

Emit RZ rotation gate.

emit_rzz¶

def emit_rzz(self, circuit: T, qubit1: int, qubit2: int, angle: float | Any) -> None

Emit RZZ gate (exp(-i * θ/2 * Z⊗Z)).

emit_s¶

def emit_s(self, circuit: T, qubit: int) -> None

Emit S gate (√Z).

emit_sdg¶

def emit_sdg(self, circuit: T, qubit: int) -> None

Emit S-dagger gate (inverse of S).

emit_swap¶

def emit_swap(self, circuit: T, qubit1: int, qubit2: int) -> None

Emit SWAP gate.

emit_t¶

def emit_t(self, circuit: T, qubit: int) -> None

Emit T gate (√S).

emit_tdg¶

def emit_tdg(self, circuit: T, qubit: int) -> None

Emit T-dagger gate (inverse of T).

emit_toffoli¶

def emit_toffoli(self, circuit: T, control1: int, control2: int, target: int) -> None

Emit Toffoli (CCX) gate.

emit_while_end¶

def emit_while_end(self, circuit: T, context: Any) -> None

End the while loop context.

emit_while_start¶

def emit_while_start(self, circuit: T, clbit: int, value: int = 1) -> Any

Start a native while loop context.

emit_x¶

def emit_x(self, circuit: T, qubit: int) -> None

Emit Pauli-X gate.

emit_y¶

def emit_y(self, circuit: T, qubit: int) -> None

Emit Pauli-Y gate.

emit_z¶

def emit_z(self, circuit: T, qubit: int) -> None

Emit Pauli-Z gate.

gate_controlled¶

def gate_controlled(self, gate: Any, num_controls: int) -> Any

Create controlled version of a gate.

Parameters:

Returns:

Any — New controlled gate

gate_inverse¶

def gate_inverse(self, gate: Any) -> Any

Create a backend-native inverse gate when supported.

Parameters:

Returns:

Any — Backend-specific inverse gate object, or None when the Any — backend cannot invert reusable gates natively.

gate_power¶

def gate_power(self, gate: Any, power: int) -> Any

Create gate raised to a power (U^n).

Parameters:

Returns:

Any — New gate representing gate^power

supports_for_loop¶

def supports_for_loop(self) -> bool

Check if backend supports native for loops.

supports_gate_inverse¶

def supports_gate_inverse(self) -> bool

Return whether reusable gates can be inverted natively.

Returns:

bool — True when gate_inverse can return a backend-native inverse for gates produced by circuit_to_gate. Defaults to False.

supports_if_else¶

def supports_if_else(self) -> bool

Check if backend supports native if/else.

supports_reusable_gates¶

def supports_reusable_gates(self) -> bool

Return whether circuit_to_gate can produce reusable gates.

Returns:

bool — True when the backend can convert emitted sub-circuits to reusable gate objects. Defaults to False so emit paths can avoid building throwaway sub-circuits for backends that only support inline fallback emission.

supports_while_loop¶

def supports_while_loop(self) -> bool

Check if backend supports native while loops.

GateKind [source]¶

class GateKind(Enum)

Classification of gates for emission.

Attributes¶

• CH

• CP

• CRX

• CRY

• CRZ

• CX

• CY

• CZ

• H

• MEASURE

• P

• RX

• RY

• RZ

• RZZ

• S

• SDG

• SWAP

• T

• TDG

• TOFFOLI

• X

• Y

• Z

GateSpec [source]¶

class GateSpec

Specification for a gate type.

Constructor¶

def __init__(
    self,
    kind: GateKind,
    num_qubits: int,
    has_angle: bool = False,
    num_controls: int = 0,
) -> None

Attributes¶

• has_angle: bool

• kind: GateKind

• num_controls: int

• num_qubits: int

MeasurementMode [source]¶

class MeasurementMode(Enum)

How a backend handles measurement operations.

Attributes¶

• NATIVE

• RUNNABLE

• STATIC

qamomile.circuit.transpiler.job¶

Job classes for quantum execution results.

Overview¶

Classes¶

ExpvalJob [source]¶

class ExpvalJob(Job[float])

Job for expectation value computation.

Returns a single float representing <psi|H|psi>.

Constructor¶

def __init__(self, exp_val: float)

Initialize expval job.

Parameters:

Methods¶

result¶

def result(self) -> float

Return the expectation value.

status¶

def status(self) -> JobStatus

Return job status.

Job [source]¶

class Job(ABC, Generic[T])

Abstract base class for quantum execution jobs.

A Job represents a quantum execution that can be awaited for results.

Methods¶

result¶

def result(self) -> T

Wait for and return the result.

Blocks until the job completes.

Returns:

T — The execution result with the appropriate type.

Raises:

• ExecutionError — If the job failed.

status¶

def status(self) -> JobStatus

Return the current job status.

JobStatus [source]¶

class JobStatus(Enum)

Status of a quantum job.

Attributes¶

• COMPLETED

• FAILED

• PENDING

• RUNNING

RunJob [source]¶

class RunJob(Job[T], Generic[T])

Job for single execution.

Returns a single result value matching the kernel’s return type.

Constructor¶

def __init__(self, raw_counts: dict[str, int], result_converter: Callable[[str], T])

Initialize run job.

Parameters:

Methods¶

result¶

def result(self) -> T

Return the single result.

status¶

def status(self) -> JobStatus

Return job status.

SampleJob [source]¶

class SampleJob(Job[SampleResult[T]], Generic[T])

Job for sampling execution (multiple shots).

Returns a SampleResult containing counts for each unique result.

Constructor¶

def __init__(
    self,
    raw_counts: dict[str, int],
    result_converter: Callable[[dict[str, int]], list[tuple[T, int]]],
    shots: int,
)

Initialize sample job.

Parameters:

Methods¶

result¶

def result(self) -> SampleResult[T]

Return the sample result.

status¶

def status(self) -> JobStatus

Return job status.

SampleResult [source]¶

class SampleResult(Generic[T])

Result of a sample() execution.

Contains results as a list of (value, count) tuples.

Example:

result.results  # [(0.25, 500), (0.75, 500)]

Constructor¶

def __init__(self, results: list[tuple[T, int]], shots: int) -> None

Attributes¶

• results: list[tuple[T, int]] List of (value, count) tuples.

• shots: int Total number of shots executed.

Methods¶

most_common¶

def most_common(self, n: int = 1) -> list[tuple[T, int]]

Return the n most common results.

Parameters:

Returns:

list[tuple[T, int]] — List of (result, count) tuples sorted by count descending.

probabilities¶

def probabilities(self) -> list[tuple[T, float]]

Return probability distribution over results.

Returns:

list[tuple[T, float]] — List of (value, probability) tuples.

qamomile.circuit.transpiler.parameter_binding¶

Parameter binding structures for compiled quantum circuits.

Overview¶

Classes¶

ParameterInfo [source]¶

class ParameterInfo

Information about a single unbound parameter in the circuit.

Constructor¶

def __init__(
    self,
    name: str,
    array_name: str,
    index: int | None,
    backend_param: Any,
    source_ref: str | None = None,
) -> None

Attributes¶

• array_name: str

• backend_param: Any

• index: int | None

• name: str

• source_ref: str | None

ParameterMetadata [source]¶

class ParameterMetadata

Metadata for all parameters in a compiled segment.

Tracks parameter information for runtime binding.

Constructor¶

def __init__(self, parameters: list[ParameterInfo] = list()) -> None

Attributes¶

• parameters: list[ParameterInfo]

Methods¶

get_array_names¶

def get_array_names(self) -> set[str]

Get unique array/scalar parameter names.

get_ordered_params¶

def get_ordered_params(self) -> list[Any]

Get backend parameter objects in definition order.

Useful for backends that require positional parameter binding (e.g., QURI Parts).

Returns:

list[Any] — List of backend_param objects in the order they were defined.

Example:

# For QURI Parts that uses positional binding:
param_values = [bindings[p.name] for p in metadata.parameters]
bound_circuit = circuit.bind_parameters(param_values)

get_param_by_name¶

def get_param_by_name(self, name: str) -> ParameterInfo | None

Get parameter info by full name.

to_binding_dict¶

def to_binding_dict(self, bindings: dict[str, Any]) -> dict[Any, Any]

Convert indexed bindings to backend parameter bindings.

Transforms user-provided bindings (with indexed names like “gammas[0]”) into a dictionary mapping backend parameter objects to values. Useful for backends that use dict-based parameter binding (e.g., Qiskit).

Parameters:

Returns:

dict[Any, Any] — Dictionary mapping backend_param objects to values.

Example:

# For Qiskit that uses dict-based binding:
qiskit_bindings = metadata.to_binding_dict(bindings)
bound_circuit = circuit.assign_parameters(qiskit_bindings)

qamomile.circuit.transpiler.passes¶

Base classes for compiler passes.

Overview¶

Classes¶

AffineTypeError [source]¶

class AffineTypeError(QamomileCompileError)

Base class for affine type violations.

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

Constructor¶

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

Attributes¶

• first_use_location

• handle_name

• operation_name

AffineValidationPass [source]¶

class AffineValidationPass(Pass[Block, Block])

Validate affine type semantics at IR level.

This pass serves as a safety net to catch affine type violations that may have bypassed the frontend checks. It verifies:

1. Each quantum value is used (consumed) at most once

2. Quantum values are not silently discarded

Input: Block (any kind) Output: Same Block (unchanged, validation only)

Attributes¶

• name: str

Methods¶

run¶

def run(self, input: Block) -> Block

Validate affine type semantics in the block.

Raises:

• ValidationError — If the block kind is not AFFINE.

• AffineTypeError — If a quantum value is consumed multiple times.

CompileTimeIfLoweringPass [source]¶

class CompileTimeIfLoweringPass(Pass[Block, Block])

Lowers compile-time resolvable IfOperations before separation.

After constant folding, some IfOperation conditions are statically known but remain as control-flow nodes. SegmentationPass treats them as segment boundaries, causing MultipleQuantumSegmentsError for classical-only compile-time if after quantum init.

This pass:

1. Evaluates conditions including expression-derived ones (CompOp, CondOp, NotOp chains).

2. Replaces resolved IfOperations with selected-branch operations.

3. Substitutes phi output UUIDs with selected-branch values in all subsequent operations and block outputs.

Constructor¶

def __init__(self, bindings: dict[str, Any] | None = None)

Attributes¶

• name: str

Methods¶

run¶

def run(self, input: Block) -> Block

Run the compile-time if lowering pass.

ConstantFoldingPass [source]¶

class ConstantFoldingPass(Pass[Block, Block])

Evaluates constant expressions at compile time.

This pass folds BinOp operations when all operands are constants or bound parameters, eliminating unnecessary classical operations that would otherwise split quantum segments.

Example:

Before (with bindings={"phase": 0.5}):
    BinOp(phase * 2) -> classical segment split

After:
    Constant 1.0 -> no segment split

Constructor¶

def __init__(self, bindings: dict[str, Any] | None = None, *, strip_slice_ops: bool = True)

Create a constant-folding pass.

Parameters:

Attributes¶

• name: str

Methods¶

run¶

def run(self, input: Block) -> Block

Run constant folding on the block.

ControlFlowVisitor [source]¶

class ControlFlowVisitor(ABC)

Base class for visiting operations with control flow handling.

Subclasses override visit_operation to define per-operation behavior. Control flow recursion is handled automatically by the base class.

Example:

class MeasurementCounter(ControlFlowVisitor):
    def __init__(self):
        self.count = 0

    def visit_operation(self, op: Operation) -> None:
        if isinstance(op, MeasureOperation):
            self.count += 1

Methods¶

visit_operation¶

def visit_operation(self, op: Operation) -> None

Process a single operation. Override in subclasses.

visit_operations¶

def visit_operations(self, operations: list[Operation]) -> None

Visit all operations including nested control flow.

DependencyError [source]¶

class DependencyError(QamomileCompileError)

Error when quantum operation depends on non-parameter classical value.

This error indicates that the program requires JIT compilation which is not yet supported.

Constructor¶

def __init__(
    self,
    message: str,
    quantum_op: str | None = None,
    classical_value: str | None = None,
)

Attributes¶

• classical_value

• quantum_op

OperationCollector [source]¶

class OperationCollector(ControlFlowVisitor)

Collects operations matching a predicate.

Example:

collector = OperationCollector(lambda op: isinstance(op, MeasureOperation))
collector.visit_operations(block.operations)
measurements = collector.collected

Constructor¶

def __init__(self, predicate: Callable[[Operation], bool])

Attributes¶

• collected: list[Operation]

Methods¶

visit_operation¶

def visit_operation(self, op: Operation) -> None

OperationTransformer [source]¶

class OperationTransformer(ABC)

Base class for transforming operations with control flow handling.

Subclasses override transform_operation to define per-operation transformation. Control flow recursion and rebuilding is handled automatically.

Example:

class OperationRenamer(OperationTransformer):
    def transform_operation(self, op: Operation) -> Operation:
        # Return modified operation
        return dataclasses.replace(op, ...)

Methods¶

transform_operation¶

def transform_operation(self, op: Operation) -> Operation | None

Transform a single operation. Return None to remove it.

transform_operations¶

def transform_operations(self, operations: list[Operation]) -> list[Operation]

Transform all operations including nested control flow.

Pass [source]¶

class Pass(ABC, Generic[InputT, OutputT])

Base class for all compiler passes.

Attributes¶

• name: str Human-readable name for this pass.

Methods¶

run¶

def run(self, input: InputT) -> OutputT

Execute the pass transformation.

QamomileCompileError [source]¶

class QamomileCompileError(Exception)

Base class for all Qamomile compilation errors.

SliceBorrowCheckPass [source]¶

class SliceBorrowCheckPass(Pass[Block, Block])

Post-fold linearity checker for sliced views and borrow state.

Runs after :class:ConstantFoldingPass (so slice bounds are concrete where possible) and before segmentation / emit. Walks the operations of the root block in order, maintaining a borrow state map modelled on the frontend’s :attr:ArrayBase._borrowed_indices — a single dict whose values are slice-view ArrayValue owners or the _ConsumedSlotMarker sentinel. Direct element borrows (q[i]) emit no IR operation and are left to the trace-time validator.

The pass does not flag a leftover slice view at block end — slice views are affine at the kernel boundary, mirroring how element borrows behave on a locally-allocated register (the frontend’s _validate_returned_arrays covers the genuine leak: returning the parent with a live borrow). Anything that actually clashes with a live view (direct slot access, destructive parent consume, overlapping views, use-after- destroy) is rejected at the eager check points listed in the module docstring.

Constructor¶

def __init__(self) -> None

Initialize per-run mutable state to safe defaults.

Attributes¶

• name: str Return the pass identifier for tracing/logging.

Methods¶

run¶

def run(self, input: Block) -> Block

Run the borrow tracker over input.

Parameters:

Returns:

Block — The same Block unchanged (pass-through).

Raises:

• ValidationError — If called on an unexpected block kind.

• SliceBorrowViolationError — If a slice view and a direct access collide, two views overlap, or a use-after- destroy is observed.

UUIDRemapper [source]¶

class UUIDRemapper

Clones values and operations with fresh UUIDs and logical_ids.

Used during inlining to create unique identities for values when a block is called multiple times.

Constructor¶

def __init__(self)

Attributes¶

• logical_id_remap: dict[str, str] Get the mapping from old logical_ids to new logical_ids.

• uuid_remap: dict[str, str] Get the mapping from old UUIDs to new UUIDs.

Methods¶

clone_operation¶

def clone_operation(self, op: Operation) -> Operation

Clone an operation with fresh UUIDs for all values.

Cloning goes through the Operation.all_input_values() / Operation.replace_values() protocol so every Value-typed field — including subclass extras (ControlledUOperation.power, ForOperation.loop_var_value, ForItemsOperation.key_var_values etc.) — is cloned consistently with the body references that point to it. Without this, a subclass field could keep an old UUID while body operands referencing the same logical Value got fresh UUIDs, breaking identity-by-UUID lookups at emit time.

Parameters:

Returns:

Operation — A clone of op with every owned Value (operands, results, subclass-extra fields) and every nested-body Value reassigned a fresh UUID / logical_id, and with CastOperation.qubit_mapping carrier keys remapped.

clone_operations¶

def clone_operations(self, operations: list[Operation]) -> list[Operation]

Clone a list of operations with fresh UUIDs.

Parameters:

Returns:

list[Operation] — list[Operation]: Cloned operations, each with fresh UUIDs, in the same order as operations.

clone_value¶

def clone_value(self, value: ValueBase) -> ValueBase

Clone any value type with a fresh UUID and logical_id.

Handles Value, ArrayValue, TupleValue, and DictValue through the unified ValueBase protocol. Nested values (tuple elements, dict entries, parent_array / element_indices / shape / slice fields) and embedded metadata references are cloned consistently. Results are cached by source UUID so a repeated clone returns the same instance.

Parameters:

Returns:

ValueBase — The cloned value of the same concrete type, with a fresh UUID / logical_id and its nested values and metadata references remapped through this remapper.

ValidateWhileContractPass [source]¶

class ValidateWhileContractPass(Pass[Block, Block])

Validates that all WhileOperation conditions are measurement-backed.

Builds a producer map (result UUID → producing Operation instance) and checks every WhileOperation operand against it. A valid condition must be:

1. A Value with BitType

2. Measurement-backed: produced by MeasureOperation directly, or by IfOperation / PhiOp where every reachable leaf source is itself measurement-backed.

Both operands[0] (initial condition) and operands[1] (loop-carried condition) are validated.

Raises ValidationError for any non-measurement while pattern.

Attributes¶

• name: str

Methods¶

run¶

def run(self, block: Block) -> Block

Validate all WhileOperations and return block unchanged.

ValidationError [source]¶

class ValidationError(QamomileCompileError)

Error during validation (e.g., non-classical I/O).

Constructor¶

def __init__(self, message: str, value_name: str | None = None)

Attributes¶

• value_name

ValueCollector [source]¶

class ValueCollector(ControlFlowVisitor)

Collects Value UUIDs from operation operands and results.

Constructor¶

def __init__(self)

Attributes¶

• operand_uuids: set[str]

• result_uuids: set[str]

Methods¶

visit_operation¶

def visit_operation(self, op: Operation) -> None

qamomile.circuit.transpiler.passes.affine_validate¶

Affine type validation pass: Verify quantum resources are used correctly.

Overview¶

Classes¶

AffineTypeError [source]¶

class AffineTypeError(QamomileCompileError)

Base class for affine type violations.

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

Constructor¶

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

Attributes¶

• first_use_location

• handle_name

• operation_name

AffineValidationPass [source]¶

class AffineValidationPass(Pass[Block, Block])

Validate affine type semantics at IR level.

This pass serves as a safety net to catch affine type violations that may have bypassed the frontend checks. It verifies:

1. Each quantum value is used (consumed) at most once

2. Quantum values are not silently discarded

Input: Block (any kind) Output: Same Block (unchanged, validation only)

Attributes¶

• name: str

Methods¶

run¶

def run(self, input: Block) -> Block

Validate affine type semantics in the block.

Raises:

• ValidationError — If the block kind is not AFFINE.

• AffineTypeError — If a quantum value is consumed multiple times.

Block [source]¶

class Block

Unified block representation for all pipeline stages.

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

Constructor¶

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

Attributes¶

• input_values: list[Value]

• kind: BlockKind

• label_args: list[str]

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[Value]

• param_slots: tuple[ParamSlot, ...]

• parameters: dict[str, Value]

Methods¶

call¶

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

Create a CallBlockOperation against this block.

is_affine¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

BlockKind [source]¶

class BlockKind(Enum)

Classification of block structure for pipeline stages.

Attributes¶

• AFFINE

• ANALYZED

• HIERARCHICAL

• TRACED

HasNestedOps [source]¶

class HasNestedOps

Mixin for operations that contain nested operation lists.

Subclasses implement nested_op_lists() and rebuild_nested() so that generic passes can recurse into control flow without isinstance chains.

Methods¶

nested_op_lists¶

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

Return all nested operation lists in this control flow op.

rebuild_nested¶

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

Return a copy with nested operation lists replaced.

new_lists must have the same length/order as nested_op_lists().

IfOperation [source]¶