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

• NotImplementedError — If a CallBlockOperation is encountered (typically because inline has not been run yet).

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

• NotImplementedError — If a CallBlockOperation 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}.

qamomile.circuit.ir.block¶

Unified block representation for all pipeline stages.

Overview¶

Classes¶

Block [source]¶

class Block

Unified block representation for all pipeline stages.

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

Constructor¶

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

Attributes¶

• input_values: list[Value]

• kind: BlockKind

• label_args: list[str]

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[Value]

• param_slots: tuple[ParamSlot, ...]

• parameters: dict[str, Value]

Methods¶

call¶

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

Create a CallBlockOperation against this block.

is_affine¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

BlockKind [source]¶

class BlockKind(Enum)

Classification of block structure for pipeline stages.

Attributes¶

• AFFINE

• ANALYZED

• HIERARCHICAL

• TRACED

CallBlockOperation [source]¶

class CallBlockOperation(Operation)

Constructor¶

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

Attributes¶

• block: Block | None

• operation_kind: OperationKind

• signature: Signature

Methods¶

is_self_reference_to¶

def is_self_reference_to(self, block: Block) -> bool

Return True if this call points to the given block (self-ref).

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’

Value [source]¶

class Value(_MetadataValueMixin, Generic[T])

A typed SSA value in the IR.

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

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

Constructor¶

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

Attributes¶

• element_indices: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

is_array_element¶

def is_array_element(self) -> bool

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version and fresh UUID.

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

qamomile.circuit.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 still contain CallBlockOperations that reference sibling Blocks by Python identity; their canonical treatment 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. numpy.ndarray payloads (except object-dtype arrays) are hashed from their raw buffer (dtype + shape + bytes) and are therefore exempt; hash stability for any other object type requires a stable repr.

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

• NotImplementedError — If a CallBlockOperation is encountered (typically because inline has not been run yet).

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

• NotImplementedError — If a CallBlockOperation 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.

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

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

Attributes¶

• input_values: list[Value]

• kind: BlockKind

• label_args: list[str]

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[Value]

• param_slots: tuple[ParamSlot, ...]

• parameters: dict[str, Value]

Methods¶

call¶

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

Create a CallBlockOperation against this block.

is_affine¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

BlockKind [source]¶

class BlockKind(Enum)

Classification of block structure for pipeline stages.

Attributes¶

• AFFINE

• ANALYZED

• HIERARCHICAL

• TRACED

CallBlockOperation [source]¶

class CallBlockOperation(Operation)

Constructor¶

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

Attributes¶

• block: Block | None

• operation_kind: OperationKind

• signature: Signature

Methods¶

is_self_reference_to¶

def is_self_reference_to(self, block: Block) -> bool

Return True if this call points to the given block (self-ref).

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

CompositeGateOperation [source]¶

class CompositeGateOperation(Operation)

Represents a composite gate (QPE, QFT, etc.) as a single operation.

CompositeGate allows representing complex multi-gate operations as a single atomic operation in the IR. This enables:

• Resource estimation without full implementation

• Backend-native conversion (e.g., Qiskit’s QPE)

• User-defined complex gates

The operands structure is:

• operands[0:num_control_qubits]: Control qubits (if any)

• operands[num_control_qubits:num_control_qubits+num_target_qubits]: Target qubits

• operands[num_control_qubits+num_target_qubits:]: Parameters

The results structure:

• results[0:num_control_qubits]: Control qubits (returned)

• results[num_control_qubits:]: Target qubits (returned)

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
    num_control_qubits: int = 0,
    num_target_qubits: int = 0,
    custom_name: str = '',
    resource_metadata: ResourceMetadata | None = None,
    has_implementation: bool = True,
    implementation_block: Block | None = None,
    composite_gate_instance: Any = None,
    strategy_name: str | None = None,
) -> None

Attributes¶

• composite_gate_instance: Any

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

• custom_name: str

• gate_type: CompositeGateType

• has_implementation: bool

• implementation: Block | None Get the implementation block, if any.

• implementation_block: Block | None

• name: str Human-readable name of this composite gate.

• num_control_qubits: int

• num_target_qubits: int

• operation_kind: OperationKind Return the operation kind (always QUANTUM).

• parameters: list[‘Value’] Get the parameter operands (angles, etc.).

• resource_metadata: ResourceMetadata | None

• signature: Signature Return the operation signature.

• strategy_name: str | None

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

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

Attributes¶

• block: Block | 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 parameter operands (non-qubit, non-block).

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

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

HasNestedOps [source]¶

class HasNestedOps

Mixin for operations that contain nested operation lists.

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

Methods¶

nested_op_lists¶

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

Return all nested operation lists in this control flow op.

rebuild_nested¶

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

Return a copy with nested operation lists replaced.

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

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

Attributes¶

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

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

TupleValue [source]¶

class TupleValue(_MetadataValueMixin)

A tuple of IR values for structured data.

Constructor¶

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

Attributes¶

• elements: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: ‘TupleType’

• uuid: str

Methods¶

is_constant¶

def is_constant(self) -> bool

next_version¶

def next_version(self) -> TupleValue

Value [source]¶

class Value(_MetadataValueMixin, Generic[T])

A typed SSA value in the IR.

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

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

Constructor¶

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

Attributes¶

• element_indices: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

is_array_element¶

def is_array_element(self) -> bool

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version and fresh UUID.

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

ValueBase [source]¶

class ValueBase(Protocol)

Protocol for IR values with typed metadata.

Attributes are declared as read-only properties to match frozen dataclass fields in concrete implementations (Value, ArrayValue, etc.).

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• uuid: str

Methods¶

get_const¶

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

is_constant¶

def is_constant(self) -> bool

is_parameter¶

def is_parameter(self) -> bool

next_version¶

def next_version(self) -> ValueBase

parameter_name¶

def parameter_name(self) -> str | None

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

qamomile.circuit.ir.operation¶

Overview¶

Classes¶

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

CompositeGateOperation [source]¶

class CompositeGateOperation(Operation)

Represents a composite gate (QPE, QFT, etc.) as a single operation.

CompositeGate allows representing complex multi-gate operations as a single atomic operation in the IR. This enables:

• Resource estimation without full implementation

• Backend-native conversion (e.g., Qiskit’s QPE)

• User-defined complex gates

The operands structure is:

• operands[0:num_control_qubits]: Control qubits (if any)

• operands[num_control_qubits:num_control_qubits+num_target_qubits]: Target qubits

• operands[num_control_qubits+num_target_qubits:]: Parameters

The results structure:

• results[0:num_control_qubits]: Control qubits (returned)

• results[num_control_qubits:]: Target qubits (returned)

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
    num_control_qubits: int = 0,
    num_target_qubits: int = 0,
    custom_name: str = '',
    resource_metadata: ResourceMetadata | None = None,
    has_implementation: bool = True,
    implementation_block: Block | None = None,
    composite_gate_instance: Any = None,
    strategy_name: str | None = None,
) -> None

Attributes¶

• composite_gate_instance: Any

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

• custom_name: str

• gate_type: CompositeGateType

• has_implementation: bool

• implementation: Block | None Get the implementation block, if any.

• implementation_block: Block | None

• name: str Human-readable name of this composite gate.

• num_control_qubits: int

• num_target_qubits: int

• operation_kind: OperationKind Return the operation kind (always QUANTUM).

• parameters: list[‘Value’] Get the parameter operands (angles, etc.).

• resource_metadata: ResourceMetadata | None

• signature: Signature Return the operation signature.

• strategy_name: str | None

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

CompositeGateType [source]¶

class CompositeGateType(enum.Enum)

Registry of known composite gate types.

Attributes¶

• CUSTOM

• IQFT

• QFT

• QPE

ConcreteControlledU [source]¶

class ConcreteControlledU(ControlledUOperation)

Controlled-U with concrete (int) number of controls.

Operand layout: [ctrl_0, ..., ctrl_n, tgt_0, ..., tgt_m, params...] Result layout: [ctrl_0', ..., ctrl_n', tgt_0', ..., tgt_m']

Constructor¶

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

Attributes¶

• control_operands: list[Value]

• num_controls: int

• param_operands: list[Value]

• signature: Signature

• target_operands: list[Value]

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

Attributes¶

• block: Block | 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 parameter operands (non-qubit, non-block).

• 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

DecodeQFixedOperation [source]¶

class DecodeQFixedOperation(Operation)

Decode measured bits to float (classical operation).

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

The decoding formula:

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

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

Example:

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

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

Constructor¶

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

Attributes¶

• int_bits: int

• num_bits: int

• operation_kind: OperationKind

• signature: Signature

ExpvalOp [source]¶

class ExpvalOp(Operation)

Expectation value operation.

This operation computes the expectation value <psi|H|psi> where psi is the quantum state and H is the Hamiltonian observable.

The operation bridges quantum and classical computation:

• Input: quantum state (qubits) + Observable reference

• Output: classical Float (expectation value)

Example IR:

Constructor¶

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

Attributes¶

• hamiltonian: Value Alias for observable (deprecated, use observable instead).

• observable: Value The Observable parameter operand.

• operation_kind: OperationKind ExpvalOp is HYBRID - bridges quantum state to classical value.

• output: Value The expectation value result.

• qubits: Value The quantum register operand.

• signature: Signature

ForItemsOperation [source]¶

class ForItemsOperation(HasNestedOps, Operation)

Represents iteration over dict/iterable items.

Example:

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

Constructor¶

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

Attributes¶

• key_is_vector: bool

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

• key_vars: list[str]

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

• value_var: str

• value_var_value: Value | None

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

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

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

nested_op_lists¶

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

rebuild_nested¶

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

replace_values¶

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

GateOperation [source]¶

class GateOperation(Operation)

Quantum gate operation.

For rotation gates (RX, RY, RZ, P, CP, RZZ), the angle parameter is stored as the last element of operands. Use the theta property for typed read access and the rotation / fixed factory class-methods for type-safe construction.

Constructor¶

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

Attributes¶

• gate_type: GateOperationType | None

• operation_kind: OperationKind

• qubit_operands: list[Value] Qubit operands (excluding the theta parameter if present).

• signature: Signature

• theta: Value | None Angle parameter for rotation gates, or None for fixed gates.

Methods¶

fixed¶

@classmethod
def fixed(
    cls,
    gate_type: GateOperationType,
    qubits: list[Value],
    results: list[Value],
) -> 'GateOperation'

Create a fixed gate (H, X, CX, SWAP, …) with no angle parameter.

rotation¶

@classmethod
def rotation(
    cls,
    gate_type: GateOperationType,
    qubits: list[Value],
    theta: Value,
    results: list[Value],
) -> 'GateOperation'

Create a rotation gate (RX, RY, RZ, P, CP, RZZ) with an angle.

GateOperationType [source]¶

class GateOperationType(enum.Enum)

Attributes¶

• CP

• CX

• CZ

• H

• P

• RX

• RY

• RZ

• RZZ

• S

• SDG

• SWAP

• T

• TDG

• TOFFOLI

• X

• Y

• Z

HasNestedOps [source]¶

class HasNestedOps

Mixin for operations that contain nested operation lists.

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

Methods¶

nested_op_lists¶

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

Return all nested operation lists in this control flow op.

rebuild_nested¶

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

Return a copy with nested operation lists replaced.

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

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

Attributes¶

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

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

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): float_value = 0.b0b1b2... = b00.5 + b10.25 + b2*0.125 + ...

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

Operation [source]¶

class Operation(abc.ABC)

Constructor¶

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

Attributes¶

• operands: list[Value]

• operation_kind: OperationKind Return the kind of this operation for classical/quantum classification.

• results: list[Value]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Return all input Values including subclass-specific fields.

Generic passes should use this instead of accessing operands directly to ensure no Value is missed. Subclasses override this to include extra Value fields (e.g. ControlledUOperation.power).

replace_values¶

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

Return a copy with all Values substituted via mapping.

Handles operands, results, and subclass-specific Value fields. Subclasses override to handle their extra fields.

ReleaseSliceViewOperation [source]¶

class ReleaseSliceViewOperation(Operation)

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

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

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

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

Example:

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

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

Constructor¶

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

Attributes¶

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

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

ResourceMetadata [source]¶

class ResourceMetadata

Resource estimation metadata for composite gates.

Gate count fields mirror GateCount categories.

None semantics:

Fields left as None mean “unknown/unspecified”. During extraction, gate_counter treats None as 0, which may undercount resources if the true value is nonzero. To ensure accurate resource estimates, set all relevant fields explicitly.

When total_gates is set but some of single_qubit_gates, two_qubit_gates, or multi_qubit_gates are None, the extractor emits a UserWarning if the known sub-total is less than total_gates, indicating potentially missing gate category data.

Constructor¶

def __init__(
    self,
    query_complexity: int | None = None,
    t_gates: int | None = None,
    ancilla_qubits: int = 0,
    total_gates: int | None = None,
    single_qubit_gates: int | None = None,
    two_qubit_gates: int | None = None,
    multi_qubit_gates: int | None = None,
    clifford_gates: int | None = None,
    rotation_gates: int | None = None,
    custom_metadata: dict[str, Any] = dict(),
) -> None

Attributes¶

• ancilla_qubits: int

• clifford_gates: int | None

• custom_metadata: dict[str, Any]

• multi_qubit_gates: int | None

• query_complexity: int | None

• rotation_gates: int | None

• single_qubit_gates: int | None

• t_gates: int | None

• total_gates: int | None

• two_qubit_gates: int | None

ReturnOperation [source]¶

class ReturnOperation(Operation)

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

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

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

Example:

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

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

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

Constructor¶

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

Attributes¶

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

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

SliceArrayOperation [source]¶

class SliceArrayOperation(Operation)

Construct a strided view of an ArrayValue.

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

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

Example:

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

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

Constructor¶

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

Attributes¶

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

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

SymbolicControlledU [source]¶

class SymbolicControlledU(ControlledUOperation)

Controlled-U with symbolic (Value) number of controls.

Operand layout: [ctrl_arg_0, ..., ctrl_arg_{k-1}, tgt_0, ..., tgt_m, params...] Result layout: [ctrl_arg_0', ..., ctrl_arg_{k-1}', tgt_0', ..., tgt_m']

The number of control arguments k is recorded in num_control_args; the default k = 1 corresponds to the historical single-pool form (operands[0] is a Vector[Qubit] / VectorView whose length equals num_controls, or whose control_indices-selected subset does). When k > 1 the control prefix is a heterogeneous sequence of scalar Qubit values and ArrayValues whose total qubit count is num_controls; the emit pass walks them in order to recover the per-physical-qubit control set.

When control_indices is None the entire control prefix is used as active controls (one-arg form: len(ctrl_vector) == num_controls; multi-arg form: the qubit-count sum of the prefix args equals num_controls). When non-None, the listed indices select exactly num_controls slots from a single-arg pool to act as controls; combining control_indices with the multi-arg control prefix is rejected at frontend time.

Each control_indices entry is stored as a Value of UIntType regardless of whether the frontend passed an int literal or a UInt handle, so all downstream value-substitution passes see a uniform shape.

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    power: int | Value = 1,
    block: Block | None = None,
    num_controls: Value = (lambda: Value(type=(UIntType()), name=''))(),
    control_indices: tuple[Value, ...] | None = None,
    num_control_args: int = 1,
) -> None

Attributes¶

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

• control_operands: list[Value]

• is_symbolic_num_controls: bool

• num_control_args: int

• num_controls: Value

• param_operands: list[Value]

• signature: Signature

• target_operands: list[Value]

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

replace_values¶

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

qamomile.circuit.ir.operation.arithmetic_operations¶

Overview¶

Functions¶

runtime_kind_from_binop [source]¶

def runtime_kind_from_binop(kind: BinOpKind) -> RuntimeOpKind

Map a BinOpKind to its RuntimeOpKind counterpart.

runtime_kind_from_compop [source]¶

def runtime_kind_from_compop(kind: CompOpKind) -> RuntimeOpKind

Map a CompOpKind to its RuntimeOpKind counterpart.

runtime_kind_from_condop [source]¶

def runtime_kind_from_condop(kind: CondOpKind) -> RuntimeOpKind

Map a CondOpKind to its RuntimeOpKind counterpart.

Classes¶

BinOp [source]¶

class BinOp(BinaryOperationBase)

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

Constructor¶

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

Attributes¶

• kind: BinOpKind | None

• operation_kind: OperationKind

• signature: Signature

BinOpKind [source]¶

class BinOpKind(enum.Enum)

Attributes¶

• ADD

• DIV

• FLOORDIV

• MIN

• MOD

• MUL

• POW

• SUB

BinaryOperationBase [source]¶

class BinaryOperationBase(Operation)

Base for binary operations with lhs, rhs, and output.

Provides common properties and validation for operations that take two operands and produce one result.

Constructor¶

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

Attributes¶

• kind: enum.Enum | None

• lhs: Value Left-hand side operand.

• output: Value Output result.

• rhs: Value Right-hand side operand.

BitType [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

CompOp [source]¶

class CompOp(BinaryOperationBase)

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

Constructor¶

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

Attributes¶

• kind: CompOpKind | None

• operation_kind: OperationKind

• signature: Signature

CompOpKind [source]¶

class CompOpKind(enum.Enum)

Attributes¶

• EQ

• GE

• GT

• LE

• LT

• NEQ

CondOp [source]¶

class CondOp(BinaryOperationBase)

Conditional logical operation (AND, OR).

Constructor¶

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

Attributes¶

• kind: CondOpKind | None

• operation_kind: OperationKind

• signature: Signature

CondOpKind [source]¶

class CondOpKind(enum.Enum)

Attributes¶

• AND

• OR

NotOp [source]¶

class NotOp(Operation)

Constructor¶

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

Attributes¶

• input: Value

• operation_kind: OperationKind

• output: Value

• signature: Signature

Operation [source]¶

class Operation(abc.ABC)

Constructor¶

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

Attributes¶

• operands: list[Value]

• operation_kind: OperationKind Return the kind of this operation for classical/quantum classification.

• results: list[Value]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Return all input Values including subclass-specific fields.

Generic passes should use this instead of accessing operands directly to ensure no Value is missed. Subclasses override this to include extra Value fields (e.g. ControlledUOperation.power).

replace_values¶

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

Return a copy with all Values substituted via mapping.

Handles operands, results, and subclass-specific Value fields. Subclasses override to handle their extra fields.

OperationKind [source]¶

class OperationKind(enum.Enum)

Classification of operations for classical/quantum separation.

This enum is used to categorize operations during compilation to determine which parts run on classical hardware vs quantum hardware.

Values:

QUANTUM: Pure quantum operations (gates, qubit allocation) CLASSICAL: Pure classical operations (arithmetic, comparisons) HYBRID: Operations that bridge classical and quantum (measurement, encode/decode) CONTROL: Control flow structures (for, while, if)

Attributes¶

• CLASSICAL

• CONTROL

• HYBRID

• QUANTUM

ParamHint [source]¶

class ParamHint

Constructor¶

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

Attributes¶

• name: str

• type: ValueType

PhiOp [source]¶

class PhiOp(Operation)

SSA Phi function: merge point after conditional branch.

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

Example:

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

Constructor¶

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

Attributes¶

• condition: Value

• false_value: Value

• operation_kind: OperationKind

• output: Value

• signature: Signature

• true_value: Value

RuntimeClassicalExpr [source]¶

class RuntimeClassicalExpr(Operation)

A classical expression known to require runtime evaluation.

Lowered from CompOp / CondOp / NotOp / BinOp by ClassicalLoweringPass when the op’s operand dataflow traces back to a MeasureOperation (i.e. cannot be folded at compile-time, by emit-time loop unrolling, or by compile_time_if_lowering). Backend emit translates this 1:1 to a backend-native runtime expression (e.g. qiskit.circuit.classical.expr.Expr).

Operand convention:

• Binary kinds (EQ/NEQ/LT/LE/GT/GE/AND/OR/ADD/SUB/MUL/DIV/FLOORDIV/MOD/POW): operands = [lhs, rhs].

• Unary kind (NOT): operands = [val].

• Result: results = [output_value].

The single-node + unified-kind shape (vs four parallel subclasses) keeps the backend dispatch a single match op.kind instead of four parallel hooks, and makes the IR self-documenting: a single RuntimeClassicalExpr instance signals “runtime evaluation required” regardless of which classical family it came from.

Constructor¶

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

Attributes¶

• kind: RuntimeOpKind | None

• operation_kind: OperationKind

• signature: Signature

RuntimeOpKind [source]¶

class RuntimeOpKind(enum.Enum)

Unified kind for RuntimeClassicalExpr covering all classical op families that can appear at runtime.

The split between this enum and the per-family BinOpKind / CompOpKind / CondOpKind is intentional: compile-time-foldable classical ops keep their original IR types so the existing fold pipeline (constant_fold → compile_time_if_lowering → emit-time evaluate_classical_predicate) is undisturbed. Only ops identified as runtime-evaluation-only by ClassicalLoweringPass get rewritten to RuntimeClassicalExpr with a member of this enum.

Attributes¶

• ADD

• AND

• DIV

• EQ

• FLOORDIV

• GE

• GT

• LE

• LT

• MOD

• MUL

• NEQ

• NOT

• OR

• POW

• SUB

Signature [source]¶

class Signature

Constructor¶

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

Attributes¶

• operands: list[ParamHint | None]

• results: list[ParamHint]

Value [source]¶

class Value(_MetadataValueMixin, Generic[T])

A typed SSA value in the IR.

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

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

Constructor¶

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

Attributes¶

• element_indices: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

is_array_element¶

def is_array_element(self) -> bool

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version and fresh UUID.

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

qamomile.circuit.ir.operation.call_block_ops¶

Overview¶

Classes¶

Block [source]¶

class Block

Unified block representation for all pipeline stages.

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

Constructor¶

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

Attributes¶

• input_values: list[Value]

• kind: BlockKind

• label_args: list[str]

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[Value]

• param_slots: tuple[ParamSlot, ...]

• parameters: dict[str, Value]

Methods¶

call¶

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

Create a CallBlockOperation against this block.

is_affine¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

BlockType [source]¶

class BlockType(ObjectTypeMixin, ValueType)

Type representing a block/function reference.

CallBlockOperation [source]¶

class CallBlockOperation(Operation)

Constructor¶

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

Attributes¶

• block: Block | None

• operation_kind: OperationKind

• signature: Signature

Methods¶

is_self_reference_to¶

def is_self_reference_to(self, block: Block) -> bool

Return True if this call points to the given block (self-ref).

Operation [source]¶

class Operation(abc.ABC)

Constructor¶

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

Attributes¶

• operands: list[Value]

• operation_kind: OperationKind Return the kind of this operation for classical/quantum classification.

• results: list[Value]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Return all input Values including subclass-specific fields.

Generic passes should use this instead of accessing operands directly to ensure no Value is missed. Subclasses override this to include extra Value fields (e.g. ControlledUOperation.power).

replace_values¶

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

Return a copy with all Values substituted via mapping.

Handles operands, results, and subclass-specific Value fields. Subclasses override to handle their extra fields.

OperationKind [source]¶

class OperationKind(enum.Enum)

Classification of operations for classical/quantum separation.

This enum is used to categorize operations during compilation to determine which parts run on classical hardware vs quantum hardware.

Values:

QUANTUM: Pure quantum operations (gates, qubit allocation) CLASSICAL: Pure classical operations (arithmetic, comparisons) HYBRID: Operations that bridge classical and quantum (measurement, encode/decode) CONTROL: Control flow structures (for, while, if)

Attributes¶

• CLASSICAL

• CONTROL

• HYBRID

• QUANTUM

ParamHint [source]¶

class ParamHint

Constructor¶

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

Attributes¶

• name: str

• type: ValueType

Signature [source]¶

class Signature

Constructor¶

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

Attributes¶

• operands: list[ParamHint | None]

• results: list[ParamHint]

qamomile.circuit.ir.operation.cast¶

Cast operation for type conversions over the same quantum resources.

Overview¶

Classes¶

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

Operation [source]¶

class Operation(abc.ABC)

Constructor¶

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

Attributes¶

• operands: list[Value]

• operation_kind: OperationKind Return the kind of this operation for classical/quantum classification.

• results: list[Value]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Return all input Values including subclass-specific fields.

Generic passes should use this instead of accessing operands directly to ensure no Value is missed. Subclasses override this to include extra Value fields (e.g. ControlledUOperation.power).

replace_values¶

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

Return a copy with all Values substituted via mapping.

Handles operands, results, and subclass-specific Value fields. Subclasses override to handle their extra fields.

OperationKind [source]¶

class OperationKind(enum.Enum)

Classification of operations for classical/quantum separation.

This enum is used to categorize operations during compilation to determine which parts run on classical hardware vs quantum hardware.

Values:

QUANTUM: Pure quantum operations (gates, qubit allocation) CLASSICAL: Pure classical operations (arithmetic, comparisons) HYBRID: Operations that bridge classical and quantum (measurement, encode/decode) CONTROL: Control flow structures (for, while, if)

Attributes¶

• CLASSICAL

• CONTROL

• HYBRID

• QUANTUM

ParamHint [source]¶

class ParamHint

Constructor¶

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

Attributes¶

• name: str

• type: ValueType

Signature [source]¶

class Signature

Constructor¶

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

Attributes¶

• operands: list[ParamHint | None]

• results: list[ParamHint]

qamomile.circuit.ir.operation.classical_ops¶

Classical operations for quantum-classical hybrid programs.

Overview¶

Classes¶

BitType [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

DecodeQFixedOperation [source]¶

class DecodeQFixedOperation(Operation)

Decode measured bits to float (classical operation).

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

The decoding formula:

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

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

Example:

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

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

Constructor¶

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

Attributes¶

• int_bits: int

• num_bits: int

• operation_kind: OperationKind

• signature: Signature

FloatType [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

Operation [source]¶

class Operation(abc.ABC)

Constructor¶

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

Attributes¶

• operands: list[Value]

• operation_kind: OperationKind Return the kind of this operation for classical/quantum classification.

• results: list[Value]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Return all input Values including subclass-specific fields.

Generic passes should use this instead of accessing operands directly to ensure no Value is missed. Subclasses override this to include extra Value fields (e.g. ControlledUOperation.power).

replace_values¶

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

Return a copy with all Values substituted via mapping.

Handles operands, results, and subclass-specific Value fields. Subclasses override to handle their extra fields.

OperationKind [source]¶

class OperationKind(enum.Enum)

Classification of operations for classical/quantum separation.

This enum is used to categorize operations during compilation to determine which parts run on classical hardware vs quantum hardware.

Values:

QUANTUM: Pure quantum operations (gates, qubit allocation) CLASSICAL: Pure classical operations (arithmetic, comparisons) HYBRID: Operations that bridge classical and quantum (measurement, encode/decode) CONTROL: Control flow structures (for, while, if)

Attributes¶

• CLASSICAL

• CONTROL

• HYBRID

• QUANTUM

ParamHint [source]¶

class ParamHint

Constructor¶

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

Attributes¶

• name: str

• type: ValueType

Signature [source]¶

class Signature

Constructor¶

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

Attributes¶

• operands: list[ParamHint | None]

• results: list[ParamHint]

qamomile.circuit.ir.operation.composite_gate¶

CompositeGate operation for representing complex multi-gate operations.

Overview¶

Classes¶

Block [source]¶

class Block

Unified block representation for all pipeline stages.

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

Constructor¶

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

Attributes¶

• input_values: list[Value]

• kind: BlockKind

• label_args: list[str]

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[Value]

• param_slots: tuple[ParamSlot, ...]

• parameters: dict[str, Value]

Methods¶

call¶

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

Create a CallBlockOperation against this block.

is_affine¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

BlockType [source]¶

class BlockType(ObjectTypeMixin, ValueType)

Type representing a block/function reference.

CompositeGateOperation [source]¶

class CompositeGateOperation(Operation)

Represents a composite gate (QPE, QFT, etc.) as a single operation.

CompositeGate allows representing complex multi-gate operations as a single atomic operation in the IR. This enables:

• Resource estimation without full implementation

• Backend-native conversion (e.g., Qiskit’s QPE)

• User-defined complex gates

The operands structure is:

• operands[0:num_control_qubits]: Control qubits (if any)

• operands[num_control_qubits:num_control_qubits+num_target_qubits]: Target qubits

• operands[num_control_qubits+num_target_qubits:]: Parameters

The results structure:

• results[0:num_control_qubits]: Control qubits (returned)

• results[num_control_qubits:]: Target qubits (returned)

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
    num_control_qubits: int = 0,
    num_target_qubits: int = 0,
    custom_name: str = '',
    resource_metadata: ResourceMetadata | None = None,
    has_implementation: bool = True,
    implementation_block: Block | None = None,
    composite_gate_instance: Any = None,
    strategy_name: str | None = None,
) -> None

Attributes¶

• composite_gate_instance: Any

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

• custom_name: str

• gate_type: CompositeGateType

• has_implementation: bool

• implementation: Block | None Get the implementation block, if any.

• implementation_block: Block | None

• name: str Human-readable name of this composite gate.

• num_control_qubits: int

• num_target_qubits: int

• operation_kind: OperationKind Return the operation kind (always QUANTUM).

• parameters: list[‘Value’] Get the parameter operands (angles, etc.).

• resource_metadata: ResourceMetadata | None

• signature: Signature Return the operation signature.

• strategy_name: str | None

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

CompositeGateType [source]¶

class CompositeGateType(enum.Enum)

Registry of known composite gate types.

Attributes¶

• CUSTOM

• IQFT

• QFT

• QPE

Operation [source]¶

class Operation(abc.ABC)

Constructor¶

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

Attributes¶

• operands: list[Value]

• operation_kind: OperationKind Return the kind of this operation for classical/quantum classification.

• results: list[Value]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Return all input Values including subclass-specific fields.

Generic passes should use this instead of accessing operands directly to ensure no Value is missed. Subclasses override this to include extra Value fields (e.g. ControlledUOperation.power).

replace_values¶

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

Return a copy with all Values substituted via mapping.

Handles operands, results, and subclass-specific Value fields. Subclasses override to handle their extra fields.

OperationKind [source]¶

class OperationKind(enum.Enum)

Classification of operations for classical/quantum separation.

This enum is used to categorize operations during compilation to determine which parts run on classical hardware vs quantum hardware.

Values:

QUANTUM: Pure quantum operations (gates, qubit allocation) CLASSICAL: Pure classical operations (arithmetic, comparisons) HYBRID: Operations that bridge classical and quantum (measurement, encode/decode) CONTROL: Control flow structures (for, while, if)

Attributes¶

• CLASSICAL

• CONTROL

• HYBRID

• QUANTUM

ParamHint [source]¶

class ParamHint

Constructor¶

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

Attributes¶

• name: str

• type: ValueType

QubitType [source]¶

class QubitType(QuantumTypeMixin, ValueType)

Type representing a quantum bit (qubit).

ResourceMetadata [source]¶

class ResourceMetadata

Resource estimation metadata for composite gates.

Gate count fields mirror GateCount categories.

None semantics:

Fields left as None mean “unknown/unspecified”. During extraction, gate_counter treats None as 0, which may undercount resources if the true value is nonzero. To ensure accurate resource estimates, set all relevant fields explicitly.

When total_gates is set but some of single_qubit_gates, two_qubit_gates, or multi_qubit_gates are None, the extractor emits a UserWarning if the known sub-total is less than total_gates, indicating potentially missing gate category data.

Constructor¶

def __init__(
    self,
    query_complexity: int | None = None,
    t_gates: int | None = None,
    ancilla_qubits: int = 0,
    total_gates: int | None = None,
    single_qubit_gates: int | None = None,
    two_qubit_gates: int | None = None,
    multi_qubit_gates: int | None = None,
    clifford_gates: int | None = None,
    rotation_gates: int | None = None,
    custom_metadata: dict[str, Any] = dict(),
) -> None

Attributes¶

• ancilla_qubits: int

• clifford_gates: int | None

• custom_metadata: dict[str, Any]

• multi_qubit_gates: int | None

• query_complexity: int | None

• rotation_gates: int | None

• single_qubit_gates: int | None

• t_gates: int | None

• total_gates: int | None

• two_qubit_gates: int | None

Signature [source]¶

class Signature

Constructor¶

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

Attributes¶

• operands: list[ParamHint | None]

• results: list[ParamHint]

Value [source]¶

class Value(_MetadataValueMixin, Generic[T])

A typed SSA value in the IR.

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

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

Constructor¶

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

Attributes¶

• element_indices: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

is_array_element¶

def is_array_element(self) -> bool

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version and fresh UUID.

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

qamomile.circuit.ir.operation.control_flow¶

Overview¶

Classes¶

BitType [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

BlockType [source]¶

class BlockType(ObjectTypeMixin, ValueType)

Type representing a block/function reference.

ForItemsOperation [source]¶

class ForItemsOperation(HasNestedOps, Operation)

Represents iteration over dict/iterable items.

Example:

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

Constructor¶

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

Attributes¶

• key_is_vector: bool

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

• key_vars: list[str]

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

• value_var: str

• value_var_value: Value | None

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

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

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

nested_op_lists¶

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

rebuild_nested¶

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

replace_values¶

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

ForOperation [source]¶

class ForOperation(HasNestedOps, Operation)

Represents a for loop operation.

Example:

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

Constructor¶

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

Attributes¶

• loop_var: str

• loop_var_value: Value | None

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Include loop_var_value so cloning/substitution stays consistent.

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

nested_op_lists¶

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

rebuild_nested¶

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

replace_values¶

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

HasNestedOps [source]¶

class HasNestedOps

Mixin for operations that contain nested operation lists.

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

Methods¶

nested_op_lists¶

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

Return all nested operation lists in this control flow op.

rebuild_nested¶

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

Return a copy with nested operation lists replaced.

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

IfOperation [source]¶

class IfOperation(HasNestedOps, Operation)

Represents an if-else conditional operation.

Example:

if condition:
    true_body
else:
    false_body

Constructor¶

def __init__(
    self,
    operands: list[Value] = list(),
    results: list[Value] = list(),
    true_operations: list[Operation] = list(),
    false_operations: list[Operation] = list(),
    phi_ops: list[PhiOp] = list(),
) -> None

Attributes¶

• condition: Value

• false_operations: list[Operation]

• operation_kind: OperationKind

• phi_ops: list[PhiOp]

• signature: Signature

• true_operations: list[Operation]

Methods¶

nested_op_lists¶

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

rebuild_nested¶

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

Operation [source]¶

class Operation(abc.ABC)

Constructor¶

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

Attributes¶

• operands: list[Value]

• operation_kind: OperationKind Return the kind of this operation for classical/quantum classification.

• results: list[Value]

• signature: Signature

Methods¶

all_input_values¶

def all_input_values(self) -> list[ValueBase]

Return all input Values including subclass-specific fields.

Generic passes should use this instead of accessing operands directly to ensure no Value is missed. Subclasses override this to include extra Value fields (e.g. ControlledUOperation.power).

replace_values¶

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

Return a copy with all Values substituted via mapping.

Handles operands, results, and subclass-specific Value fields. Subclasses override to handle their extra fields.

OperationKind [source]¶

class OperationKind(enum.Enum)

Classification of operations for classical/quantum separation.

This enum is used to categorize operations during compilation to determine which parts run on classical hardware vs quantum hardware.

Values:

QUANTUM: Pure quantum operations (gates, qubit allocation) CLASSICAL: Pure classical operations (arithmetic, comparisons) HYBRID: Operations that bridge classical and quantum (measurement, encode/decode) CONTROL: Control flow structures (for, while, if)

Attributes¶

• CLASSICAL

• CONTROL

• HYBRID

• QUANTUM

ParamHint [source]¶

class ParamHint

Constructor¶

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

Attributes¶

• name: str

• type: ValueType

PhiOp [source]¶

class PhiOp(Operation)

SSA Phi function: merge point after conditional branch.

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

Example:

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

Constructor¶

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

Attributes¶

• condition: Value

• false_value: Value

• operation_kind: OperationKind

• output: Value

• signature: Signature

• true_value: Value

Signature [source]¶

class Signature

Constructor¶

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

Attributes¶

• operands: list[ParamHint | None]

• results: list[ParamHint]

UIntType [source]¶

class UIntType(ClassicalTypeMixin, ValueType)

Type representing an unsigned integer.

Value [source]¶

class Value(_MetadataValueMixin, Generic[T])

A typed SSA value in the IR.

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

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

Constructor¶

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

Attributes¶

• element_indices: tuple[Value, ...]

• logical_id: str

• metadata: ValueMetadata

• name: str

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

is_array_element¶

def is_array_element(self) -> bool

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version and fresh UUID.

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

ValueBase [source]¶

class ValueBase(Protocol)

Protocol for IR values with typed metadata.

Attributes are declared as read-only properties to match frozen dataclass fields in concrete implementations (Value, ArrayValue, etc.).

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• uuid: str

Methods¶

get_const¶

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

is_constant¶

def is_constant(self) -> bool

is_parameter¶

def is_parameter(self) -> bool

next_version¶

def next_version(self) -> ValueBase

parameter_name¶

def parameter_name(self) -> str | None

WhileOperation [source]¶

class WhileOperation(HasNestedOps, Operation)

Represents a while loop operation.

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

Example::

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

Constructor¶

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

Attributes¶

• max_iterations: int | None

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

Methods¶

nested_op_lists¶

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

rebuild_nested¶

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

qamomile.circuit.ir.operation.expval¶

Expectation value operation for computing <psi|H|psi>.

This module defines the ExpvalOp IR operation that represents computing the expectation value of a Hamiltonian observable with respect to a quantum state.

Overview¶

Classes¶

ExpvalOp [source]¶

class ExpvalOp(Operation)

Expectation value operation.

This operation computes the expectation value <psi|H|psi> where psi is the quantum state and H is the Hamiltonian observable.

The operation bridges quantum and classical computation:

• Input: quantum state (qubits) + Observable reference

• Output: classical Float (expectation value)

Example IR:

Constructor¶

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

Attributes¶

• hamiltonian: Value Alias for observable (deprecated, use observable instead).

• observable: Value The Observable parameter operand.

• operation_kind: OperationKind ExpvalOp is HYBRID - bridges quantum state to classical value.

• output: Value The expectation value result.

• qubits: Value The quantum register operand.

• signature: Signature