Bloch 球可视化
pyqpanda3 中 Bloch 球可视化函数的 API 参考。这些函数将单量子比特态和线路渲染为 Bloch 球上的交互式或静态图表。
plot_bloch
统一入口函数，根据输入类型自动分发到合适的 Bloch 可视化函数。
签名
python
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，可选 | 图表尺寸（英寸）。 |
| save | str，可选 | 保存输出图像的文件路径。 |
分发行为
| 输入类型 | 分发到 |
|---|---|
长度为 3 的 list / tuple | plot_bloch_vector |
| 任意可迭代对象（如状态向量） | plot_bloch_multivector |
QCircuit / QProg | plot_bloch_circuit |
示例
python
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
在 Bloch 球上绘制单个三元素 Bloch 向量。
签名
python
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。
示例
python
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 向量。
签名
python
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 球子图的图表对象。
示例
python
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
在 Bloch 球上对单量子比特量子线路进行动画演示。随着每个门的施加，状态向量逐帧更新，生成平滑的旋转动画。
签名
python
plot_bloch_circuit(
circuit,
trace=True,
saveas=None,
fps=20,
secs_per_gate=1
)参数
| 参数 | 类型 | 说明 |
|---|---|---|
| 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-- 当线路为空、包含不支持的门或作用于多个量子比特时抛出。
示例
python
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)