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: Graph, style: CircuitStyle | None = None)

Initialize the drawer.

Parameters:

Name	Type	Description
`graph`	`Graph`	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 values with shape information.
`BinOp`	Binary arithmetic operation (ADD, SUB, MUL, DIV, FLOORDIV, POW).
`BinOpKind`
`BlockValue`	Represents a subroutine as a function block.
`CallBlockOperation`
`CastOperation`	Type cast operation for creating aliases over the same quantum resources.
`CircuitAnalyzer`	Analyzes IR graphs for circuit visualization.
`CircuitStyle`	Style configuration for circuit visualization.
`CompositeGateOperation`	Represents a composite gate (QPE, QFT, etc.) as a single operation.
`ControlledUOperation`	Controlled-U operation that applies a unitary block conditionally.
`ExpvalOp`	Expectation value operation.
`ForItemsOperation`	Represents iteration over dict/iterable items.
`ForOperation`	Represents a for loop operation.
`GateOperation`
`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 value in the IR with SSA-style versioning.
`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 values with shape information.

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

Constructor¶

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

Attributes¶

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

Methods¶

`next_version`¶

def next_version(self) -> ArrayValue[T]

Create a new ArrayValue with incremented version, preserving shape.

`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

`BlockValue` [source]¶

class BlockValue(Value[BlockType])

Represents a subroutine as a function block.

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

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

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

Constructor¶

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

Attributes¶

input_values: list[Value]
label_args: list[str]
name: str
operations: list[Operation]
return_values: list[Value]
type: BlockType

Methods¶

`call`¶

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

Create a CallBlockOperation to call this BlockValue.

Example:

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

`CallBlockOperation` [source]¶

class CallBlockOperation(Operation)

Constructor¶

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

Attributes¶

operation_kind: OperationKind
signature: Signature

`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 graphs for circuit visualization.

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

Constructor¶

def __init__(
    self,
    graph: Graph,
    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: Graph) -> 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`	`Graph`	Computation graph.

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: Graph,
    qubit_map: dict[str, int],
    qubit_names: dict[int, str],
    num_qubits: int,
) -> VisualCircuit

Build a Visual IR tree from the IR graph.

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`	`Graph`	IR computation graph.
`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 depends on has_implementation:

If has_implementation=True:
- operands[0]: BlockValue (the implementation)
- operands[1:1+num_control_qubits]: Control qubits (if any)
- operands[1+num_control_qubits:1+num_control_qubits+num_target_qubits]: Target qubits
- operands[1+num_control_qubits+num_target_qubits:]: Parameters
If has_implementation=False (stub):
- operands[0:num_control_qubits]: Control qubits (if any)
- operands[num_control_qubits:num_control_qubits+num_target_qubits]: Target qubits
- operands[num_control_qubits+num_target_qubits:]: Parameters

The results structure:

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

Constructor¶

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

Attributes¶

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

`ControlledUOperation` [source]¶

class ControlledUOperation(Operation)

Controlled-U operation that applies a unitary block conditionally.

The operands structure is:

operands[0]: BlockValue (the unitary U to apply)
operands[1:1+num_controls]: Control qubits
operands[1+num_controls:]: Target qubits (arguments to U)

The results structure is:

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

Constructor¶

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

Attributes¶

block Get the BlockValue (unitary U).
control_operands Get the control qubit values.
controlled_indices: list[Value] | None
has_index_spec: bool Whether target/control positions are specified via index lists.
is_symbolic_num_controls: bool Whether num_controls is symbolic (Value) rather than concrete (int).
num_controls: int | Value
operation_kind: OperationKind
param_operands Get parameter operands (non-qubit, non-block).
power: int | Value
signature: Signature
target_indices: list[Value] | None
target_operands Get the target qubit values (arguments to U).

`ExpvalOp` [source]¶

class ExpvalOp(Operation)

Expectation value operation.

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

The operation bridges quantum and classical computation:

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

Example IR:

Constructor¶

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

Attributes¶

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

`ForItemsOperation` [source]¶

class ForItemsOperation(Operation)

Represents iteration over dict/iterable items.

Example:

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

Constructor¶

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

Attributes¶

key_is_vector: bool
key_vars: list[str]
operation_kind: OperationKind
operations: list[Operation]
signature: Signature
value_var: str

`ForOperation` [source]¶

class ForOperation(Operation)

Represents a for loop operation.

Example:

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

Constructor¶

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

Attributes¶

loop_var: str
operation_kind: OperationKind
operations: list[Operation]
signature: Signature

`GateOperation` [source]¶

class GateOperation(Operation)

Constructor¶

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

Attributes¶

gate_type: GateOperationType | None
operation_kind: OperationKind
signature: Signature
theta: float | Value | None

`GateOperationType` [source]¶

class GateOperationType(enum.Enum)

Attributes¶

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

`IfOperation` [source]¶

class IfOperation(Operation)

Represents an if-else conditional operation.

Example:

if condition:
    true_body
else:
    false_body

Constructor¶

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

Attributes¶

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

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

Constructor¶

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

Attributes¶

affected_qubits: list[int]
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,
) -> None

Attributes¶

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

`Value` [source]¶

class Value(Generic[T])

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

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

SSA versioning via uuid/logical_id
Parameter binding
Constant folding
Array element tracking

Constructor¶

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

Attributes¶

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

Methods¶

`get_cast_qubit_logical_ids`¶

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

Get the underlying qubit logical_ids for this cast value.

`get_cast_qubit_uuids`¶

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

Get the underlying qubit UUIDs for this cast value.

`get_cast_source_logical_id`¶

def get_cast_source_logical_id(self) -> str | None

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

`get_cast_source_uuid`¶

def get_cast_source_uuid(self) -> str | None

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

`get_const`¶

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

Get constant value if available, otherwise None.

`get_lowered_bits`¶

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

Get lowered bit list if available, otherwise None.

`get_lowered_qubits`¶

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

Get lowered qubit list if available, otherwise None.

`is_array_element`¶

def is_array_element(self) -> bool

Check if this value is an element of an array.

`is_cast_result`¶

def is_cast_result(self) -> bool

Check if this value is the result of a CastOperation.

`is_constant`¶

def is_constant(self) -> bool

Check if this value is a constant.

`is_parameter`¶

def is_parameter(self) -> bool

Check if this value is an unbound parameter.

`next_version`¶

def next_version(self) -> Value[T]

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

`parameter_name`¶

def parameter_name(self) -> str | None

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

`set_cast_metadata`¶

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

Set cast metadata for this value.

`set_lowered_bits`¶

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

Set lowered bit list.

`set_lowered_qubits`¶

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

Set lowered qubit list.

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

Represents a while loop operation.

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

Example::

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

Constructor¶

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

Attributes¶

operation_kind: OperationKind
operations: list[Operation]
signature: Signature

qamomile.circuit.visualization.drawer¶

Matplotlib-based circuit visualization.

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

Overview¶

Class	Description
`CircuitAnalyzer`	Analyzes IR graphs 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¶

`CircuitAnalyzer` [source]¶

class CircuitAnalyzer

Analyzes IR graphs for circuit visualization.

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

Constructor¶

def __init__(
    self,
    graph: Graph,
    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: Graph) -> 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`	`Graph`	Computation graph.

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: Graph,
    qubit_map: dict[str, int],
    qubit_names: dict[int, str],
    num_qubits: int,
) -> VisualCircuit

Build a Visual IR tree from the IR graph.

Parameters:

Name	Type	Description
`graph`	`Graph`	IR computation graph.
`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: Graph, style: CircuitStyle | None = None)

Initialize the drawer.

Parameters:

Name	Type	Description
`graph`	`Graph`	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: int,
    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: int

`LayoutState` [source]¶

class LayoutState

Mutable state shared across layout handler methods.

Constructor¶

def __init__(
    self,
    positions: dict[tuple, int] = dict(),
    block_ranges: list[dict] = list(),
    block_widths: dict[tuple, float] = dict(),
    column: int = 1,
    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, int] = _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: int
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, int]
qubit_columns: dict[int, int]
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,
) -> None

Attributes¶

affected_qubits: list[int]
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,
) -> None

Attributes¶

affected_qubits: list[int]
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: int,
    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: int

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

Attributes¶

affected_qubits: list[int]
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,
) -> None

Attributes¶

affected_qubits: list[int]
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: int,
    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: int

`LayoutState` [source]¶

class LayoutState

Mutable state shared across layout handler methods.

Constructor¶

def __init__(
    self,
    positions: dict[tuple, int] = dict(),
    block_ranges: list[dict] = list(),
    block_widths: dict[tuple, float] = dict(),
    column: int = 1,
    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, int] = _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: int
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, int]
qubit_columns: dict[int, int]
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,
) -> None

Attributes¶

affected_qubits: list[int]
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,
) -> None

Attributes¶

affected_qubits: list[int]
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¶

BlockValue [source]¶

Constructor¶

Attributes¶

Methods¶

call¶

CallBlockOperation [source]¶

Constructor¶

Attributes¶

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¶

ExpvalOp [source]¶

Constructor¶

Attributes¶

ForItemsOperation [source]¶

Constructor¶

Attributes¶

ForOperation [source]¶

Constructor¶

Attributes¶

GateOperation [source]¶

Constructor¶

Attributes¶

GateOperationType [source]¶

Attributes¶

IfOperation [source]¶

Constructor¶

Attributes¶

MeasureOperation [source]¶

Constructor¶

Attributes¶

MeasureVectorOperation [source]¶

Constructor¶

Attributes¶

QInitOperation [source]¶

Constructor¶

Attributes¶

QubitType [source]¶

`CircuitStyle` [source]¶

`MatplotlibDrawer` [source]¶

`draw`¶

`draw_kernel`¶

`compute_border_padding` [source]¶

`ArrayValue` [source]¶

`next_version`¶

`BinOp` [source]¶

`BinOpKind` [source]¶

`BlockValue` [source]¶

`call`¶

`CallBlockOperation` [source]¶

`CastOperation` [source]¶

`CircuitAnalyzer` [source]¶

`build_qubit_map`¶

`build_visual_ir`¶

`CircuitStyle` [source]¶

`CompositeGateOperation` [source]¶

`ControlledUOperation` [source]¶

`ExpvalOp` [source]¶

`ForItemsOperation` [source]¶

`ForOperation` [source]¶

`GateOperation` [source]¶

`GateOperationType` [source]¶

`IfOperation` [source]¶

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

`get_cast_qubit_logical_ids`¶

`get_cast_qubit_uuids`¶

`get_cast_source_logical_id`¶

`get_cast_source_uuid`¶

`get_const`¶

`get_lowered_bits`¶

`get_lowered_qubits`¶

`is_array_element`¶

`is_cast_result`¶

`is_constant`¶

`is_parameter`¶

`next_version`¶

`parameter_name`¶

`set_cast_metadata`¶

`set_lowered_bits`¶

`set_lowered_qubits`¶

`VisualCircuit` [source]¶

`WhileOperation` [source]¶

`CircuitAnalyzer` [source]¶

`build_qubit_map`¶

`build_visual_ir`¶

`CircuitLayoutEngine` [source]¶

`compute_layout`¶

`CircuitStyle` [source]¶

`MatplotlibDrawer` [source]¶

`draw`¶

`draw_kernel`¶