cqlib.visualization package

visualization module defines methods to visualize qcis circuits and plotting experiment results.

class cqlib.visualization.MatplotlibDrawer(circuit: Circuit, qubit_order: list[int | cqlib.circuits.qubit.Qubit] | None = None, figure_styles: dict[str, str | bool | float | tuple[float | int]] | None = None, gate_styles: dict[str, str | bool | float | tuple[float | int]] | None = None, title: str | None = None, fonts: str | list[str] | None = None, filename: str | None = None, style: str = 'default')

Bases: BaseDrawer

Quantum circuit visualizer using Matplotlib.

Renders circuit diagrams with customizable styling and layout. Supports multi-qubit gates, parameterized operations, and classical registers.

draw_column(column: list[dict])

Renders a single column of instructions onto the axes.

Parameters:

column (list[InstructionData]) – Group of gates to draw vertically aligned.

drawer() → Figure

Generates complete circuit visualization.

Processes circuit structure, computes layout, and renders all components.

Returns:

Matplotlib figure containing circuit diagram

Return type:

Figure

figure_styles = {'axes_color': 'white', 'figure_color': 'white', 'gate_height': 1.2, 'gate_width': 0.8, 'margin_bottom': 0.11, 'margin_left': 0.125, 'margin_right': 0.9, 'margin_top': 0.88, 'moment_width': 0.3, 'show_axis': '0'}
setup_figure() → tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes]

Configures Matplotlib figure and axes with specified styles.

Returns:

Configured figure and axes objects.

Return type:

tuple[Figure, Axes]

class cqlib.visualization.TextDrawer(circuit: Circuit, qubit_order: list[int | cqlib.circuits.qubit.Qubit] | None = None, line_width: int | None = None)

Bases: BaseDrawer

Renders quantum circuits as text diagrams using box-drawing characters

draw_column(column: list[cqlib.circuits.instruction_data.InstructionData])

Processes a vertical column of parallel operations

Parameters:

column – Group of non-overlapping operations from the same moment

Returns:

Formatted lines ready for insertion into main drawing

Return type:

list

draw_multi_gate(ins: InstructionData, lines: list[list[str]])

Visualizes multi-qubit operations with vertical connections

Special cases: - SWAP: Uses ‘X’ connection symbols - CZ: Uses solid dots - Barriers: Vertical lines spanning involved qubits - Controlled gates: Differentiates control/target qubits

Parameters:

  • ins – Multi-qubit instruction to render

  • lines – Current drawing lines state

Returns:

Updated lines with gate symbols and connection lines

draw_single_gate(ins: InstructionData, lines: list[list[str]])

Handles single-qubit gate visualization

Parameters:

  • ins – Gate instruction to render

  • lines – Current drawing lines state

Returns:

Updated lines with gate symbol placed on target qubit line

drawer() → str

Generates the complete text-based circuit diagram.

Returns:

Full circuit representation characters.

Return type:

str

get_line_width()

Determines the effective display width for circuit rendering.

Priority order for width determination: 1. User-specified line_width (if > MIN_LINE_WIDTH) 2. Current terminal width 3. DEFAULT_LINE_WIDTH fallback

Returns:

display width in characters.

Return type:

int

make_lines() → list[list[list[str]]]

Constructs the circuit visualization line structure.

Builds a 3-level nested list representing the circuit layout: - Outer list: Moments (vertical slices of parallel operations) - Middle list: Text lines per moment (including qubit labels and connections) - Inner list: Character sequences for each line segment

Returns:

List of moments, each containing lists of text lines with box characters. Structure details: - Even indices: Spacer lines between qubits - Odd indices: Qubit lines with labels and gate symbols - First element: Initial qubit label headers - Subsequent elements: Circuit moments with gate representations

cqlib.visualization.draw_gplot(machine_name: str | None, info: str | None = None, file_name: str | None = None, interactive: bool | None = False, scale: float | None = 1.0)

Draw a topology diagram of a quantum computer

Parameters:

  • machine_name – name of quantum computer.

  • info – Quantum computer information,Only one of [‘T1’, ‘T2’, ‘gate_error’, ‘two_gate_error’, ‘Readout_Error’] can be selected.Default to ‘None’

  • file_name – The address to save the image.Default to ‘None’

  • interactive – Displays the created image.Default to ‘False’

  • scale – Scale of image to draw .The value must be greater than 0,if it is greater than 1.0, it is enlarged, and if it is less than 1.0, it is shrunk. Default to ‘1.0’

Returns:

a matplotlib figure object for the gplot diagram

Return type:

matplotlib.figure.Figure

Raises:

  • VisualizationError – The failure to query the topology data of the quantum computer may be due to network reasons, or the input ‘machine_name’ parameter is incorrect

  • ValueError – ‘info’ parameter error

cqlib.visualization.draw_histogram(histogram_data: dict | List[dict] | None, title: str | None = None, bar_value_show: str | None = True, file_name: str | None = None, axis_label: list | None = None, interactive: bool | None = False, fig_size: tuple | None = (6.4, 4.8), legend: list | None = None)

draw histogram of experiment results

Args:

histogram_data: histogram data title: histogram title. Default to ‘None’ bar_value_show: Whether to display bar chart values。Default to ‘True’ file_name: file_name: The address to save the image.Default to ‘None’ axis_label: List of axis labels,size 2. one element is the X-axis label and the second element is the Y-axis label. e.g.:[“Categories”,”value”]).Default to ‘None’ interactive:Displays the created image.Default to ‘False’ fig_size: Figure size. Default to ‘(6.4,4.8)’ legend : The length of the data label must be the same as the number of data

Returns:

a matplotlib figure object for the histogram

Return type:

matplotlib.figure.Figure

cqlib.visualization.draw_mpl(circuit: Circuit, title: str | None = None, filename: str | None = None, qubit_order: list[int | cqlib.circuits.qubit.Qubit] | None = None, figure_styles: dict[str, str | bool | float | tuple[float | int]] | None = None, gate_styles: dict[str, str | bool | float | tuple[float | int]] | None = None, fonts: str | list[str] | None = None, style: str = 'default') → Figure

Quick visualization entry point.

Parameters:

  • circuit (Circuit) – Quantum circuit to draw

  • title (str | None) – Optional diagram title

  • filename (str | None) – Optional filename to save the diagram

  • qubit_order (list[int | Qubit] | None) – Custom display order for qubits. Defaults to circuit’s natural ordering.

  • figure_styles (dict | None) – Overrides for default figure styles (colors, margins, etc.).

  • gate_styles (dict | None) – Overrides for default gate rendering styles.

  • fonts (str | list[str] | None) – Font family/families for text rendering.

  • style (str) – Style name for consistent visual appearance.

Returns:

Ready-to-display circuit visualization

Return type:

Figure

cqlib.visualization.draw_text(circuit: Circuit, qubit_order: list[int | cqlib.circuits.qubit.Qubit] | None = None, line_width: int | None = None)

Quick-access function for text circuit visualization.

Parameters:

  • circuit (Circuit) – Quantum circuit to visualize

  • qubit_order (list[int | Qubit]) – Optional custom qubit arrangement

  • line_width (int) –

Returns:

Ready-to-print circuit diagram

Return type:

str

Submodules

cqlib.visualization.circuit module

Quantum circuit visualization

class cqlib.visualization.circuit.MatplotlibDrawer(circuit: Circuit, qubit_order: list[int | cqlib.circuits.qubit.Qubit] | None = None, figure_styles: dict[str, str | bool | float | tuple[float | int]] | None = None, gate_styles: dict[str, str | bool | float | tuple[float | int]] | None = None, title: str | None = None, fonts: str | list[str] | None = None, filename: str | None = None, style: str = 'default')

Bases: BaseDrawer

Quantum circuit visualizer using Matplotlib.

Renders circuit diagrams with customizable styling and layout. Supports multi-qubit gates, parameterized operations, and classical registers.

draw_column(column: list[dict])

Renders a single column of instructions onto the axes.

Parameters:

column (list[InstructionData]) – Group of gates to draw vertically aligned.

drawer() → Figure

Generates complete circuit visualization.

Processes circuit structure, computes layout, and renders all components.

Returns:

Matplotlib figure containing circuit diagram

Return type:

Figure

figure_styles = {'axes_color': 'white', 'figure_color': 'white', 'gate_height': 1.2, 'gate_width': 0.8, 'margin_bottom': 0.11, 'margin_left': 0.125, 'margin_right': 0.9, 'margin_top': 0.88, 'moment_width': 0.3, 'show_axis': '0'}
qubit_mapping: dict[cqlib.circuits.bit.Bit, int]
setup_figure() → tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes]

Configures Matplotlib figure and axes with specified styles.

Returns:

Configured figure and axes objects.

Return type:

tuple[Figure, Axes]

sorted_qubits: list[cqlib.circuits.bit.Bit]
class cqlib.visualization.circuit.TextDrawer(circuit: Circuit, qubit_order: list[int | cqlib.circuits.qubit.Qubit] | None = None, line_width: int | None = None)

Bases: BaseDrawer

Renders quantum circuits as text diagrams using box-drawing characters

draw_column(column: list[cqlib.circuits.instruction_data.InstructionData])

Processes a vertical column of parallel operations

Parameters:

column – Group of non-overlapping operations from the same moment

Returns:

Formatted lines ready for insertion into main drawing

Return type:

list

draw_multi_gate(ins: InstructionData, lines: list[list[str]])

Visualizes multi-qubit operations with vertical connections

Special cases: - SWAP: Uses ‘X’ connection symbols - CZ: Uses solid dots - Barriers: Vertical lines spanning involved qubits - Controlled gates: Differentiates control/target qubits

Parameters:

  • ins – Multi-qubit instruction to render

  • lines – Current drawing lines state

Returns:

Updated lines with gate symbols and connection lines

draw_single_gate(ins: InstructionData, lines: list[list[str]])

Handles single-qubit gate visualization

Parameters:

  • ins – Gate instruction to render

  • lines – Current drawing lines state

Returns:

Updated lines with gate symbol placed on target qubit line

drawer() → str

Generates the complete text-based circuit diagram.

Returns:

Full circuit representation characters.

Return type:

str

get_line_width()

Determines the effective display width for circuit rendering.

Priority order for width determination: 1. User-specified line_width (if > MIN_LINE_WIDTH) 2. Current terminal width 3. DEFAULT_LINE_WIDTH fallback

Returns:

display width in characters.

Return type:

int

make_lines() → list[list[list[str]]]

Constructs the circuit visualization line structure.

Builds a 3-level nested list representing the circuit layout: - Outer list: Moments (vertical slices of parallel operations) - Middle list: Text lines per moment (including qubit labels and connections) - Inner list: Character sequences for each line segment

Returns:

List of moments, each containing lists of text lines with box characters. Structure details: - Even indices: Spacer lines between qubits - Odd indices: Qubit lines with labels and gate symbols - First element: Initial qubit label headers - Subsequent elements: Circuit moments with gate representations

cqlib.visualization.circuit.draw_mpl(circuit: Circuit, title: str | None = None, filename: str | None = None, qubit_order: list[int | cqlib.circuits.qubit.Qubit] | None = None, figure_styles: dict[str, str | bool | float | tuple[float | int]] | None = None, gate_styles: dict[str, str | bool | float | tuple[float | int]] | None = None, fonts: str | list[str] | None = None, style: str = 'default') → Figure

Quick visualization entry point.

Parameters:

  • circuit (Circuit) – Quantum circuit to draw

  • title (str | None) – Optional diagram title

  • filename (str | None) – Optional filename to save the diagram

  • qubit_order (list[int | Qubit] | None) – Custom display order for qubits. Defaults to circuit’s natural ordering.

  • figure_styles (dict | None) – Overrides for default figure styles (colors, margins, etc.).

  • gate_styles (dict | None) – Overrides for default gate rendering styles.

  • fonts (str | list[str] | None) – Font family/families for text rendering.

  • style (str) – Style name for consistent visual appearance.

Returns:

Ready-to-display circuit visualization

Return type:

Figure

cqlib.visualization.circuit.draw_text(circuit: Circuit, qubit_order: list[int | cqlib.circuits.qubit.Qubit] | None = None, line_width: int | None = None)

Quick-access function for text circuit visualization.

Parameters:

  • circuit (Circuit) – Quantum circuit to visualize

  • qubit_order (list[int | Qubit]) – Optional custom qubit arrangement

  • line_width (int) –

Returns:

Ready-to-print circuit diagram

Return type:

str

cqlib.visualization.gplot module

cqlib.visualization.gplot.draw_gplot(machine_name: str | None, info: str | None = None, file_name: str | None = None, interactive: bool | None = False, scale: float | None = 1.0)

Draw a topology diagram of a quantum computer

Parameters:

  • machine_name – name of quantum computer.

  • info – Quantum computer information,Only one of [‘T1’, ‘T2’, ‘gate_error’, ‘two_gate_error’, ‘Readout_Error’] can be selected.Default to ‘None’

  • file_name – The address to save the image.Default to ‘None’

  • interactive – Displays the created image.Default to ‘False’

  • scale – Scale of image to draw .The value must be greater than 0,if it is greater than 1.0, it is enlarged, and if it is less than 1.0, it is shrunk. Default to ‘1.0’

Returns:

a matplotlib figure object for the gplot diagram

Return type:

matplotlib.figure.Figure

Raises:

  • VisualizationError – The failure to query the topology data of the quantum computer may be due to network reasons, or the input ‘machine_name’ parameter is incorrect

  • ValueError – ‘info’ parameter error

cqlib.visualization.result module

cqlib.visualization.result.draw_histogram(histogram_data: dict | List[dict] | None, title: str | None = None, bar_value_show: str | None = True, file_name: str | None = None, axis_label: list | None = None, interactive: bool | None = False, fig_size: tuple | None = (6.4, 4.8), legend: list | None = None)

draw histogram of experiment results

Args:

histogram_data: histogram data title: histogram title. Default to ‘None’ bar_value_show: Whether to display bar chart values。Default to ‘True’ file_name: file_name: The address to save the image.Default to ‘None’ axis_label: List of axis labels,size 2. one element is the X-axis label and the second element is the Y-axis label. e.g.:[“Categories”,”value”]).Default to ‘None’ interactive:Displays the created image.Default to ‘False’ fig_size: Figure size. Default to ‘(6.4,4.8)’ legend : The length of the data label must be the same as the number of data

Returns:

a matplotlib figure object for the histogram

Return type:

matplotlib.figure.Figure