qamomile.circuit.frontend

qamomile.circuit.frontend.ast_transform¶

Overview¶

Function	Description
`collect_quantum_rebind_violations`	Analyze func for forbidden quantum rebind patterns.
`emit_if`	Builder function for if-else conditional with Phi function merging.
`for_items`	Builder function to create a for-items loop in Qamomile frontend.
`for_loop`	Builder function to create a for loop in Qamomile frontend.
`transform_control_flow`
`while_loop`	Create a while loop whose condition is a measurement result.

Class	Description
`ControlFlowTransformer`
`QuantumRebindAnalyzer`	Detects forbidden quantum variable reassignment at the AST level.
`RebindViolation`	A detected forbidden quantum variable rebinding.
`VariableCollector`	ブロック内で使用・変更される変数を収集します。

Functions¶

`collect_quantum_rebind_violations` [source]¶

def collect_quantum_rebind_violations(func: Callable, quantum_param_names: set[str]) -> list[RebindViolation]

Analyze func for forbidden quantum rebind patterns.

Returns a (possibly empty) list of violations. Never raises on analysis failure – returns [] instead.

`emit_if` [source]¶

def emit_if(
    cond_func: Callable,
    true_func: Callable,
    false_func: Callable,
    variables: list,
) -> Any

Builder function for if-else conditional with Phi function merging.

This function is called from AST-transformed code. The AST transformer converts: if condition: true_body else: false_body

Into:

def _cond_N(vars): return condition def _body_N(vars): true_body; return vars def _body_N+1(vars): false_body; return vars result = emit_if(_cond_N, _body_N, _body_N+1, [var_list])

Parameters:

Name	Type	Description
`cond_func`	`typing.Callable`	Function returning the condition (Bit or bool-like Handle)
`true_func`	`typing.Callable`	Function executing true branch, returns updated variables
`false_func`	`typing.Callable`	Function executing false branch, returns updated variables
`variables`	`list`	List of variables used in the branches

Returns:

typing.Any — Merged variable values after conditional execution (using Phi functions)

Example:

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

`for_items` [source]¶

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

Builder function to create a for-items loop in Qamomile frontend.

This context manager creates a ForItemsOperation that iterates over dictionary (key, value) pairs. The operation is always unrolled at transpile time since quantum backends cannot natively iterate over classical data structures.

Parameters:

Name	Type	Description
`d`	`Dict`	Dict handle to iterate over
`key_var_names`	`list[str]`	Names of key unpacking variables (e.g., [“i”, “j”] for tuple keys)
`value_var_name`	`str`	Name of value variable (e.g., “Jij”)

Yields:

tuple[typing.Any, typing.Any] — Tuple of (key_handles, value_handle) for use in loop body

Example:

@qkernel
def ising_cost(
    q: Vector[Qubit],
    ising: Dict[Tuple[UInt, UInt], Float],
    gamma: Float,
) -> Vector[Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

`for_loop` [source]¶

def for_loop(
    start,
    stop,
    step = 1,
    var_name: str = '_loop_idx',
) -> Generator[UInt, None, None]

Builder function to create a for loop in Qamomile frontend.

Parameters:

Name	Type	Description
`start`	``	Loop start value (can be Handle or int)
`stop`	``	Loop stop value (can be Handle or int)
`step`	``	Loop step value (default=1)
`var_name`	`str`	Name of the loop variable (default=“_loop_idx”)

Yields:

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

Example:

@QKernel
def my_kernel(qubits: Array[Qubit, Literal[3]]) -> Array[Qubit, Literal[3]]:
    for i in qm.range(3):
        qubits[i] = h(qubits[i])
    return qubits

@QKernel
def my_kernel2(qubits: Array[Qubit, Literal[5]]) -> Array[Qubit, Literal[5]]:
    for i in qm.range(1, 4):  # i = 1, 2, 3
        qubits[i] = h(qubits[i])
    return qubits

`transform_control_flow` [source]¶

def transform_control_flow(func: Callable)

`while_loop` [source]¶

def while_loop(cond: Callable) -> Generator[WhileLoop, None, None]

Create a while loop whose condition is a measurement result.

The condition must be a Bit produced by qmc.measure(). Non-measurement conditions (classical variables, constants, comparisons) are accepted at build time but will be rejected by ValidateWhileContractPass during transpilation.

Parameters:

Name	Type	Description
`cond`	`typing.Callable`	A callable (lambda) that returns the loop condition. Must return a `Bit` handle originating from `qmc.measure()`.

Yields:

WhileLoop — A marker object for the while loop context.

Example::

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

Classes¶

`ControlFlowTransformer` [source]¶

class ControlFlowTransformer(ast.NodeTransformer)

Constructor¶

def __init__(
    self,
    global_names: set[str] | None = None,
    param_names: set[str] | None = None,
    namespace: dict[str, Any] | None = None,
) -> None

Attributes¶

counter: int
for_func_name
if_func_name
type_registry: dict[str, ast.AST]
while_func_name

Methods¶

`visit_AnnAssign`¶

def visit_AnnAssign(self, node: ast.AnnAssign) -> Any

a: int = 0 のような型注釈付き代入を検出し、型情報を登録します。

`visit_For`¶

def visit_For(self, node: ast.For) -> Any

`visit_FunctionDef`¶

def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef

Process the function body with definition tracking.

Collects parameter names as the initial set of defined variables and delegates to _visit_body_with_tracking for sequential statement processing.

`visit_If`¶

def visit_If(self, node: ast.If) -> Any

`visit_While`¶

def visit_While(self, node: ast.While) -> Any

`QuantumRebindAnalyzer` [source]¶

class QuantumRebindAnalyzer(ast.NodeVisitor)

Detects forbidden quantum variable reassignment at the AST level.

Forbidden patterns (target is an existing quantum variable):

a = b where b is quantum with a different origin
a = f(b, ...) where b is quantum with a different origin

Allowed patterns:

a = f(a, ...) (self-update)
new = f(b, ...) (new binding – target was not quantum before)
alias = q (new alias – target was not quantum before)

Constructor¶

def __init__(self, quantum_param_names: set[str]) -> None

Attributes¶

quantum_vars: dict[str, str]
violations: list[RebindViolation]

Methods¶

`visit_Assign`¶

def visit_Assign(self, node: ast.Assign) -> None

`RebindViolation` [source]¶

class RebindViolation

A detected forbidden quantum variable rebinding.

Constructor¶

def __init__(
    self,
    target_name: str,
    source_name: str,
    func_name: str | None,
    lineno: int,
) -> None

Attributes¶

func_name: str | None
lineno: int
source_name: str
target_name: str

`VariableCollector` [source]¶

class VariableCollector(ast.NodeVisitor)

ブロック内で使用・変更される変数を収集します。

以下を除外:

関数呼び出しの関数名 (func in Call)
属性アクセスのグローバルなベースオブジェクト (value in Attribute)
グローバル変数（モジュール、組み込み関数など）

Constructor¶

def __init__(self, global_names: set[str] | None = None)

Attributes¶

incoming_vars: set[str] 外部スコープから渡される必要がある変数（初回が Load）。
load_vars: set[str] Load コンテキストで参照される変数（実際に読まれる変数）。
locally_defined_vars: set[str] このスコープ内で初めて定義（Store）される変数。
store_vars: set[str] Store コンテキストで代入される変数。
vars

Methods¶

`visit_Assign`¶

def visit_Assign(self, node: ast.Assign)

右辺を先に走査し、Python の評価順序に合わせる。

q1 = qm.h(q1) → 右辺 q1 (Load) が先 → first_context は “Load” cond2 = qm.measure(q2) → 右辺 q2 (Load) が先、左辺 cond2 (Store) が後

`visit_Attribute`¶

def visit_Attribute(self, node: ast.Attribute)

属性アクセスのベース名を記録する。

モジュール名などグローバル名 (qm.h) は従来どおり除外し、ユーザー変数 (qs.shape) は Load として扱う。

`visit_AugAssign`¶

def visit_AugAssign(self, node: ast.AugAssign)

AugAssign (e.g. x += 1) は暗黙の Read-before-Write。

右辺を先に走査し、Name ターゲットは Load + Store として記録する。 first_context は “Load”（既存値の読み出しが先行するため）。

`visit_Call`¶

def visit_Call(self, node: ast.Call)

関数呼び出しの関数名を除外

`visit_FunctionDef`¶

def visit_FunctionDef(self, node: ast.FunctionDef)

内部関数定義の走査をスキップする。

`visit_Name`¶

def visit_Name(self, node: ast.Name)

変数名を収集（除外リストにないもののみ）

qamomile.circuit.frontend.composite_gate¶

Frontend interface for composite gates.

Overview¶

Function	Description
`composite_gate`	Decorator to create a CompositeGate from a qkernel function or as a stub.
`get_current_tracer`
`trace`	Context manager to set the current tracer.

Class	Description
`BlockValue`	Represents a subroutine as a function block.
`CompositeGate`	Base class for user-facing composite gate definitions.
`CompositeGateOperation`	Represents a composite gate (QPE, QFT, etc.) as a single operation.
`CompositeGateType`	Registry of known composite gate types.
`DecompositionStrategy`	Protocol for defining decomposition strategies.
`Qubit`
`ResourceMetadata`	Resource estimation metadata for composite gates.
`Tracer`
`Value`	A typed value in the IR with SSA-style versioning.
`Vector`	1-dimensional array type.

Functions¶

`composite_gate` [source]¶

def composite_gate(
    func: Callable | None = None,
    *,
    stub: bool = False,
    name: str = '',
    num_qubits: int | None = None,
    num_controls: int = 0,
    resource_metadata: ResourceMetadata | None = None,
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
) -> _WrappedCompositeGate | _StubCompositeGate | Callable[[Callable], _WrappedCompositeGate | _StubCompositeGate]

Decorator to create a CompositeGate from a qkernel function or as a stub.

Usage with qkernel (implementation provided): composite_gate [source](name=“my_qft”) qkernel [source] def my_qft(q0: Qubit, q1: Qubit) -> tuple[Qubit, Qubit]: q0 = h(q0) q0, q1 = cp(q0, q1, pi/2) q1 = h(q1) return q0, q1

# Usage:
q0, q1 = my_qft(q0, q1)

Usage as stub (no implementation, for resource estimation): composite_gate [source]( stub=True, name=“oracle”, num_qubits=5, resource_metadata=ResourceMetadata(query_complexity=100, t_gates=10), ) def oracle(): pass

# Usage:
results = oracle(*qubits)
metadata = oracle.get_resource_metadata()

Parameters:

Name	Type	Description
`func`	`Callable \| None`	The qkernel function (when used without arguments)
`stub`	`bool`	If True, create a stub gate with no implementation
`name`	`str`	Name for the composite gate
`num_qubits`	`int \| None`	Number of target qubits (required for stub)
`num_controls`	`int`	Number of control qubits (default: 0)
`resource_metadata`	`ResourceMetadata \| None`	ResourceMetadata for resource estimation (stub mode)
`gate_type`	`CompositeGateType`	The type of composite gate (default: CUSTOM)

Returns:

_WrappedCompositeGate | _StubCompositeGate | Callable[[Callable], _WrappedCompositeGate | _StubCompositeGate] — A CompositeGate instance that can be called like a gate function.

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

`trace` [source]¶

def trace(tracer: Tracer | None = None) -> Generator[Tracer, None, None]

Context manager to set the current tracer.

Classes¶

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

`CompositeGate` [source]¶

class CompositeGate(abc.ABC)

Base class for user-facing composite gate definitions.

Subclasses can define composite gates in two ways:

Using _decompose() (recommended for users): Define the gate decomposition using frontend syntax (same as qkernel [source]).

class QFT(CompositeGate):
    def __init__(self, num_qubits: int):
        self._num_qubits = num_qubits

    @property
    def num_target_qubits(self) -> int:
        return self._num_qubits

    def _decompose(self, qubits: Vector[Qubit]) -> Vector[Qubit]:
        # Use frontend syntax: qm.h(), qm.cp(), qm.range(), etc.
        n = self._num_qubits
        for j in qmc.range(n - 1, -1, -1):
            qubits[j] = qmc.h(qubits[j])
            for k in qmc.range(j - 1, -1, -1):
                angle = math.pi / (2 ** (j - k))
                qubits[j], qubits[k] = qmc.cp(qubits[j], qubits[k], angle)
        return qubits

    def _resources(self) -> ResourceMetadata:
        return ResourceMetadata(t_gates=0)

Using get_implementation() (advanced): Return a pre-built BlockValue directly.

Example usage:

# Factory function pattern
def qft(qubits: Vector[Qubit]) -> Vector[Qubit]:
    n = _get_size(qubits)
    return QFT(n)(qubits)

# Direct class usage
result = QFT(3)(*qubit_list)

Attributes¶

custom_name: str
gate_type: CompositeGateType
num_control_qubits: int Number of control qubits (default: 0).
num_target_qubits: int Number of target qubits this gate operates on.

Methods¶

`build_decomposition`¶

def build_decomposition(self, *qubits: Qubit = (), **params: Any = {}) -> 'BlockValue | None'

Build the decomposition circuit dynamically.

Override this method to provide a decomposition that depends on runtime arguments (e.g., QPE needs the unitary BlockValue).

This method is called by InlinePass when inlining composite gates that have dynamic implementations.

Parameters:

Name	Type	Description
`*qubits`	`Qubit`	The qubits passed to the gate
`**params`	`Any`	Additional parameters (e.g., unitary for QPE)

Returns:

'BlockValue | None' — BlockValue containing the decomposition, or None if not available.

Example:

class QPE(CompositeGate):
    def build_decomposition(self, *qubits, **params):
        unitary = params.get("unitary")
        # Build QPE circuit using the unitary
        return self._build_qpe_impl(qubits, unitary)

`get_implementation`¶

def get_implementation(self) -> 'BlockValue | None'

Get the implementation BlockValue, if any.

Return None for stub gates (used in resource estimation). Override in subclasses to provide implementation.

Note: If _decompose() is defined, it takes precedence over this method.

`get_resource_metadata`¶

def get_resource_metadata(self) -> ResourceMetadata | None

Get resource estimation metadata.

Returns _resources() if defined, otherwise None. Override _resources() to provide resource hints.

`get_resources_for_strategy`¶

def get_resources_for_strategy(self, strategy_name: str | None = None) -> ResourceMetadata | None

Get resource metadata for a specific strategy.

Parameters:

Name	Type	Description
`strategy_name`	`str \| None`	Strategy to query, or None for default

Returns:

ResourceMetadata | None — ResourceMetadata for the strategy, or None if not available

`get_strategy`¶

@classmethod
def get_strategy(cls, name: str | None = None) -> 'DecompositionStrategy | None'

Get a registered decomposition strategy.

Parameters:

Name	Type	Description
`name`	`str \| None`	Strategy name, or None for default strategy

Returns:

'DecompositionStrategy | None' — DecompositionStrategy instance, or None if not found

`list_strategies`¶

@classmethod
def list_strategies(cls) -> list[str]

List all registered strategy names.

Returns:

list[str] — List of strategy names

`register_strategy`¶

@classmethod
def register_strategy(cls, name: str, strategy: 'DecompositionStrategy') -> None

Parameters:

Name	Type	Description
`name`	`str`	Strategy identifier (e.g., “standard”, “approximate”)
`strategy`	`'DecompositionStrategy'`	DecompositionStrategy instance

Example:

QFT.register_strategy("approximate", ApproximateQFTStrategy(k=3))

`set_default_strategy`¶

@classmethod
def set_default_strategy(cls, name: str) -> None

Set the default decomposition strategy.

Parameters:

Name	Type	Description
`name`	`str`	Strategy name to use as default

Raises:

ValueError — If strategy is not registered

`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

`DecompositionStrategy` [source]¶

class DecompositionStrategy(Protocol)

Protocol for defining decomposition strategies.

A decomposition strategy provides:

A unique name for identification
A decompose method that performs the actual decomposition
Resource estimation for the decomposition

Strategies allow the same composite gate to have multiple implementations with different trade-offs (e.g., precision vs. gate count).

Attributes¶

name: str Unique identifier for this strategy.

Methods¶

`decompose`¶

def decompose(self, qubits: tuple['Qubit', ...]) -> tuple['Qubit', ...]

Perform the decomposition.

Parameters:

Name	Type	Description
`qubits`	`tuple['Qubit', ...]`	Input qubits to decompose

Returns:

tuple['Qubit', ...] — Output qubits after decomposition

`resources`¶

def resources(self, num_qubits: int) -> 'ResourceMetadata'

Return resource estimates for this decomposition.

Parameters:

Name	Type	Description
`num_qubits`	`int`	Number of qubits the gate operates on

Returns:

'ResourceMetadata' — ResourceMetadata with gate counts, depth estimates, etc.

`Qubit` [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QubitType]

`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

`Tracer` [source]¶

class Tracer

Constructor¶

def __init__(self, _operations: list[Operation] = list()) -> None

Attributes¶

operations: list[Operation]

Methods¶

`add_operation`¶

def add_operation(self, op) -> None

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

`Vector` [source]¶

class Vector(ArrayBase[T])

1-dimensional array type.

Example:

import qamomile.circuit as qmc

# Create a vector of 3 qubits
qubits: qmc.Vector[qmc.Qubit] = qmc.qubit_array(3, name="qubits")

# Access elements
q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0

# Apply H gate to all qubits (CORRECT)
n = qubits.shape[0]
for i in qmc.range(n):
    qubits[i] = qmc.h(qubits[i])

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

qamomile.circuit.frontend.constructors¶

Overview¶

Function	Description
`bit`	Create a Bit handle from a boolean/int literal or declare a named Bit parameter.
`float_`	Create a Float handle from a float literal or declare a named Float parameter.
`get_current_tracer`
`qubit`	Create a new qubit and emit a QInitOperation.
`qubit_array`	Create a new qubit array (vector/matrix/tensor) and emit QInitOperations.
`uint`	Create a UInt handle from an integer literal or declare a named UInt parameter.

Class	Description
`ArrayValue`	An array of values with shape information.
`QInitOperation`	Initialize the qubit
`Value`	A typed value in the IR with SSA-style versioning.

Functions¶

`bit` [source]¶

def bit(arg: bool | str | int) -> Bit

Create a Bit handle from a boolean/int literal or declare a named Bit parameter.

`float_` [source]¶

def float_(arg: float | str) -> Float

Create a Float handle from a float literal or declare a named Float parameter.

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

`qubit` [source]¶

def qubit(name: str) -> Qubit

Create a new qubit and emit a QInitOperation.

`qubit_array` [source]¶

def qubit_array(
    shape: UInt | int | tuple[UInt | int, ...],
    name: str,
) -> Vector[Qubit] | Matrix[Qubit] | Tensor[Qubit]

Create a new qubit array (vector/matrix/tensor) and emit QInitOperations.

`uint` [source]¶

def uint(arg: int | str) -> UInt

Create a UInt handle from an integer literal or declare a named UInt parameter.

Classes¶

`ArrayValue` [source]¶

class ArrayValue(Value[T])

An array of values with shape information.

ArrayValue extends Value to represent multi-dimensional arrays of typed values (e.g., qubit registers, parameter vectors).

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

logical_id: str
name: str
params: dict[str, Any]
shape: tuple[Value, ...]
type: T
uuid: str

Methods¶

`next_version`¶

def next_version(self) -> ArrayValue[T]

Create a new ArrayValue with incremented version, preserving shape.

`QInitOperation` [source]¶

class QInitOperation(Operation)

Initialize the qubit

Constructor¶

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

Attributes¶

operation_kind: OperationKind
signature: Signature

`Value` [source]¶

class Value(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.frontend.decomposition¶

Decomposition strategy framework for composite gates.

This module provides the infrastructure for defining multiple decomposition patterns for composite gates, enabling flexible gate synthesis strategies.

Example:

class StandardQFTStrategy:
    @property
    def name(self) -> str:
        return "standard"

    def decompose(self, qubits: tuple[Qubit, ...]) -> tuple[Qubit, ...]:
        # Full precision QFT implementation
        ...

    def resources(self, num_qubits: int) -> ResourceMetadata:
        return ResourceMetadata(...)

class ApproximateQFTStrategy:
    def __init__(self, truncation_depth: int = 3):
        self._k = truncation_depth

    @property
    def name(self) -> str:
        return f"approximate_k{self._k}"

    def decompose(self, qubits: tuple[Qubit, ...]) -> tuple[Qubit, ...]:
        # Truncated rotations QFT
        ...

# Register strategies
QFT.register_strategy("standard", StandardQFTStrategy())
QFT.register_strategy("approximate", ApproximateQFTStrategy(truncation_depth=3))

Overview¶

Function	Description
`get_global_registry`	Get the global strategy registry.
`get_strategy`	Get a strategy from the global registry.
`register_strategy`	Register a strategy in the global registry.

Class	Description
`DecompositionConfig`	Configuration for decomposition strategy selection.
`DecompositionStrategy`	Protocol for defining decomposition strategies.
`Qubit`
`ResourceMetadata`	Resource estimation metadata for composite gates.
`StrategyRegistry`	Registry for managing decomposition strategies.

Functions¶

`get_global_registry` [source]¶

def get_global_registry() -> StrategyRegistry

Get the global strategy registry.

Returns:

StrategyRegistry — The global StrategyRegistry instance

`get_strategy` [source]¶

def get_strategy(
    gate_name: str,
    strategy_name: str | None = None,
) -> DecompositionStrategy | None

Get a strategy from the global registry.

Parameters:

Name	Type	Description
`gate_name`	`str`	The gate name
`strategy_name`	`str \| None`	The strategy name (uses “standard” if None)

Returns:

DecompositionStrategy | None — The strategy instance, or None if not found

`register_strategy` [source]¶

def register_strategy(gate_name: str, strategy_name: str, strategy: DecompositionStrategy) -> None

Parameters:

Name	Type	Description
`gate_name`	`str`	The gate name (e.g., “qft”, “iqft”)
`strategy_name`	`str`	The strategy name (e.g., “standard”, “approximate”)
`strategy`	`DecompositionStrategy`	The strategy instance

Classes¶

`DecompositionConfig` [source]¶

class DecompositionConfig

Configuration for decomposition strategy selection.

This configuration is passed to the transpiler to control which decomposition strategies are used for composite gates.

Constructor¶

def __init__(
    self,
    strategy_overrides: dict[str, str] = dict(),
    strategy_params: dict[str, dict[str, Any]] = dict(),
    default_strategy: str = 'standard',
) -> None

Attributes¶

default_strategy: str
strategy_overrides: dict[str, str]
strategy_params: dict[str, dict[str, Any]]

Methods¶

`get_strategy_for_gate`¶

def get_strategy_for_gate(self, gate_name: str) -> str

Get the strategy name for a specific gate.

Parameters:

Name	Type	Description
`gate_name`	`str`	The gate name (e.g., “qft”, “iqft”)

Returns:

str — Strategy name to use

`get_strategy_params`¶

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

Get parameters for a specific strategy.

Parameters:

Name	Type	Description
`strategy_name`	`str`	The strategy name

Returns:

dict[str, Any] — Dictionary of parameters

`DecompositionStrategy` [source]¶

class DecompositionStrategy(Protocol)

Protocol for defining decomposition strategies.

A decomposition strategy provides:

A unique name for identification
A decompose method that performs the actual decomposition
Resource estimation for the decomposition

Strategies allow the same composite gate to have multiple implementations with different trade-offs (e.g., precision vs. gate count).

Attributes¶

name: str Unique identifier for this strategy.

Methods¶

`decompose`¶

def decompose(self, qubits: tuple['Qubit', ...]) -> tuple['Qubit', ...]

Perform the decomposition.

Parameters:

Name	Type	Description
`qubits`	`tuple['Qubit', ...]`	Input qubits to decompose

Returns:

tuple['Qubit', ...] — Output qubits after decomposition

`resources`¶

def resources(self, num_qubits: int) -> 'ResourceMetadata'

Return resource estimates for this decomposition.

Parameters:

Name	Type	Description
`num_qubits`	`int`	Number of qubits the gate operates on

Returns:

'ResourceMetadata' — ResourceMetadata with gate counts, depth estimates, etc.

`Qubit` [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QubitType]

`ResourceMetadata` [source]¶

class ResourceMetadata

Resource estimation metadata for composite gates.

Gate count fields mirror GateCount categories.

None semantics:

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

`StrategyRegistry` [source]¶

class StrategyRegistry

Registry for managing decomposition strategies.

This class provides a centralized registry for strategies, allowing them to be looked up by name across the transpiler pipeline.

Example:

registry = StrategyRegistry()
registry.register("qft", "standard", StandardQFTStrategy())
registry.register("qft", "approximate", ApproximateQFTStrategy())

strategy = registry.get("qft", "standard")

Constructor¶

def __init__(self) -> None

Initialize empty registry.

Methods¶

`get`¶

def get(
    self,
    gate_name: str,
    strategy_name: str | None = None,
) -> DecompositionStrategy | None

Get a strategy for a gate.

Parameters:

Name	Type	Description
`gate_name`	`str`	The gate name
`strategy_name`	`str \| None`	The strategy name (uses “standard” if None)

Returns:

DecompositionStrategy | None — The strategy instance, or None if not found

`list_gates`¶

def list_gates(self) -> list[str]

List all gates with registered strategies.

Returns:

list[str] — List of gate names

`list_strategies`¶

def list_strategies(self, gate_name: str) -> list[str]

List available strategies for a gate.

Parameters:

Name	Type	Description
`gate_name`	`str`	The gate name

Returns:

list[str] — List of strategy names

`register`¶

def register(
    self,
    gate_name: str,
    strategy_name: str,
    strategy: DecompositionStrategy,
) -> None

Parameters:

Name	Type	Description
`gate_name`	`str`	The gate name (e.g., “qft”, “iqft”)
`strategy_name`	`str`	The strategy name (e.g., “standard”, “approximate”)
`strategy`	`DecompositionStrategy`	The strategy instance

qamomile.circuit.frontend.func_to_block¶

Overview¶

Function	Description
`create_dummy_handle`	Create a dummy Handle instance based on ValueType.
`create_dummy_input`	Create a dummy input based on parameter type annotation.
`func_to_block`	Convert a function to a BlockValue.
`get_current_tracer`
`handle_type_map`	Map Handle type to ValueType.
`is_array_type`	Check if type is a Vector, Matrix, or Tensor subclass.
`is_dict_type`	Check if type is a Dict handle type.
`is_tuple_type`	Check if type is a Tuple handle type.
`trace`	Context manager to set the current tracer.

Class	Description
`ArrayValue`	An array of values with shape information.
`Bit`
`BitType`	Type representing a classical bit.
`BlockValue`	Represents a subroutine as a function block.
`Dict`	Dict handle for qkernel functions.
`DictType`	Type representing a dictionary mapping keys to values.
`DictValue`	A dictionary mapping keys to values.
`Float`	Floating-point handle with arithmetic operations.
`FloatType`	Type representing a floating-point number.
`Observable`	Handle representing a Hamiltonian observable parameter.
`ObservableType`	Type representing a Hamiltonian observable parameter.
`QInitOperation`	Initialize the qubit
`Qubit`
`ReturnOperation`	Explicit return operation marking the end of a block with return values.
`Tracer`
`Tuple`	Tuple handle for qkernel functions.
`TupleType`	Type representing a tuple of values.
`TupleValue`	A tuple of values for structured data.
`UInt`	Unsigned integer handle with arithmetic operations.
`UIntType`	Type representing an unsigned integer.
`Value`	A typed value in the IR with SSA-style versioning.
`ValueType`	Base class for all value types in the IR.

Constants¶

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

Functions¶

`create_dummy_handle` [source]¶

def create_dummy_handle(value_type: ValueType, name: str = 'dummy', emit_init: bool = True) -> Handle

Create a dummy Handle instance based on ValueType.

Parameters:

Name	Type	Description
`value_type`	`ValueType`	The IR type for the value.
`name`	`str`	Name for the value.
`emit_init`	`bool`	If True, emit QInitOperation for qubit types (requires active tracer).

Used for creating input parameters during tracing.

`create_dummy_input` [source]¶

def create_dummy_input(param_type: Any, name: str = 'param', emit_init: bool = True) -> Handle

Create a dummy input based on parameter type annotation.

Parameters:

Name	Type	Description
`param_type`	`typing.Any`	The type annotation for the parameter.
`name`	`str`	Name for the value.
`emit_init`	`bool`	If True, emit QInitOperation for qubit arrays (default: True). Set to False when creating BlockValue’s internal dummy inputs.

This creates input Handles for function parameters.

`func_to_block` [source]¶

def func_to_block(func: Callable) -> BlockValue

Convert a function to a BlockValue.

Example:

def my_func(a: UInt, b: UInt) -> tuple[UInt]:
    c = a + b
    return (c, )

block_value = func_to_block(my_func)

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

`handle_type_map` [source]¶

def handle_type_map(handle_type: type[Handle] | type) -> ValueType

Map Handle type to ValueType.

`is_array_type` [source]¶

def is_array_type(t: Any) -> bool

Check if type is a Vector, Matrix, or Tensor subclass.

`is_dict_type` [source]¶

def is_dict_type(t: Any) -> bool

Check if type is a Dict handle type.

`is_tuple_type` [source]¶

def is_tuple_type(t: Any) -> bool

Check if type is a Tuple handle type.

`trace` [source]¶

def trace(tracer: Tracer | None = None) -> Generator[Tracer, None, None]

Context manager to set the current tracer.

Classes¶

`ArrayValue` [source]¶

class ArrayValue(Value[T])

An array of values with shape information.

ArrayValue extends Value to represent multi-dimensional arrays of typed values (e.g., qubit registers, parameter vectors).

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

logical_id: str
name: str
params: dict[str, Any]
shape: tuple[Value, ...]
type: T
uuid: str

Methods¶

`next_version`¶

def next_version(self) -> ArrayValue[T]

Create a new ArrayValue with incremented version, preserving shape.

`Bit` [source]¶

class Bit(Handle)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: bool = False,
) -> None

Attributes¶

init_value: bool

`BitType` [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

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

`Dict` [source]¶

class Dict(Handle, Generic[K, V])

Dict handle for qkernel functions.

Represents a dictionary mapping keys to values, commonly used for Ising coefficients like {(i, j): Jij}.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

Constructor¶

def __init__(
    self,
    value: DictValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
) -> None

Attributes¶

size: UInt Return the number of entries as a UInt handle.
value: DictValue

Methods¶

`items`¶

def items(self) -> DictItemsIterator[K, V]

Return an iterator over (key, value) pairs.

`DictType` [source]¶

class DictType(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

`DictValue` [source]¶

class DictValue

A dictionary mapping keys to values.

Used for structured data like Ising coefficients {(i, j): Jij}. Entries are stored as a list of (key, value) pairs for consistent ordering. Implements the ValueBase protocol for unified handling.

Constructor¶

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

Attributes¶

entries: list[tuple[TupleValue | Value, Value]]
logical_id: str
name: str
params: dict[str, Any]
type: DictType Return type interface for compatibility with Value.
uuid: str

Methods¶

`is_constant`¶

def is_constant(self) -> bool

Check if all entries have constant values.

`is_parameter`¶

def is_parameter(self) -> bool

Check if this dict is a parameter (bound at transpile time).

`next_version`¶

def next_version(self) -> DictValue

Create a new DictValue with a fresh uuid but same logical_id.

`parameter_name`¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter.

`Float` [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: float = 0.0,
) -> None

Attributes¶

init_value: float

`FloatType` [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

`Observable` [source]¶

class Observable(Handle)

Handle representing a Hamiltonian observable parameter.

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

Example:

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

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

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

# Pass via bindings
executable = transpiler.transpile(vqe, bindings={"H": H})

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

`ObservableType` [source]¶

class ObservableType(ObjectTypeMixin, ValueType)

Type representing a Hamiltonian observable parameter.

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

Example usage:

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

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

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

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

Constructor¶

def __init__(self) -> None

`QInitOperation` [source]¶

class QInitOperation(Operation)

Initialize the qubit

Constructor¶

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

Attributes¶

operation_kind: OperationKind
signature: Signature

`Qubit` [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QubitType]

`ReturnOperation` [source]¶

class ReturnOperation(Operation)

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

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

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

Example:

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

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

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

Constructor¶

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

Attributes¶

operation_kind: OperationKind Return CLASSICAL as this is a control flow operation without quantum effects.
signature: Signature Return the signature with operands for each return value and no results.

`Tracer` [source]¶

class Tracer

Constructor¶

def __init__(self, _operations: list[Operation] = list()) -> None

Attributes¶

operations: list[Operation]

Methods¶

`add_operation`¶

def add_operation(self, op) -> None

`Tuple` [source]¶

class Tuple(Handle, Generic[K, V])

Tuple handle for qkernel functions.

Represents a tuple of values, commonly used for multi-index keys like (i, j) in Ising models.

Example:

@qmc.qkernel
def my_kernel(idx: qmc.Tuple[qmc.UInt, qmc.UInt]) -> qmc.UInt:
    i, j = idx
    return i + j

Constructor¶

def __init__(
    self,
    value: TupleValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _elements: tuple[Handle, ...] = tuple(),
) -> None

Attributes¶

value: TupleValue

`TupleType` [source]¶

class TupleType(ClassicalTypeMixin, ValueType)

Type representing a tuple of values.

Unlike simple types, TupleType stores the types of its elements, so equality and hashing depend on the element types.

Constructor¶

def __init__(self, element_types: tuple[ValueType, ...]) -> None

Attributes¶

element_types: tuple[ValueType, ...]

Methods¶

`label`¶

def label(self) -> str

`TupleValue` [source]¶

class TupleValue

A tuple of values for structured data.

Used for structured data like Ising model indices (i, j). Implements the ValueBase protocol for unified handling.

Constructor¶

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

Attributes¶

elements: tuple[Value, ...]
logical_id: str
name: str
params: dict[str, Any]
uuid: str

Methods¶

`is_constant`¶

def is_constant(self) -> bool

Check if all elements are constants.

`is_parameter`¶

def is_parameter(self) -> bool

Check if this tuple is a parameter (has symbolic elements).

`next_version`¶

def next_version(self) -> TupleValue

Create a new TupleValue with a fresh uuid but same logical_id.

`parameter_name`¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter.

`UInt` [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: int = 0,
) -> None

Attributes¶

init_value: int

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

`ValueType` [source]¶

class ValueType(abc.ABC)

Base class for all value types in the IR.

Type instances are compared by class - all instances of the same type class are considered equal. This allows using type instances as dictionary keys where all QubitType() instances match.

Methods¶

`is_classical`¶

def is_classical(self) -> bool

`is_object`¶

def is_object(self) -> bool

`is_quantum`¶

def is_quantum(self) -> bool

`label`¶

def label(self) -> str

qamomile.circuit.frontend.handle¶

Overview¶

Class	Description
`Bit`
`Dict`	Dict handle for qkernel functions.
`Float`	Floating-point handle with arithmetic operations.
`Handle`
`Matrix`	2-dimensional array type.
`Observable`	Handle representing a Hamiltonian observable parameter.
`QFixed`
`Qubit`
`Tensor`	N-dimensional array type (3 or more dimensions).
`Tuple`	Tuple handle for qkernel functions.
`UInt`	Unsigned integer handle with arithmetic operations.
`Vector`	1-dimensional array type.

Classes¶

`Bit` [source]¶

class Bit(Handle)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: bool = False,
) -> None

Attributes¶

init_value: bool

`Dict` [source]¶

class Dict(Handle, Generic[K, V])

Dict handle for qkernel functions.

Represents a dictionary mapping keys to values, commonly used for Ising coefficients like {(i, j): Jij}.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

Constructor¶

def __init__(
    self,
    value: DictValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
) -> None

Attributes¶

size: UInt Return the number of entries as a UInt handle.
value: DictValue

Methods¶

`items`¶

def items(self) -> DictItemsIterator[K, V]

Return an iterator over (key, value) pairs.

`Float` [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: float = 0.0,
) -> None

Attributes¶

init_value: float

`Handle` [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

id: str
indices: tuple[‘UInt’, ...]
name: str | None
parent: ‘ArrayBase | None’
value: Value

Methods¶

`consume`¶

def consume(self, operation_name: str = 'unknown') -> 'Handle'

Mark this handle as consumed and return a fresh handle.

Parameters:

Name	Type	Description
`operation_name`	`str`	Name of the operation consuming this handle, used for error messages.

Returns:

'Handle' — A new handle pointing to the same underlying value.

Raises:

QubitConsumedError — If this handle was already consumed and is a quantum type.

`Matrix` [source]¶

class Matrix(ArrayBase[T])

2-dimensional array type.

Example:

import qamomile as qm

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

# Access elements (always requires 2 indices)
q = matrix[0, 1]
q = qm.h(q)
matrix[0, 1] = q

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt, int | UInt] = (0, 0),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

`Observable` [source]¶

class Observable(Handle)

Handle representing a Hamiltonian observable parameter.

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

Example:

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

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

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

# Pass via bindings
executable = transpiler.transpile(vqe, bindings={"H": H})

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

`QFixed` [source]¶

class QFixed(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QFixedType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QFixedType]

`Qubit` [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QubitType]

`Tensor` [source]¶

class Tensor(ArrayBase[T])

N-dimensional array type (3 or more dimensions).

Example:

import qamomile as qm

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

# Access elements (requires all indices)
q = tensor[0, 1, 2]
q = qm.h(q)
tensor[0, 1, 2] = q

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

`Tuple` [source]¶

class Tuple(Handle, Generic[K, V])

Tuple handle for qkernel functions.

Represents a tuple of values, commonly used for multi-index keys like (i, j) in Ising models.

Example:

@qmc.qkernel
def my_kernel(idx: qmc.Tuple[qmc.UInt, qmc.UInt]) -> qmc.UInt:
    i, j = idx
    return i + j

Constructor¶

def __init__(
    self,
    value: TupleValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _elements: tuple[Handle, ...] = tuple(),
) -> None

Attributes¶

value: TupleValue

`UInt` [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: int = 0,
) -> None

Attributes¶

init_value: int

`Vector` [source]¶

class Vector(ArrayBase[T])

1-dimensional array type.

Example:

import qamomile.circuit as qmc

# Create a vector of 3 qubits
qubits: qmc.Vector[qmc.Qubit] = qmc.qubit_array(3, name="qubits")

# Access elements
q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0

# Apply H gate to all qubits (CORRECT)
n = qubits.shape[0]
for i in qmc.range(n):
    qubits[i] = qmc.h(qubits[i])

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

qamomile.circuit.frontend.handle.array¶

Overview¶

Function	Description
`get_current_tracer`

Class	Description
`AffineTypeError`	Base class for affine type violations.
`ArrayBase`	Base class for array types (Vector, Matrix, Tensor).
`ArrayValue`	An array of values with shape information.
`Bit`
`BitType`	Type representing a classical bit.
`CInitOperation`	Initialize the classical values (const, arguments etc)
`Float`	Floating-point handle with arithmetic operations.
`FloatType`	Type representing a floating-point number.
`Handle`
`Matrix`	2-dimensional array type.
`QInitOperation`	Initialize the qubit
`Qubit`
`QubitConsumedError`	Qubit handle used after being consumed by a previous operation.
`QubitType`	Type representing a quantum bit (qubit).
`Tensor`	N-dimensional array type (3 or more dimensions).
`UInt`	Unsigned integer handle with arithmetic operations.
`UIntType`	Type representing an unsigned integer.
`UnreturnedBorrowError`	Borrowed array element not returned before array use.
`Value`	A typed value in the IR with SSA-style versioning.
`Vector`	1-dimensional array type.

Functions¶

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

Classes¶

`AffineTypeError` [source]¶

class AffineTypeError(QamomileCompileError)

Base class for affine type violations.

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

Constructor¶

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

Attributes¶

first_use_location
handle_name
operation_name

`ArrayBase` [source]¶

class ArrayBase(Handle, Generic[T])

Base class for array types (Vector, Matrix, Tensor).

Provides common functionality for array indexing and element access.

Constructor¶

def __init__(
    self,
    value: ArrayValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

element_type: Type[T]
shape: tuple[int | UInt, ...] Return the shape of the array.
value: ArrayValue

Methods¶

`consume`¶

def consume(self, operation_name: str = 'unknown') -> 'ArrayBase[T]'

Consume the array, enforcing borrow-return contract for quantum arrays.

For quantum arrays, all borrowed elements must be returned before the array can be consumed. This ensures that no unreturned borrows are silently discarded by operations like qkernel calls or controlled gates.

`create`¶

@classmethod
def create(
    cls,
    shape: tuple[int | UInt, ...],
    name: str,
    el_type: Type[T],
) -> 'ArrayBase[T]'

Create an ArrayValue for the given shape and name.

`validate_all_returned`¶

def validate_all_returned(self) -> None

Validate all borrowed elements have been returned.

This method is useful for ensuring that all borrowed elements have been properly written back before using the array in operations that require the entire array.

Raises:

UnreturnedBorrowError — If any elements are still borrowed.

`ArrayValue` [source]¶

class ArrayValue(Value[T])

An array of values with shape information.

ArrayValue extends Value to represent multi-dimensional arrays of typed values (e.g., qubit registers, parameter vectors).

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

logical_id: str
name: str
params: dict[str, Any]
shape: tuple[Value, ...]
type: T
uuid: str

Methods¶

`next_version`¶

def next_version(self) -> ArrayValue[T]

Create a new ArrayValue with incremented version, preserving shape.

`Bit` [source]¶

class Bit(Handle)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: bool = False,
) -> None

Attributes¶

init_value: bool

`BitType` [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

`CInitOperation` [source]¶

class CInitOperation(Operation)

Initialize the classical values (const, arguments etc)

Constructor¶

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

Attributes¶

operation_kind: OperationKind
signature: Signature

`Float` [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: float = 0.0,
) -> None

Attributes¶

init_value: float

`FloatType` [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

`Handle` [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

id: str
indices: tuple[‘UInt’, ...]
name: str | None
parent: ‘ArrayBase | None’
value: Value

Methods¶

`consume`¶

def consume(self, operation_name: str = 'unknown') -> 'Handle'

Mark this handle as consumed and return a fresh handle.

Parameters:

Name	Type	Description
`operation_name`	`str`	Name of the operation consuming this handle, used for error messages.

Returns:

'Handle' — A new handle pointing to the same underlying value.

Raises:

QubitConsumedError — If this handle was already consumed and is a quantum type.

`Matrix` [source]¶

class Matrix(ArrayBase[T])

2-dimensional array type.

Example:

import qamomile as qm

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

# Access elements (always requires 2 indices)
q = matrix[0, 1]
q = qm.h(q)
matrix[0, 1] = q

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt, int | UInt] = (0, 0),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

`QInitOperation` [source]¶

class QInitOperation(Operation)

Initialize the qubit

Constructor¶

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

Attributes¶

operation_kind: OperationKind
signature: Signature

`Qubit` [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QubitType]

`QubitConsumedError` [source]¶

class QubitConsumedError(AffineTypeError)

Qubit handle used after being consumed by a previous operation.

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

Example of incorrect code:

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

Correct code:

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

`QubitType` [source]¶

class QubitType(QuantumTypeMixin, ValueType)

Type representing a quantum bit (qubit).

`Tensor` [source]¶

class Tensor(ArrayBase[T])

N-dimensional array type (3 or more dimensions).

Example:

import qamomile as qm

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

# Access elements (requires all indices)
q = tensor[0, 1, 2]
q = qm.h(q)
tensor[0, 1, 2] = q

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

`UInt` [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: int = 0,
) -> None

Attributes¶

init_value: int

`UIntType` [source]¶

class UIntType(ClassicalTypeMixin, ValueType)

Type representing an unsigned integer.

`UnreturnedBorrowError` [source]¶

class UnreturnedBorrowError(AffineTypeError)

Borrowed array element not returned before array use.

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

Example of incorrect code:

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

Correct code:

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

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

`Vector` [source]¶

class Vector(ArrayBase[T])

1-dimensional array type.

Example:

import qamomile.circuit as qmc

# Create a vector of 3 qubits
qubits: qmc.Vector[qmc.Qubit] = qmc.qubit_array(3, name="qubits")

# Access elements
q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0

# Apply H gate to all qubits (CORRECT)
n = qubits.shape[0]
for i in qmc.range(n):
    qubits[i] = qmc.h(qubits[i])

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

qamomile.circuit.frontend.handle.containers¶

Container types for qkernel: Tuple and Dict handles.

Overview¶

Class	Description
`Dict`	Dict handle for qkernel functions.
`DictItemsIterator`	Iterator for Dict.items() that yields (key, value) pairs.
`DictValue`	A dictionary mapping keys to values.
`Handle`
`Tuple`	Tuple handle for qkernel functions.
`TupleValue`	A tuple of values for structured data.
`UInt`	Unsigned integer handle with arithmetic operations.
`UIntType`	Type representing an unsigned integer.
`Value`	A typed value in the IR with SSA-style versioning.

Classes¶

`Dict` [source]¶

class Dict(Handle, Generic[K, V])

Dict handle for qkernel functions.

Represents a dictionary mapping keys to values, commonly used for Ising coefficients like {(i, j): Jij}.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

Constructor¶

def __init__(
    self,
    value: DictValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
) -> None

Attributes¶

size: UInt Return the number of entries as a UInt handle.
value: DictValue

Methods¶

`items`¶

def items(self) -> DictItemsIterator[K, V]

Return an iterator over (key, value) pairs.

`DictItemsIterator` [source]¶

class DictItemsIterator(Generic[K, V])

Iterator for Dict.items() that yields (key, value) pairs.

This is used internally for iterating over Dict entries in qkernel.

Constructor¶

def __init__(self, dict_handle: 'Dict[K, V]', _index: int = 0) -> None

Attributes¶

dict_handle: ‘Dict[K, V]’

`DictValue` [source]¶

class DictValue

A dictionary mapping keys to values.

Used for structured data like Ising coefficients {(i, j): Jij}. Entries are stored as a list of (key, value) pairs for consistent ordering. Implements the ValueBase protocol for unified handling.

Constructor¶

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

Attributes¶

entries: list[tuple[TupleValue | Value, Value]]
logical_id: str
name: str
params: dict[str, Any]
type: DictType Return type interface for compatibility with Value.
uuid: str

Methods¶

`is_constant`¶

def is_constant(self) -> bool

Check if all entries have constant values.

`is_parameter`¶

def is_parameter(self) -> bool

Check if this dict is a parameter (bound at transpile time).

`next_version`¶

def next_version(self) -> DictValue

Create a new DictValue with a fresh uuid but same logical_id.

`parameter_name`¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter.

`Handle` [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

id: str
indices: tuple[‘UInt’, ...]
name: str | None
parent: ‘ArrayBase | None’
value: Value

Methods¶

`consume`¶

def consume(self, operation_name: str = 'unknown') -> 'Handle'

Mark this handle as consumed and return a fresh handle.

Parameters:

Name	Type	Description
`operation_name`	`str`	Name of the operation consuming this handle, used for error messages.

Returns:

'Handle' — A new handle pointing to the same underlying value.

Raises:

QubitConsumedError — If this handle was already consumed and is a quantum type.

`Tuple` [source]¶

class Tuple(Handle, Generic[K, V])

Tuple handle for qkernel functions.

Represents a tuple of values, commonly used for multi-index keys like (i, j) in Ising models.

Example:

@qmc.qkernel
def my_kernel(idx: qmc.Tuple[qmc.UInt, qmc.UInt]) -> qmc.UInt:
    i, j = idx
    return i + j

Constructor¶

def __init__(
    self,
    value: TupleValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _elements: tuple[Handle, ...] = tuple(),
) -> None

Attributes¶

value: TupleValue

`TupleValue` [source]¶

class TupleValue

A tuple of values for structured data.

Used for structured data like Ising model indices (i, j). Implements the ValueBase protocol for unified handling.

Constructor¶

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

Attributes¶

elements: tuple[Value, ...]
logical_id: str
name: str
params: dict[str, Any]
uuid: str

Methods¶

`is_constant`¶

def is_constant(self) -> bool

Check if all elements are constants.

`is_parameter`¶

def is_parameter(self) -> bool

Check if this tuple is a parameter (has symbolic elements).

`next_version`¶

def next_version(self) -> TupleValue

Create a new TupleValue with a fresh uuid but same logical_id.

`parameter_name`¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter.

`UInt` [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: int = 0,
) -> None

Attributes¶

init_value: int

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

qamomile.circuit.frontend.handle.hamiltonian¶

Observable handle for Hamiltonian parameters.

This module provides the Observable handle class that represents a reference to a Hamiltonian observable provided via bindings during transpilation. Unlike HamiltonianExpr in previous versions, this is a pure parameter handle with no arithmetic operations.

Overview¶

Class	Description
`Handle`
`Observable`	Handle representing a Hamiltonian observable parameter.

Classes¶

`Handle` [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

id: str
indices: tuple[‘UInt’, ...]
name: str | None
parent: ‘ArrayBase | None’
value: Value

Methods¶

`consume`¶

def consume(self, operation_name: str = 'unknown') -> 'Handle'

Mark this handle as consumed and return a fresh handle.

Parameters:

Name	Type	Description
`operation_name`	`str`	Name of the operation consuming this handle, used for error messages.

Returns:

'Handle' — A new handle pointing to the same underlying value.

Raises:

QubitConsumedError — If this handle was already consumed and is a quantum type.

`Observable` [source]¶

class Observable(Handle)

Handle representing a Hamiltonian observable parameter.

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

Example:

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

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

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

# Pass via bindings
executable = transpiler.transpile(vqe, bindings={"H": H})

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

qamomile.circuit.frontend.handle.handle¶

Overview¶

Function	Description
`get_current_tracer`

Class	Description
`ArithmeticMixin`	Mixin providing arithmetic operations for numeric Handle types.
`ArrayBase`	Base class for array types (Vector, Matrix, Tensor).
`BinOp`	Binary arithmetic operation (ADD, SUB, MUL, DIV, FLOORDIV, POW).
`BinOpKind`
`CompOp`	Comparison operation (EQ, NEQ, LT, LE, GT, GE).
`CompOpKind`
`Handle`
`QubitConsumedError`	Qubit handle used after being consumed by a previous operation.
`UInt`	Unsigned integer handle with arithmetic operations.
`Value`	A typed value in the IR with SSA-style versioning.

Functions¶

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

Classes¶

`ArithmeticMixin` [source]¶

class ArithmeticMixin

Mixin providing arithmetic operations for numeric Handle types.

Requires:

value: Value attribute
_make_result(): Method to create result Handle of same type
_coerce(): Method to convert Python literals to Handle

Attributes¶

value: Value

`ArrayBase` [source]¶

class ArrayBase(Handle, Generic[T])

Base class for array types (Vector, Matrix, Tensor).

Provides common functionality for array indexing and element access.

Constructor¶

def __init__(
    self,
    value: ArrayValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

element_type: Type[T]
shape: tuple[int | UInt, ...] Return the shape of the array.
value: ArrayValue

Methods¶

`consume`¶

def consume(self, operation_name: str = 'unknown') -> 'ArrayBase[T]'

Consume the array, enforcing borrow-return contract for quantum arrays.

`create`¶

@classmethod
def create(
    cls,
    shape: tuple[int | UInt, ...],
    name: str,
    el_type: Type[T],
) -> 'ArrayBase[T]'

Create an ArrayValue for the given shape and name.

`validate_all_returned`¶

def validate_all_returned(self) -> None

Validate all borrowed elements have been returned.

This method is useful for ensuring that all borrowed elements have been properly written back before using the array in operations that require the entire array.

Raises:

UnreturnedBorrowError — If any elements are still borrowed.

`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

`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

`Handle` [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

id: str
indices: tuple[‘UInt’, ...]
name: str | None
parent: ‘ArrayBase | None’
value: Value

Methods¶

`consume`¶

def consume(self, operation_name: str = 'unknown') -> 'Handle'

Mark this handle as consumed and return a fresh handle.

Parameters:

Name	Type	Description
`operation_name`	`str`	Name of the operation consuming this handle, used for error messages.

Returns:

'Handle' — A new handle pointing to the same underlying value.

Raises:

QubitConsumedError — If this handle was already consumed and is a quantum type.

`QubitConsumedError` [source]¶

class QubitConsumedError(AffineTypeError)

Qubit handle used after being consumed by a previous operation.

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

Example of incorrect code:

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

Correct code:

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

`UInt` [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: int = 0,
) -> None

Attributes¶

init_value: int

`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.frontend.handle.primitives¶

Overview¶

Class	Description
`ArithmeticMixin`	Mixin providing arithmetic operations for numeric Handle types.
`BinOpKind`
`Bit`
`BitType`	Type representing a classical bit.
`CompOpKind`
`Float`	Floating-point handle with arithmetic operations.
`FloatType`	Type representing a floating-point number.
`Handle`
`QFixed`
`Qubit`
`QubitType`	Type representing a quantum bit (qubit).
`UInt`	Unsigned integer handle with arithmetic operations.
`UIntType`	Type representing an unsigned integer.
`Value`	A typed value in the IR with SSA-style versioning.

Classes¶

`ArithmeticMixin` [source]¶

class ArithmeticMixin

Mixin providing arithmetic operations for numeric Handle types.

Requires:

value: Value attribute
_make_result(): Method to create result Handle of same type
_coerce(): Method to convert Python literals to Handle

Attributes¶

value: Value

`BinOpKind` [source]¶

class BinOpKind(enum.Enum)

Attributes¶

ADD
DIV
FLOORDIV
MUL
POW
SUB

`Bit` [source]¶

class Bit(Handle)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: bool = False,
) -> None

Attributes¶

init_value: bool

`BitType` [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

`CompOpKind` [source]¶

class CompOpKind(enum.Enum)

Attributes¶

EQ
GE
GT
LE
LT
NEQ

`Float` [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: float = 0.0,
) -> None

Attributes¶

init_value: float

`FloatType` [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

`Handle` [source]¶

class Handle(abc.ABC)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

id: str
indices: tuple[‘UInt’, ...]
name: str | None
parent: ‘ArrayBase | None’
value: Value

Methods¶

`consume`¶

def consume(self, operation_name: str = 'unknown') -> 'Handle'

Mark this handle as consumed and return a fresh handle.

Parameters:

Name	Type	Description
`operation_name`	`str`	Name of the operation consuming this handle, used for error messages.

Returns:

'Handle' — A new handle pointing to the same underlying value.

Raises:

QubitConsumedError — If this handle was already consumed and is a quantum type.

`QFixed` [source]¶

class QFixed(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QFixedType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QFixedType]

`Qubit` [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QubitType]

`QubitType` [source]¶

class QubitType(QuantumTypeMixin, ValueType)

Type representing a quantum bit (qubit).

`UInt` [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: int = 0,
) -> None

Attributes¶

init_value: int

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

qamomile.circuit.frontend.operation¶

qamomile.circuit.frontend.operation.cast¶

Cast operation for type conversions over the same quantum resources.

Overview¶

Function	Description
`cast`	Cast a quantum value to a different type without allocating new qubits.
`get_current_tracer`

Class	Description
`CastOperation`	Type cast operation for creating aliases over the same quantum resources.
`QFixed`
`QFixedType`	Quantum fixed-point type.
`Qubit`
`Value`	A typed value in the IR with SSA-style versioning.
`Vector`	1-dimensional array type.

Functions¶

`cast` [source]¶

def cast(source: Vector[Qubit], target_type: type, *, int_bits: int = 0) -> QFixed

Cast a quantum value to a different type without allocating new qubits.

The cast performs a move: the source handle is consumed and cannot be reused after the cast. The returned handle references the same physical qubits.

Parameters:

Name	Type	Description
`source`	`Vector[Qubit]`	The value to cast (currently supports Vector[Qubit])
`target_type`	`type`	The target type class (currently supports QFixed)
`int_bits`	`int`	For QFixed, number of integer bits (default: 0 = all fractional)

Returns:

QFixed — A new handle of the target type referencing the same qubits.

Example:

@qmc.qkernel
def my_circuit():
    phase_register = qmc.qubit_array(5, name="phase")
    # ... apply some operations ...

    # Cast the qubit array to QFixed for measurement
    phase_qfixed = qmc.cast(phase_register, qmc.QFixed, int_bits=0)
    phase_value = qmc.measure(phase_qfixed)
    return phase_value

Raises:

TypeError — If the source type or target type is not supported
ValueError — If int_bits is negative or larger than the number of qubits

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

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

`QFixed` [source]¶

class QFixed(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QFixedType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QFixedType]

`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¶

fractional_bits: int | Value[UIntType]
integer_bits: int | Value[UIntType]

Methods¶

`label`¶

def label(self) -> str

`Qubit` [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QubitType]

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

`Vector` [source]¶

class Vector(ArrayBase[T])

1-dimensional array type.

Example:

import qamomile.circuit as qmc

# Create a vector of 3 qubits
qubits: qmc.Vector[qmc.Qubit] = qmc.qubit_array(3, name="qubits")

# Access elements
q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0

# Apply H gate to all qubits (CORRECT)
n = qubits.shape[0]
for i in qmc.range(n):
    qubits[i] = qmc.h(qubits[i])

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

qamomile.circuit.frontend.operation.control_flow¶

Overview¶

Function	Description
`emit_if`	Builder function for if-else conditional with Phi function merging.
`for_items`	Builder function to create a for-items loop in Qamomile frontend.
`for_loop`	Builder function to create a for loop in Qamomile frontend.
`get_current_tracer`
`is_array_type`	Check if type is a Vector, Matrix, or Tensor subclass.
`items`	Iterate over dictionary key-value pairs.
`range`	Symbolic range for use in qkernel for-loops.
`trace`	Context manager to set the current tracer.
`while_loop`	Create a while loop whose condition is a measurement result.

Class	Description
`ArrayBase`	Base class for array types (Vector, Matrix, Tensor).
`ArrayValue`	An array of values with shape information.
`Bit`
`BitType`	Type representing a classical bit.
`Dict`	Dict handle for qkernel functions.
`DictItemsIterator`	Iterator for Dict.items() that yields (key, value) pairs.
`Float`	Floating-point handle with arithmetic operations.
`FloatType`	Type representing a floating-point number.
`ForItemsOperation`	Represents iteration over dict/iterable items.
`ForOperation`	Represents a for loop operation.
`IfOperation`	Represents an if-else conditional operation.
`PhiOp`	SSA Phi function: merge point after conditional branch.
`Qubit`
`Tracer`
`UInt`	Unsigned integer handle with arithmetic operations.
`UIntType`	Type representing an unsigned integer.
`Value`	A typed value in the IR with SSA-style versioning.
`Vector`	1-dimensional array type.
`WhileLoop`
`WhileOperation`	Represents a while loop operation.

Functions¶

`emit_if` [source]¶

def emit_if(
    cond_func: Callable,
    true_func: Callable,
    false_func: Callable,
    variables: list,
) -> Any

Builder function for if-else conditional with Phi function merging.

This function is called from AST-transformed code. The AST transformer converts: if condition: true_body else: false_body

Into:

def _cond_N(vars): return condition def _body_N(vars): true_body; return vars def _body_N+1(vars): false_body; return vars result = emit_if(_cond_N, _body_N, _body_N+1, [var_list])

Parameters:

Name	Type	Description
`cond_func`	`typing.Callable`	Function returning the condition (Bit or bool-like Handle)
`true_func`	`typing.Callable`	Function executing true branch, returns updated variables
`false_func`	`typing.Callable`	Function executing false branch, returns updated variables
`variables`	`list`	List of variables used in the branches

Returns:

typing.Any — Merged variable values after conditional execution (using Phi functions)

Example:

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

`for_items` [source]¶

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

Builder function to create a for-items loop in Qamomile frontend.

Parameters:

Name	Type	Description
`d`	`Dict`	Dict handle to iterate over
`key_var_names`	`list[str]`	Names of key unpacking variables (e.g., [“i”, “j”] for tuple keys)
`value_var_name`	`str`	Name of value variable (e.g., “Jij”)

Yields:

tuple[typing.Any, typing.Any] — Tuple of (key_handles, value_handle) for use in loop body

Example:

@qkernel
def ising_cost(
    q: Vector[Qubit],
    ising: Dict[Tuple[UInt, UInt], Float],
    gamma: Float,
) -> Vector[Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

`for_loop` [source]¶

def for_loop(
    start,
    stop,
    step = 1,
    var_name: str = '_loop_idx',
) -> Generator[UInt, None, None]

Builder function to create a for loop in Qamomile frontend.

Parameters:

Name	Type	Description
`start`	``	Loop start value (can be Handle or int)
`stop`	``	Loop stop value (can be Handle or int)
`step`	``	Loop step value (default=1)
`var_name`	`str`	Name of the loop variable (default=“_loop_idx”)

Yields:

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

Example:

@QKernel
def my_kernel(qubits: Array[Qubit, Literal[3]]) -> Array[Qubit, Literal[3]]:
    for i in qm.range(3):
        qubits[i] = h(qubits[i])
    return qubits

@QKernel
def my_kernel2(qubits: Array[Qubit, Literal[5]]) -> Array[Qubit, Literal[5]]:
    for i in qm.range(1, 4):  # i = 1, 2, 3
        qubits[i] = h(qubits[i])
    return qubits

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

`is_array_type` [source]¶

def is_array_type(t: Any) -> bool

Check if type is a Vector, Matrix, or Tensor subclass.

`items` [source]¶

def items(d: Dict) -> DictItemsIterator

Iterate over dictionary key-value pairs.

This function returns an iterator over (key, value) pairs from a Dict. Used for iterating over Ising coefficients and similar data structures.

Example:

for (i, j), Jij in qmc.items(ising):
    q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)

Parameters:

Name	Type	Description
`d`	`Dict`	A Dict handle to iterate over

Returns:

DictItemsIterator — DictItemsIterator yielding (key, value) pairs

`range` [source]¶

def range(
    stop_or_start: int | UInt,
    stop: int | UInt | None = None,
    step: int | UInt = 1,
) -> Iterator[UInt]

Symbolic range for use in qkernel for-loops.

This function accepts UInt (symbolic) values and is transformed by the AST transformer into for_loop() calls.

Example:

for i in qmc.range(n):          # 0 to n-1
for i in qmc.range(start, stop):  # start to stop-1
for i in qmc.range(start, stop, step):

`trace` [source]¶

def trace(tracer: Tracer | None = None) -> Generator[Tracer, None, None]

Context manager to set the current tracer.

`while_loop` [source]¶

def while_loop(cond: Callable) -> Generator[WhileLoop, None, None]

Create a while loop whose condition is a measurement result.

Parameters:

Name	Type	Description
`cond`	`typing.Callable`	A callable (lambda) that returns the loop condition. Must return a `Bit` handle originating from `qmc.measure()`.

Yields:

WhileLoop — A marker object for the while loop context.

Example::

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

Classes¶

`ArrayBase` [source]¶

class ArrayBase(Handle, Generic[T])

Base class for array types (Vector, Matrix, Tensor).

Provides common functionality for array indexing and element access.

Constructor¶

def __init__(
    self,
    value: ArrayValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt, ...] = tuple(),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

element_type: Type[T]
shape: tuple[int | UInt, ...] Return the shape of the array.
value: ArrayValue

Methods¶

`consume`¶

def consume(self, operation_name: str = 'unknown') -> 'ArrayBase[T]'

Consume the array, enforcing borrow-return contract for quantum arrays.

`create`¶

@classmethod
def create(
    cls,
    shape: tuple[int | UInt, ...],
    name: str,
    el_type: Type[T],
) -> 'ArrayBase[T]'

Create an ArrayValue for the given shape and name.

`validate_all_returned`¶

def validate_all_returned(self) -> None

Validate all borrowed elements have been returned.

This method is useful for ensuring that all borrowed elements have been properly written back before using the array in operations that require the entire array.

Raises:

UnreturnedBorrowError — If any elements are still borrowed.

`ArrayValue` [source]¶

class ArrayValue(Value[T])

An array of values with shape information.

ArrayValue extends Value to represent multi-dimensional arrays of typed values (e.g., qubit registers, parameter vectors).

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

logical_id: str
name: str
params: dict[str, Any]
shape: tuple[Value, ...]
type: T
uuid: str

Methods¶

`next_version`¶

def next_version(self) -> ArrayValue[T]

Create a new ArrayValue with incremented version, preserving shape.

`Bit` [source]¶

class Bit(Handle)

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: bool = False,
) -> None

Attributes¶

init_value: bool

`BitType` [source]¶

class BitType(ClassicalTypeMixin, ValueType)

Type representing a classical bit.

`Dict` [source]¶

class Dict(Handle, Generic[K, V])

Dict handle for qkernel functions.

Represents a dictionary mapping keys to values, commonly used for Ising coefficients like {(i, j): Jij}.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

Constructor¶

def __init__(
    self,
    value: DictValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
) -> None

Attributes¶

size: UInt Return the number of entries as a UInt handle.
value: DictValue

Methods¶

`items`¶

def items(self) -> DictItemsIterator[K, V]

Return an iterator over (key, value) pairs.

`DictItemsIterator` [source]¶

class DictItemsIterator(Generic[K, V])

Iterator for Dict.items() that yields (key, value) pairs.

This is used internally for iterating over Dict entries in qkernel.

Constructor¶

def __init__(self, dict_handle: 'Dict[K, V]', _index: int = 0) -> None

Attributes¶

dict_handle: ‘Dict[K, V]’

`Float` [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: float = 0.0,
) -> None

Attributes¶

init_value: float

`FloatType` [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

`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]

`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

`Qubit` [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QubitType]

`Tracer` [source]¶

class Tracer

Constructor¶

def __init__(self, _operations: list[Operation] = list()) -> None

Attributes¶

operations: list[Operation]

Methods¶

`add_operation`¶

def add_operation(self, op) -> None

`UInt` [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: int = 0,
) -> None

Attributes¶

init_value: int

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

`Vector` [source]¶

class Vector(ArrayBase[T])

1-dimensional array type.

Example:

import qamomile.circuit as qmc

# Create a vector of 3 qubits
qubits: qmc.Vector[qmc.Qubit] = qmc.qubit_array(3, name="qubits")

# Access elements
q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0

# Apply H gate to all qubits (CORRECT)
n = qubits.shape[0]
for i in qmc.range(n):
    qubits[i] = qmc.h(qubits[i])

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

`WhileLoop` [source]¶

class WhileLoop

`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.frontend.operation.controlled¶

Controlled gate operations.

Overview¶

Function	Description
`controlled`	Create a controlled version of a quantum gate (QKernel).
`get_current_tracer`

Class	Description
`ControlledGate`	Wrapper for controlled version of a QKernel.
`ControlledUOperation`	Controlled-U operation that applies a unitary block conditionally.
`Float`	Floating-point handle with arithmetic operations.
`FloatType`	Type representing a floating-point number.
`QKernel`	Decorator class for Qamomile quantum kernels.
`Qubit`
`QubitAliasError`	Same qubit used multiple times in one operation.
`UInt`	Unsigned integer handle with arithmetic operations.
`UIntType`	Type representing an unsigned integer.
`Value`	A typed value in the IR with SSA-style versioning.

Functions¶

`controlled` [source]¶

def controlled(qkernel: 'QKernel', num_controls: int | UInt = 1) -> ControlledGate

Create a controlled version of a quantum gate (QKernel).

Parameters:

Name	Type	Description
`qkernel`	`'QKernel'`	A QKernel defining the gate to control.
`num_controls`	`int \| UInt`	Number of control qubits (default: 1). Can be int (concrete) or UInt (symbolic).

Returns:

ControlledGate — ControlledGate that can be called with (*controls, *targets, **params)

Example:

@qmc.qkernel
def rx_gate(q: Qubit, theta: float) -> Qubit:
    return qmc.rx(q, theta)

crx = qmc.controlled(rx_gate)
ctrl_out, tgt_out = crx(ctrl_qubit, target_qubit, theta=0.5)

# Double-controlled
ccrx = qmc.controlled(rx_gate, num_controls=2)
c0, c1, tgt = ccrx(ctrl0, ctrl1, target, theta=0.5)

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

Classes¶

`ControlledGate` [source]¶

class ControlledGate

Wrapper for controlled version of a QKernel.

Created by calling controlled(qkernel). The resulting object can be called like a gate function.

Example:

@qmc.qkernel
def phase_gate(q: Qubit, theta: float) -> Qubit:
    return qmc.p(q, theta)

controlled_phase = qmc.controlled(phase_gate)
ctrl_out, tgt_out = controlled_phase(ctrl, target, theta=0.5)

# Double-controlled
cc_phase = qmc.controlled(phase_gate, num_controls=2)
c0, c1, tgt = cc_phase(ctrl0, ctrl1, target, theta=0.5)

Constructor¶

def __init__(self, qkernel: 'QKernel', num_controls: int | UInt = 1) -> None

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

`Float` [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: float = 0.0,
) -> None

Attributes¶

init_value: float

`FloatType` [source]¶

class FloatType(ClassicalTypeMixin, ValueType)

Type representing a floating-point number.

`QKernel` [source]¶

class QKernel(Generic[P, R])

Decorator class for Qamomile quantum kernels.

Constructor¶

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

Attributes¶

block: BlockValue Compiles the function to a BlockValue (IR) if not already compiled.
func
input_types
name
output_types
raw_func
signature

Methods¶

`build`¶

def build(self, parameters: list[str] | None = None, **kwargs: Any = {}) -> Graph

Build the computation graph by tracing this kernel.

Parameters:

Name	Type	Description
`parameters`	`list[str] \| None`	List of argument names to keep as unbound parameters. - None (default): Auto-detect parameters (non-Qubit args without value/default) - []: No parameters (all non-Qubit args must have value/default) - [“name”]: Explicit parameter list Only float, int, UInt, and their arrays are allowed as parameters.
`**kwargs`	`Any`	Concrete values for non-parameter arguments.

Returns:

Graph — The traced computation graph ready for transpilation.

Raises:

TypeError — If a non-parameterizable type is specified as parameter.
ValueError — If required arguments are missing.

Example:

@qm.qkernel
def circuit(q: Qubit, theta: float) -> Qubit:
    q = qm.rx(q, theta)
    return q

# Auto-detect theta as parameter
graph = circuit.build()

# Explicit parameter list
graph = circuit.build(parameters=["theta"])

# theta bound to concrete value
graph = circuit.build(theta=0.5)

# Transpile with binding
transpiler = QiskitTranspiler()
result = transpiler.emit(graph, binding={"theta": 0.5})

`draw`¶

def draw(
    self,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
    **kwargs: Any = {},
) -> Any

Visualize the circuit using Matplotlib.

This method builds the computation graph and creates a static visualization. Parameters are auto-detected: non-Qubit arguments without concrete values are shown as symbolic parameters.

Parameters:

Name	Type	Description
`inline`	`bool`	If True, expand CallBlockOperation contents (inlining). If False (default), show CallBlockOperation as boxes.
`fold_loops`	`bool`	If True (default), display ForOperation as blocks instead of unrolling. If False, expand loops and show all iterations.
`expand_composite`	`bool`	If True, expand CompositeGateOperation (QFT, IQFT, etc.). If False (default), show as boxes. Independent of inline.
`inline_depth`	`int \| None`	Maximum nesting depth for inline expansion. None means unlimited (default). 0 means no inlining, 1 means top-level only, etc. Only affects CallBlock/ControlledU, not CompositeGate.
`**kwargs`	`Any`	Concrete values for arguments. Arguments not provided here (and without defaults) will be shown as symbolic parameters.

Returns:

Any — matplotlib.figure.Figure object.

Raises:

ImportError — If matplotlib is not installed.

Example:

import qamomile.circuit as qm

@qm.qkernel
def inner(q: qm.Qubit) -> qm.Qubit:
    return qm.x(q)

@qm.qkernel
def circuit(q: qm.Qubit, theta: float) -> qm.Qubit:
    q = inner(q)
    q = qm.h(q)
    q = qm.rx(q, theta)
    return q

# Draw with auto-detected symbolic parameter (theta)
fig = circuit.draw()

# Draw with bound parameter
fig = circuit.draw(theta=0.5)

# Draw with blocks as boxes (default)
fig = circuit.draw()

# Draw with blocks expanded (inlined)
fig = circuit.draw(inline=True)

# Draw with loops folded (shown as blocks)
fig = circuit.draw(fold_loops=True)

# Draw with composite gates expanded
fig = circuit.draw(expand_composite=True)

`estimate_resources`¶

def estimate_resources(self, *, bindings: dict[str, Any] | None = None) -> ResourceEstimate

Estimate all resources for this kernel’s circuit.

Convenience method that delegates to the module-level estimate_resources function, eliminating the need to access .block directly.

Parameters:

Name	Type	Description
`bindings`	`dict[str, Any] \| None`	Optional concrete parameter bindings (scalars and dicts). Dict values trigger `\|key\|` cardinality substitution.

Returns:

ResourceEstimate — ResourceEstimate with qubits, gates, and parameters.

Example:

>>> @qm.qkernel
... def bell() -> qm.Vector[qm.Qubit]:
...     q = qm.qubit_array(2)
...     q[0] = qm.h(q[0])
...     q[0], q[1] = qm.cx(q[0], q[1])
...     return q
>>> est = bell.estimate_resources()
>>> print(est.qubits)  # 2

`Qubit` [source]¶

class Qubit(Handle)

Constructor¶

def __init__(
    self,
    value: Value[QubitType],
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
) -> None

Attributes¶

value: Value[QubitType]

`QubitAliasError` [source]¶

class QubitAliasError(AffineTypeError)

Same qubit used multiple times in one operation.

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

Example of incorrect code:

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

Correct code:

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

`UInt` [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: int = 0,
) -> None

Attributes¶

init_value: int

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

qamomile.circuit.frontend.operation.expval¶

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

This module provides the expval() function for computing the expectation value of a Hamiltonian observable with respect to a quantum state.

Overview¶

Function	Description
`expval`	Compute the expectation value of an observable on a quantum state.
`get_current_tracer`

Class	Description
`ArrayValue`	An array of values with shape information.
`ExpvalOp`	Expectation value operation.
`FloatType`	Type representing a floating-point number.
`Value`	A typed value in the IR with SSA-style versioning.

Functions¶

`expval` [source]¶

def expval(qubits: Vector[Qubit] | tuple[Qubit, ...], hamiltonian: Observable) -> Float

Compute the expectation value of an observable on a quantum state.

This function computes <psi|H|psi> where psi is the quantum state represented by the qubits and H is the Hamiltonian observable.

The quantum state (qubits) is NOT consumed by this operation - the qubits can still be used for further operations after expval.

Parameters:

Name	Type	Description
`qubits`	`Vector[Qubit] \| tuple[Qubit, ...]`	The quantum register holding the prepared state. Can be a Vector[Qubit] or a tuple of individual Qubits.
`hamiltonian`	`Observable`	The Observable parameter representing the Hamiltonian. The actual qamomile.observable.Hamiltonian is provided via bindings.

Returns:

Float — Float containing the expectation value.

Example:

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

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

@qm.qkernel
def vqe_step(q: qm.Vector[qm.Qubit], H: qm.Observable) -> qm.Float:
    # Ansatz
    q[0] = qm.ry(q[0], theta)
    q[0], q[1] = qm.cx(q[0], q[1])

    # Expectation value -> Float
    return qm.expval(q, H)

# Pass Hamiltonian via bindings
executable = transpiler.transpile(vqe_step, bindings={"H": H})

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

Classes¶

`ArrayValue` [source]¶

class ArrayValue(Value[T])

An array of values with shape information.

ArrayValue extends Value to represent multi-dimensional arrays of typed values (e.g., qubit registers, parameter vectors).

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

logical_id: str
name: str
params: dict[str, Any]
shape: tuple[Value, ...]
type: T
uuid: str

Methods¶

`next_version`¶

def next_version(self) -> ArrayValue[T]

Create a new ArrayValue with incremented version, preserving shape.

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

`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.frontend.operation.measurement¶

Measurement operations for quantum circuits.

Overview¶

Function	Description
`get_current_tracer`
`measure`	Measure a qubit or QFixed in the computational basis.

Class	Description
`ArrayValue`	An array of values with shape information.
`IRMeasureOperation`
`MeasureQFixedOperation`	Measure a quantum fixed-point number.
`MeasureVectorOperation`	Measure a vector of qubits.
`UIntType`	Type representing an unsigned integer.
`Value`	A typed value in the IR with SSA-style versioning.
`VectorClass`	1-dimensional array type.

Functions¶

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

`measure` [source]¶

def measure(target: Union[Qubit, QFixed, Vector[Qubit]]) -> Union[Bit, Float, Vector[Bit]]

Measure a qubit or QFixed in the computational basis.

Performs a projective measurement in the Z-basis. The quantum resource is consumed by this operation and cannot be used afterwards.

Parameters:

Name	Type	Description
`target`	`Union[Qubit, QFixed, Vector[Qubit]]`	The quantum resource to measure. - Qubit: Returns a classical Bit - QFixed: Returns a Float (decoded from measured bits)

Returns:

Union[Bit, Float, Vector[Bit]] — Bit for Qubit input, Float for QFixed input.

Example:

@qkernel
def measure_qubit(q: Qubit) -> Bit:
    q = h(q)
    return measure(q)

@qkernel
def measure_qfixed(qf: QFixed) -> Float:
    # After QPE, qf holds phase bits
    return measure(qf)

Classes¶

`ArrayValue` [source]¶

class ArrayValue(Value[T])

An array of values with shape information.

ArrayValue extends Value to represent multi-dimensional arrays of typed values (e.g., qubit registers, parameter vectors).

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

logical_id: str
name: str
params: dict[str, Any]
shape: tuple[Value, ...]
type: T
uuid: str

Methods¶

`next_version`¶

def next_version(self) -> ArrayValue[T]

Create a new ArrayValue with incremented version, preserving shape.

`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

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

`Vector` [source]¶

class Vector(ArrayBase[T])

1-dimensional array type.

Example:

import qamomile.circuit as qmc

# Create a vector of 3 qubits
qubits: qmc.Vector[qmc.Qubit] = qmc.qubit_array(3, name="qubits")

# Access elements
q0 = qubits[0]
q0 = qmc.h(q0)
qubits[0] = q0

# Apply H gate to all qubits (CORRECT)
n = qubits.shape[0]
for i in qmc.range(n):
    qubits[i] = qmc.h(qubits[i])

Constructor¶

def __init__(
    self,
    value: ArrayValue = None,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _shape: tuple[int | UInt] = (0,),
    _borrowed_indices: dict[tuple[str, ...], tuple[UInt, ...]] = dict(),
) -> None

Attributes¶

value: ArrayValue

qamomile.circuit.frontend.operation.qubit_gates¶

Overview¶

Function	Description
`ccx`	Toffoli (CCX) gate: flips target when both controls are \|1>.
`cp`	Controlled-Phase gate.
`cx`	CNOT (Controlled-X) gate.
`cz`	CZ (Controlled-Z) gate.
`get_current_tracer`
`h`	Hadamard gate.
`p`	Phase gate: P(theta)\|1> = e^{i*theta}\|1>.
`rx`	Rotation around X-axis: RX(angle) = exp(-i * angle/2 * X).
`ry`	Rotation around Y-axis: RY(angle) = exp(-i * angle/2 * Y).
`rz`	Rotation around Z-axis: RZ(angle) = exp(-i * angle/2 * Z).
`rzz`	RZZ gate: exp(-i * angle/2 * Z ⊗ Z).
`s`	S gate (square root of Z).
`sdg`	S-dagger gate (inverse of S gate).
`swap`	SWAP gate: exchanges two qubits.
`t`	T gate (fourth root of Z).
`tdg`	T-dagger gate (inverse of T gate).
`x`	Pauli-X gate (NOT gate).
`y`	Pauli-Y gate.
`z`	Pauli-Z gate.

Class	Description
`GateOperationType`
`IRGateOperation`
`QubitAliasError`	Same qubit used multiple times in one operation.

Functions¶

`ccx` [source]¶

def ccx(control1: Qubit, control2: Qubit, target: Qubit) -> tuple[Qubit, Qubit, Qubit]

Toffoli (CCX) gate: flips target when both controls are |1>.

Parameters:

Name	Type	Description
`control1`	`Qubit`	First control qubit.
`control2`	`Qubit`	Second control qubit.
`target`	`Qubit`	Target qubit.

Returns:

tuple[Qubit, Qubit, Qubit] — Tuple of (control1_out, control2_out, target_out) after CCX.

`cp` [source]¶

def cp(control: Qubit, target: Qubit, theta: float | Float) -> tuple[Qubit, Qubit]

Controlled-Phase gate.

`cx` [source]¶

def cx(control: Qubit, target: Qubit) -> tuple[Qubit, Qubit]

CNOT (Controlled-X) gate.

`cz` [source]¶

def cz(control: Qubit, target: Qubit) -> tuple[Qubit, Qubit]

CZ (Controlled-Z) gate.

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

`h` [source]¶

def h(qubit: Qubit) -> Qubit

Hadamard gate.

`p` [source]¶

def p(qubit: Qubit, theta: float | Float) -> Qubit

Phase gate: P(theta)|1> = e^{i*theta}|1>.

`rx` [source]¶

def rx(qubit: Qubit, angle: float | Float) -> Qubit

Rotation around X-axis: RX(angle) = exp(-i * angle/2 * X).

`ry` [source]¶

def ry(qubit: Qubit, angle: float | Float) -> Qubit

Rotation around Y-axis: RY(angle) = exp(-i * angle/2 * Y).

`rz` [source]¶

def rz(qubit: Qubit, angle: float | Float) -> Qubit

Rotation around Z-axis: RZ(angle) = exp(-i * angle/2 * Z).

`rzz` [source]¶

def rzz(qubit_0: Qubit, qubit_1: Qubit, angle: float | Float) -> tuple[Qubit, Qubit]

RZZ gate: exp(-i * angle/2 * Z ⊗ Z).

The RZZ gate applies a rotation around the ZZ axis on two qubits.

Parameters:

Name	Type	Description
`qubit_0`	`Qubit`	First qubit.
`qubit_1`	`Qubit`	Second qubit.
`angle`	`float \| Float`	Rotation angle in radians.

Returns:

tuple[Qubit, Qubit] — Tuple of (qubit_0_out, qubit_1_out) after RZZ.

`s` [source]¶

def s(qubit: Qubit) -> Qubit

S gate (square root of Z).

`sdg` [source]¶

def sdg(qubit: Qubit) -> Qubit

S-dagger gate (inverse of S gate).

`swap` [source]¶

def swap(qubit_0: Qubit, qubit_1: Qubit) -> tuple[Qubit, Qubit]

SWAP gate: exchanges two qubits.

The SWAP gate swaps the states of two qubits.

Parameters:

Name	Type	Description
`qubit_0`	`Qubit`	First qubit.
`qubit_1`	`Qubit`	Second qubit.

Returns:

tuple[Qubit, Qubit] — Tuple of (qubit_0_out, qubit_1_out) after SWAP.

`t` [source]¶

def t(qubit: Qubit) -> Qubit

T gate (fourth root of Z).

`tdg` [source]¶

def tdg(qubit: Qubit) -> Qubit

T-dagger gate (inverse of T gate).

`x` [source]¶

def x(qubit: Qubit) -> Qubit

Pauli-X gate (NOT gate).

`y` [source]¶

def y(qubit: Qubit) -> Qubit

Pauli-Y gate.

`z` [source]¶

def z(qubit: Qubit) -> Qubit

Pauli-Z gate.

Classes¶

`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

`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

`QubitAliasError` [source]¶

class QubitAliasError(AffineTypeError)

Same qubit used multiple times in one operation.

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

Example of incorrect code:

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

Correct code:

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

qamomile.circuit.frontend.qkernel¶

Overview¶

Function	Description
`collect_quantum_rebind_violations`	Analyze func for forbidden quantum rebind patterns.
`create_dummy_input`	Create a dummy input based on parameter type annotation.
`func_to_block`	Convert a function to a BlockValue.
`get_current_tracer`
`is_array_type`	Check if type is a Vector, Matrix, or Tensor subclass.
`is_dict_type`	Check if type is a Dict handle type.
`is_tuple_type`	Check if type is a Tuple handle type.
`qkernel`	Decorator to define a Qamomile quantum kernel.
`qubit_array`	Create a new qubit array (vector/matrix/tensor) and emit QInitOperations.
`trace`	Context manager to set the current tracer.
`transform_control_flow`

Class	Description
`ArrayValue`	An array of values with shape information.
`BlockValue`	Represents a subroutine as a function block.
`Dict`	Dict handle for qkernel functions.
`DictValue`	A dictionary mapping keys to values.
`Float`	Floating-point handle with arithmetic operations.
`QKernel`	Decorator class for Qamomile quantum kernels.
`ResourceEstimate`	Comprehensive resource estimate for a quantum circuit.
`Tracer`
`UInt`	Unsigned integer handle with arithmetic operations.
`Value`	A typed value in the IR with SSA-style versioning.

Functions¶

`collect_quantum_rebind_violations` [source]¶

def collect_quantum_rebind_violations(func: Callable, quantum_param_names: set[str]) -> list[RebindViolation]

Analyze func for forbidden quantum rebind patterns.

Returns a (possibly empty) list of violations. Never raises on analysis failure – returns [] instead.

`create_dummy_input` [source]¶

def create_dummy_input(param_type: Any, name: str = 'param', emit_init: bool = True) -> Handle

Create a dummy input based on parameter type annotation.

Parameters:

Name	Type	Description
`param_type`	`typing.Any`	The type annotation for the parameter.
`name`	`str`	Name for the value.
`emit_init`	`bool`	If True, emit QInitOperation for qubit arrays (default: True). Set to False when creating BlockValue’s internal dummy inputs.

This creates input Handles for function parameters.

`func_to_block` [source]¶

def func_to_block(func: Callable) -> BlockValue

Convert a function to a BlockValue.

Example:

def my_func(a: UInt, b: UInt) -> tuple[UInt]:
    c = a + b
    return (c, )

block_value = func_to_block(my_func)

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

`is_array_type` [source]¶

def is_array_type(t: Any) -> bool

Check if type is a Vector, Matrix, or Tensor subclass.

`is_dict_type` [source]¶

def is_dict_type(t: Any) -> bool

Check if type is a Dict handle type.

`is_tuple_type` [source]¶

def is_tuple_type(t: Any) -> bool

Check if type is a Tuple handle type.

`qkernel` [source]¶

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

Decorator to define a Qamomile quantum kernel.

Parameters:

Name	Type	Description
`func`	`Callable[P, R]`	The function to decorate.

Returns:

QKernel[P, R] — An instance of QKernel wrapping the function.

`qubit_array` [source]¶

def qubit_array(
    shape: UInt | int | tuple[UInt | int, ...],
    name: str,
) -> Vector[Qubit] | Matrix[Qubit] | Tensor[Qubit]

Create a new qubit array (vector/matrix/tensor) and emit QInitOperations.

`trace` [source]¶

def trace(tracer: Tracer | None = None) -> Generator[Tracer, None, None]

Context manager to set the current tracer.

`transform_control_flow` [source]¶

def transform_control_flow(func: Callable)

Classes¶

`ArrayValue` [source]¶

class ArrayValue(Value[T])

An array of values with shape information.

ArrayValue extends Value to represent multi-dimensional arrays of typed values (e.g., qubit registers, parameter vectors).

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, ...] = (),
    shape: tuple[Value, ...] = tuple(),
) -> None

Attributes¶

logical_id: str
name: str
params: dict[str, Any]
shape: tuple[Value, ...]
type: T
uuid: str

Methods¶

`next_version`¶

def next_version(self) -> ArrayValue[T]

Create a new ArrayValue with incremented version, preserving shape.

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

`Dict` [source]¶

class Dict(Handle, Generic[K, V])

Dict handle for qkernel functions.

Represents a dictionary mapping keys to values, commonly used for Ising coefficients like {(i, j): Jij}.

Example:

@qmc.qkernel
def ising_cost(
    q: qmc.Vector[qmc.Qubit],
    ising: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]:
    for (i, j), Jij in qmc.items(ising):
        q[i], q[j] = qmc.rzz(q[i], q[j], gamma * Jij)
    return q

Constructor¶

def __init__(
    self,
    value: DictValue,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    _entries: list[tuple[Handle, Handle]] = list(),
    _size: UInt | None = None,
    _key_type: type | None = None,
) -> None

Attributes¶

size: UInt Return the number of entries as a UInt handle.
value: DictValue

Methods¶

`items`¶

def items(self) -> DictItemsIterator[K, V]

Return an iterator over (key, value) pairs.

`DictValue` [source]¶

class DictValue

A dictionary mapping keys to values.

Used for structured data like Ising coefficients {(i, j): Jij}. Entries are stored as a list of (key, value) pairs for consistent ordering. Implements the ValueBase protocol for unified handling.

Constructor¶

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

Attributes¶

entries: list[tuple[TupleValue | Value, Value]]
logical_id: str
name: str
params: dict[str, Any]
type: DictType Return type interface for compatibility with Value.
uuid: str

Methods¶

`is_constant`¶

def is_constant(self) -> bool

Check if all entries have constant values.

`is_parameter`¶

def is_parameter(self) -> bool

Check if this dict is a parameter (bound at transpile time).

`next_version`¶

def next_version(self) -> DictValue

Create a new DictValue with a fresh uuid but same logical_id.

`parameter_name`¶

def parameter_name(self) -> str | None

Get the parameter name if this is a parameter.

`Float` [source]¶

class Float(ArithmeticMixin, Handle)

Floating-point handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: float = 0.0,
) -> None

Attributes¶

init_value: float

`QKernel` [source]¶

class QKernel(Generic[P, R])

Decorator class for Qamomile quantum kernels.

Constructor¶

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

Attributes¶

block: BlockValue Compiles the function to a BlockValue (IR) if not already compiled.
func
input_types
name
output_types
raw_func
signature

Methods¶

`build`¶

def build(self, parameters: list[str] | None = None, **kwargs: Any = {}) -> Graph

Build the computation graph by tracing this kernel.

Parameters:

Name	Type	Description
`parameters`	`list[str] \| None`	List of argument names to keep as unbound parameters. - None (default): Auto-detect parameters (non-Qubit args without value/default) - []: No parameters (all non-Qubit args must have value/default) - [“name”]: Explicit parameter list Only float, int, UInt, and their arrays are allowed as parameters.
`**kwargs`	`Any`	Concrete values for non-parameter arguments.

Returns:

Graph — The traced computation graph ready for transpilation.

Raises:

TypeError — If a non-parameterizable type is specified as parameter.
ValueError — If required arguments are missing.

Example:

@qm.qkernel
def circuit(q: Qubit, theta: float) -> Qubit:
    q = qm.rx(q, theta)
    return q

# Auto-detect theta as parameter
graph = circuit.build()

# Explicit parameter list
graph = circuit.build(parameters=["theta"])

# theta bound to concrete value
graph = circuit.build(theta=0.5)

# Transpile with binding
transpiler = QiskitTranspiler()
result = transpiler.emit(graph, binding={"theta": 0.5})

`draw`¶

def draw(
    self,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
    **kwargs: Any = {},
) -> Any

Visualize the circuit using Matplotlib.

This method builds the computation graph and creates a static visualization. Parameters are auto-detected: non-Qubit arguments without concrete values are shown as symbolic parameters.

Parameters:

Name	Type	Description
`inline`	`bool`	If True, expand CallBlockOperation contents (inlining). If False (default), show CallBlockOperation as boxes.
`fold_loops`	`bool`	If True (default), display ForOperation as blocks instead of unrolling. If False, expand loops and show all iterations.
`expand_composite`	`bool`	If True, expand CompositeGateOperation (QFT, IQFT, etc.). If False (default), show as boxes. Independent of inline.
`inline_depth`	`int \| None`	Maximum nesting depth for inline expansion. None means unlimited (default). 0 means no inlining, 1 means top-level only, etc. Only affects CallBlock/ControlledU, not CompositeGate.
`**kwargs`	`Any`	Concrete values for arguments. Arguments not provided here (and without defaults) will be shown as symbolic parameters.

Returns:

Any — matplotlib.figure.Figure object.

Raises:

ImportError — If matplotlib is not installed.

Example:

import qamomile.circuit as qm

@qm.qkernel
def inner(q: qm.Qubit) -> qm.Qubit:
    return qm.x(q)

@qm.qkernel
def circuit(q: qm.Qubit, theta: float) -> qm.Qubit:
    q = inner(q)
    q = qm.h(q)
    q = qm.rx(q, theta)
    return q

# Draw with auto-detected symbolic parameter (theta)
fig = circuit.draw()

# Draw with bound parameter
fig = circuit.draw(theta=0.5)

# Draw with blocks as boxes (default)
fig = circuit.draw()

# Draw with blocks expanded (inlined)
fig = circuit.draw(inline=True)

# Draw with loops folded (shown as blocks)
fig = circuit.draw(fold_loops=True)

# Draw with composite gates expanded
fig = circuit.draw(expand_composite=True)

`estimate_resources`¶

def estimate_resources(self, *, bindings: dict[str, Any] | None = None) -> ResourceEstimate

Estimate all resources for this kernel’s circuit.

Convenience method that delegates to the module-level estimate_resources function, eliminating the need to access .block directly.

Parameters:

Name	Type	Description
`bindings`	`dict[str, Any] \| None`	Optional concrete parameter bindings (scalars and dicts). Dict values trigger `\|key\|` cardinality substitution.

Returns:

ResourceEstimate — ResourceEstimate with qubits, gates, and parameters.

Example:

>>> @qm.qkernel
... def bell() -> qm.Vector[qm.Qubit]:
...     q = qm.qubit_array(2)
...     q[0] = qm.h(q[0])
...     q[0], q[1] = qm.cx(q[0], q[1])
...     return q
>>> est = bell.estimate_resources()
>>> print(est.qubits)  # 2

`ResourceEstimate` [source]¶

class ResourceEstimate

Comprehensive resource estimate for a quantum circuit.

All metrics are SymPy expressions that may contain symbols for parametric problem sizes.

Constructor¶

def __init__(
    self,
    qubits: sp.Expr,
    gates: GateCount,
    parameters: dict[str, sp.Symbol] = dict(),
) -> None

Attributes¶

gates: GateCount
parameters: dict[str, sp.Symbol]
qubits: sp.Expr

Methods¶

`simplify`¶

def simplify(self) -> ResourceEstimate

Simplify all SymPy expressions.

Returns:

ResourceEstimate — New ResourceEstimate with simplified expressions

`substitute`¶

def substitute(self, **values: int | float = {}) -> ResourceEstimate

Substitute concrete values for parameters.

Parameters:

Name	Type	Description
`**values`	`int \| float`	Parameter name -> concrete value mappings

Returns:

ResourceEstimate — New ResourceEstimate with substituted values

Example:

>>> est = estimate_resources(circuit)
>>> concrete = est.substitute(n=100, p=3)
>>> print(concrete.qubits)  # 100 (instead of 'n')

`to_dict`¶

def to_dict(self) -> dict[str, Any]

Convert to a dictionary for serialization.

Returns:

dict[str, Any] — Dictionary with all metrics as strings (for JSON/YAML export)

Example:

>>> est = estimate_resources(circuit)
>>> data = est.to_dict()
>>> import json
>>> print(json.dumps(data, indent=2))

`Tracer` [source]¶

class Tracer

Constructor¶

def __init__(self, _operations: list[Operation] = list()) -> None

Attributes¶

operations: list[Operation]

Methods¶

`add_operation`¶

def add_operation(self, op) -> None

`UInt` [source]¶

class UInt(ArithmeticMixin, Handle)

Unsigned integer handle with arithmetic operations.

Constructor¶

def __init__(
    self,
    value: Value,
    parent: 'ArrayBase | None' = None,
    indices: tuple['UInt', ...] = (),
    name: str | None = None,
    id: str = (lambda: str(uuid.uuid4()))(),
    _consumed: bool = False,
    _consumed_by: str | None = None,
    init_value: int = 0,
) -> None

Attributes¶

init_value: int

`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.frontend.tracer¶

Overview¶

Function	Description
`get_current_tracer`
`trace`	Context manager to set the current tracer.

Class	Description
`Operation`
`Tracer`

Functions¶

`get_current_tracer` [source]¶

def get_current_tracer() -> Tracer

`trace` [source]¶

def trace(tracer: Tracer | None = None) -> Generator[Tracer, None, None]

Context manager to set the current tracer.

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

`Tracer` [source]¶

class Tracer

Constructor¶

def __init__(self, _operations: list[Operation] = list()) -> None

Attributes¶

operations: list[Operation]

Methods¶

`add_operation`¶

def add_operation(self, op) -> None

qamomile.circuit.frontend.ast_transform¶

Overview¶

Functions¶

collect_quantum_rebind_violations [source]¶

emit_if [source]¶

for_items [source]¶

for_loop [source]¶

transform_control_flow [source]¶

while_loop [source]¶

Classes¶

ControlFlowTransformer [source]¶

Constructor¶

Attributes¶

Methods¶

visit_AnnAssign¶

visit_For¶

visit_FunctionDef¶

visit_If¶

visit_While¶

QuantumRebindAnalyzer [source]¶

Constructor¶

Attributes¶

Methods¶

visit_Assign¶

RebindViolation [source]¶

Constructor¶

Attributes¶

VariableCollector [source]¶

Constructor¶

Attributes¶

Methods¶

visit_Assign¶

visit_Attribute¶

visit_AugAssign¶

visit_Call¶

visit_FunctionDef¶

visit_Name¶

qamomile.circuit.frontend.composite_gate¶

Overview¶

Functions¶

composite_gate [source]¶

get_current_tracer [source]¶

trace [source]¶

Classes¶

BlockValue [source]¶

Constructor¶

Attributes¶

Methods¶

call¶

CompositeGate [source]¶

Attributes¶

Methods¶

build_decomposition¶

get_implementation¶

get_resource_metadata¶

get_resources_for_strategy¶

get_strategy¶

list_strategies¶

register_strategy¶

set_default_strategy¶

CompositeGateOperation [source]¶

Constructor¶

Attributes¶

CompositeGateType [source]¶

Attributes¶

DecompositionStrategy [source]¶

Attributes¶

Methods¶

decompose¶

resources¶

Qubit [source]¶

Constructor¶

Attributes¶

ResourceMetadata [source]¶

Constructor¶

Attributes¶

Tracer [source]¶

Constructor¶

Attributes¶

`collect_quantum_rebind_violations` [source]¶

`emit_if` [source]¶

`for_items` [source]¶

`for_loop` [source]¶

`transform_control_flow` [source]¶

`while_loop` [source]¶

`ControlFlowTransformer` [source]¶

`visit_AnnAssign`¶

`visit_For`¶

`visit_FunctionDef`¶

`visit_If`¶

`visit_While`¶

`QuantumRebindAnalyzer` [source]¶

`visit_Assign`¶

`RebindViolation` [source]¶

`VariableCollector` [source]¶

`visit_Assign`¶

`visit_Attribute`¶

`visit_AugAssign`¶

`visit_Call`¶

`visit_FunctionDef`¶

`visit_Name`¶

`composite_gate` [source]¶

`get_current_tracer` [source]¶

`trace` [source]¶

`BlockValue` [source]¶

`call`¶

`CompositeGate` [source]¶

`build_decomposition`¶

`get_implementation`¶

`get_resource_metadata`¶

`get_resources_for_strategy`¶

`get_strategy`¶

`list_strategies`¶

`register_strategy`¶

`set_default_strategy`¶

`CompositeGateOperation` [source]¶

`CompositeGateType` [source]¶

`DecompositionStrategy` [source]¶

`decompose`¶

`resources`¶

`Qubit` [source]¶

`ResourceMetadata` [source]¶

`Tracer` [source]¶

`add_operation`¶

`Value` [source]¶

`get_cast_qubit_logical_ids`¶

`get_cast_qubit_uuids`¶

`get_cast_source_logical_id`¶

`get_cast_source_uuid`¶

`get_const`¶

`get_lowered_bits`¶

`get_lowered_qubits`¶

`is_array_element`¶

`is_cast_result`¶

`is_constant`¶

`is_parameter`¶

`next_version`¶

`parameter_name`¶

`set_cast_metadata`¶

`set_lowered_bits`¶

`set_lowered_qubits`¶

`Vector` [source]¶

`bit` [source]¶

`float_` [source]¶

`get_current_tracer` [source]¶

`qubit` [source]¶

`qubit_array` [source]¶

`uint` [source]¶

`ArrayValue` [source]¶

`next_version`¶

`QInitOperation` [source]¶

`Value` [source]¶

`get_cast_qubit_logical_ids`¶

`get_cast_qubit_uuids`¶

`get_cast_source_logical_id`¶

`get_cast_source_uuid`¶

`get_const`¶

`get_lowered_bits`¶

`get_lowered_qubits`¶