Visualization

Visualize quantum circuits, quantum states, and simulation results using pyqpanda3's built-in drawing and plotting tools.

Prerequisites: Circuit Construction -- you should be comfortable building QProg and QCircuit objects before working through this tutorial.

Overview
1. Circuit Drawing
2. Print Options
3. The visualization Module
4. Practical Examples
5. Visualization Workflow
6. API Quick Reference
Summary

Overview

pyqpanda3 provides two layers of visualization tools:

Core module (pyqpanda3.core) -- Circuit drawing functions (draw_qprog, PIC_TYPE, set_print_options) that produce text or LaTeX representations directly, no extra dependencies required.
Visualization module (pyqpanda3.visualization) -- Rich plotting functions (Bloch sphere, state city plots, density matrices, probability bar charts) that depend on matplotlib for rendering graphical output.

The following diagram shows how these two layers relate to the quantum objects you create:

1. Circuit Drawing

Circuit drawing is the most common visualization task. It renders a quantum circuit as a human-readable diagram showing qubit wires, gates, measurements, and their connectivity. pyqpanda3 supports three output formats: text (ASCII art), image (matplotlib), and LaTeX source code.

1.1 Quick Text Output with print()

The fastest way to visualize a circuit is the built-in print() function. Both QProg and QCircuit implement __repr__ so that print() renders a text circuit diagram automatically.

python

from pyqpanda3 import core

# Build a Bell state circuit
prog = core.QProg()
prog << core.H(0) << core.CNOT(0, 1) << core.measure([0, 1], [0, 1])

# Quick text rendering
print(prog)

This produces a text circuit diagram showing the gate sequence on qubit wires:

qubit 0: ──H──*─M─
              │  │
qubit 1: ─────X─M─

You can also print a QCircuit object the same way:

python

circuit = core.QCircuit()
circuit << core.H(0) << core.RY(1, 1.57) << core.CNOT(0, 1)

print(circuit)

The output displays each gate on the appropriate qubit wire, with control and target markers for two-qubit gates.

1.2 Drawing with core.draw_qprog()

The core.draw_qprog() function gives you more control over the output format and parameters. It accepts either a QProg or QCircuit as its first argument and a PIC_TYPE enum to select the output format.

The two available picture types are:

Constant	Description
`core.PIC_TYPE.TEXT`	ASCII text diagram (default for most uses)
`core.PIC_TYPE.LATEX`	LaTeX source code for publication-quality rendering

Text Output

python

from pyqpanda3 import core

prog = core.QProg()
prog << core.H(0) << core.CNOT(0, 1) << core.measure([0, 1], [0, 1])

# Draw as text with gate parameters shown
result = core.draw_qprog(
    prog,
    p=core.PIC_TYPE.TEXT,
    param_show=True,
    line_length=100
)
print(result)

The param_show=True flag reveals numerical parameters on rotation gates (for example, showing the angle on an RX gate).

LaTeX Output

python

# Draw as LaTeX source code
latex_result = core.draw_qprog(
    prog,
    p=core.PIC_TYPE.LATEX,
    with_logo=False
)
print(latex_result)

The returned string is valid LaTeX source using the quantikz package. You can paste it into a LaTeX document or compile it standalone to produce a PDF circuit diagram.

Saving to File

Both text and LaTeX output can be saved directly to a file:

python

# Save text diagram to file
core.draw_qprog(
    prog,
    p=core.PIC_TYPE.TEXT,
    output_file="bell_circuit.txt"
)

# Save LaTeX source to file
core.draw_qprog(
    prog,
    p=core.PIC_TYPE.LATEX,
    output_file="bell_circuit.tex"
)

The output_file parameter writes the result to the specified path. When the output_file is empty (the default), the function returns the result as a string instead.

1.3 The draw() Member Method

Both QProg and QCircuit have a draw() method injected by the visualization module. This provides a convenient, object-oriented interface for circuit drawing. The method is available as soon as pyqpanda3 is imported.

python

from pyqpanda3 import core

prog = core.QProg()
prog << core.H(0) << core.CNOT(0, 1)

# Text output (default)
text = prog.draw()
print(text)

# Explicit text output
text = prog.draw('text')
print(text)

The draw() method accepts the following keyword arguments:

Parameter	Type	Default	Description
`output`	`str`	`'text'`	Output format: `'text'`, `'pic'`, or `'latex'`
`filename`	`str`	`None`	Save output to this file path
`scale`	`float`	`0.7`	Image scale factor (`'pic'` only)
`fold`	`int`	`30`	Maximum image width in gates (`'pic'` only)
`with_logo`	`bool`	`False`	Include logo in LaTeX output
`with_gate_params`	`bool`	`False`	Show gate parameters
`line_length`	`int`	`100`	Maximum line length for text output
`console_encode_type`	`str`	`'utf8'`	Character encoding: `'utf8'` or `'gbk'`

1.4 Drawing as an Image (PIC)

The 'pic' output format uses matplotlib to render a colorful circuit diagram and save it as an image file (JPEG or PNG). This is useful for reports, presentations, and Jupyter notebooks.

python

from pyqpanda3 import core

prog = core.QProg()
prog << core.H(0) << core.CNOT(0, 1) << core.measure([0, 1], [0, 1])

# Save as JPEG with default filename
prog.draw('pic')

# Save to a custom path with custom scale
prog.draw('pic', filename='my_circuit.png', scale=0.5)

# Show gate parameters in the image
prog.draw('pic', filename='circuit_with_params.jpg', with_gate_params=True)

When using 'pic' output without specifying a filename, the image is saved to QCircuit_pic.jpg in the current working directory.

1.5 LaTeX Output

LaTeX output produces source code that you can embed in academic papers, theses, or any LaTeX document. The output uses the quantikz TikZ library for typesetting circuit diagrams.

python

from pyqpanda3 import core

prog = core.QProg()
prog << core.H(0) << core.T(1) << core.CNOT(0, 1)
prog << core.measure([0, 1], [0, 1])

# Get LaTeX source code
latex = prog.draw('latex')
print(latex)

# Save to .tex file with logo
prog.draw('latex', filename='paper_circuit.tex', with_logo=True)

# Also accessible via core.draw_qprog
latex2 = core.draw_qprog(
    prog,
    p=core.PIC_TYPE.LATEX,
    with_logo=True,
    output_file='circuit.tex'
)

To compile the LaTeX output into a PDF, you need a LaTeX distribution with the quantikz package installed. A minimal compilation command is:

bash

pdflatex circuit.tex

1.6 Drawing Parameters in Detail

param_show / with_gate_params

By default, parameterized gates (such as RX, RY, RZ, U3) are drawn without their numerical parameters. Set param_show=True (for core.draw_qprog) or with_gate_params=True (for .draw()) to display them:

python

from pyqpanda3 import core

prog = core.QProg()
prog << core.RX(0, 1.5708) << core.RY(1, 0.7854) << core.CNOT(0, 1)

# Without parameters (default)
print(prog.draw())

# With parameters
print(prog.draw(with_gate_params=True))

with_logo

When using LaTeX output, setting with_logo=True includes the pyqpanda3 logo in the circuit diagram header. This is mainly useful for presentations and demonstrations.

line_length

Controls the maximum number of characters per line in text output. Circuits that exceed this length wrap to multiple lines:

python

# Short lines for narrow terminals
result = prog.draw('text', line_length=60)

expend_map

The expend_map parameter controls expansion of nested circuits. Passing {"all": 1} expands all nested sub-circuits into individual gates:

python

# Expand all nested circuits
result = core.draw_qprog(
    prog,
    p=core.PIC_TYPE.TEXT,
    expend_map={"all": 1}
)

encode

Controls the character encoding for text output. The default is "utf-8". Use "gbk" for compatibility with terminals that use GBK encoding (common in some Chinese locales).

2. Print Options

The core.set_print_options() function configures global defaults for how circuit information is displayed when using print() or core.draw_qprog(). This affects all subsequent print operations in your session.

python

from pyqpanda3 import core

# Configure print options
core.set_print_options(
    precision=8,       # Decimal places for gate parameters
    param_show=True,   # Show gate parameters by default
    linewidth=100      # Maximum line width
)

Parameters

Parameter	Type	Default	Description
`precision`	`int`	`8`	Number of decimal places for floating-point parameters
`param_show`	`bool`	`False`	Whether to display gate parameters
`linewidth`	`int`	`100`	Maximum line width for text output

Usage Example

python

from pyqpanda3 import core

# Build a circuit with parameterized gates
prog = core.QProg()
prog << core.RX(0, 3.14159265) << core.RY(1, 1.57079633) << core.CNOT(0, 1)

# Default print options
print("Default:")
print(prog)

# Set high precision with parameters visible
core.set_print_options(precision=4, param_show=True, linewidth=80)
print("\nWith options (precision=4, param_show=True):")
print(prog)

# Reset to defaults
core.set_print_options(precision=8, param_show=False, linewidth=100)

The precision setting is particularly useful when working with variational circuits where you need to inspect parameter values during optimization.

3. The visualization Module

The pyqpanda3.visualization module provides rich graphical visualization tools that go beyond text-based circuit drawing. It depends on matplotlib for rendering and offers functions for Bloch sphere plots, state city visualizations, density matrix heatmaps, and probability bar charts.

3.1 Importing the Module

python

# Import specific functions
from pyqpanda3.visualization import (
    plot_bloch,
    plot_state,
    plot_probabilities,
    circuit_summary
)

# Or import the module as a whole
import pyqpanda3.visualization as viz

The module also exposes lower-level functions for specialized use cases:

python

from pyqpanda3.visualization import (
    plot_bloch_vector,
    plot_bloch_multivector,
    plot_bloch_circuit,
    plot_state_city,
    plot_density_matrix,
    draw_probability,
    draw_probability_dict
)

3.2 Bloch Sphere Visualization

The Bloch sphere is a geometric representation of a single-qubit quantum state. Any pure single-qubit state can be written as:

| ψ ⟩ = \cos \frac{θ}{2} | 0 ⟩ + e^{i ϕ} \sin \frac{θ}{2} | 1 ⟩

and represented as a point on the unit sphere with coordinates $(x, y, z)$ where:

x = \sin θ \cos ϕ, y = \sin θ \sin ϕ, z = \cos θ

The visualization module provides three functions for Bloch sphere rendering:

plot_bloch_vector(bloch, title, axis_obj, fig_size)

Plot a single Bloch vector on a 3D sphere. The input is a list of three floats [x, y, z] representing the Cartesian coordinates of the Bloch vector.

python

from pyqpanda3.visualization import plot_bloch_vector

# Plot the |0> state (north pole, z-axis)
plot_bloch_vector([0, 0, 1], title="|0> state")

# Plot the |1> state (south pole)
plot_bloch_vector([0, 0, -1], title="|1> state")

# Plot the |+> state (x-axis)
plot_bloch_vector([1, 0, 0], title="|+> state")

# Plot the |-i> state (-y-axis)
plot_bloch_vector([0, -1, 0], title="|-i> state")

Common single-qubit states and their Bloch vectors:

State	Bloch Vector	Description
$\| 0 ⟩$	`[0, 0, 1]`	North pole
$\| 1 ⟩$	`[0, 0, -1]`	South pole
$\| + ⟩ = \frac{1}{\sqrt{2}} (\| 0 ⟩ + \| 1 ⟩)$	`[1, 0, 0]`	+X direction
$\| - ⟩ = \frac{1}{\sqrt{2}} (\| 0 ⟩ - \| 1 ⟩)$	`[-1, 0, 0]`	-X direction
$\| + i ⟩ = \frac{1}{\sqrt{2}} (\| 0 ⟩ + i \| 1 ⟩)$	`[0, 1, 0]`	+Y direction
$\| - i ⟩ = \frac{1}{\sqrt{2}} (\| 0 ⟩ - i \| 1 ⟩)$	`[0, -1, 0]`	-Y direction

plot_bloch_multivector(state, title, fig_size)

Plot each qubit of a multi-qubit state on its own Bloch sphere. This function takes a state vector (list or numpy array) and computes the reduced density matrix for each qubit to determine its Bloch vector.

python

import numpy as np
from pyqpanda3.visualization import plot_bloch_multivector

# Bell state: (|00> + |11>) / sqrt(2)
# Each qubit is maximally mixed -> Bloch vector at origin
bell_state = np.array([1, 0, 0, 1]) / np.sqrt(2)
plot_bloch_multivector(bell_state, title="Bell State Qubits")

# Product state: |+>|0>
# Qubit 0 at +X, qubit 1 at +Z
product_state = np.array([1, 1, 0, 0]) / np.sqrt(2)
plot_bloch_multivector(product_state, title="|+>|0> State")

For entangled states like the Bell state, the reduced state of each individual qubit is a maximally mixed state, so the Bloch vector sits at the origin. This is a visual indication of entanglement.

plot_bloch_circuit(circuit, trace, saveas, fps, secs_per_gate)

Animate the evolution of a single-qubit circuit on the Bloch sphere. This function traverses the circuit gate by gate, showing how each gate rotates the state vector on the sphere. It supports common single-qubit gates: H, X, Y, Z, RX, RY, RZ, S, T, and their dagger variants.

python

from pyqpanda3 import core
from pyqpanda3.visualization import plot_bloch_circuit

# Build a single-qubit circuit
circuit = core.QCircuit()
circuit << core.H(0)
circuit << core.RY(0, 1.5708)  # pi/2 rotation
circuit << core.Z(0)

# Animate the circuit on the Bloch sphere
plot_bloch_circuit(
    circuit,
    trace=True,          # Show the path of the state vector
    saveas='bloch_animation.gif',  # Save as animated GIF
    fps=20,              # Frames per second
    secs_per_gate=1      # Duration per gate in seconds
)

When trace=True, the animation draws a colored trail showing the path of the state vector as each gate is applied. Each gate has a distinct color to help you follow the evolution.

Unified plot_bloch() Interface

The plot_bloch() function provides a unified interface that automatically detects the input type and calls the appropriate function:

python

from pyqpanda3.visualization import plot_bloch

# Single Bloch vector (list/tuple of 3 numbers)
plot_bloch([1, 0, 0], title="X State")

# State vector (array-like)
import numpy as np
state = np.array([1, 0, 0, 1]) / np.sqrt(2)
plot_bloch(state, title="Bell State")

# Circuit (single-qubit only)
circuit = core.QCircuit()
circuit << core.H(0) << core.T(0)
plot_bloch(circuit)

3.3 State City Plots

State city plots provide a 3D visualization of a quantum state's density matrix. They show both the real and imaginary parts of the density matrix as side-by-side bar charts, giving you an intuitive picture of the state's structure.

The density matrix for a pure state $| ψ ⟩$ is:

ρ = | ψ ⟩ ⟨ ψ |

plot_state_city(state, title, figsize, color)

python

import numpy as np
from pyqpanda3.visualization import plot_state_city

# Bell state density matrix
bell_state = np.array([1, 0, 0, 1]) / np.sqrt(2)
plot_state_city(bell_state, title="Bell State Density Matrix")

# Custom colors and figure size
plot_state_city(
    bell_state,
    title="Bell State",
    figsize=(12, 4),
    color=["#1f77b4", "#ff7f0e"]  # [real color, imaginary color]
)

The function accepts either a state vector (1D array) or a density matrix (2D array). When given a state vector, it computes the density matrix automatically.

The left subplot shows $Re [ρ]$ and the right shows $Im [ρ]$ . For a Bell state $| Φ^{+} ⟩ = \frac{1}{\sqrt{2}} (| 00 ⟩ + | 11 ⟩)$ , the density matrix is:

ρ_{Bell} = \frac{1}{2} (\begin{matrix} 1 & 0 & 0 & 1 \\ 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 \\ 1 & 0 & 0 & 1 \end{matrix})

All entries are real, so the imaginary part is zero and the right subplot shows a flat surface.

Unified plot_state() Interface

python

from pyqpanda3.visualization import plot_state

state = np.array([1, 0, 0, 1]) / np.sqrt(2)

# City plot (default)
plot_state(state, kind='city', title="Bell State")

# Density matrix heatmap
plot_state(state, kind='density', title="Bell State")

The kind parameter selects the visualization type: 'city' for a 3D bar plot, 'density' for a heatmap with phase coloring.

3.4 Density Matrix Visualization

The plot_density_matrix() function renders the density matrix as a 3D bar chart where the height of each bar represents the absolute value $| ρ_{i j} |$ and the color encodes the complex phase $\arg (ρ_{i j})$ .

python

import numpy as np
from pyqpanda3.visualization import plot_density_matrix

# Create a mixed state density matrix
rho = np.array([
    [0.5, 0.0, 0.0, 0.5],
    [0.0, 0.0, 0.0, 0.0],
    [0.0, 0.0, 0.0, 0.0],
    [0.5, 0.0, 0.0, 0.5]
])

fig, ax = plot_density_matrix(
    rho,
    title="Bell State Density Matrix",
    xlabels=['00', '01', '10', '11'],
    ylabels=['00', '01', '10', '11']
)

The color bar maps the phase angle from $- π$ to $π$ , making it easy to identify phase relationships between matrix elements.

3.5 Probability Bar Charts

Probability bar charts visualize measurement outcome distributions. They are useful for inspecting simulator results and understanding the output distribution of quantum circuits.

plot_probabilities(data, title, figsize, top_k, save)

The unified plot_probabilities() function accepts either a dictionary mapping state labels to probabilities, or a list/array of probabilities:

python

from pyqpanda3.visualization import plot_probabilities

# From a dictionary
plot_probabilities(
    {'00': 0.5, '11': 0.5},
    title="Bell State Probabilities"
)

# From a raw array (auto-generates labels)
import numpy as np
probs = [0.5, 0, 0, 0.5]
plot_probabilities(probs, title="Bell State")

# Show only top-K most probable outcomes
noisy_results = {
    '000': 0.485, '111': 0.492,
    '001': 0.008, '010': 0.006,
    '100': 0.005, '011': 0.004
}
plot_probabilities(noisy_results, top_k=3, title="Noisy GHZ (top 3)")

When top_k is specified, only the k most probable outcomes are displayed. This is useful for circuits with many qubits where most basis states have near-zero probability.

draw_probability() and draw_probability_dict()

Lower-level functions for backward compatibility:

python

from pyqpanda3.visualization import draw_probability, draw_probability_dict

# From a dictionary of counts or probabilities
data = {'00': 497, '11': 503}
draw_probability(data)

# From a probability dictionary (filters zero entries)
draw_probability_dict({'|00>': 0.5, '|11>': 0.5})

Computing Probabilities from Simulation Results

A typical workflow combines simulation with probability visualization:

python

from pyqpanda3 import core
from pyqpanda3.visualization import plot_probabilities

# Build and run a circuit
prog = core.QProg()
prog << core.H(0) << core.CNOT(0, 1) << core.measure([0, 1], [0, 1])

machine = core.CPUQVM()
machine.run(prog, shots=10000)
counts = machine.result().get_counts()

# Convert counts to probabilities
total = sum(counts.values())
probs = {state: count / total for state, count in counts.items()}

# Visualize
plot_probabilities(probs, title="Bell State Measurement (10000 shots)")

3.6 Circuit Summary

The circuit_summary() function provides a statistical overview of a circuit's composition: how many single-qubit gates, two-qubit gates, and multi-control gates it contains, along with layer information.

python

from pyqpanda3 import core
from pyqpanda3.visualization import circuit_summary

prog = core.QProg()
prog << core.H(0) << core.H(1)
prog << core.CNOT(0, 1) << core.SWAP(1, 2)
prog << core.measure([0, 1, 2], [0, 1, 2])

# Get summary (optionally display pie chart)
summary = circuit_summary(prog, show=False)

# Print textual summary
print(summary)

# Access statistics programmatically
info = summary.info
print(f"Total nodes:    {info.node_num}")
print(f"Single gates:   {info.single_gate_num}")
print(f"Two-qubit gates: {info.double_gate_num}")
print(f"Total layers:   {info.layer_num}")
print(f"Single layers:  {info.single_gate_layer_num}")
print(f"Double layers:  {info.double_gate_layer_num}")

When show=True (the default), circuit_summary() displays a pair of pie charts showing the distribution of gate types and layer types. This is useful for quickly assessing circuit complexity and estimating execution cost on hardware.

4. Practical Examples

4.1 Drawing a Bell State Circuit

This complete example builds a Bell state circuit and demonstrates all three output formats:

python

from pyqpanda3 import core

# Build the Bell state circuit
prog = core.QProg()
prog << core.H(0)
prog << core.CNOT(0, 1)
prog << core.measure([0, 1], [0, 1])

# 1. Quick text print
print("=== Text via print() ===")
print(prog)

# 2. Text with parameters via core.draw_qprog
print("\n=== Text via draw_qprog ===")
text = core.draw_qprog(prog, p=core.PIC_TYPE.TEXT, param_show=True)
print(text)

# 3. LaTeX output
print("\n=== LaTeX ===")
latex = core.draw_qprog(prog, p=core.PIC_TYPE.LATEX)
print(latex)

# 4. Save as image
prog.draw('pic', filename='bell_state.jpg')
print("\nImage saved to bell_state.jpg")

4.2 Drawing Parameterized Circuits

Parameterized circuits are common in variational algorithms. Use param_show=True or with_gate_params=True to inspect parameter values in the circuit diagram:

python

import math
from pyqpanda3 import core

# Build a parameterized circuit
prog = core.QProg()
prog << core.H(0)
prog << core.RY(0, math.pi / 4)
prog << core.RX(1, math.pi / 3)
prog << core.CNOT(0, 1)
prog << core.RZ(0, 0.7854)
prog << core.U3(1, 0.1, 0.2, 0.3)
prog << core.measure([0, 1], [0, 1])

# Draw without parameters
print("Without parameters:")
print(prog.draw())

# Draw with parameters
print("\nWith parameters:")
print(prog.draw(with_gate_params=True))

# Save image with parameters visible
prog.draw('pic', filename='param_circuit.jpg', with_gate_params=True)

# Set global print options so parameters always show
core.set_print_options(precision=4, param_show=True)
print("\nAfter set_print_options:")
print(prog)

4.3 Drawing Large Circuits

Large circuits require careful management of line length and image dimensions. Here are techniques for handling circuits with many qubits or many gates:

python

from pyqpanda3 import core

# Build a 6-qubit GHZ-like circuit
prog = core.QProg()
prog << core.H(0)
for i in range(1, 6):
    prog << core.CNOT(i - 1, i)
prog << core.measure(list(range(6)), list(range(6)))

# Use longer line length for wide circuits
text = core.draw_qprog(prog, p=core.PIC_TYPE.TEXT, line_length=150)
print(text)

# For image output, use a larger fold value to fit more gates per row
prog.draw('pic', filename='large_circuit.jpg', fold=50, scale=0.5)

For very large circuits (20+ qubits), text output may become unwieldy. In these cases, use the LaTeX output and compile it to PDF, or use circuit_summary() to inspect statistics rather than the full diagram:

python

from pyqpanda3.visualization import circuit_summary

# Get statistics instead of full diagram
summary = circuit_summary(prog, show=True)
print(f"\nCircuit has {summary.info.node_num} gates across {summary.info.layer_num} layers")

4.4 Exporting to File

pyqpanda3 supports exporting circuit diagrams in multiple file formats for different use cases:

python

from pyqpanda3 import core

prog = core.QProg()
prog << core.H(0) << core.CNOT(0, 1) << core.measure([0, 1], [0, 1])

# Text file (useful for version control and diffs)
core.draw_qprog(prog, p=core.PIC_TYPE.TEXT, output_file="circuit.txt")

# LaTeX file (for papers and presentations)
core.draw_qprog(
    prog,
    p=core.PIC_TYPE.LATEX,
    output_file="circuit.tex",
    with_logo=True
)

# Image file (for reports and quick sharing)
prog.draw('pic', filename='circuit_diagram.png', scale=0.7)

# Alternative: use the draw() method with filename
prog.draw('text', filename='circuit_text.txt')
prog.draw('latex', filename='circuit_latex.tex')

The following table summarizes the output formats and their typical use cases:

Format	File Extension	Best For
Text	`.txt`	Debugging, terminal output, version control
LaTeX	`.tex`	Academic papers, presentations, documentation
Image	`.jpg`, `.png`	Reports, slides, quick sharing, Jupyter

4.5 Visualizing a GHZ State End-to-End

This example demonstrates a complete workflow: build a circuit, simulate it, draw the circuit diagram, and visualize the results.

python

import numpy as np
from pyqpanda3 import core
from pyqpanda3.visualization import plot_probabilities, plot_bloch_multivector, circuit_summary

# Build a 3-qubit GHZ state circuit
prog = core.QProg()
prog << core.H(0)
prog << core.CNOT(0, 1)
prog << core.CNOT(1, 2)
prog << core.measure([0, 1, 2], [0, 1, 2])

# Step 1: Draw the circuit
print("=== Circuit Diagram ===")
print(prog.draw())

# Step 2: Get circuit statistics
print("\n=== Circuit Summary ===")
summary = circuit_summary(prog, show=False)
print(f"Gates: {summary.info.node_num}, Layers: {summary.info.layer_num}")
print(f"Single-qubit gates: {summary.info.single_gate_num}")
print(f"Two-qubit gates: {summary.info.double_gate_num}")

# Step 3: Simulate
machine = core.CPUQVM()
machine.run(prog, shots=10000)

# Step 4: Visualize probabilities
counts = machine.result().get_counts()
total = sum(counts.values())
probs = {state: count / total for state, count in counts.items()}
plot_probabilities(probs, title="GHZ State Probabilities (10000 shots)")

# Step 5: Visualize the GHZ state on Bloch spheres
# (requires the state vector before measurement)
ghz_circuit = core.QCircuit()
ghz_circuit << core.H(0) << core.CNOT(0, 1) << core.CNOT(1, 2)
state = ghz_circuit.matrix()[:, 0]  # first column = |000> input
plot_bloch_multivector(state, title="GHZ State (Per-Qubit Bloch)")

For the GHZ state $| G H Z_{3} ⟩ = \frac{1}{\sqrt{2}} (| 000 ⟩ + | 111 ⟩)$ , each individual qubit is maximally mixed, so all three Bloch sphere vectors point to the origin. This is expected because tracing out any two qubits leaves the remaining one in the maximally mixed state $\frac{I}{2}$ .

4.6 Bloch Sphere Animation of a Single-Qubit Circuit

This example creates an animated Bloch sphere visualization showing how a sequence of gates transforms a single qubit:

python

import math
from pyqpanda3 import core
from pyqpanda3.visualization import plot_bloch_circuit, plot_bloch_vector

# Build a single-qubit circuit with several gates
circuit = core.QCircuit()
circuit << core.H(0)              # Move to equator (+X)
circuit << core.T(0)              # Rotate pi/4 around Z
circuit << core.RY(0, math.pi/4)  # Tilt toward +Z
circuit << core.Z(0)              # Flip phase

# Animate the circuit on the Bloch sphere
plot_bloch_circuit(
    circuit,
    trace=True,
    saveas='single_qubit_evolution.gif',
    fps=20,
    secs_per_gate=1
)

# Static visualization of specific states
from pyqpanda3.visualization import plot_bloch

# Show the |0> starting state
plot_bloch([0, 0, 1], title="Initial |0> state")

# Show the state after Hadamard (|+>)
plot_bloch([1, 0, 0], title="After H: |+> state")

# Show the state after H then T
plot_bloch([1/math.sqrt(2), 1/math.sqrt(2), 0], title="After H+T")

The animation proceeds through each gate in order, showing the state vector rotating on the sphere. The trace=True parameter leaves a colored trail so you can see the full path of the state.

5. Visualization Workflow

The following diagram illustrates the complete visualization workflow in pyqpanda3, from circuit construction to visual output:

Decision Guide

Your Goal	Recommended Function
Quick circuit inspection	`print(prog)`
Save circuit to text file	`core.draw_qprog(prog, p=core.PIC_TYPE.TEXT, output_file='out.txt')`
Circuit image for a report	`prog.draw('pic', filename='circuit.jpg')`
Circuit for a paper (LaTeX)	`prog.draw('latex', filename='circuit.tex')`
See gate parameters	`prog.draw(with_gate_params=True)` or `core.set_print_options(param_show=True)`
Inspect a single-qubit state	`plot_bloch_vector([x, y, z])`
Inspect a multi-qubit state	`plot_bloch_multivector(state_vector)`
View density matrix structure	`plot_state_city(state)` or `plot_state(state, kind='density')`
View measurement distribution	`plot_probabilities(counts_dict)`
Animate single-qubit evolution	`plot_bloch_circuit(circuit)`
Get circuit gate statistics	`circuit_summary(prog)`

6. API Quick Reference

Core Module (pyqpanda3.core)

Function / Constant	Description
`core.draw_qprog(prog, p, ...)`	Draw circuit as text or LaTeX
`core.PIC_TYPE.TEXT`	Text output format
`core.PIC_TYPE.LATEX`	LaTeX output format
`core.set_print_options(precision, param_show, linewidth)`	Configure global print settings

core.draw_qprog() Parameters

Parameter	Type	Default	Description
`prog`	`QProg` or `QCircuit`	(required)	Circuit to draw
`p`	`PIC_TYPE`	`PIC_TYPE.TEXT`	Output format
`expend_map`	`dict`	`None`	Control expansion, e.g., `{"all": 1}`
`param_show`	`bool`	`False`	Show gate parameters
`with_logo`	`bool`	`False`	Include logo (LaTeX only)
`line_length`	`int`	`100`	Max line length (text only)
`output_file`	`str`	`""`	Save to file (empty = return string)
`encode`	`str`	`"utf-8"`	Character encoding

Member Method (.draw())

Parameter	Type	Default	Description
`output`	`str`	`'text'`	`'text'`, `'pic'`, or `'latex'`
`filename`	`str`	`None`	Output file path
`scale`	`float`	`0.7`	Image scale (pic only)
`fold`	`int`	`30`	Max image width in gates (pic only)
`with_logo`	`bool`	`False`	Include logo (LaTeX only)
`with_gate_params`	`bool`	`False`	Show gate parameters
`line_length`	`int`	`100`	Max line length (text only)
`console_encode_type`	`str`	`'utf8'`	`'utf8'` or `'gbk'`

Visualization Module (pyqpanda3.visualization)

Function	Description
`plot_bloch(state, title, figsize, save)`	Unified Bloch sphere interface
`plot_bloch_vector(bloch, title, axis_obj, fig_size)`	Single Bloch vector
`plot_bloch_multivector(state, title, fig_size)`	Per-qubit Bloch spheres
`plot_bloch_circuit(circuit, trace, saveas, fps, secs_per_gate)`	Animate circuit on Bloch sphere
`plot_state(state, kind, title, figsize)`	Unified state visualization
`plot_state_city(state, title, figsize, color)`	3D density matrix bars
`plot_density_matrix(M, title, ...)`	Density matrix heatmap
`plot_probabilities(data, title, figsize, top_k, save)`	Probability bar chart
`circuit_summary(prog, show)`	Circuit statistics and pie charts

Summary

In this tutorial you learned:

Circuit drawing -- Use print(prog) for quick inspection, core.draw_qprog() for controlled output, and .draw() for an object-oriented interface. Three output formats are available: text (ASCII), image (matplotlib), and LaTeX.
Print options -- core.set_print_options() configures the precision, parameter visibility, and line width for all text-based circuit output.
Bloch sphere -- Visualize single-qubit states with plot_bloch_vector(), multi-qubit states per-qubit with plot_bloch_multivector(), and animate single-qubit circuit evolution with plot_bloch_circuit().
State visualization -- Use plot_state_city() for 3D bar plots of the density matrix, plot_density_matrix() for phase-colored heatmaps, and plot_state() as a unified interface.
Probability charts -- plot_probabilities() renders measurement outcome distributions, with optional top_k filtering for large state spaces.
Exporting -- Save diagrams as text files, LaTeX source, or JPEG/PNG images using output_file or filename parameters.

The next tutorial in the series covers Transpilation, where you will learn how to optimize circuits for specific hardware topologies and gate sets.

Visualization ​

Table of Contents ​

Overview ​

1. Circuit Drawing ​

1.1 Quick Text Output with print() ​

1.2 Drawing with core.draw_qprog() ​

Text Output ​

LaTeX Output ​

Saving to File ​

1.3 The draw() Member Method ​

1.4 Drawing as an Image (PIC) ​

1.5 LaTeX Output ​

1.6 Drawing Parameters in Detail ​

param_show / with_gate_params ​

with_logo ​

line_length ​

expend_map ​

encode ​

2. Print Options ​

Parameters ​

Usage Example ​

3. The visualization Module ​

3.1 Importing the Module ​

3.2 Bloch Sphere Visualization ​

plot_bloch_vector(bloch, title, axis_obj, fig_size) ​

plot_bloch_multivector(state, title, fig_size) ​

plot_bloch_circuit(circuit, trace, saveas, fps, secs_per_gate) ​

Unified plot_bloch() Interface ​

3.3 State City Plots ​

plot_state_city(state, title, figsize, color) ​

Unified plot_state() Interface ​

3.4 Density Matrix Visualization ​

3.5 Probability Bar Charts ​

plot_probabilities(data, title, figsize, top_k, save) ​

draw_probability() and draw_probability_dict() ​

Computing Probabilities from Simulation Results ​

3.6 Circuit Summary ​

4. Practical Examples ​

4.1 Drawing a Bell State Circuit ​

4.2 Drawing Parameterized Circuits ​

4.3 Drawing Large Circuits ​

4.4 Exporting to File ​

4.5 Visualizing a GHZ State End-to-End ​

4.6 Bloch Sphere Animation of a Single-Qubit Circuit ​

5. Visualization Workflow ​

Decision Guide ​

6. API Quick Reference ​

Core Module (pyqpanda3.core) ​

core.draw_qprog() Parameters ​

Member Method (.draw()) ​

Visualization Module (pyqpanda3.visualization) ​

Summary ​

Visualization

Table of Contents

Overview

1. Circuit Drawing

1.1 Quick Text Output with print()

1.2 Drawing with core.draw_qprog()

Text Output

LaTeX Output

Saving to File

1.3 The draw() Member Method

1.4 Drawing as an Image (PIC)

1.5 LaTeX Output

1.6 Drawing Parameters in Detail

param_show / with_gate_params

with_logo

line_length

expend_map

encode

2. Print Options

Parameters

Usage Example

3. The visualization Module

3.1 Importing the Module

3.2 Bloch Sphere Visualization

plot_bloch_vector(bloch, title, axis_obj, fig_size)

plot_bloch_multivector(state, title, fig_size)

plot_bloch_circuit(circuit, trace, saveas, fps, secs_per_gate)

Unified plot_bloch() Interface

3.3 State City Plots

plot_state_city(state, title, figsize, color)

Unified plot_state() Interface

3.4 Density Matrix Visualization

3.5 Probability Bar Charts

plot_probabilities(data, title, figsize, top_k, save)

draw_probability() and draw_probability_dict()

Computing Probabilities from Simulation Results

3.6 Circuit Summary

4. Practical Examples

4.1 Drawing a Bell State Circuit

4.2 Drawing Parameterized Circuits

4.3 Drawing Large Circuits

4.4 Exporting to File

4.5 Visualizing a GHZ State End-to-End

4.6 Bloch Sphere Animation of a Single-Qubit Circuit

5. Visualization Workflow

Decision Guide

6. API Quick Reference

Core Module (pyqpanda3.core)

core.draw_qprog() Parameters

Member Method (.draw())

Visualization Module (pyqpanda3.visualization)

Summary