qamomile.circuit.visualization

Circuit visualization module.

This module provides static matplotlib-based circuit visualization with a Qiskit-inspired layout style.

Overview¶

Class	Description
`CircuitStyle`	Style configuration for circuit visualization.
`MatplotlibDrawer`	Matplotlib-based circuit drawer with Qiskit-style layout.

Classes¶

`CircuitStyle` [source]¶

class CircuitStyle

Style configuration for circuit visualization.

Constructor¶

def __init__(
    self,
    gate_width: float = 0.65,
    gate_height: float = 0.65,
    gate_corner_radius: float = 0.2,
    background_color: str = '#FFFFFF',
    wire_color: str = '#000000',
    gate_face_color: str = '#E8B878',
    gate_symbol_color: str = '#E8B878',
    gate_symbol_edge_color: str = '#000000',
    gate_text_color: str = '#000000',
    connection_line_color: str = '#000000',
    block_face_color: str = '#5B7F61',
    block_text_color: str = '#FFFFFF',
    block_border_color: str = '#4A6B50',
    block_box_edge_color: str = '#4A6B50',
    measure_face_color: str = '#D5CCC4',
    measure_symbol_color: str = '#6B5F55',
    for_loop_face_color: str = '#F0E4D0',
    for_loop_text_color: str = '#000000',
    for_loop_edge_color: str = '#C4A882',
    while_loop_face_color: str = '#E0D4F0',
    while_loop_text_color: str = '#000000',
    while_loop_edge_color: str = '#A88BC8',
    for_items_face_color: str = '#D0E8D0',
    for_items_text_color: str = '#000000',
    for_items_edge_color: str = '#90B890',
    if_face_color: str = '#F0D8D0',
    if_text_color: str = '#000000',
    if_edge_color: str = '#C8A898',
    expval_face_color: str = '#D4E8F0',
    expval_text_color: str = '#000000',
    expval_edge_color: str = '#8AB4C8',
    font_size: int = 13,
    subfont_size: int = 10,
    param_font_size: int = 9,
    margin: tuple[float, float, float, float] = (0.5, 0.1, 0.1, 0.3),
    gate_gap: float = 0.3,
    char_width_base: float = 0.12,
    char_width_bold: float = 0.14,
    char_width_gate: float = 0.14,
    char_width_block: float = 0.17,
    char_width_monospace: float = 0.17,
    text_padding: float = 0.25,
    border_padding_base: float = 0.3,
    border_padding_depth_factor: float = 0.1,
    min_left_margin: float = 0.3,
    label_height: float = 0.35,
    box_padding_x: float = 0.3,
    box_padding_y: float = 0.2,
    label_vertical_offset: float = 0.05,
    label_horizontal_padding: float = 0.1,
    initial_wire_position: float = 0.3,
    wire_extension: float = 0.3,
    operation_width_padding: float = 0.4,
    operation_content_padding: float = 0.6,
    line_height: float = 0.4,
    fallback_char_width: float = 0.15,
    fallback_text_height: float = 0.15,
    font_scaling_adjustment: float = 0.85,
    nested_margin: float = 0.15,
    border_extra_margin_right: float = 0.8,
    border_extra_margin_left: float = 0.3,
    folded_loop_width: float = 1.5,
    folded_call_block_width: float = 1.5,
    gate_text_padding: float = 0.1,
    nested_padding_decay: float = 0.85,
    min_block_padding: float = 0.1,
    power_wrapper_margin: float = 0.2,
    folded_box_text_v_padding: float = 0.15,
    max_folded_body_chars: int = 40,
    qubit_base_spacing: float = 1.0,
    qubit_clearance: float = 0.15,
    label_step_gap: float = 0.1,
    overlap_step_gap: float = 0.15,
    label_padding: float = 0.05,
    qubit_y_label_height: float = 0.25,
    figure_scale_factor: float = 0.8,
    figure_min_width: float = 4.0,
    figure_min_height: float = 2.0,
    x_left_min_bound: float = -1.0,
) -> None

Attributes¶

background_color: str
block_border_color: str
block_box_edge_color: str
block_face_color: str
block_text_color: str
border_extra_margin_left: float
border_extra_margin_right: float
border_padding_base: float
border_padding_depth_factor: float
box_padding_x: float
box_padding_y: float
char_width_base: float
char_width_block: float
char_width_bold: float
char_width_gate: float
char_width_monospace: float
connection_line_color: str
expval_edge_color: str
expval_face_color: str
expval_text_color: str
fallback_char_width: float
fallback_text_height: float
figure_min_height: float
figure_min_width: float
figure_scale_factor: float
folded_box_text_v_padding: float
folded_call_block_width: float
folded_loop_width: float
font_scaling_adjustment: float
font_size: int
for_items_edge_color: str
for_items_face_color: str
for_items_text_color: str
for_loop_edge_color: str
for_loop_face_color: str
for_loop_text_color: str
gate_corner_radius: float
gate_face_color: str
gate_gap: float
gate_height: float
gate_symbol_color: str
gate_symbol_edge_color: str
gate_text_color: str
gate_text_padding: float
gate_width: float
if_edge_color: str
if_face_color: str
if_text_color: str
initial_wire_position: float
label_height: float
label_horizontal_padding: float
label_padding: float
label_step_gap: float
label_vertical_offset: float
line_height: float
margin: tuple[float, float, float, float]
max_folded_body_chars: int
measure_face_color: str
measure_symbol_color: str
min_block_padding: float
min_left_margin: float
nested_margin: float
nested_padding_decay: float
operation_content_padding: float
operation_width_padding: float
overlap_step_gap: float
param_font_size: int
power_wrapper_margin: float
qubit_base_spacing: float
qubit_clearance: float
qubit_y_label_height: float
subfont_size: int
text_padding: float
while_loop_edge_color: str
while_loop_face_color: str
while_loop_text_color: str
wire_color: str
wire_extension: float
x_left_min_bound: float

`MatplotlibDrawer` [source]¶

class MatplotlibDrawer

Matplotlib-based circuit drawer with Qiskit-style layout.

This drawer produces static matplotlib figures showing quantum circuits. It supports two modes:

Block mode (inline=False): Shows CallBlockOperation as boxes
Inline mode (inline=True): Expands CallBlockOperation contents

Constructor¶

def __init__(self, graph: Block, style: CircuitStyle | None = None)

Initialize the drawer.

Parameters:

Name	Type	Description
`graph`	`Block`	Computation graph to visualize.
`style`	`CircuitStyle \| None`	Visual style configuration. Uses DEFAULT_STYLE if None.

Attributes¶

graph
style

Methods¶

`draw`¶

def draw(
    self,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
) -> Figure

Generate a matplotlib Figure of the circuit.

Parameters:

Name	Type	Description
`inline`	`bool`	If True, expand CallBlockOperation. If False, show 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.

Returns:

Figure — Figure object.

`draw_kernel`¶

@classmethod
def draw_kernel(
    cls,
    kernel: Any,
    *,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
    style: CircuitStyle | None = None,
    **kwargs: Any = {},
) -> Figure

Draw a QKernel, handling Vector[Qubit] params with integer sizes.

For kernels with Vector[Qubit] parameters, pass an integer to specify the array size (e.g., inputs=3 for a 3-qubit vector).

Parameters:

Name	Type	Description
`kernel`	`Any`	A QKernel instance to visualize.
`inline`	`bool`	If True, expand CallBlockOperation contents.
`fold_loops`	`bool`	If True (default), display ForOperation as blocks.
`expand_composite`	`bool`	If True, expand CompositeGateOperation.
`inline_depth`	`int \| None`	Maximum nesting depth for inline expansion.
`style`	`CircuitStyle \| None`	Visual style configuration.
`**kwargs`	`Any`	Concrete values for kernel arguments. For Vector[Qubit] parameters, pass an integer size.

Returns:

Figure — Figure object.

qamomile.circuit.visualization.analyzer¶

Circuit analysis: IR inspection, value resolution, and label generation.

This module provides CircuitAnalyzer, which handles all IR-level analysis for the circuit visualization pipeline. It has no matplotlib dependency.

Overview¶

Function	Description
`compute_border_padding`	Compute border padding for a given nesting depth.

Class	Description
`ArrayValue`	An array of typed IR values.
`BinOp`	Binary arithmetic operation (ADD, SUB, MUL, DIV, FLOORDIV, POW).
`BinOpKind`
`Block`	Unified block representation for all pipeline stages.
`CallBlockOperation`
`CastOperation`	Type cast operation for creating aliases over the same quantum resources.
`CircuitAnalyzer`	Analyzes IR blocks for circuit visualization.
`CircuitStyle`	Style configuration for circuit visualization.
`CompositeGateOperation`	Represents a composite gate (QPE, QFT, etc.) as a single operation.
`ControlledUOperation`	Base class for controlled-U operations.
`ExpvalOp`	Expectation value operation.
`ForItemsOperation`	Represents iteration over dict/iterable items.
`ForOperation`	Represents a for loop operation.
`GateOperation`	Quantum gate operation.
`GateOperationType`
`IfOperation`	Represents an if-else conditional operation.
`MeasureOperation`
`MeasureVectorOperation`	Measure a vector of qubits.
`QInitOperation`	Initialize the qubit
`QubitType`	Type representing a quantum bit (qubit).
`VFoldedBlock`	Folded control-flow block (For/While/ForItems/If).
`VFoldedKind`	Classification of folded control-flow blocks.
`VGate`	Pre-resolved gate, measurement, block-box, or expval node.
`VGateKind`	Classification of VGate nodes for rendering dispatch.
`VInlineBlock`	Inlined CallBlock/ControlledU/CompositeGate with visible border.
`VSkip`	Zero-space node for QInit, Cast, or zero-iteration loops.
`VUnfoldedKind`	Classification of unfolded control-flow sequences.
`VUnfoldedSequence`	Unfolded control-flow sequence (For/ForItems/If).
`Value`	A typed SSA value in the IR.
`VisualCircuit`	Root container for the Visual IR tree.
`WhileOperation`	Represents a while loop operation.

Functions¶

`compute_border_padding` [source]¶

def compute_border_padding(style: CircuitStyle, depth: int) -> float

Compute border padding for a given nesting depth.

Parameters:

Name	Type	Description
`style`	`CircuitStyle`	Visual style configuration.
`depth`	`int`	Nesting depth of the block.

Returns:

float — Border padding value, clamped to min_block_padding.

Classes¶

`ArrayValue` [source]¶

class ArrayValue(Value[T])

An array of typed IR values.

Constructor¶

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

Attributes¶

logical_id: str
metadata: ValueMetadata
name: str
shape: tuple[Value, ...]
type: T
uuid: str

Methods¶

`next_version`¶

def next_version(self) -> ArrayValue[T]

`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

`Block` [source]¶

class Block

Unified block representation for all pipeline stages.

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

Constructor¶

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

Attributes¶

input_values: list[Value]
kind: BlockKind
label_args: list[str]
name: str
operations: list[‘Operation’]
output_names: list[str]
output_values: list[Value]
parameters: dict[str, Value]

Methods¶

`call`¶

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

Create a CallBlockOperation against this block.

`is_affine`¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

`unbound_parameters`¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

`CallBlockOperation` [source]¶

class CallBlockOperation(Operation)

Constructor¶

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

Attributes¶

block: Block | None
operation_kind: OperationKind
signature: Signature

Methods¶

`is_self_reference_to`¶

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

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

`CastOperation` [source]¶

class CastOperation(Operation)

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

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

Use cases:

Vector[Qubit] -> QFixed (after QPE, for phase measurement)
Vector[Qubit] -> QUInt (for quantum arithmetic)
QUInt -> QFixed (reinterpret bits with different encoding)
QFixed -> QUInt (reinterpret bits with different encoding)

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

Constructor¶

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

Attributes¶

num_qubits: int Number of qubits involved in the cast.
operation_kind: OperationKind Cast stays in the same segment as its source (QUANTUM for quantum types).
qubit_mapping: list[str]
signature: Signature Return the type signature of this cast operation.
source_type: ValueType | None
target_type: ValueType | None

`CircuitAnalyzer` [source]¶

class CircuitAnalyzer

Analyzes IR blocks for circuit visualization.

Handles qubit mapping, value resolution, label generation, and width estimation. Has no matplotlib dependency.

Constructor¶

def __init__(
    self,
    graph: 'Block',
    style: CircuitStyle,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
)

Attributes¶

expand_composite
fold_loops
graph
inline
inline_depth
style

Methods¶

`build_qubit_map`¶

def build_qubit_map(self, graph: 'Block') -> tuple[dict[str, int], dict[int, str], int]

Build mapping from qubit logical_id to wire indices.

In SSA form, each operation creates new Values via next_version(), which preserves logical_id. This means all versions of a qubit share the same logical_id, so we only need logical_id-based tracking.

Parameters:

Name	Type	Description
`graph`	`'Block'`	Computation block.

Returns:

tuple[dict[str, int], dict[int, str], int] — Tuple of (qubit_map, qubit_names, num_qubits).

`build_visual_ir`¶

def build_visual_ir(
    self,
    graph: 'Block',
    qubit_map: dict[str, int],
    qubit_names: dict[int, str],
    num_qubits: int,
) -> VisualCircuit

Build a Visual IR tree from the IR block.

Walks all operations, resolving labels, qubit indices, and widths into pre-computed VisualNode dataclasses. The resulting VisualCircuit can be consumed by Layout and Renderer without any Analyzer access.

Parameters:

Name	Type	Description
`graph`	`'Block'`	IR computation block.
`qubit_map`	`dict[str, int]`	Mapping from logical_id to wire index.
`qubit_names`	`dict[int, str]`	Mapping from wire index to display name.
`num_qubits`	`int`	Total number of qubit wires.

Returns:

VisualCircuit — VisualCircuit containing the VisualNode tree.

`CircuitStyle` [source]¶

class CircuitStyle

Style configuration for circuit visualization.

Constructor¶

def __init__(
    self,
    gate_width: float = 0.65,
    gate_height: float = 0.65,
    gate_corner_radius: float = 0.2,
    background_color: str = '#FFFFFF',
    wire_color: str = '#000000',
    gate_face_color: str = '#E8B878',
    gate_symbol_color: str = '#E8B878',
    gate_symbol_edge_color: str = '#000000',
    gate_text_color: str = '#000000',
    connection_line_color: str = '#000000',
    block_face_color: str = '#5B7F61',
    block_text_color: str = '#FFFFFF',
    block_border_color: str = '#4A6B50',
    block_box_edge_color: str = '#4A6B50',
    measure_face_color: str = '#D5CCC4',
    measure_symbol_color: str = '#6B5F55',
    for_loop_face_color: str = '#F0E4D0',
    for_loop_text_color: str = '#000000',
    for_loop_edge_color: str = '#C4A882',
    while_loop_face_color: str = '#E0D4F0',
    while_loop_text_color: str = '#000000',
    while_loop_edge_color: str = '#A88BC8',
    for_items_face_color: str = '#D0E8D0',
    for_items_text_color: str = '#000000',
    for_items_edge_color: str = '#90B890',
    if_face_color: str = '#F0D8D0',
    if_text_color: str = '#000000',
    if_edge_color: str = '#C8A898',
    expval_face_color: str = '#D4E8F0',
    expval_text_color: str = '#000000',
    expval_edge_color: str = '#8AB4C8',
    font_size: int = 13,
    subfont_size: int = 10,
    param_font_size: int = 9,
    margin: tuple[float, float, float, float] = (0.5, 0.1, 0.1, 0.3),
    gate_gap: float = 0.3,
    char_width_base: float = 0.12,
    char_width_bold: float = 0.14,
    char_width_gate: float = 0.14,
    char_width_block: float = 0.17,
    char_width_monospace: float = 0.17,
    text_padding: float = 0.25,
    border_padding_base: float = 0.3,
    border_padding_depth_factor: float = 0.1,
    min_left_margin: float = 0.3,
    label_height: float = 0.35,
    box_padding_x: float = 0.3,
    box_padding_y: float = 0.2,
    label_vertical_offset: float = 0.05,
    label_horizontal_padding: float = 0.1,
    initial_wire_position: float = 0.3,
    wire_extension: float = 0.3,
    operation_width_padding: float = 0.4,
    operation_content_padding: float = 0.6,
    line_height: float = 0.4,
    fallback_char_width: float = 0.15,
    fallback_text_height: float = 0.15,
    font_scaling_adjustment: float = 0.85,
    nested_margin: float = 0.15,
    border_extra_margin_right: float = 0.8,
    border_extra_margin_left: float = 0.3,
    folded_loop_width: float = 1.5,
    folded_call_block_width: float = 1.5,
    gate_text_padding: float = 0.1,
    nested_padding_decay: float = 0.85,
    min_block_padding: float = 0.1,
    power_wrapper_margin: float = 0.2,
    folded_box_text_v_padding: float = 0.15,
    max_folded_body_chars: int = 40,
    qubit_base_spacing: float = 1.0,
    qubit_clearance: float = 0.15,
    label_step_gap: float = 0.1,
    overlap_step_gap: float = 0.15,
    label_padding: float = 0.05,
    qubit_y_label_height: float = 0.25,
    figure_scale_factor: float = 0.8,
    figure_min_width: float = 4.0,
    figure_min_height: float = 2.0,
    x_left_min_bound: float = -1.0,
) -> None

Attributes¶

background_color: str
block_border_color: str
block_box_edge_color: str
block_face_color: str
block_text_color: str
border_extra_margin_left: float
border_extra_margin_right: float
border_padding_base: float
border_padding_depth_factor: float
box_padding_x: float
box_padding_y: float
char_width_base: float
char_width_block: float
char_width_bold: float
char_width_gate: float
char_width_monospace: float
connection_line_color: str
expval_edge_color: str
expval_face_color: str
expval_text_color: str
fallback_char_width: float
fallback_text_height: float
figure_min_height: float
figure_min_width: float
figure_scale_factor: float
folded_box_text_v_padding: float
folded_call_block_width: float
folded_loop_width: float
font_scaling_adjustment: float
font_size: int
for_items_edge_color: str
for_items_face_color: str
for_items_text_color: str
for_loop_edge_color: str
for_loop_face_color: str
for_loop_text_color: str
gate_corner_radius: float
gate_face_color: str
gate_gap: float
gate_height: float
gate_symbol_color: str
gate_symbol_edge_color: str
gate_text_color: str
gate_text_padding: float
gate_width: float
if_edge_color: str
if_face_color: str
if_text_color: str
initial_wire_position: float
label_height: float
label_horizontal_padding: float
label_padding: float
label_step_gap: float
label_vertical_offset: float
line_height: float
margin: tuple[float, float, float, float]
max_folded_body_chars: int
measure_face_color: str
measure_symbol_color: str
min_block_padding: float
min_left_margin: float
nested_margin: float
nested_padding_decay: float
operation_content_padding: float
operation_width_padding: float
overlap_step_gap: float
param_font_size: int
power_wrapper_margin: float
qubit_base_spacing: float
qubit_clearance: float
qubit_y_label_height: float
subfont_size: int
text_padding: float
while_loop_edge_color: str
while_loop_face_color: str
while_loop_text_color: str
wire_color: str
wire_extension: float
x_left_min_bound: float

`CompositeGateOperation` [source]¶

class CompositeGateOperation(Operation)

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

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

Resource estimation without full implementation
Backend-native conversion (e.g., Qiskit’s QPE)
User-defined complex gates

The operands structure is:

operands[0:num_control_qubits]: Control qubits (if any)
operands[num_control_qubits:num_control_qubits+num_target_qubits]: Target qubits
operands[num_control_qubits+num_target_qubits:]: Parameters

The results structure:

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

Constructor¶

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

Attributes¶

composite_gate_instance: Any
control_qubits: list[‘Value’] Get the control qubit operands.
custom_name: str
gate_type: CompositeGateType
has_implementation: bool
implementation: Block | None Get the implementation block, if any.
implementation_block: Block | None
name: str Human-readable name of this composite gate.
num_control_qubits: int
num_target_qubits: int
operation_kind: OperationKind Return the operation kind (always QUANTUM).
parameters: list[‘Value’] Get the parameter operands (angles, etc.).
resource_metadata: ResourceMetadata | None
signature: Signature Return the operation signature.
strategy_name: str | None
target_qubits: list[‘Value’] Get the target qubit operands.

`ControlledUOperation` [source]¶

class ControlledUOperation(Operation)

Base class for controlled-U operations.

Three concrete subclasses handle distinct operand layouts:

ConcreteControlledU: Fixed num_controls: int, individual qubit operands.
SymbolicControlledU: Symbolic num_controls: Value, vector-based control operands.
IndexSpecControlledU: Single vector with explicit index lists selecting which elements are controls/targets.

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

Constructor¶

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

Attributes¶

block: Block | None
control_operands: list[Value] Get the control qubit values.
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.
operation_kind: OperationKind
param_operands: list[Value] Get parameter operands (non-qubit, non-block).
power: int | Value
signature: Signature
target_operands: list[Value] Get the target qubit values (arguments to U).

Methods¶

`all_input_values`¶

def all_input_values(self) -> list[ValueBase]

`replace_values`¶

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

`ExpvalOp` [source]¶

class ExpvalOp(Operation)

Expectation value operation.

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

The operation bridges quantum and classical computation:

Input: quantum state (qubits) + Observable reference
Output: classical Float (expectation value)

Example IR:

Constructor¶

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

Attributes¶

hamiltonian: Value Alias for observable (deprecated, use observable instead).
observable: Value The Observable parameter operand.
operation_kind: OperationKind ExpvalOp is HYBRID - bridges quantum state to classical value.
output: Value The expectation value result.
qubits: Value The quantum register operand.
signature: Signature

`ForItemsOperation` [source]¶

class ForItemsOperation(HasNestedOps, Operation)

Represents iteration over dict/iterable items.

Example:

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

Constructor¶

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

Attributes¶

key_is_vector: bool
key_var_values: tuple[Value, ...] | None
key_vars: list[str]
operation_kind: OperationKind
operations: list[Operation]
signature: Signature
value_var: str
value_var_value: Value | None

Methods¶

`all_input_values`¶

def all_input_values(self) -> list[ValueBase]

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

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

`nested_op_lists`¶

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

`rebuild_nested`¶

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

`replace_values`¶

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

`ForOperation` [source]¶

class ForOperation(HasNestedOps, Operation)

Represents a for loop operation.

Example:

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

Constructor¶

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

Attributes¶

loop_var: str
loop_var_value: Value | None
operation_kind: OperationKind
operations: list[Operation]
signature: Signature

Methods¶

`all_input_values`¶

def all_input_values(self) -> list[ValueBase]

Include loop_var_value so cloning/substitution stays consistent.

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

`nested_op_lists`¶

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

`rebuild_nested`¶

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

`replace_values`¶

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

`GateOperation` [source]¶

class GateOperation(Operation)

Quantum gate operation.

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

Constructor¶

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

Attributes¶

gate_type: GateOperationType | None
operation_kind: OperationKind
qubit_operands: list[Value] Qubit operands (excluding the theta parameter if present).
signature: Signature
theta: Value | None Angle parameter for rotation gates, or None for fixed gates.

Methods¶

`fixed`¶

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

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

`rotation`¶

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

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

`GateOperationType` [source]¶

class GateOperationType(enum.Enum)

Attributes¶

CP
CX
CZ
H
P
RX
RY
RZ
RZZ
S
SDG
SWAP
T
TDG
TOFFOLI
X
Y
Z

`IfOperation` [source]¶

class IfOperation(HasNestedOps, Operation)

Represents an if-else conditional operation.

Example:

if condition:
    true_body
else:
    false_body

Constructor¶

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

Attributes¶

condition: Value
false_operations: list[Operation]
operation_kind: OperationKind
phi_ops: list[PhiOp]
signature: Signature
true_operations: list[Operation]

Methods¶

`nested_op_lists`¶

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

`rebuild_nested`¶

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

`MeasureOperation` [source]¶

class MeasureOperation(Operation)

Constructor¶

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

Attributes¶

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

`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

`QubitType` [source]¶

class QubitType(QuantumTypeMixin, ValueType)

Type representing a quantum bit (qubit).

`VFoldedBlock` [source]¶

class VFoldedBlock

Folded control-flow block (For/While/ForItems/If).

Rendered as a single box with header label and body summary text.

affected_qubits_precise is True when the analyzer determined the affected-qubit set from a precise iteration walk with all operands resolved; False when the conservative fallback was used and the set may over-approximate. Renderers use this to decide whether to mark participating wires with dots.

Constructor¶

def __init__(
    self,
    node_key: tuple,
    header_label: str,
    body_lines: list[str],
    affected_qubits: list[int],
    folded_width: float,
    kind: VFoldedKind,
    affected_qubits_precise: bool = True,
) -> None

Attributes¶

affected_qubits: list[int]
affected_qubits_precise: bool
body_lines: list[str]
folded_width: float
header_label: str
kind: VFoldedKind
node_key: tuple

`VFoldedKind` [source]¶

class VFoldedKind(enum.Enum)

Classification of folded control-flow blocks.

Attributes¶

FOR
FOR_ITEMS
IF
WHILE

`VGate` [source]¶

class VGate

Pre-resolved gate, measurement, block-box, or expval node.

Carries all information needed for layout and rendering:

label: TeX-formatted display text (e.g. “ $R_x(0.5)$ ”)
qubit_indices: resolved wire indices for all operands
estimated_width: pre-computed width for layout
kind: determines rendering strategy
gate_type: for CX/SWAP/TOFFOLI special drawing

Constructor¶

def __init__(
    self,
    node_key: tuple,
    label: str,
    qubit_indices: list[int],
    estimated_width: float,
    kind: VGateKind,
    gate_type: GateOperationType | None = None,
    has_param: bool = False,
    box_width: float | None = None,
    control_count: int = 0,
) -> None

Attributes¶

box_width: float | None
control_count: int
estimated_width: float
gate_type: GateOperationType | None
has_param: bool
kind: VGateKind
label: str
node_key: tuple
qubit_indices: list[int]

`VGateKind` [source]¶

class VGateKind(enum.Enum)

Classification of VGate nodes for rendering dispatch.

Attributes¶

BLOCK_BOX
COMPOSITE_BOX
CONTROLLED_U_BOX
EXPVAL
GATE
MEASURE
MEASURE_VECTOR

`VInlineBlock` [source]¶

class VInlineBlock

Inlined CallBlock/ControlledU/CompositeGate with visible border.

Carries pre-resolved children, affected qubits, and pre-computed widths so that Layout and Renderer need no Analyzer access.

Constructor¶

def __init__(
    self,
    node_key: tuple,
    label: str,
    children: list[VisualNode],
    affected_qubits: list[int],
    control_qubit_indices: list[int],
    power: int,
    depth: int,
    border_padding: float,
    max_gate_width: float,
    label_width: float,
    content_width: float,
    final_width: float,
) -> None

Attributes¶

affected_qubits: list[int]
border_padding: float
children: list[VisualNode]
content_width: float
control_qubit_indices: list[int]
depth: int
final_width: float
label: str
label_width: float
max_gate_width: float
node_key: tuple
power: int

`VSkip` [source]¶

class VSkip

Zero-space node for QInit, Cast, or zero-iteration loops.

Constructor¶

def __init__(self, node_key: tuple = ()) -> None

Attributes¶

node_key: tuple

`VUnfoldedKind` [source]¶

class VUnfoldedKind(enum.Enum)

Classification of unfolded control-flow sequences.

Attributes¶

FOR
FOR_ITEMS
IF

`VUnfoldedSequence` [source]¶

class VUnfoldedSequence

Unfolded control-flow sequence (For/ForItems/If).

For loops: iterations[i] = children of iteration i. For if: iterations[0] = true branch, iterations[1] = false branch (if exists).

Constructor¶

def __init__(
    self,
    node_key: tuple,
    iterations: list[list[VisualNode]],
    affected_qubits: list[int],
    kind: VUnfoldedKind,
    iteration_widths: list[float] = list(),
    condition_label: str | None = None,
    affected_qubits_precise: bool = True,
) -> None

Attributes¶

affected_qubits: list[int]
affected_qubits_precise: bool
condition_label: str | None
iteration_widths: list[float]
iterations: list[list[VisualNode]]
kind: VUnfoldedKind
node_key: tuple

`Value` [source]¶

class Value(_MetadataValueMixin, Generic[T])

A typed SSA value in the IR.

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

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

Constructor¶

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

Attributes¶

element_indices: tuple[Value, ...]
logical_id: str
metadata: ValueMetadata
name: str
parent_array: ArrayValue | None
type: T
uuid: str
version: int

Methods¶

`is_array_element`¶

def is_array_element(self) -> bool

`next_version`¶

def next_version(self) -> Value[T]

Create a new Value with incremented version and fresh UUID.

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

`VisualCircuit` [source]¶

class VisualCircuit

Root container for the Visual IR tree.

Carries the node tree plus qubit mapping information needed by Layout and Renderer.

Constructor¶

def __init__(
    self,
    children: list[VisualNode],
    qubit_map: dict[str, int],
    qubit_names: dict[int, str],
    num_qubits: int,
    output_names: list[str] = list(),
) -> None

Attributes¶

children: list[VisualNode]
num_qubits: int
output_names: list[str]
qubit_map: dict[str, int]
qubit_names: dict[int, str]

`WhileOperation` [source]¶

class WhileOperation(HasNestedOps, Operation)

Represents a while loop operation.

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

Example::

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

Constructor¶

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

Attributes¶

max_iterations: int | None
operation_kind: OperationKind
operations: list[Operation]
signature: Signature

Methods¶

`nested_op_lists`¶

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

`rebuild_nested`¶

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

qamomile.circuit.visualization.drawer¶

Matplotlib-based circuit visualization.

This module provides the MatplotlibDrawer facade that orchestrates circuit analysis, layout computation, and rendering.

Overview¶

Class	Description
`Block`	Unified block representation for all pipeline stages.
`CircuitAnalyzer`	Analyzes IR blocks for circuit visualization.
`CircuitLayoutEngine`	Computes layout coordinates for circuit visualization.
`CircuitStyle`	Style configuration for circuit visualization.
`MatplotlibDrawer`	Matplotlib-based circuit drawer with Qiskit-style layout.
`MatplotlibRenderer`	Renders circuit diagrams using matplotlib.

Classes¶

`Block` [source]¶

class Block

Unified block representation for all pipeline stages.

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

Constructor¶

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

Attributes¶

input_values: list[Value]
kind: BlockKind
label_args: list[str]
name: str
operations: list[‘Operation’]
output_names: list[str]
output_values: list[Value]
parameters: dict[str, Value]

Methods¶

`call`¶

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

Create a CallBlockOperation against this block.

`is_affine`¶

def is_affine(self) -> bool

Check if block contains no CallBlockOperations.

`unbound_parameters`¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

`CircuitAnalyzer` [source]¶

class CircuitAnalyzer

Analyzes IR blocks for circuit visualization.

Handles qubit mapping, value resolution, label generation, and width estimation. Has no matplotlib dependency.

Constructor¶

def __init__(
    self,
    graph: 'Block',
    style: CircuitStyle,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
)

Attributes¶

expand_composite
fold_loops
graph
inline
inline_depth
style

Methods¶

`build_qubit_map`¶

def build_qubit_map(self, graph: 'Block') -> tuple[dict[str, int], dict[int, str], int]

Build mapping from qubit logical_id to wire indices.

In SSA form, each operation creates new Values via next_version(), which preserves logical_id. This means all versions of a qubit share the same logical_id, so we only need logical_id-based tracking.

Parameters:

Name	Type	Description
`graph`	`'Block'`	Computation block.

Returns:

tuple[dict[str, int], dict[int, str], int] — Tuple of (qubit_map, qubit_names, num_qubits).

`build_visual_ir`¶

def build_visual_ir(
    self,
    graph: 'Block',
    qubit_map: dict[str, int],
    qubit_names: dict[int, str],
    num_qubits: int,
) -> VisualCircuit

Build a Visual IR tree from the IR block.

Parameters:

Name	Type	Description
`graph`	`'Block'`	IR computation block.
`qubit_map`	`dict[str, int]`	Mapping from logical_id to wire index.
`qubit_names`	`dict[int, str]`	Mapping from wire index to display name.
`num_qubits`	`int`	Total number of qubit wires.

Returns:

VisualCircuit — VisualCircuit containing the VisualNode tree.

`CircuitLayoutEngine` [source]¶

class CircuitLayoutEngine

Computes layout coordinates for circuit visualization.

Takes a VisualCircuit (pre-resolved Visual IR tree) and assigns x/y coordinates to each node. No Measure Phase is needed since widths are already computed in the Visual IR nodes.

Has no matplotlib dependency.

Constructor¶

def __init__(self, style: CircuitStyle)

Attributes¶

style

Methods¶

`compute_layout`¶

def compute_layout(self, vc: VisualCircuit) -> LayoutResult

Compute layout from a VisualCircuit.

Uses the Visual IR tree which carries all pre-resolved information (labels, qubit indices, widths). No Measure Phase is needed since widths are already computed in the Visual IR nodes.

Parameters:

Name	Type	Description
`vc`	`VisualCircuit`	VisualCircuit containing pre-resolved Visual IR nodes.

Returns:

LayoutResult — LayoutResult with all computed positions and sizing.

`CircuitStyle` [source]¶

class CircuitStyle

Style configuration for circuit visualization.

Constructor¶

def __init__(
    self,
    gate_width: float = 0.65,
    gate_height: float = 0.65,
    gate_corner_radius: float = 0.2,
    background_color: str = '#FFFFFF',
    wire_color: str = '#000000',
    gate_face_color: str = '#E8B878',
    gate_symbol_color: str = '#E8B878',
    gate_symbol_edge_color: str = '#000000',
    gate_text_color: str = '#000000',
    connection_line_color: str = '#000000',
    block_face_color: str = '#5B7F61',
    block_text_color: str = '#FFFFFF',
    block_border_color: str = '#4A6B50',
    block_box_edge_color: str = '#4A6B50',
    measure_face_color: str = '#D5CCC4',
    measure_symbol_color: str = '#6B5F55',
    for_loop_face_color: str = '#F0E4D0',
    for_loop_text_color: str = '#000000',
    for_loop_edge_color: str = '#C4A882',
    while_loop_face_color: str = '#E0D4F0',
    while_loop_text_color: str = '#000000',
    while_loop_edge_color: str = '#A88BC8',
    for_items_face_color: str = '#D0E8D0',
    for_items_text_color: str = '#000000',
    for_items_edge_color: str = '#90B890',
    if_face_color: str = '#F0D8D0',
    if_text_color: str = '#000000',
    if_edge_color: str = '#C8A898',
    expval_face_color: str = '#D4E8F0',
    expval_text_color: str = '#000000',
    expval_edge_color: str = '#8AB4C8',
    font_size: int = 13,
    subfont_size: int = 10,
    param_font_size: int = 9,
    margin: tuple[float, float, float, float] = (0.5, 0.1, 0.1, 0.3),
    gate_gap: float = 0.3,
    char_width_base: float = 0.12,
    char_width_bold: float = 0.14,
    char_width_gate: float = 0.14,
    char_width_block: float = 0.17,
    char_width_monospace: float = 0.17,
    text_padding: float = 0.25,
    border_padding_base: float = 0.3,
    border_padding_depth_factor: float = 0.1,
    min_left_margin: float = 0.3,
    label_height: float = 0.35,
    box_padding_x: float = 0.3,
    box_padding_y: float = 0.2,
    label_vertical_offset: float = 0.05,
    label_horizontal_padding: float = 0.1,
    initial_wire_position: float = 0.3,
    wire_extension: float = 0.3,
    operation_width_padding: float = 0.4,
    operation_content_padding: float = 0.6,
    line_height: float = 0.4,
    fallback_char_width: float = 0.15,
    fallback_text_height: float = 0.15,
    font_scaling_adjustment: float = 0.85,
    nested_margin: float = 0.15,
    border_extra_margin_right: float = 0.8,
    border_extra_margin_left: float = 0.3,
    folded_loop_width: float = 1.5,
    folded_call_block_width: float = 1.5,
    gate_text_padding: float = 0.1,
    nested_padding_decay: float = 0.85,
    min_block_padding: float = 0.1,
    power_wrapper_margin: float = 0.2,
    folded_box_text_v_padding: float = 0.15,
    max_folded_body_chars: int = 40,
    qubit_base_spacing: float = 1.0,
    qubit_clearance: float = 0.15,
    label_step_gap: float = 0.1,
    overlap_step_gap: float = 0.15,
    label_padding: float = 0.05,
    qubit_y_label_height: float = 0.25,
    figure_scale_factor: float = 0.8,
    figure_min_width: float = 4.0,
    figure_min_height: float = 2.0,
    x_left_min_bound: float = -1.0,
) -> None

Attributes¶

background_color: str
block_border_color: str
block_box_edge_color: str
block_face_color: str
block_text_color: str
border_extra_margin_left: float
border_extra_margin_right: float
border_padding_base: float
border_padding_depth_factor: float
box_padding_x: float
box_padding_y: float
char_width_base: float
char_width_block: float
char_width_bold: float
char_width_gate: float
char_width_monospace: float
connection_line_color: str
expval_edge_color: str
expval_face_color: str
expval_text_color: str
fallback_char_width: float
fallback_text_height: float
figure_min_height: float
figure_min_width: float
figure_scale_factor: float
folded_box_text_v_padding: float
folded_call_block_width: float
folded_loop_width: float
font_scaling_adjustment: float
font_size: int
for_items_edge_color: str
for_items_face_color: str
for_items_text_color: str
for_loop_edge_color: str
for_loop_face_color: str
for_loop_text_color: str
gate_corner_radius: float
gate_face_color: str
gate_gap: float
gate_height: float
gate_symbol_color: str
gate_symbol_edge_color: str
gate_text_color: str
gate_text_padding: float
gate_width: float
if_edge_color: str
if_face_color: str
if_text_color: str
initial_wire_position: float
label_height: float
label_horizontal_padding: float
label_padding: float
label_step_gap: float
label_vertical_offset: float
line_height: float
margin: tuple[float, float, float, float]
max_folded_body_chars: int
measure_face_color: str
measure_symbol_color: str
min_block_padding: float
min_left_margin: float
nested_margin: float
nested_padding_decay: float
operation_content_padding: float
operation_width_padding: float
overlap_step_gap: float
param_font_size: int
power_wrapper_margin: float
qubit_base_spacing: float
qubit_clearance: float
qubit_y_label_height: float
subfont_size: int
text_padding: float
while_loop_edge_color: str
while_loop_face_color: str
while_loop_text_color: str
wire_color: str
wire_extension: float
x_left_min_bound: float

`MatplotlibDrawer` [source]¶

class MatplotlibDrawer

Matplotlib-based circuit drawer with Qiskit-style layout.

This drawer produces static matplotlib figures showing quantum circuits. It supports two modes:

Block mode (inline=False): Shows CallBlockOperation as boxes
Inline mode (inline=True): Expands CallBlockOperation contents

Constructor¶

def __init__(self, graph: Block, style: CircuitStyle | None = None)

Initialize the drawer.

Parameters:

Name	Type	Description
`graph`	`Block`	Computation graph to visualize.
`style`	`CircuitStyle \| None`	Visual style configuration. Uses DEFAULT_STYLE if None.

Attributes¶

graph
style

Methods¶

`draw`¶

def draw(
    self,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
) -> Figure

Generate a matplotlib Figure of the circuit.

Parameters:

Name	Type	Description
`inline`	`bool`	If True, expand CallBlockOperation. If False, show 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.

Returns:

Figure — Figure object.

`draw_kernel`¶

@classmethod
def draw_kernel(
    cls,
    kernel: Any,
    *,
    inline: bool = False,
    fold_loops: bool = True,
    expand_composite: bool = False,
    inline_depth: int | None = None,
    style: CircuitStyle | None = None,
    **kwargs: Any = {},
) -> Figure

Draw a QKernel, handling Vector[Qubit] params with integer sizes.

For kernels with Vector[Qubit] parameters, pass an integer to specify the array size (e.g., inputs=3 for a 3-qubit vector).

Parameters:

Name	Type	Description
`kernel`	`Any`	A QKernel instance to visualize.
`inline`	`bool`	If True, expand CallBlockOperation contents.
`fold_loops`	`bool`	If True (default), display ForOperation as blocks.
`expand_composite`	`bool`	If True, expand CompositeGateOperation.
`inline_depth`	`int \| None`	Maximum nesting depth for inline expansion.
`style`	`CircuitStyle \| None`	Visual style configuration.
`**kwargs`	`Any`	Concrete values for kernel arguments. For Vector[Qubit] parameters, pass an integer size.

Returns:

Figure — Figure object.

`MatplotlibRenderer` [source]¶

class MatplotlibRenderer

Renders circuit diagrams using matplotlib.

Takes pre-computed layout coordinates and draws the circuit using matplotlib primitives.

Constructor¶

def __init__(self, style: CircuitStyle)

Attributes¶

layout: LayoutResult | None
qubit_end_positions: dict[int, float]
qubit_names: dict[int, str]
qubit_y: list[float]
style

Methods¶

`render`¶

def render(self, vc: VisualCircuit, layout: LayoutResult) -> Figure

Render the circuit from a VisualCircuit.

Uses the Visual IR tree which carries all pre-resolved information.

Parameters:

Name	Type	Description
`vc`	`VisualCircuit`	VisualCircuit containing pre-resolved Visual IR nodes.
`layout`	`LayoutResult`	Pre-computed layout result.

Returns:

Figure — matplotlib Figure.

qamomile.circuit.visualization.geometry¶

Pure geometry utilities for circuit visualization.

Standalone functions for computing border padding and block box bounds, shared by Layout and Renderer without requiring Analyzer.

Overview¶

Function	Description
`compute_block_box_bounds`	Compute outermost (box_left, box_right) for an inlined block border.
`compute_border_padding`	Compute border padding for a given nesting depth.
`compute_nested_block_box_bounds`	Compute (inner_bounds, outer_bounds) for an inlined block border.

Class	Description
`CircuitStyle`	Style configuration for circuit visualization.

Functions¶

`compute_block_box_bounds` [source]¶

def compute_block_box_bounds(
    style: CircuitStyle,
    name: str,
    start_x: float,
    end_x: float,
    depth: int,
    max_gate_width: float,
    power: int = 1,
) -> tuple[float, float]

Compute outermost (box_left, box_right) for an inlined block border.

Label expansion is right-only: box_left is always gate-based, box_right expands rightward if the label text needs more space.

Parameters:

Name	Type	Description
`style`	`CircuitStyle`	Visual style configuration.
`name`	`str`	Block label text.
`start_x`	`float`	X position of the first gate in the block.
`end_x`	`float`	X position of the last gate in the block.
`depth`	`int`	Nesting depth of the block.
`max_gate_width`	`float`	Width of the widest gate in the block.
`power`	`int`	Power annotation value (displayed as “pow=N” when > 1).

Returns:

tuple[float, float] — Tuple of (box_left, box_right).

`compute_border_padding` [source]¶

def compute_border_padding(style: CircuitStyle, depth: int) -> float

Compute border padding for a given nesting depth.

Parameters:

Name	Type	Description
`style`	`CircuitStyle`	Visual style configuration.
`depth`	`int`	Nesting depth of the block.

Returns:

float — Border padding value, clamped to min_block_padding.

`compute_nested_block_box_bounds` [source]¶

def compute_nested_block_box_bounds(
    style: CircuitStyle,
    name: str,
    start_x: float,
    end_x: float,
    depth: int,
    max_gate_width: float,
    power: int = 1,
) -> tuple[tuple[float, float], tuple[float, float]]

Compute (inner_bounds, outer_bounds) for an inlined block border.

When power <= 1, inner_bounds == outer_bounds (no wrapper). When power > 1, outer_bounds expand by power_wrapper_margin and account for the “pow=N” label width.

Parameters:

Name	Type	Description
`style`	`CircuitStyle`	Visual style configuration.
`name`	`str`	Block label text.
`start_x`	`float`	X position of the first gate in the block.
`end_x`	`float`	X position of the last gate in the block.
`depth`	`int`	Nesting depth of the block.
`max_gate_width`	`float`	Width of the widest gate in the block.
`power`	`int`	Power annotation value (displayed as “pow=N” when > 1).

Returns:

tuple[tuple[float, float], tuple[float, float]] — Tuple of ((inner_left, inner_right), (outer_left, outer_right)).

Classes¶

`CircuitStyle` [source]¶

class CircuitStyle

Style configuration for circuit visualization.

Constructor¶

def __init__(
    self,
    gate_width: float = 0.65,
    gate_height: float = 0.65,
    gate_corner_radius: float = 0.2,
    background_color: str = '#FFFFFF',
    wire_color: str = '#000000',
    gate_face_color: str = '#E8B878',
    gate_symbol_color: str = '#E8B878',
    gate_symbol_edge_color: str = '#000000',
    gate_text_color: str = '#000000',
    connection_line_color: str = '#000000',
    block_face_color: str = '#5B7F61',
    block_text_color: str = '#FFFFFF',
    block_border_color: str = '#4A6B50',
    block_box_edge_color: str = '#4A6B50',
    measure_face_color: str = '#D5CCC4',
    measure_symbol_color: str = '#6B5F55',
    for_loop_face_color: str = '#F0E4D0',
    for_loop_text_color: str = '#000000',
    for_loop_edge_color: str = '#C4A882',
    while_loop_face_color: str = '#E0D4F0',
    while_loop_text_color: str = '#000000',
    while_loop_edge_color: str = '#A88BC8',
    for_items_face_color: str = '#D0E8D0',
    for_items_text_color: str = '#000000',
    for_items_edge_color: str = '#90B890',
    if_face_color: str = '#F0D8D0',
    if_text_color: str = '#000000',
    if_edge_color: str = '#C8A898',
    expval_face_color: str = '#D4E8F0',
    expval_text_color: str = '#000000',
    expval_edge_color: str = '#8AB4C8',
    font_size: int = 13,
    subfont_size: int = 10,
    param_font_size: int = 9,
    margin: tuple[float, float, float, float] = (0.5, 0.1, 0.1, 0.3),
    gate_gap: float = 0.3,
    char_width_base: float = 0.12,
    char_width_bold: float = 0.14,
    char_width_gate: float = 0.14,
    char_width_block: float = 0.17,
    char_width_monospace: float = 0.17,
    text_padding: float = 0.25,
    border_padding_base: float = 0.3,
    border_padding_depth_factor: float = 0.1,
    min_left_margin: float = 0.3,
    label_height: float = 0.35,
    box_padding_x: float = 0.3,
    box_padding_y: float = 0.2,
    label_vertical_offset: float = 0.05,
    label_horizontal_padding: float = 0.1,
    initial_wire_position: float = 0.3,
    wire_extension: float = 0.3,
    operation_width_padding: float = 0.4,
    operation_content_padding: float = 0.6,
    line_height: float = 0.4,
    fallback_char_width: float = 0.15,
    fallback_text_height: float = 0.15,
    font_scaling_adjustment: float = 0.85,
    nested_margin: float = 0.15,
    border_extra_margin_right: float = 0.8,
    border_extra_margin_left: float = 0.3,
    folded_loop_width: float = 1.5,
    folded_call_block_width: float = 1.5,
    gate_text_padding: float = 0.1,
    nested_padding_decay: float = 0.85,
    min_block_padding: float = 0.1,
    power_wrapper_margin: float = 0.2,
    folded_box_text_v_padding: float = 0.15,
    max_folded_body_chars: int = 40,
    qubit_base_spacing: float = 1.0,
    qubit_clearance: float = 0.15,
    label_step_gap: float = 0.1,
    overlap_step_gap: float = 0.15,
    label_padding: float = 0.05,
    qubit_y_label_height: float = 0.25,
    figure_scale_factor: float = 0.8,
    figure_min_width: float = 4.0,
    figure_min_height: float = 2.0,
    x_left_min_bound: float = -1.0,
) -> None

Attributes¶

background_color: str
block_border_color: str
block_box_edge_color: str
block_face_color: str
block_text_color: str
border_extra_margin_left: float
border_extra_margin_right: float
border_padding_base: float
border_padding_depth_factor: float
box_padding_x: float
box_padding_y: float
char_width_base: float
char_width_block: float
char_width_bold: float
char_width_gate: float
char_width_monospace: float
connection_line_color: str
expval_edge_color: str
expval_face_color: str
expval_text_color: str
fallback_char_width: float
fallback_text_height: float
figure_min_height: float
figure_min_width: float
figure_scale_factor: float
folded_box_text_v_padding: float
folded_call_block_width: float
folded_loop_width: float
font_scaling_adjustment: float
font_size: int
for_items_edge_color: str
for_items_face_color: str
for_items_text_color: str
for_loop_edge_color: str
for_loop_face_color: str
for_loop_text_color: str
gate_corner_radius: float
gate_face_color: str
gate_gap: float
gate_height: float
gate_symbol_color: str
gate_symbol_edge_color: str
gate_text_color: str
gate_text_padding: float
gate_width: float
if_edge_color: str
if_face_color: str
if_text_color: str
initial_wire_position: float
label_height: float
label_horizontal_padding: float
label_padding: float
label_step_gap: float
label_vertical_offset: float
line_height: float
margin: tuple[float, float, float, float]
max_folded_body_chars: int
measure_face_color: str
measure_symbol_color: str
min_block_padding: float
min_left_margin: float
nested_margin: float
nested_padding_decay: float
operation_content_padding: float
operation_width_padding: float
overlap_step_gap: float
param_font_size: int
power_wrapper_margin: float
qubit_base_spacing: float
qubit_clearance: float
qubit_y_label_height: float
subfont_size: int
text_padding: float
while_loop_edge_color: str
while_loop_face_color: str
while_loop_text_color: str
wire_color: str
wire_extension: float
x_left_min_bound: float

qamomile.circuit.visualization.layout¶

Circuit layout engine: coordinate computation from Visual IR.

This module provides CircuitLayoutEngine, which assigns x/y coordinates to pre-resolved Visual IR nodes. It has no matplotlib dependency.

Overview¶

Function	Description
`compute_block_box_bounds`	Compute outermost (box_left, box_right) for an inlined block border.

Class	Description
`CircuitLayoutEngine`	Computes layout coordinates for circuit visualization.
`CircuitStyle`	Style configuration for circuit visualization.
`LayoutResult`	Result of the layout computation.
`LayoutState`	Mutable state shared across layout handler methods.
`VFoldedBlock`	Folded control-flow block (For/While/ForItems/If).
`VGate`	Pre-resolved gate, measurement, block-box, or expval node.
`VGateKind`	Classification of VGate nodes for rendering dispatch.
`VInlineBlock`	Inlined CallBlock/ControlledU/CompositeGate with visible border.
`VSkip`	Zero-space node for QInit, Cast, or zero-iteration loops.
`VUnfoldedKind`	Classification of unfolded control-flow sequences.
`VUnfoldedSequence`	Unfolded control-flow sequence (For/ForItems/If).
`VisualCircuit`	Root container for the Visual IR tree.

Functions¶

`compute_block_box_bounds` [source]¶

def compute_block_box_bounds(
    style: CircuitStyle,
    name: str,
    start_x: float,
    end_x: float,
    depth: int,
    max_gate_width: float,
    power: int = 1,
) -> tuple[float, float]

Compute outermost (box_left, box_right) for an inlined block border.

Label expansion is right-only: box_left is always gate-based, box_right expands rightward if the label text needs more space.

Parameters:

Name	Type	Description
`style`	`CircuitStyle`	Visual style configuration.
`name`	`str`	Block label text.
`start_x`	`float`	X position of the first gate in the block.
`end_x`	`float`	X position of the last gate in the block.
`depth`	`int`	Nesting depth of the block.
`max_gate_width`	`float`	Width of the widest gate in the block.
`power`	`int`	Power annotation value (displayed as “pow=N” when > 1).

Returns:

tuple[float, float] — Tuple of (box_left, box_right).

Classes¶

`CircuitLayoutEngine` [source]¶

class CircuitLayoutEngine

Computes layout coordinates for circuit visualization.

Takes a VisualCircuit (pre-resolved Visual IR tree) and assigns x/y coordinates to each node. No Measure Phase is needed since widths are already computed in the Visual IR nodes.

Has no matplotlib dependency.

Constructor¶

def __init__(self, style: CircuitStyle)

Attributes¶

style

Methods¶

`compute_layout`¶

def compute_layout(self, vc: VisualCircuit) -> LayoutResult

Compute layout from a VisualCircuit.

Uses the Visual IR tree which carries all pre-resolved information (labels, qubit indices, widths). No Measure Phase is needed since widths are already computed in the Visual IR nodes.

Parameters:

Name	Type	Description
`vc`	`VisualCircuit`	VisualCircuit containing pre-resolved Visual IR nodes.

Returns:

LayoutResult — LayoutResult with all computed positions and sizing.

`CircuitStyle` [source]¶

class CircuitStyle

Style configuration for circuit visualization.

Constructor¶

def __init__(
    self,
    gate_width: float = 0.65,
    gate_height: float = 0.65,
    gate_corner_radius: float = 0.2,
    background_color: str = '#FFFFFF',
    wire_color: str = '#000000',
    gate_face_color: str = '#E8B878',
    gate_symbol_color: str = '#E8B878',
    gate_symbol_edge_color: str = '#000000',
    gate_text_color: str = '#000000',
    connection_line_color: str = '#000000',
    block_face_color: str = '#5B7F61',
    block_text_color: str = '#FFFFFF',
    block_border_color: str = '#4A6B50',
    block_box_edge_color: str = '#4A6B50',
    measure_face_color: str = '#D5CCC4',
    measure_symbol_color: str = '#6B5F55',
    for_loop_face_color: str = '#F0E4D0',
    for_loop_text_color: str = '#000000',
    for_loop_edge_color: str = '#C4A882',
    while_loop_face_color: str = '#E0D4F0',
    while_loop_text_color: str = '#000000',
    while_loop_edge_color: str = '#A88BC8',
    for_items_face_color: str = '#D0E8D0',
    for_items_text_color: str = '#000000',
    for_items_edge_color: str = '#90B890',
    if_face_color: str = '#F0D8D0',
    if_text_color: str = '#000000',
    if_edge_color: str = '#C8A898',
    expval_face_color: str = '#D4E8F0',
    expval_text_color: str = '#000000',
    expval_edge_color: str = '#8AB4C8',
    font_size: int = 13,
    subfont_size: int = 10,
    param_font_size: int = 9,
    margin: tuple[float, float, float, float] = (0.5, 0.1, 0.1, 0.3),
    gate_gap: float = 0.3,
    char_width_base: float = 0.12,
    char_width_bold: float = 0.14,
    char_width_gate: float = 0.14,
    char_width_block: float = 0.17,
    char_width_monospace: float = 0.17,
    text_padding: float = 0.25,
    border_padding_base: float = 0.3,
    border_padding_depth_factor: float = 0.1,
    min_left_margin: float = 0.3,
    label_height: float = 0.35,
    box_padding_x: float = 0.3,
    box_padding_y: float = 0.2,
    label_vertical_offset: float = 0.05,
    label_horizontal_padding: float = 0.1,
    initial_wire_position: float = 0.3,
    wire_extension: float = 0.3,
    operation_width_padding: float = 0.4,
    operation_content_padding: float = 0.6,
    line_height: float = 0.4,
    fallback_char_width: float = 0.15,
    fallback_text_height: float = 0.15,
    font_scaling_adjustment: float = 0.85,
    nested_margin: float = 0.15,
    border_extra_margin_right: float = 0.8,
    border_extra_margin_left: float = 0.3,
    folded_loop_width: float = 1.5,
    folded_call_block_width: float = 1.5,
    gate_text_padding: float = 0.1,
    nested_padding_decay: float = 0.85,
    min_block_padding: float = 0.1,
    power_wrapper_margin: float = 0.2,
    folded_box_text_v_padding: float = 0.15,
    max_folded_body_chars: int = 40,
    qubit_base_spacing: float = 1.0,
    qubit_clearance: float = 0.15,
    label_step_gap: float = 0.1,
    overlap_step_gap: float = 0.15,
    label_padding: float = 0.05,
    qubit_y_label_height: float = 0.25,
    figure_scale_factor: float = 0.8,
    figure_min_width: float = 4.0,
    figure_min_height: float = 2.0,
    x_left_min_bound: float = -1.0,
) -> None

Attributes¶

background_color: str
block_border_color: str
block_box_edge_color: str
block_face_color: str
block_text_color: str
border_extra_margin_left: float
border_extra_margin_right: float
border_padding_base: float
border_padding_depth_factor: float
box_padding_x: float
box_padding_y: float
char_width_base: float
char_width_block: float
char_width_bold: float
char_width_gate: float
char_width_monospace: float
connection_line_color: str
expval_edge_color: str
expval_face_color: str
expval_text_color: str
fallback_char_width: float
fallback_text_height: float
figure_min_height: float
figure_min_width: float
figure_scale_factor: float
folded_box_text_v_padding: float
folded_call_block_width: float
folded_loop_width: float
font_scaling_adjustment: float
font_size: int
for_items_edge_color: str
for_items_face_color: str
for_items_text_color: str
for_loop_edge_color: str
for_loop_face_color: str
for_loop_text_color: str
gate_corner_radius: float
gate_face_color: str
gate_gap: float
gate_height: float
gate_symbol_color: str
gate_symbol_edge_color: str
gate_text_color: str
gate_text_padding: float
gate_width: float
if_edge_color: str
if_face_color: str
if_text_color: str
initial_wire_position: float
label_height: float
label_horizontal_padding: float
label_padding: float
label_step_gap: float
label_vertical_offset: float
line_height: float
margin: tuple[float, float, float, float]
max_folded_body_chars: int
measure_face_color: str
measure_symbol_color: str
min_block_padding: float
min_left_margin: float
nested_margin: float
nested_padding_decay: float
operation_content_padding: float
operation_width_padding: float
overlap_step_gap: float
param_font_size: int
power_wrapper_margin: float
qubit_base_spacing: float
qubit_clearance: float
qubit_y_label_height: float
subfont_size: int
text_padding: float
while_loop_edge_color: str
while_loop_face_color: str
while_loop_text_color: str
wire_color: str
wire_extension: float
x_left_min_bound: float

`LayoutResult` [source]¶

class LayoutResult

Result of the layout computation.

Constructor¶

def __init__(
    self,
    width: float,
    positions: dict[tuple, float],
    block_ranges: list[dict],
    max_depth: int,
    block_widths: dict[tuple, float],
    actual_width: float,
    first_gate_x: float,
    first_gate_half_width: float,
    qubit_y: list[float] = list(),
    qubit_end_positions: dict[int, float] = dict(),
    inlined_op_keys: set[tuple] = set(),
    gate_widths: dict[tuple, float] = dict(),
    folded_block_extents: dict[tuple, dict] = dict(),
    max_above: dict[int, float] = dict(),
    max_below: dict[int, float] = dict(),
) -> None

Attributes¶

actual_width: float
block_ranges: list[dict]
block_widths: dict[tuple, float]
first_gate_half_width: float
first_gate_x: float
folded_block_extents: dict[tuple, dict]
gate_widths: dict[tuple, float]
inlined_op_keys: set[tuple]
max_above: dict[int, float]
max_below: dict[int, float]
max_depth: int
positions: dict[tuple, float]
qubit_end_positions: dict[int, float]
qubit_y: list[float]
width: float

`LayoutState` [source]¶

class LayoutState

Mutable state shared across layout handler methods.

Constructor¶

def __init__(
    self,
    positions: dict[tuple, float] = dict(),
    block_ranges: list[dict] = list(),
    block_widths: dict[tuple, float] = dict(),
    column: float = 1.0,
    max_depth: int = 0,
    actual_width: float = 1.0,
    first_gate_x: float | None = None,
    first_gate_half_width: float = 0.0,
    qubit_columns: dict[int, float] = _default_qubit_columns(),
    qubit_right_edges: dict[int, float] = dict(),
    qubit_end_positions: dict[int, float] = dict(),
    inlined_op_keys: set[tuple] = set(),
    gate_widths: dict[tuple, float] = dict(),
    folded_block_extents: dict[tuple, dict] = dict(),
) -> None

Attributes¶

actual_width: float
block_ranges: list[dict]
block_widths: dict[tuple, float]
column: float
first_gate_half_width: float
first_gate_x: float | None
folded_block_extents: dict[tuple, dict]
gate_widths: dict[tuple, float]
inlined_op_keys: set[tuple]
max_depth: int
positions: dict[tuple, float]
qubit_columns: dict[int, float]
qubit_end_positions: dict[int, float]
qubit_right_edges: dict[int, float]

`VFoldedBlock` [source]¶

class VFoldedBlock

Folded control-flow block (For/While/ForItems/If).

Rendered as a single box with header label and body summary text.

Constructor¶

def __init__(
    self,
    node_key: tuple,
    header_label: str,
    body_lines: list[str],
    affected_qubits: list[int],
    folded_width: float,
    kind: VFoldedKind,
    affected_qubits_precise: bool = True,
) -> None

Attributes¶

affected_qubits: list[int]
affected_qubits_precise: bool
body_lines: list[str]
folded_width: float
header_label: str
kind: VFoldedKind
node_key: tuple

`VGate` [source]¶

class VGate

Pre-resolved gate, measurement, block-box, or expval node.

Carries all information needed for layout and rendering:

label: TeX-formatted display text (e.g. “ $R_x(0.5)$ ”)
qubit_indices: resolved wire indices for all operands
estimated_width: pre-computed width for layout
kind: determines rendering strategy
gate_type: for CX/SWAP/TOFFOLI special drawing

Constructor¶

def __init__(
    self,
    node_key: tuple,
    label: str,
    qubit_indices: list[int],
    estimated_width: float,
    kind: VGateKind,
    gate_type: GateOperationType | None = None,
    has_param: bool = False,
    box_width: float | None = None,
    control_count: int = 0,
) -> None

Attributes¶

box_width: float | None
control_count: int
estimated_width: float
gate_type: GateOperationType | None
has_param: bool
kind: VGateKind
label: str
node_key: tuple
qubit_indices: list[int]

`VGateKind` [source]¶

class VGateKind(enum.Enum)

Classification of VGate nodes for rendering dispatch.

Attributes¶

BLOCK_BOX
COMPOSITE_BOX
CONTROLLED_U_BOX
EXPVAL
GATE
MEASURE
MEASURE_VECTOR

`VInlineBlock` [source]¶

class VInlineBlock

Inlined CallBlock/ControlledU/CompositeGate with visible border.

Carries pre-resolved children, affected qubits, and pre-computed widths so that Layout and Renderer need no Analyzer access.

Constructor¶

def __init__(
    self,
    node_key: tuple,
    label: str,
    children: list[VisualNode],
    affected_qubits: list[int],
    control_qubit_indices: list[int],
    power: int,
    depth: int,
    border_padding: float,
    max_gate_width: float,
    label_width: float,
    content_width: float,
    final_width: float,
) -> None

Attributes¶

affected_qubits: list[int]
border_padding: float
children: list[VisualNode]
content_width: float
control_qubit_indices: list[int]
depth: int
final_width: float
label: str
label_width: float
max_gate_width: float
node_key: tuple
power: int

`VSkip` [source]¶

class VSkip

Zero-space node for QInit, Cast, or zero-iteration loops.

Constructor¶

def __init__(self, node_key: tuple = ()) -> None

Attributes¶

node_key: tuple

`VUnfoldedKind` [source]¶

class VUnfoldedKind(enum.Enum)

Classification of unfolded control-flow sequences.

Attributes¶

FOR
FOR_ITEMS
IF

`VUnfoldedSequence` [source]¶

class VUnfoldedSequence

Unfolded control-flow sequence (For/ForItems/If).

For loops: iterations[i] = children of iteration i. For if: iterations[0] = true branch, iterations[1] = false branch (if exists).

Constructor¶

def __init__(
    self,
    node_key: tuple,
    iterations: list[list[VisualNode]],
    affected_qubits: list[int],
    kind: VUnfoldedKind,
    iteration_widths: list[float] = list(),
    condition_label: str | None = None,
    affected_qubits_precise: bool = True,
) -> None

Attributes¶

affected_qubits: list[int]
affected_qubits_precise: bool
condition_label: str | None
iteration_widths: list[float]
iterations: list[list[VisualNode]]
kind: VUnfoldedKind
node_key: tuple

`VisualCircuit` [source]¶

class VisualCircuit

Root container for the Visual IR tree.

Carries the node tree plus qubit mapping information needed by Layout and Renderer.

Constructor¶

def __init__(
    self,
    children: list[VisualNode],
    qubit_map: dict[str, int],
    qubit_names: dict[int, str],
    num_qubits: int,
    output_names: list[str] = list(),
) -> None

Attributes¶

children: list[VisualNode]
num_qubits: int
output_names: list[str]
qubit_map: dict[str, int]
qubit_names: dict[int, str]

qamomile.circuit.visualization.renderer¶

Matplotlib-based circuit rendering.

This module provides MatplotlibRenderer, which handles all matplotlib drawing operations for circuit visualization.

Overview¶

Function	Description
`compute_block_box_bounds`	Compute outermost (box_left, box_right) for an inlined block border.
`compute_border_padding`	Compute border padding for a given nesting depth.
`compute_nested_block_box_bounds`	Compute (inner_bounds, outer_bounds) for an inlined block border.

Class	Description
`CircuitStyle`	Style configuration for circuit visualization.
`LayoutResult`	Result of the layout computation.
`MatplotlibRenderer`	Renders circuit diagrams using matplotlib.
`VFoldedBlock`	Folded control-flow block (For/While/ForItems/If).
`VFoldedKind`	Classification of folded control-flow blocks.
`VGate`	Pre-resolved gate, measurement, block-box, or expval node.
`VGateKind`	Classification of VGate nodes for rendering dispatch.
`VInlineBlock`	Inlined CallBlock/ControlledU/CompositeGate with visible border.
`VSkip`	Zero-space node for QInit, Cast, or zero-iteration loops.
`VUnfoldedSequence`	Unfolded control-flow sequence (For/ForItems/If).
`VisualCircuit`	Root container for the Visual IR tree.

Functions¶

`compute_block_box_bounds` [source]¶

def compute_block_box_bounds(
    style: CircuitStyle,
    name: str,
    start_x: float,
    end_x: float,
    depth: int,
    max_gate_width: float,
    power: int = 1,
) -> tuple[float, float]

Compute outermost (box_left, box_right) for an inlined block border.

Label expansion is right-only: box_left is always gate-based, box_right expands rightward if the label text needs more space.

Parameters:

Name	Type	Description
`style`	`CircuitStyle`	Visual style configuration.
`name`	`str`	Block label text.
`start_x`	`float`	X position of the first gate in the block.
`end_x`	`float`	X position of the last gate in the block.
`depth`	`int`	Nesting depth of the block.
`max_gate_width`	`float`	Width of the widest gate in the block.
`power`	`int`	Power annotation value (displayed as “pow=N” when > 1).

Returns:

tuple[float, float] — Tuple of (box_left, box_right).

`compute_border_padding` [source]¶

def compute_border_padding(style: CircuitStyle, depth: int) -> float

Compute border padding for a given nesting depth.

Parameters:

Name	Type	Description
`style`	`CircuitStyle`	Visual style configuration.
`depth`	`int`	Nesting depth of the block.

Returns:

float — Border padding value, clamped to min_block_padding.

`compute_nested_block_box_bounds` [source]¶

def compute_nested_block_box_bounds(
    style: CircuitStyle,
    name: str,
    start_x: float,
    end_x: float,
    depth: int,
    max_gate_width: float,
    power: int = 1,
) -> tuple[tuple[float, float], tuple[float, float]]

Compute (inner_bounds, outer_bounds) for an inlined block border.

When power <= 1, inner_bounds == outer_bounds (no wrapper). When power > 1, outer_bounds expand by power_wrapper_margin and account for the “pow=N” label width.

Parameters:

Name	Type	Description
`style`	`CircuitStyle`	Visual style configuration.
`name`	`str`	Block label text.
`start_x`	`float`	X position of the first gate in the block.
`end_x`	`float`	X position of the last gate in the block.
`depth`	`int`	Nesting depth of the block.
`max_gate_width`	`float`	Width of the widest gate in the block.
`power`	`int`	Power annotation value (displayed as “pow=N” when > 1).

Returns:

tuple[tuple[float, float], tuple[float, float]] — Tuple of ((inner_left, inner_right), (outer_left, outer_right)).

Classes¶

`CircuitStyle` [source]¶

class CircuitStyle

Style configuration for circuit visualization.

Constructor¶

def __init__(
    self,
    gate_width: float = 0.65,
    gate_height: float = 0.65,
    gate_corner_radius: float = 0.2,
    background_color: str = '#FFFFFF',
    wire_color: str = '#000000',
    gate_face_color: str = '#E8B878',
    gate_symbol_color: str = '#E8B878',
    gate_symbol_edge_color: str = '#000000',
    gate_text_color: str = '#000000',
    connection_line_color: str = '#000000',
    block_face_color: str = '#5B7F61',
    block_text_color: str = '#FFFFFF',
    block_border_color: str = '#4A6B50',
    block_box_edge_color: str = '#4A6B50',
    measure_face_color: str = '#D5CCC4',
    measure_symbol_color: str = '#6B5F55',
    for_loop_face_color: str = '#F0E4D0',
    for_loop_text_color: str = '#000000',
    for_loop_edge_color: str = '#C4A882',
    while_loop_face_color: str = '#E0D4F0',
    while_loop_text_color: str = '#000000',
    while_loop_edge_color: str = '#A88BC8',
    for_items_face_color: str = '#D0E8D0',
    for_items_text_color: str = '#000000',
    for_items_edge_color: str = '#90B890',
    if_face_color: str = '#F0D8D0',
    if_text_color: str = '#000000',
    if_edge_color: str = '#C8A898',
    expval_face_color: str = '#D4E8F0',
    expval_text_color: str = '#000000',
    expval_edge_color: str = '#8AB4C8',
    font_size: int = 13,
    subfont_size: int = 10,
    param_font_size: int = 9,
    margin: tuple[float, float, float, float] = (0.5, 0.1, 0.1, 0.3),
    gate_gap: float = 0.3,
    char_width_base: float = 0.12,
    char_width_bold: float = 0.14,
    char_width_gate: float = 0.14,
    char_width_block: float = 0.17,
    char_width_monospace: float = 0.17,
    text_padding: float = 0.25,
    border_padding_base: float = 0.3,
    border_padding_depth_factor: float = 0.1,
    min_left_margin: float = 0.3,
    label_height: float = 0.35,
    box_padding_x: float = 0.3,
    box_padding_y: float = 0.2,
    label_vertical_offset: float = 0.05,
    label_horizontal_padding: float = 0.1,
    initial_wire_position: float = 0.3,
    wire_extension: float = 0.3,
    operation_width_padding: float = 0.4,
    operation_content_padding: float = 0.6,
    line_height: float = 0.4,
    fallback_char_width: float = 0.15,
    fallback_text_height: float = 0.15,
    font_scaling_adjustment: float = 0.85,
    nested_margin: float = 0.15,
    border_extra_margin_right: float = 0.8,
    border_extra_margin_left: float = 0.3,
    folded_loop_width: float = 1.5,
    folded_call_block_width: float = 1.5,
    gate_text_padding: float = 0.1,
    nested_padding_decay: float = 0.85,
    min_block_padding: float = 0.1,
    power_wrapper_margin: float = 0.2,
    folded_box_text_v_padding: float = 0.15,
    max_folded_body_chars: int = 40,
    qubit_base_spacing: float = 1.0,
    qubit_clearance: float = 0.15,
    label_step_gap: float = 0.1,
    overlap_step_gap: float = 0.15,
    label_padding: float = 0.05,
    qubit_y_label_height: float = 0.25,
    figure_scale_factor: float = 0.8,
    figure_min_width: float = 4.0,
    figure_min_height: float = 2.0,
    x_left_min_bound: float = -1.0,
) -> None

Attributes¶

background_color: str
block_border_color: str
block_box_edge_color: str
block_face_color: str
block_text_color: str
border_extra_margin_left: float
border_extra_margin_right: float
border_padding_base: float
border_padding_depth_factor: float
box_padding_x: float
box_padding_y: float
char_width_base: float
char_width_block: float
char_width_bold: float
char_width_gate: float
char_width_monospace: float
connection_line_color: str
expval_edge_color: str
expval_face_color: str
expval_text_color: str
fallback_char_width: float
fallback_text_height: float
figure_min_height: float
figure_min_width: float
figure_scale_factor: float
folded_box_text_v_padding: float
folded_call_block_width: float
folded_loop_width: float
font_scaling_adjustment: float
font_size: int
for_items_edge_color: str
for_items_face_color: str
for_items_text_color: str
for_loop_edge_color: str
for_loop_face_color: str
for_loop_text_color: str
gate_corner_radius: float
gate_face_color: str
gate_gap: float
gate_height: float
gate_symbol_color: str
gate_symbol_edge_color: str
gate_text_color: str
gate_text_padding: float
gate_width: float
if_edge_color: str
if_face_color: str
if_text_color: str
initial_wire_position: float
label_height: float
label_horizontal_padding: float
label_padding: float
label_step_gap: float
label_vertical_offset: float
line_height: float
margin: tuple[float, float, float, float]
max_folded_body_chars: int
measure_face_color: str
measure_symbol_color: str
min_block_padding: float
min_left_margin: float
nested_margin: float
nested_padding_decay: float
operation_content_padding: float
operation_width_padding: float
overlap_step_gap: float
param_font_size: int
power_wrapper_margin: float
qubit_base_spacing: float
qubit_clearance: float
qubit_y_label_height: float
subfont_size: int
text_padding: float
while_loop_edge_color: str
while_loop_face_color: str
while_loop_text_color: str
wire_color: str
wire_extension: float
x_left_min_bound: float

`LayoutResult` [source]¶

class LayoutResult

Result of the layout computation.

Constructor¶

def __init__(
    self,
    width: float,
    positions: dict[tuple, float],
    block_ranges: list[dict],
    max_depth: int,
    block_widths: dict[tuple, float],
    actual_width: float,
    first_gate_x: float,
    first_gate_half_width: float,
    qubit_y: list[float] = list(),
    qubit_end_positions: dict[int, float] = dict(),
    inlined_op_keys: set[tuple] = set(),
    gate_widths: dict[tuple, float] = dict(),
    folded_block_extents: dict[tuple, dict] = dict(),
    max_above: dict[int, float] = dict(),
    max_below: dict[int, float] = dict(),
) -> None

Attributes¶

actual_width: float
block_ranges: list[dict]
block_widths: dict[tuple, float]
first_gate_half_width: float
first_gate_x: float
folded_block_extents: dict[tuple, dict]
gate_widths: dict[tuple, float]
inlined_op_keys: set[tuple]
max_above: dict[int, float]
max_below: dict[int, float]
max_depth: int
positions: dict[tuple, float]
qubit_end_positions: dict[int, float]
qubit_y: list[float]
width: float

`MatplotlibRenderer` [source]¶

class MatplotlibRenderer

Renders circuit diagrams using matplotlib.

Takes pre-computed layout coordinates and draws the circuit using matplotlib primitives.

Constructor¶

def __init__(self, style: CircuitStyle)

Attributes¶

layout: LayoutResult | None
qubit_end_positions: dict[int, float]
qubit_names: dict[int, str]
qubit_y: list[float]
style

Methods¶

`render`¶

def render(self, vc: VisualCircuit, layout: LayoutResult) -> Figure

Render the circuit from a VisualCircuit.

Uses the Visual IR tree which carries all pre-resolved information.

Parameters:

Name	Type	Description
`vc`	`VisualCircuit`	VisualCircuit containing pre-resolved Visual IR nodes.
`layout`	`LayoutResult`	Pre-computed layout result.

Returns:

Figure — matplotlib Figure.

`VFoldedBlock` [source]¶

class VFoldedBlock

Folded control-flow block (For/While/ForItems/If).

Rendered as a single box with header label and body summary text.

Constructor¶

def __init__(
    self,
    node_key: tuple,
    header_label: str,
    body_lines: list[str],
    affected_qubits: list[int],
    folded_width: float,
    kind: VFoldedKind,
    affected_qubits_precise: bool = True,
) -> None

Attributes¶

affected_qubits: list[int]
affected_qubits_precise: bool
body_lines: list[str]
folded_width: float
header_label: str
kind: VFoldedKind
node_key: tuple

`VFoldedKind` [source]¶

class VFoldedKind(enum.Enum)

Classification of folded control-flow blocks.

Attributes¶

FOR
FOR_ITEMS
IF
WHILE

`VGate` [source]¶

class VGate

Pre-resolved gate, measurement, block-box, or expval node.

Carries all information needed for layout and rendering:

label: TeX-formatted display text (e.g. “ $R_x(0.5)$ ”)
qubit_indices: resolved wire indices for all operands
estimated_width: pre-computed width for layout
kind: determines rendering strategy
gate_type: for CX/SWAP/TOFFOLI special drawing

Constructor¶

def __init__(
    self,
    node_key: tuple,
    label: str,
    qubit_indices: list[int],
    estimated_width: float,
    kind: VGateKind,
    gate_type: GateOperationType | None = None,
    has_param: bool = False,
    box_width: float | None = None,
    control_count: int = 0,
) -> None

Attributes¶

box_width: float | None
control_count: int
estimated_width: float
gate_type: GateOperationType | None
has_param: bool
kind: VGateKind
label: str
node_key: tuple
qubit_indices: list[int]

`VGateKind` [source]¶

class VGateKind(enum.Enum)

Classification of VGate nodes for rendering dispatch.

Attributes¶

BLOCK_BOX
COMPOSITE_BOX
CONTROLLED_U_BOX
EXPVAL
GATE
MEASURE
MEASURE_VECTOR

`VInlineBlock` [source]¶

class VInlineBlock

Inlined CallBlock/ControlledU/CompositeGate with visible border.

Carries pre-resolved children, affected qubits, and pre-computed widths so that Layout and Renderer need no Analyzer access.

Constructor¶

def __init__(
    self,
    node_key: tuple,
    label: str,
    children: list[VisualNode],
    affected_qubits: list[int],
    control_qubit_indices: list[int],
    power: int,
    depth: int,
    border_padding: float,
    max_gate_width: float,
    label_width: float,
    content_width: float,
    final_width: float,
) -> None

Attributes¶

affected_qubits: list[int]
border_padding: float
children: list[VisualNode]
content_width: float
control_qubit_indices: list[int]
depth: int
final_width: float
label: str
label_width: float
max_gate_width: float
node_key: tuple
power: int

`VSkip` [source]¶

class VSkip

Zero-space node for QInit, Cast, or zero-iteration loops.

Constructor¶

def __init__(self, node_key: tuple = ()) -> None

Attributes¶

node_key: tuple

`VUnfoldedSequence` [source]¶

class VUnfoldedSequence

Unfolded control-flow sequence (For/ForItems/If).

For loops: iterations[i] = children of iteration i. For if: iterations[0] = true branch, iterations[1] = false branch (if exists).

Constructor¶

def __init__(
    self,
    node_key: tuple,
    iterations: list[list[VisualNode]],
    affected_qubits: list[int],
    kind: VUnfoldedKind,
    iteration_widths: list[float] = list(),
    condition_label: str | None = None,
    affected_qubits_precise: bool = True,
) -> None

Attributes¶

affected_qubits: list[int]
affected_qubits_precise: bool
condition_label: str | None
iteration_widths: list[float]
iterations: list[list[VisualNode]]
kind: VUnfoldedKind
node_key: tuple

`VisualCircuit` [source]¶

class VisualCircuit

Root container for the Visual IR tree.

Carries the node tree plus qubit mapping information needed by Layout and Renderer.

Constructor¶

def __init__(
    self,
    children: list[VisualNode],
    qubit_map: dict[str, int],
    qubit_names: dict[int, str],
    num_qubits: int,
    output_names: list[str] = list(),
) -> None

Attributes¶

children: list[VisualNode]
num_qubits: int
output_names: list[str]
qubit_map: dict[str, int]
qubit_names: dict[int, str]

qamomile.circuit.visualization.style¶

Circuit visualization style configuration.

This module provides style configuration for circuit drawings, inspired by Qiskit’s matplotlib drawer styling approach.

Overview¶

Class	Description
`CircuitStyle`	Style configuration for circuit visualization.

Classes¶

`CircuitStyle` [source]¶

class CircuitStyle

Style configuration for circuit visualization.

Constructor¶

def __init__(
    self,
    gate_width: float = 0.65,
    gate_height: float = 0.65,
    gate_corner_radius: float = 0.2,
    background_color: str = '#FFFFFF',
    wire_color: str = '#000000',
    gate_face_color: str = '#E8B878',
    gate_symbol_color: str = '#E8B878',
    gate_symbol_edge_color: str = '#000000',
    gate_text_color: str = '#000000',
    connection_line_color: str = '#000000',
    block_face_color: str = '#5B7F61',
    block_text_color: str = '#FFFFFF',
    block_border_color: str = '#4A6B50',
    block_box_edge_color: str = '#4A6B50',
    measure_face_color: str = '#D5CCC4',
    measure_symbol_color: str = '#6B5F55',
    for_loop_face_color: str = '#F0E4D0',
    for_loop_text_color: str = '#000000',
    for_loop_edge_color: str = '#C4A882',
    while_loop_face_color: str = '#E0D4F0',
    while_loop_text_color: str = '#000000',
    while_loop_edge_color: str = '#A88BC8',
    for_items_face_color: str = '#D0E8D0',
    for_items_text_color: str = '#000000',
    for_items_edge_color: str = '#90B890',
    if_face_color: str = '#F0D8D0',
    if_text_color: str = '#000000',
    if_edge_color: str = '#C8A898',
    expval_face_color: str = '#D4E8F0',
    expval_text_color: str = '#000000',
    expval_edge_color: str = '#8AB4C8',
    font_size: int = 13,
    subfont_size: int = 10,
    param_font_size: int = 9,
    margin: tuple[float, float, float, float] = (0.5, 0.1, 0.1, 0.3),
    gate_gap: float = 0.3,
    char_width_base: float = 0.12,
    char_width_bold: float = 0.14,
    char_width_gate: float = 0.14,
    char_width_block: float = 0.17,
    char_width_monospace: float = 0.17,
    text_padding: float = 0.25,
    border_padding_base: float = 0.3,
    border_padding_depth_factor: float = 0.1,
    min_left_margin: float = 0.3,
    label_height: float = 0.35,
    box_padding_x: float = 0.3,
    box_padding_y: float = 0.2,
    label_vertical_offset: float = 0.05,
    label_horizontal_padding: float = 0.1,
    initial_wire_position: float = 0.3,
    wire_extension: float = 0.3,
    operation_width_padding: float = 0.4,
    operation_content_padding: float = 0.6,
    line_height: float = 0.4,
    fallback_char_width: float = 0.15,
    fallback_text_height: float = 0.15,
    font_scaling_adjustment: float = 0.85,
    nested_margin: float = 0.15,
    border_extra_margin_right: float = 0.8,
    border_extra_margin_left: float = 0.3,
    folded_loop_width: float = 1.5,
    folded_call_block_width: float = 1.5,
    gate_text_padding: float = 0.1,
    nested_padding_decay: float = 0.85,
    min_block_padding: float = 0.1,
    power_wrapper_margin: float = 0.2,
    folded_box_text_v_padding: float = 0.15,
    max_folded_body_chars: int = 40,
    qubit_base_spacing: float = 1.0,
    qubit_clearance: float = 0.15,
    label_step_gap: float = 0.1,
    overlap_step_gap: float = 0.15,
    label_padding: float = 0.05,
    qubit_y_label_height: float = 0.25,
    figure_scale_factor: float = 0.8,
    figure_min_width: float = 4.0,
    figure_min_height: float = 2.0,
    x_left_min_bound: float = -1.0,
) -> None

Attributes¶

background_color: str
block_border_color: str
block_box_edge_color: str
block_face_color: str
block_text_color: str
border_extra_margin_left: float
border_extra_margin_right: float
border_padding_base: float
border_padding_depth_factor: float
box_padding_x: float
box_padding_y: float
char_width_base: float
char_width_block: float
char_width_bold: float
char_width_gate: float
char_width_monospace: float
connection_line_color: str
expval_edge_color: str
expval_face_color: str
expval_text_color: str
fallback_char_width: float
fallback_text_height: float
figure_min_height: float
figure_min_width: float
figure_scale_factor: float
folded_box_text_v_padding: float
folded_call_block_width: float
folded_loop_width: float
font_scaling_adjustment: float
font_size: int
for_items_edge_color: str
for_items_face_color: str
for_items_text_color: str
for_loop_edge_color: str
for_loop_face_color: str
for_loop_text_color: str
gate_corner_radius: float
gate_face_color: str
gate_gap: float
gate_height: float
gate_symbol_color: str
gate_symbol_edge_color: str
gate_text_color: str
gate_text_padding: float
gate_width: float
if_edge_color: str
if_face_color: str
if_text_color: str
initial_wire_position: float
label_height: float
label_horizontal_padding: float
label_padding: float
label_step_gap: float
label_vertical_offset: float
line_height: float
margin: tuple[float, float, float, float]
max_folded_body_chars: int
measure_face_color: str
measure_symbol_color: str
min_block_padding: float
min_left_margin: float
nested_margin: float
nested_padding_decay: float
operation_content_padding: float
operation_width_padding: float
overlap_step_gap: float
param_font_size: int
power_wrapper_margin: float
qubit_base_spacing: float
qubit_clearance: float
qubit_y_label_height: float
subfont_size: int
text_padding: float
while_loop_edge_color: str
while_loop_face_color: str
while_loop_text_color: str
wire_color: str
wire_extension: float
x_left_min_bound: float

qamomile.circuit.visualization.types¶

Shared data structures and constants for circuit visualization.

Overview¶

Class	Description
`LayoutResult`	Result of the layout computation.
`LayoutState`	Mutable state shared across layout handler methods.

Classes¶

`LayoutResult` [source]¶

class LayoutResult

Result of the layout computation.

Constructor¶

def __init__(
    self,
    width: float,
    positions: dict[tuple, float],
    block_ranges: list[dict],
    max_depth: int,
    block_widths: dict[tuple, float],
    actual_width: float,
    first_gate_x: float,
    first_gate_half_width: float,
    qubit_y: list[float] = list(),
    qubit_end_positions: dict[int, float] = dict(),
    inlined_op_keys: set[tuple] = set(),
    gate_widths: dict[tuple, float] = dict(),
    folded_block_extents: dict[tuple, dict] = dict(),
    max_above: dict[int, float] = dict(),
    max_below: dict[int, float] = dict(),
) -> None

Attributes¶

actual_width: float
block_ranges: list[dict]
block_widths: dict[tuple, float]
first_gate_half_width: float
first_gate_x: float
folded_block_extents: dict[tuple, dict]
gate_widths: dict[tuple, float]
inlined_op_keys: set[tuple]
max_above: dict[int, float]
max_below: dict[int, float]
max_depth: int
positions: dict[tuple, float]
qubit_end_positions: dict[int, float]
qubit_y: list[float]
width: float

`LayoutState` [source]¶

class LayoutState

Mutable state shared across layout handler methods.

Constructor¶

def __init__(
    self,
    positions: dict[tuple, float] = dict(),
    block_ranges: list[dict] = list(),
    block_widths: dict[tuple, float] = dict(),
    column: float = 1.0,
    max_depth: int = 0,
    actual_width: float = 1.0,
    first_gate_x: float | None = None,
    first_gate_half_width: float = 0.0,
    qubit_columns: dict[int, float] = _default_qubit_columns(),
    qubit_right_edges: dict[int, float] = dict(),
    qubit_end_positions: dict[int, float] = dict(),
    inlined_op_keys: set[tuple] = set(),
    gate_widths: dict[tuple, float] = dict(),
    folded_block_extents: dict[tuple, dict] = dict(),
) -> None

Attributes¶

actual_width: float
block_ranges: list[dict]
block_widths: dict[tuple, float]
column: float
first_gate_half_width: float
first_gate_x: float | None
folded_block_extents: dict[tuple, dict]
gate_widths: dict[tuple, float]
inlined_op_keys: set[tuple]
max_depth: int
positions: dict[tuple, float]
qubit_columns: dict[int, float]
qubit_end_positions: dict[int, float]
qubit_right_edges: dict[int, float]

qamomile.circuit.visualization.visual_ir¶

Visual IR: pre-resolved intermediate representation for circuit visualization.

This module defines the Visual IR node types that carry all resolved information (labels, qubit indices, widths) needed by Layout and Renderer. The Visual IR serves as the decoupling boundary between Analyzer (which understands IR semantics) and Layout/Renderer (which only need pre-resolved visual information).

Overview¶

Class	Description
`GateOperationType`
`VFoldedBlock`	Folded control-flow block (For/While/ForItems/If).
`VFoldedKind`	Classification of folded control-flow blocks.
`VGate`	Pre-resolved gate, measurement, block-box, or expval node.
`VGateKind`	Classification of VGate nodes for rendering dispatch.
`VInlineBlock`	Inlined CallBlock/ControlledU/CompositeGate with visible border.
`VSkip`	Zero-space node for QInit, Cast, or zero-iteration loops.
`VUnfoldedKind`	Classification of unfolded control-flow sequences.
`VUnfoldedSequence`	Unfolded control-flow sequence (For/ForItems/If).
`VisualCircuit`	Root container for the Visual IR tree.

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

`VFoldedBlock` [source]¶

class VFoldedBlock

Folded control-flow block (For/While/ForItems/If).

Rendered as a single box with header label and body summary text.

Constructor¶

def __init__(
    self,
    node_key: tuple,
    header_label: str,
    body_lines: list[str],
    affected_qubits: list[int],
    folded_width: float,
    kind: VFoldedKind,
    affected_qubits_precise: bool = True,
) -> None

Attributes¶

affected_qubits: list[int]
affected_qubits_precise: bool
body_lines: list[str]
folded_width: float
header_label: str
kind: VFoldedKind
node_key: tuple

`VFoldedKind` [source]¶

class VFoldedKind(enum.Enum)

Classification of folded control-flow blocks.

Attributes¶

FOR
FOR_ITEMS
IF
WHILE

`VGate` [source]¶

class VGate

Pre-resolved gate, measurement, block-box, or expval node.

Carries all information needed for layout and rendering:

label: TeX-formatted display text (e.g. “ $R_x(0.5)$ ”)
qubit_indices: resolved wire indices for all operands
estimated_width: pre-computed width for layout
kind: determines rendering strategy
gate_type: for CX/SWAP/TOFFOLI special drawing

Constructor¶

def __init__(
    self,
    node_key: tuple,
    label: str,
    qubit_indices: list[int],
    estimated_width: float,
    kind: VGateKind,
    gate_type: GateOperationType | None = None,
    has_param: bool = False,
    box_width: float | None = None,
    control_count: int = 0,
) -> None

Attributes¶

box_width: float | None
control_count: int
estimated_width: float
gate_type: GateOperationType | None
has_param: bool
kind: VGateKind
label: str
node_key: tuple
qubit_indices: list[int]

`VGateKind` [source]¶

class VGateKind(enum.Enum)

Classification of VGate nodes for rendering dispatch.

Attributes¶

BLOCK_BOX
COMPOSITE_BOX
CONTROLLED_U_BOX
EXPVAL
GATE
MEASURE
MEASURE_VECTOR

`VInlineBlock` [source]¶

class VInlineBlock

Inlined CallBlock/ControlledU/CompositeGate with visible border.

Carries pre-resolved children, affected qubits, and pre-computed widths so that Layout and Renderer need no Analyzer access.

Constructor¶

def __init__(
    self,
    node_key: tuple,
    label: str,
    children: list[VisualNode],
    affected_qubits: list[int],
    control_qubit_indices: list[int],
    power: int,
    depth: int,
    border_padding: float,
    max_gate_width: float,
    label_width: float,
    content_width: float,
    final_width: float,
) -> None

Attributes¶

affected_qubits: list[int]
border_padding: float
children: list[VisualNode]
content_width: float
control_qubit_indices: list[int]
depth: int
final_width: float
label: str
label_width: float
max_gate_width: float
node_key: tuple
power: int

`VSkip` [source]¶

class VSkip

Zero-space node for QInit, Cast, or zero-iteration loops.

Constructor¶

def __init__(self, node_key: tuple = ()) -> None

Attributes¶

node_key: tuple

`VUnfoldedKind` [source]¶

class VUnfoldedKind(enum.Enum)

Classification of unfolded control-flow sequences.

Attributes¶

FOR
FOR_ITEMS
IF

`VUnfoldedSequence` [source]¶

class VUnfoldedSequence

Unfolded control-flow sequence (For/ForItems/If).

For loops: iterations[i] = children of iteration i. For if: iterations[0] = true branch, iterations[1] = false branch (if exists).

Constructor¶

def __init__(
    self,
    node_key: tuple,
    iterations: list[list[VisualNode]],
    affected_qubits: list[int],
    kind: VUnfoldedKind,
    iteration_widths: list[float] = list(),
    condition_label: str | None = None,
    affected_qubits_precise: bool = True,
) -> None

Attributes¶

affected_qubits: list[int]
affected_qubits_precise: bool
condition_label: str | None
iteration_widths: list[float]
iterations: list[list[VisualNode]]
kind: VUnfoldedKind
node_key: tuple

`VisualCircuit` [source]¶

class VisualCircuit

Root container for the Visual IR tree.

Carries the node tree plus qubit mapping information needed by Layout and Renderer.

Constructor¶

def __init__(
    self,
    children: list[VisualNode],
    qubit_map: dict[str, int],
    qubit_names: dict[int, str],
    num_qubits: int,
    output_names: list[str] = list(),
) -> None

Attributes¶

children: list[VisualNode]
num_qubits: int
output_names: list[str]
qubit_map: dict[str, int]
qubit_names: dict[int, str]

Overview¶

Classes¶

CircuitStyle [source]¶

Constructor¶

Attributes¶

MatplotlibDrawer [source]¶

Constructor¶

Attributes¶

Methods¶

draw¶

draw_kernel¶

qamomile.circuit.visualization.analyzer¶

Overview¶

Functions¶

compute_border_padding [source]¶

Classes¶

ArrayValue [source]¶

Constructor¶

Attributes¶

Methods¶

next_version¶

BinOp [source]¶

Constructor¶

Attributes¶

BinOpKind [source]¶

Attributes¶

Block [source]¶

Constructor¶

Attributes¶

Methods¶

call¶

is_affine¶

unbound_parameters¶

CallBlockOperation [source]¶

Constructor¶

Attributes¶

Methods¶

is_self_reference_to¶

CastOperation [source]¶

Constructor¶

Attributes¶

CircuitAnalyzer [source]¶

Constructor¶

Attributes¶

Methods¶

build_qubit_map¶

build_visual_ir¶

CircuitStyle [source]¶

Constructor¶

Attributes¶

CompositeGateOperation [source]¶

Constructor¶

Attributes¶

ControlledUOperation [source]¶

Constructor¶

Attributes¶

Methods¶

all_input_values¶

replace_values¶

ExpvalOp [source]¶

Constructor¶

Attributes¶

ForItemsOperation [source]¶

Constructor¶

Attributes¶

Methods¶

all_input_values¶

nested_op_lists¶

rebuild_nested¶

replace_values¶

ForOperation [source]¶

Constructor¶

Attributes¶

Methods¶

all_input_values¶

nested_op_lists¶

rebuild_nested¶

replace_values¶

GateOperation [source]¶

`CircuitStyle` [source]¶

`MatplotlibDrawer` [source]¶

`draw`¶

`draw_kernel`¶

`compute_border_padding` [source]¶

`ArrayValue` [source]¶

`next_version`¶

`BinOp` [source]¶

`BinOpKind` [source]¶

`Block` [source]¶

`call`¶

`is_affine`¶

`unbound_parameters`¶

`CallBlockOperation` [source]¶

`is_self_reference_to`¶

`CastOperation` [source]¶

`CircuitAnalyzer` [source]¶

`build_qubit_map`¶

`build_visual_ir`¶

`CircuitStyle` [source]¶

`CompositeGateOperation` [source]¶

`ControlledUOperation` [source]¶

`all_input_values`¶

`replace_values`¶

`ExpvalOp` [source]¶

`ForItemsOperation` [source]¶

`all_input_values`¶

`nested_op_lists`¶

`rebuild_nested`¶

`replace_values`¶

`ForOperation` [source]¶

`all_input_values`¶

`nested_op_lists`¶

`rebuild_nested`¶

`replace_values`¶

`GateOperation` [source]¶

`fixed`¶

`rotation`¶

`GateOperationType` [source]¶

`IfOperation` [source]¶

`nested_op_lists`¶

`rebuild_nested`¶

`MeasureOperation` [source]¶

`MeasureVectorOperation` [source]¶

`QInitOperation` [source]¶

`QubitType` [source]¶

`VFoldedBlock` [source]¶

`VFoldedKind` [source]¶

`VGate` [source]¶

`VGateKind` [source]¶

`VInlineBlock` [source]¶

`VSkip` [source]¶

`VUnfoldedKind` [source]¶

`VUnfoldedSequence` [source]¶

`Value` [source]¶

`is_array_element`¶

`next_version`¶

`VisualCircuit` [source]¶

`WhileOperation` [source]¶

`nested_op_lists`¶

`rebuild_nested`¶

`Block` [source]¶

`call`¶

`is_affine`¶

`unbound_parameters`¶

`CircuitAnalyzer` [source]¶