qamomile.circuit.ir

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 both BlockValue and Graph 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(),
    operations: list[Operation] = list(),
    kind: BlockKind = BlockKind.HIERARCHICAL,
    parameters: dict[str, Value] = dict(),
    _dependency_graph: dict[str, set[str]] | None = None,
) -> None

Attributes¶

• input_values: list[Value]

• kind: BlockKind

• label_args: list[str]

• name: str

• operations: list[Operation]

• output_values: list[Value]

• parameters: dict[str, Value]

Methods¶

from_block_value¶

@classmethod
def from_block_value(
    cls,
    block_value: 'BlockValue',
    parameters: dict[str, Value] | None = None,
) -> 'Block'

Create a Block from a BlockValue.

Parameters:

Returns:

'Block' — A new Block in HIERARCHICAL state

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

BlockValue [source]¶

class BlockValue(Value[BlockType])

Represents a subroutine as a function block.

def func_block(a: UInt, b: UInt) -> tuple[UInt]: ...

BlockValue( name=“func_block”, inputs_type={“a”: UIntType(), “b”: UIntType()}, outputs_type=(UIntType(), ), operations=[...], )

Function to BlockValue conversion can be done via func_to_block function. Each Values in operations are dummy values. The execution of the BlockValue is corresponding to the BlockOperation.

Constructor¶

def __init__(
    self,
    type: BlockType = BlockType(),
    name: str = '',
    version: int = 0,
    params: dict[str, Any] = dict(),
    uuid: str = (lambda: str(uuid.uuid4()))(),
    logical_id: str = (lambda: str(uuid.uuid4()))(),
    parent_array: ArrayValue | None = None,
    element_indices: tuple[Value, ...] = (),
    label_args: list[str] = list(),
    input_values: list[Value] = list(),
    return_values: list[Value] = list(),
    operations: list[Operation] = list(),
) -> None

Attributes¶

• input_values: list[Value]

• label_args: list[str]

• name: str

• operations: list[Operation]

• return_values: list[Value]

• type: BlockType

Methods¶

call¶

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

Create a CallBlockOperation to call this BlockValue.

Example:

block_value = BlockValue(
    name="func_block",
    inputs_type={"a": UIntType(), "b": UIntType()},
    outputs_type=(UIntType(), ),
    operations=[...],
)
a = Value(UIntType())
b = Value(UIntType())
call_op = block_value.call(a=a, b=b)

Value [source]¶

class Value(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

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

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.

qamomile.circuit.ir.block_value¶

Overview¶

Classes¶

BlockType [source]¶

class BlockType(ObjectTypeMixin, ValueType)

Type representing a block/function reference.

BlockValue [source]¶

class BlockValue(Value[BlockType])

Represents a subroutine as a function block.

def func_block(a: UInt, b: UInt) -> tuple[UInt]: ...

BlockValue( name=“func_block”, inputs_type={“a”: UIntType(), “b”: UIntType()}, outputs_type=(UIntType(), ), operations=[...], )

Function to BlockValue conversion can be done via func_to_block function. Each Values in operations are dummy values. The execution of the BlockValue is corresponding to the BlockOperation.

Constructor¶

def __init__(
    self,
    type: BlockType = BlockType(),
    name: str = '',
    version: int = 0,
    params: dict[str, Any] = dict(),
    uuid: str = (lambda: str(uuid.uuid4()))(),
    logical_id: str = (lambda: str(uuid.uuid4()))(),
    parent_array: ArrayValue | None = None,
    element_indices: tuple[Value, ...] = (),
    label_args: list[str] = list(),
    input_values: list[Value] = list(),
    return_values: list[Value] = list(),
    operations: list[Operation] = list(),
) -> None

Attributes¶

• input_values: list[Value]

• label_args: list[str]

• name: str

• operations: list[Operation]

• return_values: list[Value]

• type: BlockType

Methods¶

call¶

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

Create a CallBlockOperation to call this BlockValue.

Example:

block_value = BlockValue(
    name="func_block",
    inputs_type={"a": UIntType(), "b": UIntType()},
    outputs_type=(UIntType(), ),
    operations=[...],
)
a = Value(UIntType())
b = Value(UIntType())
call_op = block_value.call(a=a, b=b)

CallBlockOperation [source]¶

class CallBlockOperation(Operation)

Constructor¶

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

Attributes¶

• operation_kind: OperationKind

• signature: Signature

Value [source]¶

class Value(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

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

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.

qamomile.circuit.ir.graph¶

Overview¶

Classes¶

Graph [source]¶

class Graph

Represents a traced computation graph.

A Graph is the result of building a QKernel with concrete parameters. It contains the list of operations and can be used for:

• Resource estimation

• Transpilation to various backends

• Visualization

Constructor¶

def __init__(
    self,
    operations: list[Operation],
    input_values: list[Value] = list(),
    output_values: list[Value] = list(),
    output_names: list[str] = list(),
    name: str = '',
    parameters: dict[str, Value] = dict(),
) -> None

Attributes¶

• input_values: list[Value]

• name: str

• operations: list[Operation]

• output_names: list[str]

• output_values: list[Value]

• parameters: dict[str, Value]

Methods¶

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

qamomile.circuit.ir.graph.graph¶

Overview¶

Classes¶

Graph [source]¶

class Graph

Represents a traced computation graph.

A Graph is the result of building a QKernel with concrete parameters. It contains the list of operations and can be used for:

• Resource estimation

• Transpilation to various backends

• Visualization

Constructor¶

def __init__(
    self,
    operations: list[Operation],
    input_values: list[Value] = list(),
    output_values: list[Value] = list(),
    output_names: list[str] = list(),
    name: str = '',
    parameters: dict[str, Value] = dict(),
) -> None

Attributes¶

• input_values: list[Value]

• name: str

• operations: list[Operation]

• output_names: list[str]

• output_values: list[Value]

• parameters: dict[str, Value]

Methods¶

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

Value [source]¶

class Value(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

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

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.

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 depends on has_implementation:

• If has_implementation=True:

  • operands[0]: BlockValue (the implementation)

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

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

  • operands[1+num_control_qubits+num_target_qubits:]: Parameters

• If has_implementation=False (stub):

  • 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,
    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: ‘BlockValue | None’ Get the implementation BlockValue, if any.

• 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

ControlledUOperation [source]¶

class ControlledUOperation(Operation)

Controlled-U operation that applies a unitary block conditionally.

The operands structure is:

• operands[0]: BlockValue (the unitary U to apply)

• operands[1:1+num_controls]: Control qubits

• operands[1+num_controls:]: Target qubits (arguments to U)

The results structure is:

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

• results[num_controls:]: Target qubits (returned from U)

Constructor¶

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

Attributes¶

• block Get the BlockValue (unitary U).

• control_operands Get the control qubit values.

• controlled_indices: list[Value] | None

• has_index_spec: bool Whether target/control positions are specified via index lists.

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

• num_controls: int | Value

• operation_kind: OperationKind

• param_operands Get parameter operands (non-qubit, non-block).

• power: int | Value

• signature: Signature

• target_indices: list[Value] | None

• target_operands Get the target qubit values (arguments to U).

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

Attributes¶

• key_is_vector: bool

• key_vars: list[str]

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

• value_var: str

GateOperation [source]¶

class GateOperation(Operation)

Constructor¶

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

Attributes¶

• gate_type: GateOperationType | None

• operation_kind: OperationKind

• signature: Signature

• theta: float | Value | None

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

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

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.

qamomile.circuit.ir.operation.arithmetic_operations¶

Overview¶

Classes¶

BinOp [source]¶

class BinOp(BinaryOperationBase)

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

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

• 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

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]

Value [source]¶

class Value(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

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

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.

qamomile.circuit.ir.operation.call_block_ops¶

Overview¶

Classes¶

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

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

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

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¶

BlockType [source]¶

class BlockType(ObjectTypeMixin, ValueType)

Type representing a block/function reference.

BlockValue [source]¶

class BlockValue(Value[BlockType])

Represents a subroutine as a function block.

def func_block(a: UInt, b: UInt) -> tuple[UInt]: ...

BlockValue( name=“func_block”, inputs_type={“a”: UIntType(), “b”: UIntType()}, outputs_type=(UIntType(), ), operations=[...], )

Function to BlockValue conversion can be done via func_to_block function. Each Values in operations are dummy values. The execution of the BlockValue is corresponding to the BlockOperation.

Constructor¶

def __init__(
    self,
    type: BlockType = BlockType(),
    name: str = '',
    version: int = 0,
    params: dict[str, Any] = dict(),
    uuid: str = (lambda: str(uuid.uuid4()))(),
    logical_id: str = (lambda: str(uuid.uuid4()))(),
    parent_array: ArrayValue | None = None,
    element_indices: tuple[Value, ...] = (),
    label_args: list[str] = list(),
    input_values: list[Value] = list(),
    return_values: list[Value] = list(),
    operations: list[Operation] = list(),
) -> None

Attributes¶

• input_values: list[Value]

• label_args: list[str]

• name: str

• operations: list[Operation]

• return_values: list[Value]

• type: BlockType

Methods¶

call¶

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

Create a CallBlockOperation to call this BlockValue.

Example:

block_value = BlockValue(
    name="func_block",
    inputs_type={"a": UIntType(), "b": UIntType()},
    outputs_type=(UIntType(), ),
    operations=[...],
)
a = Value(UIntType())
b = Value(UIntType())
call_op = block_value.call(a=a, b=b)

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 depends on has_implementation:

• If has_implementation=True:

  • operands[0]: BlockValue (the implementation)

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

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

  • operands[1+num_control_qubits+num_target_qubits:]: Parameters

• If has_implementation=False (stub):

  • 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,
    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: ‘BlockValue | None’ Get the implementation BlockValue, if any.

• 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

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(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

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

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.

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

Attributes¶

• key_is_vector: bool

• key_vars: list[str]

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

• value_var: str

ForOperation [source]¶

class ForOperation(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 = '',
    operations: list[Operation] = list(),
) -> None

Attributes¶

• loop_var: str

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

IfOperation [source]¶

class IfOperation(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]

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

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(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

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

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.

WhileOperation [source]¶

class WhileOperation(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(),
) -> None

Attributes¶

• operation_kind: OperationKind

• operations: list[Operation]

• signature: Signature

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

FloatType [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

ObservableType [source]¶

class ObservableType(ObjectTypeMixin, ValueType)

Type representing a Hamiltonian observable parameter.

This is a reference type - the actual qamomile.observable.Hamiltonian is provided via bindings during transpilation. It cannot be constructed or manipulated within qkernels.

Example usage:

import qamomile.circuit as qm
import qamomile.observable as qm_o

# Build Hamiltonian in Python
H = qm_o.Z(0) * qm_o.Z(1)

@qm.qkernel
def vqe(q: qm.Vector[qm.Qubit], H: qm.Observable) -> qm.Float:
    return qm.expval(q, H)

# H is passed as binding
executable = transpiler.transpile(vqe, bindings={"H": H})

Constructor¶

def __init__(self) -> None

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

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]

Value [source]¶

class Value(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

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

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.

qamomile.circuit.ir.operation.gate¶

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.

ControlledUOperation [source]¶

class ControlledUOperation(Operation)

Controlled-U operation that applies a unitary block conditionally.

The operands structure is:

• operands[0]: BlockValue (the unitary U to apply)

• operands[1:1+num_controls]: Control qubits

• operands[1+num_controls:]: Target qubits (arguments to U)

The results structure is:

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

• results[num_controls:]: Target qubits (returned from U)

Constructor¶

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

Attributes¶

• block Get the BlockValue (unitary U).

• control_operands Get the control qubit values.

• controlled_indices: list[Value] | None

• has_index_spec: bool Whether target/control positions are specified via index lists.

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

• num_controls: int | Value

• operation_kind: OperationKind

• param_operands Get parameter operands (non-qubit, non-block).

• power: int | Value

• signature: Signature

• target_indices: list[Value] | None

• target_operands Get the target qubit values (arguments to U).

FloatType [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

GateOperation [source]¶

class GateOperation(Operation)

Constructor¶

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

Attributes¶

• gate_type: GateOperationType | None

• operation_kind: OperationKind

• signature: Signature

• theta: float | Value | None

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

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

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

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(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

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

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.

qamomile.circuit.ir.operation.operation¶

Overview¶

Classes¶

CInitOperation [source]¶

class CInitOperation(Operation)

Initialize the classical values (const, arguments etc)

Constructor¶

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

Attributes¶

• operation_kind: OperationKind

• signature: Signature

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

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

QInitOperation [source]¶

class QInitOperation(Operation)

Initialize the qubit

Constructor¶

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

Attributes¶

• operation_kind: OperationKind

• signature: Signature

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(Generic[T])

A typed value in the IR with SSA-style versioning.

Value represents a single typed value (qubit, float, int, bit, etc.) with support for:

• SSA versioning via uuid/logical_id

• Parameter binding

• Constant folding

• Array element tracking

Constructor¶

def __init__(
    self,
    type: T,
    name: str,
    version: int = 0,
    params: dict[str, Any] = dict(),
    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

• name: str

• params: dict[str, Any]

• parent_array: ArrayValue | None

• type: T

• uuid: str

• version: int

Methods¶

get_cast_qubit_logical_ids¶

def get_cast_qubit_logical_ids(self) -> list[str] | None

Get the underlying qubit logical_ids for this cast value.

get_cast_qubit_uuids¶

def get_cast_qubit_uuids(self) -> list[str] | None

Get the underlying qubit UUIDs for this cast value.

get_cast_source_logical_id¶

def get_cast_source_logical_id(self) -> str | None

Get the source value logical_id if this is a cast result.

get_cast_source_uuid¶

def get_cast_source_uuid(self) -> str | None

Get the source value UUID if this is a cast result.

get_const¶

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

Get constant value if available, otherwise None.

get_lowered_bits¶

def get_lowered_bits(self) -> list[Value] | None

Get lowered bit list if available, otherwise None.

get_lowered_qubits¶

def get_lowered_qubits(self) -> list[Value] | None

Get lowered qubit list if available, otherwise None.

is_array_element¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

is_cast_result¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

is_constant¶

def is_constant(self) -> bool

Check if this value is a constant.

is_parameter¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

next_version¶

def next_version(self) -> Value[T]

Create a new Value with incremented version (SSA style).

parameter_name¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter, otherwise None.

set_cast_metadata¶

def set_cast_metadata(
    self,
    source_uuid: str,
    qubit_uuids: list[str],
    source_logical_id: str | None = None,
    qubit_logical_ids: list[str] | None = None,
) -> None

Set cast metadata for this value.

set_lowered_bits¶

def set_lowered_bits(self, bits: list[Value]) -> None

Set lowered bit list.

set_lowered_qubits¶

def set_lowered_qubits(self, qubits: list[Value]) -> None

Set lowered qubit list.

qamomile.circuit.ir.operation.return_operation¶

Return operation for explicit block termination.

Overview¶

Classes¶

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

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

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.

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.types¶

qamomile.circuit.ir.types module.

qamomile.circuit.ir.types is most fundamental module defining types used in Qamomile IR.

Overview¶

Classes¶

BitType [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

DictType [source]¶

class DictType(ClassicalTypeMixin, ValueType)

Type representing a dictionary mapping keys to values.

Unlike simple types, DictType stores the key and value types, so equality and hashing depend on those types. When key_type and value_type are None, represents a generic Dict type.

Constructor¶

def __init__(
    self,
    key_type: ValueType | None = None,
    value_type: ValueType | None = None,
) -> None

Attributes¶

• key_type: ValueType | None

• value_type: ValueType | None

Methods¶

label¶

def label(self) -> str

FloatType [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

ObservableType [source]¶

class ObservableType(ObjectTypeMixin, ValueType)

Type representing a Hamiltonian observable parameter.

This is a reference type - the actual qamomile.observable.Hamiltonian is provided via bindings during transpilation. It cannot be constructed or manipulated within qkernels.

Example usage:

import qamomile.circuit as qm
import qamomile.observable as qm_o

# Build Hamiltonian in Python
H = qm_o.Z(0) * qm_o.Z(1)

@qm.qkernel
def vqe(q: qm.Vector[qm.Qubit], H: qm.Observable) -> qm.Float:
    return qm.expval(q, H)

# H is passed as binding
executable = transpiler.transpile(vqe, bindings={"H": H})

Constructor¶

def __init__(self) -> None

QFixedType [source]¶

class QFixedType(QuantumTypeMixin, ValueType)

Quantum fixed-point type.

Represents a quantum register encoding a fixed-point number with specified integer and fractional bits.

Constructor¶

def __init__(
    self,
    integer_bits: int | Value[UIntType] = 0,
    fractional_bits: int | Value[UIntType] = 0,
) -> None

Attributes¶