Bloch Sphere Visualization

API reference for Bloch sphere visualization functions in pyqpanda3. These functions render single-qubit states and circuits as interactive or static plots on the Bloch sphere.

plot_bloch

Unified entry point that automatically dispatches to the appropriate Bloch visualization function based on the input type.

Signature

plot_bloch(
    state,
    title: str = '',
    figsize: Optional[tuple] = None,
    save: Optional[str] = None
)

Parameters

Parameter	Type	Description
state	array_like or QCircuit	Input to visualize. A 3-element list/tuple dispatches to plot_bloch_vector; a longer iterable dispatches to plot_bloch_multivector; a QCircuit or QProg dispatches to plot_bloch_circuit.
title	str	Plot title (default '').
figsize	tuple, optional	Figure size in inches.
save	str, optional	File path to save the output image.

Dispatch Behavior

Input Type	Dispatches To
list / tuple of length 3	plot_bloch_vector
Any iterable (e.g., state vector)	plot_bloch_multivector
QCircuit / QProg	plot_bloch_circuit

Examples

from pyqpanda3.visualization import plot_bloch

# Single Bloch vector (|+> state on X axis)
plot_bloch([1, 0, 0], title="X State")

# Multi-qubit state vector
plot_bloch([1, 0, 0, 0], title="Bell-like State")

# Save to file
plot_bloch([0, 0, 1], title="Z State", save="bloch.png")

---

plot_bloch_vector

Plot a single 3-element Bloch vector on a Bloch sphere.

Signature

plot_bloch_vector(
    bloch,
    title="bloch",
    axis_obj=None,
    fig_size=None
)

Parameters

Parameter	Type	Description
bloch	array_like	A 3-element sequence [x, y, z] representing the Bloch vector.
title	str	Plot title (default "bloch").
axis_obj	matplotlib.axes.Axes, optional	An existing 3D axes to draw on. If None, a new figure is created.
fig_size	tuple, optional	Figure size in inches (default (5, 5)).

Returns

• matplotlib.figure.Figure when axis_obj is None.
• None when drawing onto an existing axis_obj.

Examples

from pyqpanda3.visualization import plot_bloch_vector

# |0> state (north pole)
plot_bloch_vector([0, 0, 1], title="|0> State")

# |+> state (positive X axis)
plot_bloch_vector([1, 0, 0], title="|+> State")

# |+i> state (positive Y axis)
plot_bloch_vector([0, 1, 0], title="|+i> State")

---

plot_bloch_multivector

Plot one Bloch sphere per qubit for a multi-qubit quantum state. Each sphere shows the reduced Bloch vector for that qubit computed via the partial trace.

Signature

plot_bloch_multivector(
    state,
    title='',
    fig_size=None
)

Parameters

Parameter	Type	Description
state	array_like	Quantum state vector. Length must be a power of 2 (e.g., 4 for 2 qubits, 8 for 3 qubits).
title	str	Overall figure title (default '').
fig_size	tuple, optional	Figure size in inches.

Returns

matplotlib.figure.Figure -- the figure containing all Bloch sphere subplots.

Examples

from pyqpanda3.visualization import plot_bloch_multivector

# Two-qubit state: both qubits in |+> (equal superposition)
plot_bloch_multivector([0.5, 0.5, 0.5, 0.5], title="Two Qubits in |+>")

# Single qubit in |0> state
plot_bloch_multivector([1, 0], title="Single Qubit |0>")

# Bell state |00> + |11> (each qubit reduced state is maximally mixed)
plot_bloch_multivector([1, 0, 0, 1] / 1.414, title="Bell State")

---

plot_bloch_circuit

Animate a single-qubit quantum circuit on a Bloch sphere. The state vector is updated frame-by-frame as each gate is applied, producing a smooth rotation animation.

Signature

plot_bloch_circuit(
    circuit,
    trace=True,
    saveas=None,
    fps=20,
    secs_per_gate=1
)

Parameters

Parameter	Type	Description
circuit	QCircuit or QProg	Single-qubit quantum circuit to animate. Only supports gates: H, X, Y, Z, RX, RY, RZ, S, S†, T, T†, U1.
trace	bool	Whether to display the path traced by the state vector (default True).
saveas	str, optional	File path to save the animation (e.g., 'bloch.gif'). If None, the animation is displayed interactively.
fps	int	Frames per gate, controlling animation smoothness (default 20).
secs_per_gate	float	Duration in seconds for each gate's animation segment (default 1).

Supported Gates

Gate	Notes
H	Hadamard
X, Y, Z	Pauli gates
RX, RY, RZ	Parameterized rotations (angle in radians)
S, S†	Phase and inverse phase
T, T†	T gate and inverse T gate
U1	Single-parameter phase gate

Raises

• ImportError -- if Matplotlib is not installed.
• RuntimeError -- if the circuit is empty, contains unsupported gates, or acts on more than one qubit.

Examples

from pyqpanda3.core import QProg, H, RX, Qubit
from pyqpanda3.visualization import plot_bloch_circuit

# Simple Hadamard circuit
q = Qubit(0)
prog = QProg()
prog << H(q)

# Display interactive animation
plot_bloch_circuit(prog)

# Save animation to file
plot_bloch_circuit(prog, saveas="hadamard.gif", fps=30)

# Rotation circuit with trace
prog2 = QProg()
prog2 << RX(q, 3.14159) << H(q)
plot_bloch_circuit(prog2, trace=True, secs_per_gate=2)

See Also

• State Visualization -- plot_state, plot_state_city, plot_density_matrix
• Probability Visualization -- plot_probabilities
• Circuit Drawing -- QCircuit.draw(), QProg.draw()