`qarp.plotting`¶

Circuit and histogram plotting. Public depth: flat for the plotters and their configuration, plus one qualified namespace — styles, the colour schemes (including the accessibility palettes) and the matplotlib theme, which users import directly. Renderers, processors and the interactive widget are private.

class qarp.plotting.CircuitAdapter(source, n_qubits: int | None = None, decompose_boxes: bool = False)[source]¶

Bases: object

Adapt a qarpx Block (or flat command list) for the plotting renderers.

A built CompositeBlock renders as one box per child sub-block (block structure preserved); decompose_boxes=True flattens it into primitive gates instead. Leaf blocks always render their gates.

Usage:

block = SimpleBlock(5, "GHZ")
block.h(0); block.cx(0, 1); ...
block.build()
plot(CircuitAdapter(block))
# or simply
block.plot()

get_commands() → List[source]¶

property n_qubits: int¶

property name: str¶

property phase: float¶

property qubits: List[_Qubit]¶

class qarp.plotting.CircuitPlotter(config: PlotConfig | None = None)[source]¶

Bases: object

property gates: List[GateInfo]¶

Get list of all gates from the last plotted circuit.

Returns:: List of GateInfo objects containing full gate information.

get_inner_circuit(index: int)[source]¶

Extract the inner circuit from a box gate by its index.

This method works with boxed sub-blocks (plain or quantum-controlled) that contain inner circuits.

Parameters:: index – The gate index as shown in the plot.
Returns:: The inner Circuit if the gate is a box type, None otherwise.

Example

>>> plotter.plot(circuit, show_gate_indices=True)
>>> inner = plotter.get_inner_circuit(5)  # Get inner circuit of gate #5
>>> if inner:
...     plot(inner)  # Plot the inner circuit

list_gates() → None[source]¶: Print a summary of all gates from the last plotted circuit.

plot(circ, figsize: Tuple[float, float] | None = None, save_fig: str | None = None, decompose_boxes: bool = False, flatten_layers: bool = True, invert_order: bool = False, scrollable: bool | None = None, interactive: bool | None = None, use_latex: bool = False, spacing: float | None = None, verbose: bool = False, label_mode: LabelMode | None = None, show_gate_indices: bool | None = None, _show: bool = True)[source]¶

Main class for plotting quantum circuits.

Parameters:

circ – The quantum circuit to plot.
figsize – Size of the figure (width, height). If None, size is auto-calculated.
save_fig – If provided, saves the figure to the given file path.
decompose_boxes – Whether to decompose box gates before plotting.
flatten_layers – Whether to flatten layers in the circuit.
invert_order – Whether to invert the order of qubits in the plot.
scrollable – If True, display the plot in a scrollable HTML container (for Jupyter). If None (default), auto-detects: scrollable inside a Jupyter notebook, plain plt.show() otherwise.
interactive – If True (default when the scrollable HTML path is used), the notebook output gains hover tooltips — full gate expression, qubits, gate index — with the rest of the circuit dimmed while a gate is hovered. Pure client-side (no widgets), so it survives nbconvert to HTML. Set False for the plain static SVG.
use_latex – Whether to use LaTeX for rendering text.
spacing – Horizontal spacing between gates. If None, uses default from config.
verbose – If True, prints additional information about the circuit.
label_mode – How to handle gate labels. Options: - LabelMode.TRUNCATE: Show only gate names without parameters (e.g., “Ry” instead of “Ry(0.5)”) - LabelMode.SMART: Intelligent positioning to avoid overlaps (default) - LabelMode.FULL: Full labels without adjustment (may overlap)
show_gate_indices – If True, display small index numbers near each gate. Use query_gate(index) or list_gates() to get full gate information.

plot_inner(index: int, **kwargs) → CircuitPlotter | None[source]¶

Plot the inner circuit of a box gate.

This is a convenience method that extracts and plots the inner circuit of a boxed sub-block (plain or quantum-controlled) in a single call.

Parameters:

index – The gate index as shown in the plot.
**kwargs – Additional arguments passed to plot() (e.g., figsize, save_fig).

Returns:

A new CircuitPlotter instance for the inner circuit, or None if the gate is not a box type.

Example

>>> plotter = plot(circuit, show_gate_indices=True, return_plotter=True)
>>> inner_plotter = plotter.plot_inner(5)  # Plot inner circuit of gate #5

query_gate(index: int) → GateInfo | None[source]¶

Query a gate by its index to get full information.

Parameters:: index – The gate index as shown in the plot.
Returns:: GateInfo object with full gate details, or None if index not found.

Example

>>> plotter.plot(circuit, show_gate_indices=True)
>>> gate = plotter.query_gate(3)
>>> print(gate)
Gate Index: 3
Gate Type: Ry
Full Expression: Ry(0.123456789*pi + theta)
Displayed As: Ry
Qubits: [q[0]]

class qarp.plotting.GateInfo(index: int, gate_type: str, full_label: str, displayed_label: str, qubits: List[str], x_position: float, y_position: float, command: Any)[source]¶

Bases: object

Information about a gate in the circuit plot for querying.

command: Any¶

displayed_label: str¶

full_label: str¶

gate_type: str¶

index: int¶

qubits: List[str]¶

x_position: float¶

y_position: float¶

class qarp.plotting.LabelMode(*values)[source]¶

Bases: Enum

Determines how gate labels are handled in circuit plots.

Variables:

TRUNCATE – Truncates labels to show only the gate name without parameters. E.g., “Ry(0.5*pi)” becomes “Ry”. This is the safest option that avoids overlap issues.
SMART – Uses intelligent positioning to avoid overlaps. Labels may be shifted vertically, line-broken, or repositioned as needed.
FULL – Displays full labels without any adjustments. May result in overlapping labels for complex circuits.

FULL = 'full'¶

SMART = 'smart'¶

TRUNCATE = 'truncate'¶

class qarp.plotting.PlotConfig(gate_colors: Dict[str, str] | None = None, spacing: float = 0.25, gate_size: int = 16, control_size: int = 4, swap_size: int = 6, text_size: int = 9, box_linewidth: float = 1.1, gate_style: str = 'outline', gate_edge_width: float = 1.3, default_gate_color: str = '#101b2d', wire_color: str = '#b6c2d1', structure_color: str = '#101b2d', text_color: str = '#101b2d', muted_color: str = '#5d6f86', gate_index_color: str = '#d03b3b', max_chars: int = 8, label_decimal_places: int = 3, label_mode: LabelMode = LabelMode.SMART, label_max_width: int = 12, label_y_margin: float = 0.4, label_x_margin: float = 0.15, show_gate_indices: bool = False, gate_index_size: int = 6)[source]¶

Bases: object

Configuration for circuit plotting.

box_linewidth: float = 1.1¶

control_size: int = 4¶

default_gate_color: str = '#101b2d'¶

gate_color(name: str) → str[source]¶: Scheme color for a gate name, with the config fallback.

gate_colors: Dict[str, str] | None = None¶

gate_edge_width: float = 1.3¶

gate_face_edge(color: str) → Tuple[str, str][source]¶: (facecolor, edgecolor) for a gate marker under the active gate_style.

gate_index_color: str = '#d03b3b'¶

gate_index_size: int = 6¶

gate_size: int = 16¶

gate_style: str = 'outline'¶

label_decimal_places: int = 3¶

label_max_width: int = 12¶

label_mode: LabelMode = 'smart'¶

label_x_margin: float = 0.15¶

label_y_margin: float = 0.4¶

max_chars: int = 8¶

muted_color: str = '#5d6f86'¶

show_gate_indices: bool = False¶

spacing: float = 0.25¶

structure_color: str = '#101b2d'¶

swap_size: int = 6¶

text_color: str = '#101b2d'¶

text_size: int = 9¶

wire_color: str = '#b6c2d1'¶

qarp.plotting.plot(circ, color_scheme: str | Dict = 'default', label_mode: LabelMode | None = None, show_gate_indices: bool = False, return_plotter: bool = False, inner_index: int | List[int] | None = None, **kwargs) → CircuitPlotter | None[source]¶

Plot the provided circuit.

Parameters:

circ – The quantum circuit to plot.
color_scheme – Color scheme for gates. Options are ‘default’ (the OpenQARP theme: role-based colors, outlined gates), ‘qarp’ (alias of default), ‘classic’ (per-gate solid-chip palette), ‘colorblind’, ‘protanopia’, ‘deuteranopia’, ‘tritanopia’, ‘high_contrast’, ‘grayscale’, or a custom dict mapping gate names to hex fill colors (drawn in the classic solid-chip treatment).
label_mode – How to handle gate labels. Options are LabelMode.TRUNCATE (show only gate names), LabelMode.SMART (intelligent positioning, default), or LabelMode.FULL (full labels without adjustment).
show_gate_indices – If True, display small index numbers near each gate. Use the returned plotter’s query_gate(index) or list_gates() to get full info.
return_plotter – If True, returns the plotter instance for gate querying.
inner_index – Index or path to the inner circuit of a box gate. Can be a single int (plots inner circuit at that index) or a list of ints (recursively zooms into nested boxes following the path, e.g., [1, 0, 3]). Use with show_gate_indices=True first to identify box gate indices. Works with any boxed sub-block (plain or quantum-controlled).
figsize – Size of the figure (width, height). If None, size is auto-calculated.
save_fig – If provided, saves the figure to the given file path.
decompose_boxes – Whether to decompose box gates before plotting.
flatten_layers – Whether to flatten layers in the circuit.
invert_order – Whether to invert the order of qubits in the plot.
scrollable – If True, display the plot in a scrollable HTML container (for Jupyter). If None (default), auto-detects: scrollable inside a Jupyter notebook, plain plt.show() otherwise.
interactive – If True (default whenever the scrollable HTML path is used), the notebook output gains hover tooltips — full gate expression, qubits, gate index — and dims the rest of the circuit while a gate is hovered. Pure client-side, so it survives nbconvert to HTML. False for plain SVG.
use_latex – Whether to use LaTeX for rendering text.
spacing – Horizontal spacing between gates. If None, uses default from config.
verbose – If True, prints additional information about the circuit.

Returns:

The plotter instance if return_plotter=True, otherwise None.: Use query_gate(index) or list_gates() to inspect gate information.

Return type:

CircuitPlotter

Example

>>> # First, plot with indices to find box gates
>>> plot(circuit, show_gate_indices=True)
>>> # Then plot the inner circuit of the box at index 5
>>> plot(circuit, inner_index=5)
>>> # Zoom into nested boxes: box 1 -> box 0 inside -> box 3 inside
>>> plot(circuit, inner_index=[1, 0, 3])
>>> # Use specific colorblind palette
>>> plot(circuit, color_scheme='deuteranopia')

qarp.plotting.plot_histogram(probs: Dict[Tuple[int, ...], float], title: str = '', figsize: Tuple[int, int] = (10, 5), show_all_solutions: bool = False, return_plotter: bool = False, show_values: bool = True, sort_by_prob: bool = False, top_k: int | None = None, highlight_max: bool = False)[source]¶

Plots a histogram of the probabilities of different solutions.

Parameters:

probs – A dictionary mapping tuples of binary values (representing solutions) to their probabilities.
title – The title of the histogram.
figsize – The size of the figure to create.
show_all_solutions – If True, includes all possible solutions in the histogram, even those with zero probability.
return_plotter – If True, returns the figure and axis objects for further manipulation.
show_values – If True, displays probability values above each bar.
sort_by_prob – If True, sorts bars by probability in descending order.
top_k – If set, only show the top k solutions by probability. Implies sort_by_prob=True.
highlight_max – If True, highlights the most probable solution(s) in a different color.

qarp.plotting¶

`qarp.plotting`¶