qamomile.circuit.ir

Public surface for the Qamomile IR package.

Re-exports the contributor-facing debugging and canonical-form helpers so callers can use the short form from qamomile.circuit.ir import pretty_print_block or from qamomile.circuit.ir import canonicalize.

Overview¶

Functions¶

canonicalize [source]¶

def canonicalize(block: Block) -> Block

Return a canonical-form clone of block.

The returned Block has the same structure as block but with every Value UUID and logical_id re-issued from a deterministic counter. All UUID references inside operations and value metadata are rewritten consistently. Block.kind is preserved.

Parameters:

Returns:

Block — A new Block with canonical UUIDs. Block.kind matches the input. Existing input/output ordering, operation ordering, metadata structure, and the param_slots manifest (carried over verbatim) are preserved.

Raises:

• ValueError — If block.kind is not in {AFFINE, ANALYZED}, or if a loop operation’s region arguments violate the SSA identity invariants (see :func:validate_region_args).

• NotImplementedError — If an unsupported operation is encountered.

Example:

>>> from qamomile.qiskit import QiskitTranspiler
>>> transpiler = QiskitTranspiler()
>>> affine = transpiler.inline(transpiler.to_block(my_kernel))
>>> canon = canonicalize(affine)
>>> canon.kind is affine.kind
True

canonicalize_and_remap [source]¶

def canonicalize_and_remap(block: Block) -> tuple[Block, dict[str, str], dict[str, str]]

Return canonical-form Block plus the UUID and logical_id remap tables.

Useful when the caller holds external references keyed on the original Value UUIDs or logical_ids (e.g., a host-side port map) and needs to update those references to match the canonical form.

Parameters:

Returns:

tuple[Block, dict[str, str], dict[str, str]] — tuple[Block, dict[str, str], dict[str, str]]: A triple (canonical_block, uuid_remap, logical_id_remap) where each remap maps every original identifier encountered during the walk to its canonical counterpart. uuid and logical_id share the same monotonic counter but are tracked in separate maps.

Raises:

• ValueError — If block.kind is not in {AFFINE, ANALYZED}, or if a loop operation’s region arguments violate the SSA identity invariants (see :func:validate_region_args).

• NotImplementedError — If an unsupported operation is encountered.

content_hash [source]¶

def content_hash(block: Block) -> str

Compute a content-addressable hash of block.

Two Blocks that canonicalize to the same form (structurally equal after UUID remapping) produce the same hash. Any IR-level change (gate added, parameter renamed, operand reordered) produces a different hash.

Parameters:

Returns:

str — The SHA-256 hex digest of to_canonical_bytes(block).

Raises:

• ValueError — If block.kind is not in {AFFINE, ANALYZED}.

Example:

>>> h1 = content_hash(canonicalize(affine_a))
>>> h2 = content_hash(canonicalize(affine_b))
>>> # If the two kernels are structurally identical, h1 == h2.

format_value [source]¶

def format_value(value: Any) -> str

Format an IR value reference as %name@vN.

Handles Value, ArrayValue, TupleValue, DictValue, and array-element Values (rendered as %parent[i]@vN). Constants and parameters are shown with their tagged metadata when available. Falls back to repr() for unrecognised inputs so callers can use this helper for any operand-like field without a type switch.

pretty_print_block [source]¶

def pretty_print_block(block: Block, *, depth: int = 0) -> str

Return a MLIR-style textual dump of block.

Parameters:

Returns:

str — A newline-separated string. The format is for human debugging and str — is not guaranteed to be stable across releases.

to_canonical_bytes [source]¶

def to_canonical_bytes(block: Block) -> bytes

Serialize block to a deterministic byte representation.

The byte format is the internal representation backing content_hash and is not stable across qamomile versions. It is suitable for hashing and equality checks within a single deployment but should not be relied upon as a serialization format. (A stable, versioned serialization format is tracked separately.)

Parameters:

Returns:

bytes — A UTF-8-encoded byte string. Two structurally-equal Blocks produce the same bytes; changing the IR yields different bytes.

Raises:

• ValueError — If block.kind is not in {AFFINE, ANALYZED}.

Classes¶

KernelEffect [source]¶

class KernelEffect(enum.Flag)

Describe non-unitary behavior reachable from a kernel body.

KernelEffect.NONE is the empty effect set and denotes unitary behavior. Flags compose with bitwise union so one kernel can expose measurement, reset, and measurement-backed feed-forward together.

Attributes¶

• FEED_FORWARD

• MEASUREMENT

• NONE

• RESET

• is_unitary: bool Return whether this is the empty effect set.

Methods¶

labels¶

def labels(self) -> tuple[str, ...]

Return stable effect names for diagnostics and serialization.

Returns:

tuple[str, ...] — tuple[str, ...]: Active flag names in declaration order.

qamomile.circuit.ir.block¶

Unified block representation for all pipeline stages.

Overview¶

Constants¶

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

Functions¶

collect_value_like_uuids [source]¶

def collect_value_like_uuids(value: 'ValueLike') -> set[str]

Collect UUIDs contained in a value-like IR object.

Parameters:

Returns:

set[str] — set[str]: UUIDs for value itself, recursively contained tuple/dict elements, and array view/element dependencies.

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[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

InvokeOperation [source]¶

class InvokeOperation(Operation)

Represent a composite, stdlib, or oracle call.

Parameters:

Constructor¶

def __init__(
    self,
    operands: Sequence[ValueLike] | None = None,
    results: Sequence[ValueLike] | None = None,
    *,
    target: CallableRef | None = None,
    transform: CallTransform = CallTransform.DIRECT,
    attrs: dict[str, Any] | None = None,
    definition: CallableDef | None = None,
) -> None

Initialize an invocation operation.

Parameters:

Raises:

• TypeError — If a controlled invocation’s control_value or an Oracle control-partition field has an invalid Python type.

• ValueError — If control_value is used on a non-controlled call or does not fit the controlled invocation’s width, or if Oracle invocation and definition control metadata disagree.

Attributes¶

• attrs: dict[str, Any]

• body: Block | None Return the callable’s default body from its definition.

• body_ref: CallableBodyRef | None Return the callable’s deferred body reference.

• control_qubits: list[‘Value’] Return the control-qubit operands.

• control_value: int | None Return the controlled invocation’s activation value.

• custom_name: str Return the display name for custom callable boxes.

• default_policy: CallPolicy Return the callable’s default lowering policy.

• definition: CallableDef | None

• effects: ‘KernelEffect’ Return cached effects of relevant callable implementations.

• gate_type: CompositeGateType Return the standard composite classification for this invocation.

• measurement_result_indices: frozenset[int] Return a conservative union of measurement-derived results.

• name: str Return the display name for this invocation.

• num_added_control_qubits: int Return controls introduced by a frontend control transform.

• num_body_external_control_qubits: int Return control operands generic lowering adds outside a base body.

• num_control_qubits: int Return the number of leading control-qubit operands.

• num_declared_control_qubits: int Return controls included in an opaque Oracle’s base definition.

• num_target_qubits: int Return the number of target-qubit operands.

• operands

• operation_kind: OperationKind Return the operation kind.

• parameters: list[‘Value’] Return non-qubit parameter operands.

• results

• signature: Signature Return the operation signature.

• strategy_name: str | None Return the selected lowering/resource strategy name.

• target: CallableRef

• target_qubits: list[‘Value’] Return the target-qubit operands.

• transform: CallTransform

Methods¶

body_for_transform¶

def body_for_transform(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
) -> tuple[Block | None, CallTransform]

Select a body and report the transform it already realizes.

A controlled-inverse invocation may reuse an explicitly registered inverse body when no implementation realizes both transforms. Keeping that fallback in the IR operation gives emitters and static analyses one selection rule while still letting each consumer apply the remaining coherent controls in its own representation.

Parameters:

Returns:

Block | None — tuple[Block | None, CallTransform]: Selected body and the transform CallTransform — already implemented by that body. The callable’s direct body is tuple[Block | None, CallTransform] — returned with DIRECT when no transform-specific body matches.

Raises:

• ValueError — If the selected body disagrees with the invocation’s input or output contract.

effective_body¶

def effective_body(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
) -> Block | None

Return the implementation body selected for this invocation.

Parameters:

Returns:

Block | None — Block | None: Selected implementation body, or the callable’s Block | None — default body when no transform-specific implementation exists. Block | None — A compiler may synthesize inverse or controlled behavior from this Block | None — fallback body.

implementation_for¶

def implementation_for(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
    require_body: bool = False,
) -> CallableImplementation | None

Return the selected implementation for this invocation.

Parameters:

Returns:

CallableImplementation | None — CallableImplementation | None: Matching implementation candidate, CallableImplementation | None — or None when the callable definition has no match.

measurement_result_indices_for¶

def measurement_result_indices_for(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
) -> frozenset[int]

Return measurement-derived results for one selected implementation.

Parameters:

Returns:

frozenset[int] — frozenset[int]: Caller-local result positions derived from measurement in the selected body.

Raises:

• ValueError — If the selected body disagrees with the invocation’s input or output contract.

select_body¶

def select_body(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
) -> CallableBodySelection

Select and validate the composable body for this invocation.

The result carries the transform already realized by the body and the exact call-site values that bind to it. Consumers therefore cannot independently disagree about whether an invocation’s control prefix belongs to the selected implementation ABI.

Parameters:

Returns:

CallableBodySelection — Validated body, realized transform, and CallableBodySelection — aligned call-site operands and results.

Raises:

• ValueError — If the selected body disagrees with the invocation’s input or output contract.

KernelEffect [source]¶

class KernelEffect(enum.Flag)

Describe non-unitary behavior reachable from a kernel body.

KernelEffect.NONE is the empty effect set and denotes unitary behavior. Flags compose with bitwise union so one kernel can expose measurement, reset, and measurement-backed feed-forward together.

Attributes¶

• FEED_FORWARD

• MEASUREMENT

• NONE

• RESET

• is_unitary: bool Return whether this is the empty effect set.

Methods¶

labels¶

def labels(self) -> tuple[str, ...]

Return stable effect names for diagnostics and serialization.

Returns:

tuple[str, ...] — tuple[str, ...]: Active flag names in declaration order.

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’

StaticBindingSlot [source]¶

class StaticBindingSlot

Declare one typed compile-time object required by a qkernel.

The object itself is not an SSA value and never reaches a backend. Only registered scalar projections and deferred callable-member references may appear in the hierarchical body. A build must resolve the slot before the block advances to a compiler stage.

Parameters:

Constructor¶

def __init__(
    self,
    name: str,
    type_key: str,
    fields: tuple[StaticBindingField, ...] = (),
) -> None

Attributes¶

• fields: tuple[StaticBindingField, ...]

• name: str

• type_key: str

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.ir.canonical¶

Canonical form for IR blocks: deterministic UUIDs and content hashing.

This module provides a normalization pass that re-numbers every Value UUID (and logical_id) in a Block from a deterministic counter, rewriting every UUID reference embedded in operations and value metadata so the resulting Block is structurally invariant across independent builds of the same kernel.

The canonical form is intended for IR-level equality checks, debugging diffs, and a content-addressable identity (content_hash) suitable for caching and (later) for serialization keyed on IR contents rather than build-local Python state.

Supported scope:

Only BlockKind.AFFINE and BlockKind.ANALYZED are accepted. HIERARCHICAL Blocks may still contain inline-policy InvokeOperations that reference nested Blocks before inlining; canonical treatment for those pre-inline references is deferred (see backlog [IR design] Add named/versioned module references for cross-process kernel composition).

Output guarantees:

1. canonicalize does not change Block.kind; it is a normalization, not a pipeline stage advance.

2. For two builds of the same kernel that produce structurally identical IR, canonicalize returns Blocks that are equal under to_canonical_bytes (and therefore under content_hash).

3. canonicalize is idempotent: running it twice on the same Block yields the same canonical bytes as running it once.

Canonical-bytes scope:

Display-only fields (Block.name, Block.output_names, Value.name) are excluded from to_canonical_bytes; functional fields are included. Block.label_args (input port names by position) and Block.param_slots (the kernel’s classical parameter contract) are both functional: two Blocks whose operations match but whose parameter manifests differ (e.g., a slot rebound from RUNTIME_PARAMETER to COMPILE_TIME_BOUND) hash differently. param_slots holds no Value/UUID references, so canonicalize carries the tuple over verbatim with nothing to remap.

Limitations:

• Value.parent_array cycles (a Value whose parent_array is itself reachable from the Value’s siblings) are not constructed by the frontend today; the canonicalizer assumes the Value-reference graph through parent_array and element_indices is acyclic.

• ValueMetadata.dict_runtime.bound_data, ArrayRuntimeMetadata.const_array, and ParamSlot.default / ParamSlot.bound_value may carry arbitrary frozen Python data. Every payload type the wire format supports is hashed structurally: numpy.ndarray (except object-dtype arrays) from its raw buffer (dtype + shape + bytes), numpy scalars via their Python value, bytes via a digest, complex via its components, and Hamiltonian via its term structure (order-independent, matching Hamiltonian.__eq__ plus the declared register width). Only object types outside that set fall back to repr and therefore require a stable repr for the hash to be reliable.

Overview¶

Constants¶

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

Functions¶

canonicalize [source]¶

def canonicalize(block: Block) -> Block

Return a canonical-form clone of block.

The returned Block has the same structure as block but with every Value UUID and logical_id re-issued from a deterministic counter. All UUID references inside operations and value metadata are rewritten consistently. Block.kind is preserved.

Parameters:

Returns:

Block — A new Block with canonical UUIDs. Block.kind matches the input. Existing input/output ordering, operation ordering, metadata structure, and the param_slots manifest (carried over verbatim) are preserved.

Raises:

• ValueError — If block.kind is not in {AFFINE, ANALYZED}, or if a loop operation’s region arguments violate the SSA identity invariants (see :func:validate_region_args).

• NotImplementedError — If an unsupported operation is encountered.

Example:

>>> from qamomile.qiskit import QiskitTranspiler
>>> transpiler = QiskitTranspiler()
>>> affine = transpiler.inline(transpiler.to_block(my_kernel))
>>> canon = canonicalize(affine)
>>> canon.kind is affine.kind
True

canonicalize_and_remap [source]¶

def canonicalize_and_remap(block: Block) -> tuple[Block, dict[str, str], dict[str, str]]

Return canonical-form Block plus the UUID and logical_id remap tables.

Useful when the caller holds external references keyed on the original Value UUIDs or logical_ids (e.g., a host-side port map) and needs to update those references to match the canonical form.

Parameters:

Returns:

tuple[Block, dict[str, str], dict[str, str]] — tuple[Block, dict[str, str], dict[str, str]]: A triple (canonical_block, uuid_remap, logical_id_remap) where each remap maps every original identifier encountered during the walk to its canonical counterpart. uuid and logical_id share the same monotonic counter but are tracked in separate maps.

Raises:

• ValueError — If block.kind is not in {AFFINE, ANALYZED}, or if a loop operation’s region arguments violate the SSA identity invariants (see :func:validate_region_args).

• NotImplementedError — If an unsupported operation is encountered.

collect_reachable_values [source]¶

def collect_reachable_values(block: Block) -> tuple[ValueBase, ...]

Collect values reachable from an IR block in canonical walk order.

The traversal includes values referenced by operation-owned nested blocks and returns each value UUID at most once. Its ordering is the same stable ordering used by canonical byte emission.

Parameters:

Returns:

tuple[ValueBase, ...] — tuple[ValueBase, ...]: Reachable values in deterministic canonical declaration order.

content_fingerprint [source]¶

def content_fingerprint(obj: Any) -> str

Compute a deterministic fingerprint for supported lowered IR content.

Unlike the legacy canonical content_hash encoder, this function rejects values that would require a repr fallback. Its accepted values are the stable scalar, collection, enum, array, Hamiltonian, type, and dataclass forms used by lowered circuit programs.

Parameters:

Returns:

str — SHA-256 hexadecimal digest of the structural content token.

Raises:

• TypeError — If obj contains a value without a stable structural encoding.

content_hash [source]¶

def content_hash(block: Block) -> str

Compute a content-addressable hash of block.

Two Blocks that canonicalize to the same form (structurally equal after UUID remapping) produce the same hash. Any IR-level change (gate added, parameter renamed, operand reordered) produces a different hash.

Parameters:

Returns:

str — The SHA-256 hex digest of to_canonical_bytes(block).

Raises:

• ValueError — If block.kind is not in {AFFINE, ANALYZED}.

Example:

>>> h1 = content_hash(canonicalize(affine_a))
>>> h2 = content_hash(canonicalize(affine_b))
>>> # If the two kernels are structurally identical, h1 == h2.

hamiltonian_to_dict [source]¶

def hamiltonian_to_dict(h: Hamiltonian) -> dict[str, Any]

Encode a Hamiltonian into the wrapper dict.

Terms are emitted in the Hamiltonian’s own term-dict iteration order; each term is a [operators, coefficient] pair where operators is a list of [pauli_name, qubit_index] entries.

Parameters:

Returns:

dict[str, Any] — dict[str, Any]: A wrapper dict with $hamiltonian, terms, constant, and num_qubits (the declared register width passed to the constructor, or None).

Raises:

• TypeError — If h is not a Hamiltonian, if a coefficient / the constant is not int, float, or complex, or if the declared num_qubits is not an int — all after coercing any numpy scalar to its Python equivalent.

• ValueError — If the declared num_qubits is negative.

remap_indexed_identifier [source]¶

def remap_indexed_identifier(identifier: str, remap_identifier: Callable[[str], str]) -> str

Remap an identifier while preserving a legacy index suffix.

Parameters:

Returns:

str — Remapped identifier. Numeric index suffixes are preserved after remapping the base identifier.

remap_value_metadata_references [source]¶

def remap_value_metadata_references(
    metadata: ValueMetadata,
    remap_uuid: Callable[[str], str],
    remap_logical_id: Callable[[str], str],
) -> ValueMetadata

Rewrite UUID and logical-id references inside value metadata.

Parameters:

Returns:

ValueMetadata — Metadata with every embedded UUID / logical-id reference rewritten. Legacy "<uuid>_<index>" carrier keys keep their index suffix while remapping the base UUID. The original bundle is returned unchanged when no reference is rewritten.

to_canonical_bytes [source]¶

def to_canonical_bytes(block: Block) -> bytes

Serialize block to a deterministic byte representation.

The byte format is the internal representation backing content_hash and is not stable across qamomile versions. It is suitable for hashing and equality checks within a single deployment but should not be relied upon as a serialization format. (A stable, versioned serialization format is tracked separately.)

Parameters:

Returns:

bytes — A UTF-8-encoded byte string. Two structurally-equal Blocks produce the same bytes; changing the IR yields different bytes.

Raises:

• ValueError — If block.kind is not in {AFFINE, ANALYZED}.

validate_region_args [source]¶

def validate_region_args(op: ForOperation | ForItemsOperation | WhileOperation) -> tuple[RegionArg, ...]

Validate the SSA identities owned by a loop’s region arguments.

A loop owns several definition namespaces: its iteration variables, every RegionArg.block_arg, and every RegionArg.result. Those identities must be pairwise disjoint. Otherwise different stages can assign incompatible meanings to one UUID: a UUID-keyed environment has only one slot, so binding either the iteration variable or the carried value overwrites the other and makes both reads observe the same value.

Parameters:

Returns:

tuple[RegionArg, ...] — tuple[RegionArg, ...]: The validated op.region_args tuple.

Raises:

• ValueError — If result counts or positions disagree, slot types differ, or any loop-owned definition identity collides with another definition or with a region initializer/body yield.

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]

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

BranchRebind [source]¶

class BranchRebind

Trace-time record of a quantum variable rebound inside an if branch.

The frontend’s branch tracing merges only the new branch values through merge operations; when both branches rebind a variable, the value the variable held before the branch no longer appears anywhere in the IfOperation. These records preserve that pre-branch binding so the transpiler’s control-flow discard check (reject_control_flow_quantum_discard in qamomile.circuit.transpiler.passes.analyze) can verify that the pre-branch quantum state is consumed or carried on every runtime execution path instead of being silently dropped.

Constructor¶

def __init__(
    self,
    var_name: str,
    before: Value,
    rebound_in_true: bool,
    rebound_in_false: bool,
) -> None

Attributes¶

• before: Value

• rebound_in_false: bool

• rebound_in_true: bool

• var_name: str

CastOperation [source]¶

class CastOperation(Operation)

Type cast operation for creating aliases over the same quantum resources.

This operation does NOT allocate new qubits. It creates a new Value that references the same underlying quantum resources with a different type.

Use cases:

• Vector[Qubit] -> QFixed (after QPE, for phase measurement)

• Vector[Qubit] -> QUInt (for quantum arithmetic)

• QUInt -> QFixed (reinterpret bits with different encoding)

• QFixed -> QUInt (reinterpret bits with different encoding)

operands: [source_value] - The value being cast results: [cast_result] - The new value with target type (same physical qubits)

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    source_type: ValueType | None = None,
    target_type: ValueType | None = None,
    qubit_mapping: list[str] = list(),
) -> None

Attributes¶

• num_qubits: int Number of qubits involved in the cast.

• operation_kind: OperationKind Cast stays in the same segment as its source (QUANTUM for quantum types).

• qubit_mapping: list[str]

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

• source_type: ValueType | None

• target_type: ValueType | None

ControlledUOperation [source]¶

class ControlledUOperation(Operation)

Base class for controlled-U operations.

Two concrete subclasses handle distinct operand layouts:

• ConcreteControlledU: Fixed num_controls: int, individual qubit operands.

• SymbolicControlledU: Symbolic num_controls: Value, vector-based control operands; optional control_indices selects a subset of the control vector to act as controls (the rest pass through).

All isinstance(op, ControlledUOperation) checks match every subclass.

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    power: int | Value = 1,
    block: Block | None = None,
    num_controls: int | Value = 1,
    callable_ref: CallableRef | None = None,
    callable_attrs: dict[str, Any] = dict(),
) -> None

Attributes¶

• block: Block | None

• body_operands: list[Value] Get the wrapped callable’s complete argument list.

• callable_attrs: dict[str, Any]

• callable_ref: CallableRef | None

• control_operands: list[Value] Get the control qubit values.

• is_symbolic_num_controls: bool Whether num_controls is symbolic (Value) rather than concrete.

• num_controls: int | Value

• operation_kind: OperationKind

• param_operands: list[Value] Get the controlled operation’s classical/object arguments.

• power: int | Value

• signature: Signature

• target_operands: list[Value] Get the target qubit values (arguments to U).

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

replace_values¶

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

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

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(),
    loop_carried_rebinds: tuple[LoopCarriedRebind, ...] = (),
    region_args: tuple[RegionArg, ...] = (),
    captures: tuple[ValueBase, ...] = (),
) -> None

Attributes¶

• captures: tuple[ValueBase, ...]

• key_is_vector: bool

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

• key_vars: list[str]

• loop_carried_rebinds: tuple[LoopCarriedRebind, ...]

• operation_kind: OperationKind

• operations: list[Operation]

• region_args: tuple[RegionArg, ...]

• 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. Loop-carried rebind records and region arguments are included for the same reason.

nested_op_lists¶

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

nested_regions¶

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

Return the items-loop body with its explicit interface.

Returns:

tuple[Region, ...] — tuple[Region, ...]: One body region containing key/value formals, carried-value formals, captures, and carried yields.

rebuild_nested¶

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

rebuild_regions¶

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

Rebuild the items-loop body and complete boundary interface.

Parameters:

Returns:

Operation — Rebuilt items-loop operation.

Raises:

• ValueError — If arity or boundary value kinds are inconsistent.

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(),
    loop_carried_rebinds: tuple[LoopCarriedRebind, ...] = (),
    region_args: tuple[RegionArg, ...] = (),
    captures: tuple[ValueBase, ...] = (),
) -> None

Attributes¶

• captures: tuple[ValueBase, ...]

• loop_carried_rebinds: tuple[LoopCarriedRebind, ...]

• loop_var: str

• loop_var_value: Value | None

• operation_kind: OperationKind

• operations: list[Operation]

• region_args: tuple[RegionArg, ...]

• 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. Loop-carried rebind records and region arguments are included for the same reason.

nested_op_lists¶

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

nested_regions¶

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

Return the range-loop body with its explicit interface.

Returns:

tuple[Region, ...] — tuple[Region, ...]: One body region containing the induction value, carried-value formals, captures, and carried yields.

rebuild_nested¶

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

rebuild_regions¶

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

Rebuild the range-loop body and complete boundary interface.

Parameters:

Returns:

Operation — Rebuilt range-loop operation.

Raises:

• ValueError — If arity or boundary value kinds are inconsistent.

replace_values¶

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

Hamiltonian [source]¶

class Hamiltonian

Represents a quantum Hamiltonian as a sum of Pauli operator products.

The Hamiltonian is stored as a dictionary where keys are tuples of PauliOperators and values are their corresponding coefficients.

Example:

>>> H = Hamiltonian()
>>> H.add_term((PauliOperator(Pauli.X, 0), PauliOperator(Pauli.Y, 1)), 0.5)
>>> H.add_term((PauliOperator(Pauli.Z, 2),), 1.0)
>>> print(H.terms)
{(X0, Y1): 0.5, (Z2,): 1.0}

Constructor¶

def __init__(self, num_qubits: int | None = None) -> None

Attributes¶

• constant: float | complex

• num_qubits: int Calculates the number of qubits in the Hamiltonian.

• terms: dict[tuple[PauliOperator, ...], complex] Getter for the terms of the Hamiltonian.

Methods¶

add_term¶

def add_term(self, operators: tuple[PauliOperator, ...], coeff: float | complex)

Adds a term to the Hamiltonian.

This method adds a product of Pauli operators with a given coefficient to the Hamiltonian. If the term already exists, the coefficients are summed.

Parameters:

Example:

>>> H = Hamiltonian()
>>> H.add_term((PauliOperator(Pauli.X, 0), PauliOperator(Pauli.Y, 1)), 0.5)
>>> H.add_term((PauliOperator(Pauli.X, 0), PauliOperator(Pauli.Y, 1)), 0.5j)
>>> print(H.terms)
{(X0, Y1): (0.5+0.5j)}

copy¶

def copy(self) -> Hamiltonian

Return an independent copy sharing no mutable state with self.

Produces a new Hamiltonian with the same terms, constant, and declared _num_qubits. The underlying _terms dict is fresh, so subsequent add_term / constant mutations on either instance do not affect the other. PauliOperator instances inside the term tuples are reused — they are dataclass(frozen=True) values and safely shared.

Returns:

Hamiltonian — A shallow-cloned Hamiltonian instance.

Example:

>>> H = Hamiltonian()
>>> H.add_term((PauliOperator(Pauli.Z, 0),), 1.0)
>>> H2 = H.copy()
>>> H2.add_term((PauliOperator(Pauli.X, 1),), 0.5)
>>> H.num_qubits  # unchanged by H2's mutation
1

identity¶

@classmethod
def identity(
    cls,
    coeff: float | complex = 1.0,
    num_qubits: int | None = None,
) -> Hamiltonian

Create a scalar times identity Hamiltonian.

remap_qubits¶

def remap_qubits(self, qubit_map: dict[int, int]) -> Hamiltonian

Remap qubit indices according to the given mapping.

This is used to translate Pauli indices (logical indices within an expval call) to physical qubit indices in the actual quantum circuit.

Parameters:

Returns:

Hamiltonian — New Hamiltonian with remapped qubit indices.

single_pauli¶

@classmethod
def single_pauli(cls, pauli: Pauli, index: int, coeff: float | complex = 1.0) -> Hamiltonian

Create a single Pauli term Hamiltonian.

to_latex¶

def to_latex(self) -> str

Converts the Hamiltonian to a LaTeX representation.

This function does not add constant term when we show the Hamiltonian. This function does not add $ symbols.

Returns:

str — A LaTeX representation of the Hamiltonian.

import qamomile.observable as qm_o
import IPython.display as ipd

h = qm_o.Hamiltonian()
h += -qm_o.X(0) * qm_o.Y(1) - 2.0 * qm_o.Z(0) * qm_o.Z(1)

# Show the Hamiltonian in LaTeX at Jupyter Notebook
ipd.display(ipd.Latex("$" + h.to_latex() + "$"))

to_numpy¶

def to_numpy(self) -> np.ndarray

Convert the Hamiltonian to a dense NumPy matrix.

Qubit 0 is mapped to the least-significant bit of computational-basis indices, matching :meth:qamomile.linalg.HermitianMatrix.to_hamiltonian. The returned array has shape (2**n, 2**n) where n is :attr:num_qubits.

zero¶

@classmethod
def zero(cls, num_qubits: int | None = None) -> Hamiltonian

Create a zero Hamiltonian.

HasNestedOps [source]¶

class HasNestedOps

Mixin for operations that contain nested operation lists.

nested_regions() is the canonical traversal API because it exposes operations together with block arguments, captures, and yields. nested_op_lists() / rebuild_nested() remain compatibility helpers for specialized consumers while they migrate to the region interface.

Methods¶

nested_op_lists¶

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

Return all nested operation lists in this control flow op.

nested_regions¶

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

Return uniform views of every nested operation region.

Subclasses with explicit block arguments, captures, or yields override this method. The fallback keeps legacy operation-owned blocks visible while consumers migrate from nested_op_lists.

Returns:

tuple[Region, ...] — tuple[Region, ...]: Region views in nested_op_lists order.

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

rebuild_regions¶

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

Return a copy with replacement region operation sequences.

Concrete control-flow operations override this method to rebuild both their body operations and boundary values. The fallback supports legacy region owners whose boundary remains operation-specific.

Parameters:

Returns:

Operation — Rebuilt control-flow operation.

Raises:

• ValueError — If the replacement region count differs from the operation’s current region count.

InverseBlockOperation [source]¶

class InverseBlockOperation(Operation)

Represent an inverse qkernel/block as a first-class IR operation.

The operation stores both the original forward block and a Qamomile-built inverse implementation block. Emitters may use source_block with a backend-native inverse/adjoint primitive, then fall back to implementation_block when native inversion is unavailable.

Operands are ordered as scalar control qubits, target quantum operands, then classical/object parameters. Results mirror the quantum operand layout: control results first, then one target result per target operand. Vector target operands therefore count as one operand/result while contributing their scalar width to num_target_qubits.

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    num_control_qubits: int = 0,
    num_target_qubits: int = 0,
    custom_name: str = '',
    source_block: Block | None = None,
    implementation_block: Block | None = None,
    callable_ref: CallableRef | None = None,
    callable_attrs: dict[str, Any] = dict(),
    control_value: int | None = None,
) -> None

Attributes¶

• callable_attrs: dict[str, Any]

• callable_ref: CallableRef | None

• control_qubits: list[‘Value’] Return control quantum operands.

• control_value: int | None

• custom_name: str

• implementation_block: Block | None

• name: str Return a human-readable inverse operation name.

• num_control_qubits: int

• num_target_qubits: int

• operation_kind: OperationKind Return the operation kind.

• parameters: list[‘Value’] Return classical/object parameter operands.

• signature: Signature Return the operation signature.

• source_block: Block | None

• target_qubits: list[‘Value’] Return target quantum operands.

InvokeOperation [source]¶

class InvokeOperation(Operation)

Represent a composite, stdlib, or oracle call.

Parameters:

Constructor¶

def __init__(
    self,
    operands: Sequence[ValueLike] | None = None,
    results: Sequence[ValueLike] | None = None,
    *,
    target: CallableRef | None = None,
    transform: CallTransform = CallTransform.DIRECT,
    attrs: dict[str, Any] | None = None,
    definition: CallableDef | None = None,
) -> None

Initialize an invocation operation.

Parameters:

Raises:

• TypeError — If a controlled invocation’s control_value or an Oracle control-partition field has an invalid Python type.

• ValueError — If control_value is used on a non-controlled call or does not fit the controlled invocation’s width, or if Oracle invocation and definition control metadata disagree.

Attributes¶

• attrs: dict[str, Any]

• body: Block | None Return the callable’s default body from its definition.

• body_ref: CallableBodyRef | None Return the callable’s deferred body reference.

• control_qubits: list[‘Value’] Return the control-qubit operands.

• control_value: int | None Return the controlled invocation’s activation value.

• custom_name: str Return the display name for custom callable boxes.

• default_policy: CallPolicy Return the callable’s default lowering policy.

• definition: CallableDef | None

• effects: ‘KernelEffect’ Return cached effects of relevant callable implementations.

• gate_type: CompositeGateType Return the standard composite classification for this invocation.

• measurement_result_indices: frozenset[int] Return a conservative union of measurement-derived results.

• name: str Return the display name for this invocation.

• num_added_control_qubits: int Return controls introduced by a frontend control transform.

• num_body_external_control_qubits: int Return control operands generic lowering adds outside a base body.

• num_control_qubits: int Return the number of leading control-qubit operands.

• num_declared_control_qubits: int Return controls included in an opaque Oracle’s base definition.

• num_target_qubits: int Return the number of target-qubit operands.

• operands

• operation_kind: OperationKind Return the operation kind.

• parameters: list[‘Value’] Return non-qubit parameter operands.

• results

• signature: Signature Return the operation signature.

• strategy_name: str | None Return the selected lowering/resource strategy name.

• target: CallableRef

• target_qubits: list[‘Value’] Return the target-qubit operands.

• transform: CallTransform

Methods¶

body_for_transform¶

def body_for_transform(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
) -> tuple[Block | None, CallTransform]

Select a body and report the transform it already realizes.

A controlled-inverse invocation may reuse an explicitly registered inverse body when no implementation realizes both transforms. Keeping that fallback in the IR operation gives emitters and static analyses one selection rule while still letting each consumer apply the remaining coherent controls in its own representation.

Parameters:

Returns:

Block | None — tuple[Block | None, CallTransform]: Selected body and the transform CallTransform — already implemented by that body. The callable’s direct body is tuple[Block | None, CallTransform] — returned with DIRECT when no transform-specific body matches.

Raises:

• ValueError — If the selected body disagrees with the invocation’s input or output contract.

effective_body¶

def effective_body(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
) -> Block | None

Return the implementation body selected for this invocation.

Parameters:

Returns:

Block | None — Block | None: Selected implementation body, or the callable’s Block | None — default body when no transform-specific implementation exists. Block | None — A compiler may synthesize inverse or controlled behavior from this Block | None — fallback body.

implementation_for¶

def implementation_for(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
    require_body: bool = False,
) -> CallableImplementation | None

Return the selected implementation for this invocation.

Parameters:

Returns:

CallableImplementation | None — CallableImplementation | None: Matching implementation candidate, CallableImplementation | None — or None when the callable definition has no match.

measurement_result_indices_for¶

def measurement_result_indices_for(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
) -> frozenset[int]

Return measurement-derived results for one selected implementation.

Parameters:

Returns:

frozenset[int] — frozenset[int]: Caller-local result positions derived from measurement in the selected body.

Raises:

• ValueError — If the selected body disagrees with the invocation’s input or output contract.

select_body¶

def select_body(
    self,
    *,
    backend: str | None = None,
    strategy: str | None = None,
) -> CallableBodySelection

Select and validate the composable body for this invocation.

The result carries the transform already realized by the body and the exact call-site values that bind to it. Consumers therefore cannot independently disagree about whether an invocation’s control prefix belongs to the selected implementation ABI.

Parameters:

Returns:

CallableBodySelection — Validated body, realized transform, and CallableBodySelection — aligned call-site operands and results.

Raises:

• ValueError — If the selected body disagrees with the invocation’s input or output contract.

LoopCarriedRebind [source]¶

class LoopCarriedRebind

Trace-time record of a variable rebound inside a loop body.

Two rebind families share this record type, distinguished by the type of before:

• Classical scalar (before classical): the frontend traces a loop body exactly once, so a Python-level reassignment like total = total + i produces IR whose right-hand side reads the fixed pre-loop value instead of the previous iteration’s value. Most such carries are now represented as explicit RegionArgs (see above) and are fully supported; a classical record is only created for the shapes region binding declines — while-body carries (a runtime while loop cannot be unrolled) and measurement-backed Bit carries — and the transpiler’s classical loop-carried check rejects those with a targeted error instead of silently miscompiling.

• Quantum (before quantum): the loop body left the variable bound to a different quantum resource (logical_id change — a fresh allocation or another register, not a gate self-update). The transpiler’s control-flow discard check (reject_control_flow_quantum_discard) rejects the ones whose incoming state the body never consumes.

Constructor¶

def __init__(
    self,
    var_name: str,
    before: ValueBase,
    after: ValueBase,
    before_synthesized: bool = False,
) -> None

Attributes¶

• after: ValueBase

• before: ValueBase

• before_synthesized: bool

• var_name: str

RegionArg [source]¶

class RegionArg

Explicit loop-carried value on a loop operation (MLIR-style iter_arg).

A RegionArg makes a loop-carried dependency explicit in the IR, the way MLIR’s scf.for models iter_args / scf.yield:

• On iteration 0 the body reads block_arg bound to init.

• After each iteration, block_arg is rebound to that iteration’s yielded value.

• After the loop, result holds the final carried value (init when the loop ran zero iterations).

The loop body’s operations reference block_arg (the frontend substitutes the traced pre-loop reads), and post-loop operations reference result (the frontend rebinds the Python handle when it closes the loop). result is also appended to the loop operation’s results list so dependency analysis sees the loop as its producer.

This subsumes the trace-once staleness that LoopCarriedRebind records exist to reject: a rebind represented as a RegionArg is a supported loop-carried value, not a miscompilation hazard.

Constructor¶

def __init__(
    self,
    var_name: str,
    init: Value,
    block_arg: Value,
    yielded: Value,
    result: Value,
) -> None

Attributes¶

• block_arg: Value

• init: Value

• result: Value

• var_name: str

• yielded: Value

SelectOperation [source]¶

class SelectOperation(Operation)

Quantum multiplexer: apply case_blocks[i] when the index reads i.

Concrete operand layout: [idx_0, ..., idx_{k-1}, tgt_0, ..., tgt_m, params...]. Symbolic-width operand layout: [idx_arg_0, ..., idx_arg_{a-1}, tgt_0, ..., tgt_m, params...]. Results mirror the quantum operand grouping.

A concrete index register is normalized to one scalar Qubit operand per physical index qubit. A symbolic-width register instead retains each leading caller argument as one scalar or array operand until its bound shape is known. Whole-Vector[Qubit] / scalar targets follow and keep their shapes, and classical parameters shared across every case come last.

Index bit order is LSB-first: idx_0 is the least-significant bit, matching Qamomile’s qubit-zero convention. Case i is selected when index qubit j reads bit j of i. len(case_blocks) need not be a power of two; index values >= len(case_blocks) apply no operation (identity).

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    num_index_qubits: int | Value = 0,
    case_blocks: list[Block] = list(),
    num_index_args: int = 0,
    case_callable_attrs: list[dict[str, Any]] = list(),
) -> None

Attributes¶

• case_blocks: list[Block]

• case_callable_attrs: list[dict[str, Any]]

• index_operands: list[Value] Return the grouped index-prefix operands.

• is_symbolic_num_index_qubits: bool Return whether the index width is a symbolic IR value.

• num_cases: int Return the number of selectable cases.

• num_index_args: int

• num_index_qubits: int | Value

• operation_kind: OperationKind Return the operation kind.

• param_operands: list[Value] Return the shared classical parameter operands.

• signature: Signature Return the operation signature.

• target_operands: list[Value] Return the quantum target operands applied by every case.

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Return every value consumed by the SELECT operation.

Returns:

list[ValueBase] — list[ValueBase]: Ordinary operands plus the symbolic index-width value when present.

replace_values¶

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

Replace operand and symbolic-width values by UUID.

Parameters:

Returns:

Operation — Rebuilt SELECT operation with matching values replaced.

StaticBindingField [source]¶

class StaticBindingField

Reference one scalar field projected from a static binding.

Parameters:

Constructor¶

def __init__(self, name: str, value: Value) -> None

Attributes¶

• name: str

• value: Value

StaticBindingSlot [source]¶

class StaticBindingSlot

Declare one typed compile-time object required by a qkernel.

The object itself is not an SSA value and never reaches a backend. Only registered scalar projections and deferred callable-member references may appear in the hierarchical body. A build must resolve the slot before the block advances to a compiler stage.

Parameters:

Constructor¶

def __init__(
    self,
    name: str,
    type_key: str,
    fields: tuple[StaticBindingField, ...] = (),
) -> None

Attributes¶

• fields: tuple[StaticBindingField, ...]

• name: str

• type_key: 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

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.

ValueBase [source]¶

class ValueBase

Nominal base for every typed IR value.

Runtime compiler passes inspect values in their innermost loops. A nominal base keeps those checks constant-time; a runtime-checkable protocol would repeatedly scan the protocol members on Python versions that do not cache structural checks.

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: ValueType Return the static IR type carried by this value.

• uuid: str

Methods¶

get_const¶

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

Return the scalar constant carried by this value.

Returns:

int | float | bool | None — int | float | bool | None: Constant value, or None when the value is not constant.

is_constant¶

def is_constant(self) -> bool

Return whether this value carries a scalar constant.

Returns:

bool — Whether scalar constant metadata is present.

is_parameter¶

def is_parameter(self) -> bool

Return whether this value represents a runtime parameter.

Returns:

bool — Whether parameter metadata is present.

next_version¶

def next_version(self) -> ValueBase

Create the next SSA version of this value.

Returns:

ValueBase — A value with a fresh version UUID and preserved logical identity.

parameter_name¶

def parameter_name(self) -> str | None

Return the public parameter name carried by this value.

Returns:

str | None — str | None: Parameter name, or None for a non-parameter value.

ValueMetadata [source]¶

class ValueMetadata

Typed metadata owned by the compiler/runtime.

Constructor¶

def __init__(
    self,
    scalar: ScalarMetadata | None = None,
    cast: CastMetadata | None = None,
    qfixed: QFixedMetadata | None = None,
    array_runtime: ArrayRuntimeMetadata | None = None,
    dict_runtime: DictRuntimeMetadata | None = None,
) -> None

Attributes¶

• array_runtime: ArrayRuntimeMetadata | None

• cast: CastMetadata | None

• dict_runtime: DictRuntimeMetadata | None

• qfixed: QFixedMetadata | None

• scalar: ScalarMetadata | None

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

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,
    loop_carried_rebinds: tuple[LoopCarriedRebind, ...] = (),
    region_args: tuple[RegionArg, ...] = (),
    captures: tuple[ValueBase, ...] = (),
) -> None

Attributes¶

• captures: tuple[ValueBase, ...]

• loop_carried_rebinds: tuple[LoopCarriedRebind, ...]

• max_iterations: int | None

• operation_kind: OperationKind

• operations: list[Operation]

• region_args: tuple[RegionArg, ...]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Include rebind records and region args for cloning/substitution.

Same rationale as ForOperation.all_input_values: rebind records and region arguments reference body/pre-loop values by identity, so inline cloning must remap them in lockstep with body operands.

Returns:

list[ValueBase] — list[ValueBase]: Base input values plus rebind-record and region-argument values.

nested_op_lists¶

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

nested_regions¶

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

Return the while body with explicit boundary values.

Returns:

tuple[Region, ...] — tuple[Region, ...]: One body region whose block arguments and yields are aligned with region_args. The updated condition, when present, is appended as the final yield.

rebuild_nested¶

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

rebuild_regions¶

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

Rebuild the while body and its complete boundary interface.

Parameters:

Returns:

Operation — Rebuilt while operation.

Raises:

• ValueError — If arity or boundary value kinds are inconsistent.

replace_values¶

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

Substitute operand, rebind-record, and region-arg values.

Parameters:

Returns:

Operation — The rewritten operation.

qamomile.circuit.ir.dataflow¶

Backend-independent dataflow utilities for semantic Qamomile IR.

Overview¶

Functions¶

build_dependency_graph [source]¶

def build_dependency_graph(operations: Sequence[Operation]) -> dict[str, set[str]]

Build result-to-input dependency edges for semantic operations.

The graph includes nested control flow, branch merges, loop-carried region arguments, array-element ancestry, and slice ancestry. These are the shared semantics used by measurement provenance, kernel effects, and the compiler’s classical lowering passes.

Parameters:

Returns:

dict[str, set[str]] — dict[str, set[str]]: Result UUIDs mapped to the UUIDs they depend on.

find_loop_carried_condition_reads [source]¶

def find_loop_carried_condition_reads(
    loop_operation: ForOperation | ForItemsOperation | WhileOperation,
    *,
    condition_values: Sequence[ValueBase] | None = None,
    selected_aliases: Mapping[str, str] | None = None,
) -> set[tuple[str, str]]

Find legacy loop rebinds whose entry value controls a nested branch.

A legacy LoopCarriedRebind does not provide runtime storage between iterations. If its entry value transitively feeds an IfOperation condition, pruning that first-iteration branch must therefore not erase the evidence that a later iteration would read the updated value.

Parameters:

Returns:

set[tuple[str, str]] — set[tuple[str, str]]: (before_uuid, after_uuid) pairs for rebinds whose entry value transitively influences a considered condition.

find_loop_carried_condition_uuids [source]¶

def find_loop_carried_condition_uuids(operations: Sequence[Operation]) -> set[str]

Find branch conditions that read legacy loop-carried scalar Bits.

Compile-time specialization normally removes a branch whose first traced condition is a constant. That is unsafe while recursively unrolling a body when the same condition reads a legacy loop-carried Bit: later iterations observe the refreshed value, so the final loop-state validator still needs the branch as dependency evidence.

Parameters:

Returns:

set[str] — set[str]: UUIDs of conditions that transitively depend on a legacy scalar Bit entry value.

find_loop_carried_value_reads [source]¶

def find_loop_carried_value_reads(
    loop_operation: ForOperation | ForItemsOperation | WhileOperation,
    values: Sequence[ValueBase],
    *,
    selected_aliases: Mapping[str, str] | None = None,
) -> set[tuple[str, str]]

Find unsupported scalar Bit carries read by selected body values.

Parameters:

Returns:

set[tuple[str, str]] — set[tuple[str, str]]: (before_uuid, after_uuid) pairs for legacy scalar Bit rebinds read by at least one selected value.

find_measurement_derived_values [source]¶

def find_measurement_derived_values(dependency_graph: dict[str, set[str]], measurement_uuids: set[str]) -> set[str]

Propagate measurement provenance forward through a dependency graph.

Parameters:

Returns:

set[str] — set[str]: Direct and transitively measurement-derived UUIDs.

find_measurement_results [source]¶

def find_measurement_results(operations: Sequence[Operation]) -> set[str]

Return UUIDs directly produced from quantum measurement.

Parameters:

Returns:

set[str] — set[str]: Direct scalar, vector, fixed-point, and projection results.

has_legacy_scalar_bit_rebinds [source]¶

def has_legacy_scalar_bit_rebinds(operations: Sequence[Operation]) -> bool

Return whether an operation tree contains legacy scalar Bit state.

Parameters:

Returns:

bool — Whether a loop carries a scalar Bit through legacy rebind metadata rather than an explicit region argument.

walk_operations [source]¶

def walk_operations(operations: Sequence[Operation]) -> Iterable[Operation]

Yield operations in preorder across every nested control-flow region.

Parameters:

Returns:

Iterable[Operation] — Iterable[Operation]: Preorder traversal including nested operations.

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]

BitType [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

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(),
    loop_carried_rebinds: tuple[LoopCarriedRebind, ...] = (),
    region_args: tuple[RegionArg, ...] = (),
    captures: tuple[ValueBase, ...] = (),
) -> None

Attributes¶

• captures: tuple[ValueBase, ...]

• key_is_vector: bool

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

• key_vars: list[str]

• loop_carried_rebinds: tuple[LoopCarriedRebind, ...]

• operation_kind: OperationKind

• operations: list[Operation]

• region_args: tuple[RegionArg, ...]

• 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. Loop-carried rebind records and region arguments are included for the same reason.

nested_op_lists¶

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

nested_regions¶

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

Return the items-loop body with its explicit interface.

Returns:

tuple[Region, ...] — tuple[Region, ...]: One body region containing key/value formals, carried-value formals, captures, and carried yields.

rebuild_nested¶

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

rebuild_regions¶

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

Rebuild the items-loop body and complete boundary interface.

Parameters:

Returns:

Operation — Rebuilt items-loop operation.

Raises:

• ValueError — If arity or boundary value kinds are inconsistent.

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(),
    loop_carried_rebinds: tuple[LoopCarriedRebind, ...] = (),
    region_args: tuple[RegionArg, ...] = (),
    captures: tuple[ValueBase, ...] = (),
) -> None

Attributes¶

• captures: tuple[ValueBase, ...]

• loop_carried_rebinds: tuple[LoopCarriedRebind, ...]

• loop_var: str

• loop_var_value: Value | None

• operation_kind: OperationKind

• operations: list[Operation]

• region_args: tuple[RegionArg, ...]

• 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. Loop-carried rebind records and region arguments are included for the same reason.

nested_op_lists¶

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

nested_regions¶

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

Return the range-loop body with its explicit interface.

Returns:

tuple[Region, ...] — tuple[Region, ...]: One body region containing the induction value, carried-value formals, captures, and carried yields.

rebuild_nested¶

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

rebuild_regions¶

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

Rebuild the range-loop body and complete boundary interface.

Parameters:

Returns:

Operation — Rebuilt range-loop operation.

Raises:

• ValueError — If arity or boundary value kinds are inconsistent.

replace_values¶

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

HasNestedOps [source]¶

class HasNestedOps

Mixin for operations that contain nested operation lists.

nested_regions() is the canonical traversal API because it exposes operations together with block arguments, captures, and yields. nested_op_lists() / rebuild_nested() remain compatibility helpers for specialized consumers while they migrate to the region interface.

Methods¶

nested_op_lists¶

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

Return all nested operation lists in this control flow op.

nested_regions¶

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

Return uniform views of every nested operation region.

Subclasses with explicit block arguments, captures, or yields override this method. The fallback keeps legacy operation-owned blocks visible while consumers migrate from nested_op_lists.

Returns:

tuple[Region, ...] — tuple[Region, ...]: Region views in nested_op_lists order.

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

rebuild_regions¶

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

Return a copy with replacement region operation sequences.

Concrete control-flow operations override this method to rebuild both their body operations and boundary values. The fallback supports legacy region owners whose boundary remains operation-specific.

Parameters:

Returns:

Operation — Rebuilt control-flow operation.

Raises:

• ValueError — If the replacement region count differs from the operation’s current region count.

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:

Operation — The rewritten operation.

MeasureOperation [source]¶

class MeasureOperation(Operation)

Constructor¶

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

Attributes¶

• operation_kind: OperationKind

• signature: Signature

MeasureQFixedOperation [source]¶

class MeasureQFixedOperation(Operation)

Measure a quantum fixed-point number.

This operation measures all qubits in a QFixed register and produces a Float result. During transpilation, this is lowered to individual MeasureOperations plus a DecodeQFixedOperation.

operands: [QFixed value (contains qubit_values in params)] results: [Float value]

Encoding:

For QPE phase (int_bits=0): Qubits are stored least-significant first. For n qubits, bit i has weight 2**(-n + i).

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

MeasureVectorOperation [source]¶

class MeasureVectorOperation(Operation)

Measure a vector of qubits.

Takes a Vector[Qubit] (ArrayValue) and produces a Vector[Bit] (ArrayValue). This operation measures all qubits in the vector as a single operation.

operands: [ArrayValue of qubits] results: [ArrayValue of bits]

Constructor¶

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

Attributes¶

• operation_kind: OperationKind

• signature: Signature

ProjectOperation [source]¶

class ProjectOperation(Operation)

Project a qubit in one Pauli basis and keep the projected state.

Constructor¶

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

Attributes¶

• axis: str

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

ValueBase [source]¶

class ValueBase

Nominal base for every typed IR value.

Runtime compiler passes inspect values in their innermost loops. A nominal base keeps those checks constant-time; a runtime-checkable protocol would repeatedly scan the protocol members on Python versions that do not cache structural checks.

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: ValueType Return the static IR type carried by this value.

• uuid: str

Methods¶

get_const¶

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

Return the scalar constant carried by this value.

Returns:

int | float | bool | None — int | float | bool | None: Constant value, or None when the value is not constant.

is_constant¶

def is_constant(self) -> bool

Return whether this value carries a scalar constant.

Returns:

bool — Whether scalar constant metadata is present.

is_parameter¶

def is_parameter(self) -> bool

Return whether this value represents a runtime parameter.

Returns:

bool — Whether parameter metadata is present.

next_version¶

def next_version(self) -> ValueBase

Create the next SSA version of this value.

Returns:

ValueBase — A value with a fresh version UUID and preserved logical identity.

parameter_name¶

def parameter_name(self) -> str | None

Return the public parameter name carried by this value.

Returns:

str | None — str | None: Parameter name, or None for a non-parameter value.

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,
    loop_carried_rebinds: tuple[LoopCarriedRebind, ...] = (),
    region_args: tuple[RegionArg, ...] = (),
    captures: tuple[ValueBase, ...] = (),
) -> None

Attributes¶

• captures: tuple[ValueBase, ...]

• loop_carried_rebinds: tuple[LoopCarriedRebind, ...]

• max_iterations: int | None

• operation_kind: OperationKind

• operations: list[Operation]

• region_args: tuple[RegionArg, ...]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Include rebind records and region args for cloning/substitution.

Same rationale as ForOperation.all_input_values: rebind records and region arguments reference body/pre-loop values by identity, so inline cloning must remap them in lockstep with body operands.

Returns:

list[ValueBase] — list[ValueBase]: Base input values plus rebind-record and region-argument values.

nested_op_lists¶

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

nested_regions¶

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

Return the while body with explicit boundary values.

Returns:

tuple[Region, ...] — tuple[Region, ...]: One body region whose block arguments and yields are aligned with region_args. The updated condition, when present, is appended as the final yield.

rebuild_nested¶

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

rebuild_regions¶

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

Rebuild the while body and its complete boundary interface.

Parameters:

Returns:

Operation — Rebuilt while operation.

Raises:

• ValueError — If arity or boundary value kinds are inconsistent.

replace_values¶

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

Substitute operand, rebind-record, and region-arg values.

Parameters:

Returns:

Operation — The rewritten operation.

qamomile.circuit.ir.effect¶

First-class semantic effects for qkernel bodies and invocations.

Overview¶

Functions¶

build_dependency_graph [source]¶

def build_dependency_graph(operations: Sequence[Operation]) -> dict[str, set[str]]

Build result-to-input dependency edges for semantic operations.

The graph includes nested control flow, branch merges, loop-carried region arguments, array-element ancestry, and slice ancestry. These are the shared semantics used by measurement provenance, kernel effects, and the compiler’s classical lowering passes.

Parameters:

Returns:

dict[str, set[str]] — dict[str, set[str]]: Result UUIDs mapped to the UUIDs they depend on.

callable_bodies [source]¶

def callable_bodies(definition: 'CallableDef', transform: CallTransform) -> tuple['Block', ...]

Return cached semantic bodies relevant to one call transform.

An explicit implementation of the complete transform takes precedence. A controlled-inverse call then reuses explicit inverse-body metadata when generic lowering only needs to add controls; all other structural fallbacks conservatively inherit the direct body’s effects.

Parameters:

Returns:

tuple['Block', ...] — tuple[Block, ...]: Candidate bodies whose cached metadata applies.

callable_effects [source]¶

def callable_effects(
    definition: 'CallableDef | None',
    transform: CallTransform = CallTransform.DIRECT,
) -> KernelEffect

Return cached effects for a callable invocation.

Parameters:

Returns:

KernelEffect — Union of the relevant cached body effects.

callable_measurement_result_indices [source]¶

def callable_measurement_result_indices(
    definition: 'CallableDef | None',
    transform: CallTransform = CallTransform.DIRECT,
) -> frozenset[int]

Return callable result positions carrying measurement provenance.

Parameters:

Returns:

frozenset[int] — frozenset[int]: Result positions derived from measurement in any applicable body.

find_measurement_derived_values [source]¶

def find_measurement_derived_values(dependency_graph: dict[str, set[str]], measurement_uuids: set[str]) -> set[str]

Propagate measurement provenance forward through a dependency graph.

Parameters:

Returns:

set[str] — set[str]: Direct and transitively measurement-derived UUIDs.

find_measurement_results [source]¶

def find_measurement_results(operations: Sequence[Operation]) -> set[str]

Return UUIDs directly produced from quantum measurement.

Parameters:

Returns:

set[str] — set[str]: Direct scalar, vector, fixed-point, and projection results.

format_kernel_effects [source]¶

def format_kernel_effects(effects: KernelEffect) -> str

Format an effect set for deterministic user-facing diagnostics.

Parameters:

Returns:

str — Comma-separated flag names, or NONE for a unitary kernel.

refresh_block_effects [source]¶

def refresh_block_effects(block: 'Block') -> None

Refresh reachable effect metadata as a least fixed point.

Recursive and mutually recursive callables are valid serialized IR. Their semantic effects therefore cannot be populated with an ordinary recursive cache: a cycle would expose and then persist a partial NONE result. The effect and measured-output lattices are finite, so this routine starts every reachable body at the empty summary and repeatedly applies the ordinary local equations until no flag or result index grows.

Parameters:

require_unitary_effects [source]¶

def require_unitary_effects(
    effects: KernelEffect,
    *,
    operation: str,
    target: str,
    alternative: str,
) -> None

Reject non-unitary effects with a uniform early diagnostic.

Parameters:

Raises:

• ValueError — If effects is not the empty unitary set.

summarize_block_effects [source]¶

def summarize_block_effects(
    operations: Sequence[Operation],
    output_values: Sequence[object],
) -> tuple[KernelEffect, frozenset[int]]

Summarize kernel effects and measurement-derived public outputs.

Parameters:

Returns:

tuple[KernelEffect, frozenset[int]] — tuple[KernelEffect, frozenset[int]]: Aggregated effects and output positions carrying measurement provenance.

walk_operations [source]¶

def walk_operations(operations: Sequence[Operation]) -> Iterable[Operation]

Yield operations in preorder across every nested control-flow region.

Parameters:

Returns:

Iterable[Operation] — Iterable[Operation]: Preorder traversal including nested operations.

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

CallTransform [source]¶

class CallTransform(enum.Enum)

Describe the requested transform of a callable implementation.

Attributes¶

• CONTROLLED

• CONTROLLED_INVERSE

• DIRECT

• INVERSE

• is_controlled: bool Return whether the transform adds coherent controls.

• is_inverse: bool Return whether the transform requests inverse application.

Methods¶

inverted¶

def inverted(self) -> CallTransform

Toggle inverse application while preserving coherent control.

Returns:

CallTransform — Transform with the inverse component toggled.

CallableDef [source]¶

class CallableDef

Describe a compiler-facing callable definition.

Parameters:

Constructor¶

def __init__(
    self,
    ref: CallableRef,
    signature: Signature | None = None,
    body: Block | None = None,
    body_ref: CallableBodyRef | None = None,
    implementations: list[CallableImplementation] = list(),
    opaque_cost: Any | None = None,
    default_policy: CallPolicy = CallPolicy.INLINE,
    attrs: dict[str, Any] = dict(),
) -> None

Attributes¶

• attrs: dict[str, Any]

• body: Block | None

• body_ref: CallableBodyRef | None

• default_policy: CallPolicy

• implementations: list[CallableImplementation]

• opaque_cost: Any | None

• ref: CallableRef

• signature: Signature | None