Bloch 球可视化

pyqpanda3 中 Bloch 球可视化函数的 API 参考。这些函数将单量子比特态和线路渲染为 Bloch 球上的交互式或静态图表。

plot_bloch

统一入口函数，根据输入类型自动分发到合适的 Bloch 可视化函数。

签名

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

参数

参数	类型	说明
state	array_like 或 QCircuit	待可视化的输入。长度为 3 的列表/元组分发到 plot_bloch_vector；更长的可迭代对象分发到 plot_bloch_multivector；QCircuit 或 QProg 分发到 plot_bloch_circuit。
title	str	图表标题（默认 ''）。
figsize	tuple，可选	图表尺寸（英寸，向量/态输入默认 (5, 5)；线路输入忽略此参数）。
save	str，可选	保存输出图像的文件路径（仅对线路输入有效；对于向量/态输入，请手动保存返回的图对象：fig.savefig()）。

返回值

• 可视化向量或状态时返回 matplotlib.figure.Figure。
• 可视化 QCircuit 或 QProg 时返回 None（动画显示或保存到文件）。

分发行为

输入类型	分发到
长度为 3 的 list / tuple	plot_bloch_vector
任意可迭代对象（如状态向量）	plot_bloch_multivector
QCircuit / QProg	plot_bloch_circuit

示例

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
fig = plot_bloch([0, 0, 1], title="Z State")
fig.savefig("bloch.png")

---

plot_bloch_vector

在 Bloch 球上绘制单个三元素 Bloch 向量。

签名

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

参数

参数	类型	说明
bloch	array_like	表示 Bloch 向量的三元素序列 [x, y, z]。
title	str	图表标题（默认 "bloch"）。
axis_obj	matplotlib.axes.Axes，可选	用于绘制的现有 3D 坐标轴。若为 None，则创建新图表。
fig_size	tuple，可选	图表尺寸（英寸，默认 (5, 5)）。

返回值

• 当 axis_obj 为 None 时，返回 matplotlib.figure.Figure。
• 当在已有的 axis_obj 上绘制时，返回 None。

示例

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

为多量子比特量子态的每个量子比特绘制一个 Bloch 球。每个球展示通过偏迹计算得到的该量子比特的约化 Bloch 向量。

签名

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

参数

参数	类型	说明
state	array_like	量子态向量。长度必须为 2 的幂（例如，2 个量子比特为 4，3 个量子比特为 8）。
title	str	整体图表标题（默认 ''）。
fig_size	tuple，可选	图表尺寸（英寸）。

返回值

matplotlib.figure.Figure -- 包含所有 Bloch 球子图的图表对象。

示例

import numpy as np
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(np.array([1, 0, 0, 1]) / np.sqrt(2), title="Bell State")

---

plot_bloch_circuit

在 Bloch 球上对单量子比特量子线路进行动画演示。随着每个门的施加，状态向量逐帧更新，生成平滑的旋转动画。

签名

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

返回值

None。动画会交互式显示或保存到 saveas 指定的文件。

参数

参数	类型	说明
circuit	QCircuit 或 QProg	待动画演示的单量子比特量子线路。仅支持以下门：H、X、Y、Z、RX、RY、RZ、S、S†、T、T†、U1。
trace	bool	是否显示状态向量经过的轨迹（默认 True）。
saveas	str，可选	保存动画的文件路径（如 'bloch.gif'）。若为 None，则以交互方式显示动画。
fps	int	每个门的帧数，控制动画平滑度（默认 20）。
secs_per_gate	float	每个门动画段的持续时间（秒，默认 1）。

支持的门

门	说明
H	Hadamard 门
X、Y、Z	Pauli 门
RX、RY、RZ	参数化旋转门（角度单位为弧度）
S、S†	S 门与 S 逆门
T、T†	T 门与 T 逆门
U1	单参数相位门

异常

• ImportError -- 未安装 Matplotlib 时抛出。
• RuntimeError -- 当线路为空、包含不支持的门或作用于多个量子比特时抛出。

示例

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)

---

Bloch（类）

用于以增量方式构建 Bloch 球图的底层类。通过 pyqpanda3.visualization.bloch.Bloch 访问。当需要比 plot_bloch_* 辅助函数更精细的控制时使用 -- 例如向同一个球面添加多个向量、点或带自定义样式的注释。

构造函数

Bloch(
    fig=None,
    axes=None,
    view=None,
    figsize=None,
    background=False
)

构造函数参数

参数	类型	说明
fig	matplotlib.figure.Figure，可选	用户提供的 Matplotlib 图对象。若为 None，渲染时自动创建。
axes	matplotlib.axes.Axes，可选	用户提供的 3D 坐标轴，用于 Bloch 球动画。若为 None，渲染时自动创建。
view	list，可选	方位角与仰角 [azim, elev]（默认 [-60, 30]）。
figsize	list，可选	图表尺寸（英寸） [w, h]（默认 [5, 5]）。
background	bool	若为 True，渲染默认的 3D 坐标轴背景而非裸球面（默认 False）。

部分属性（构造后可修改）

属性	默认值	说明
sphere_color	"#FFDDDD"	Bloch 球表面颜色。
sphere_alpha	0.2	球面透明度。
frame_color	"gray"	线框颜色。
frame_width	1	线框线宽。
frame_alpha	0.2	线框透明度。
font_color	matplotlib 默认	轴标签颜色。
font_size	20	轴标签字号。
xlabel / ylabel / zlabel	["$x$", ""] / ["$y$", ""] / [r"$|0\rangle$", r"$|1\rangle$"]	各轴标签对（+轴、-轴）。
xlpos / ylpos / zlpos	[1.2, -1.2]	各轴标签位置。
vector_color	["#dc267f", "#648fff", "#fe6100", "#785ef0", "#ffb000"]	绘制向量时循环使用的颜色。
vector_width	5	向量线宽。
vector_style	`"-	>"`
vector_mutation	20	箭头大小。
point_color	["b", "r", "g", "#CC6600"]	绘制点时循环使用的颜色。
point_size	[25, 32, 35, 45]	循环使用的标记大小。
point_marker	["o", "s", "d", "^"]	循环使用的标记形状。

方法

方法	签名	说明
add_vectors	add_vectors(vectors)	添加单个向量（3 元素）或向量列表。
add_points	add_points(points, meth="s")	添加点；meth 取 "s"（单色）、"m"（多色）或 "l"（连成线）。
add_annotation	add_annotation(state_or_vector, text, **kwargs)	在 3D 位置添加文本/LaTeX 注释。额外关键字参数会转发到 mpl_toolkits.mplot3d.axes3d.Axes3D.text（如 fontsize、color、horizontalalignment）。
set_label_convention	set_label_convention(convention)	应用预设标签集。可选值："original"、"xyz"、"sx sy sz"、"01"、"polarization jones"、"polarization jones letters"、"polarization stokes"。
clear	clear()	清空所有已存储的点、向量和注释。
render	render(title="")	将球面和所有数据渲染到当前图与坐标轴上。
make_sphere	make_sphere()	无标题的 render() 别名。
show	show(title="")	渲染球面并调用 pyplot.show()。
save	save(name=None, output="png", dirc=None)	渲染并保存到文件。若指定 name，将覆盖 output 和 dirc；默认保存为当前目录下的 bloch_<n>.png。

示例

from pyqpanda3.visualization.bloch import Bloch

# Build a custom Bloch sphere with two vectors and an annotation
sphere = Bloch()
sphere.add_vectors([1, 0, 0])
sphere.add_vectors([0, 0, 1])
sphere.add_annotation([0, 0, 1.2], r"$|0\rangle$")
sphere.set_label_convention("01")
sphere.save(name="two_states.png")

# Save to file
sphere2 = Bloch(view=[-30, 20], figsize=[6, 6])
sphere2.add_vectors([0, 1, 0])
sphere2.save(name="my_bloch.png")

另见

• 态可视化 -- plot_state、plot_state_city、plot_density_matrix
• 概率可视化 -- plot_probabilities
• 线路绘制 -- QCircuit.draw()、QProg.draw()