调试 · 量子程序怎么 debug · 写给程序员的量子计算

量子程序没法打断点、没法 print 变量，一测还坍缩——那怎么 debug？靠模拟器的「上帝视角」：随时打印中途状态向量、看概率分布、把整段线路当矩阵看、画 Bloch 球。这一章给一套可操作的量子调试工作流，并抓一个真实的 bug。

调试 · 量子程序怎么 debug

这是「写给程序员」这个专栏的立身之本。写普通程序卡壳了，你打断点、print 变量、单步跟踪。可量子程序呢？qubit 看不见摸不着，你想 print 它——一测量就坍缩，把要调的状态给毁了。那还怎么 debug？

答案是：在模拟器上调，用它的「上帝视角」。

核心工具：随时打印状态向量

模拟器和真机最大的区别，是它知道全部内幕——任何时刻的完整状态向量，它都能给你（真机给不了）。所以调试量子程序的头号手段，就是在线路的任意位置，把状态向量打印出来，和你脑子里的预期对比。

技巧很简单：想看第 k 步之后的状态，就构造「只到第 k 步」的线路，Statevector 它。（注意别加测量。）

from qiskit import QuantumCircuit
from qiskit.quantum_info import Statevector

# 想调一个「本应造出 Bell 态」的线路,一步步看
qc = QuantumCircuit(2)

qc.h(0)
print("H 之后:", Statevector(qc).probabilities_dict())
# {'00': 0.5, '01': 0.5}   ← qubit0 叠加,符合预期

qc.cx(0, 1)
print("CX 之后:", Statevector(qc).probabilities_dict())
# {'00': 0.5, '11': 0.5}   ← Bell 态,对了

probabilities_dict() 比原始振幅更好读（直接给每个基础态的测量概率）。一步步打印、一步步核对——这就是量子版的「单步调试」。

其它几件趁手的工具

工具	干什么	代码
`qc.draw()`	画出线路 ASCII 图，核对结构	`print(qc.draw())`
`Statevector(qc)`	看完整振幅（含相位）	如上
`.probabilities_dict()`	看测量概率（更好读）	如上
`Operator(qc)`	把整段线路当一个矩阵看	`print(Operator(qc).data)`
`plot_bloch_multivector`	画 Bloch 球(1~2 qubit)	需 matplotlib

Operator 是个被低估的调试利器。 当你写了一段子线路、怀疑它整体做的变换不对，别一个个门去看——直接 Operator(qc).data 把它整体的矩阵打出来，和你期望的幺正矩阵比对。比如你想实现一个 $X$ 门，却发现整段线路的矩阵不是 $\begin{bmatrix}0&1\\1&0\end{bmatrix}$ ，那就是搭错了。把一段线路「压平」成一个矩阵来看，常常一眼看穿 bug。

抓一个真实的 bug

调试讲一百遍不如抓一个虫。看这段「想造 Bell 态」却有问题的代码：

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(1, 0)      # ← bug 在这
print(Statevector(qc).probabilities_dict())
# {'00': 0.5, '01': 0.5}     ← 不对!这不是 Bell 态

预期 Bell 态应该是 {'00': 0.5, '11': 0.5}，实际却是 {'00': 0.5, '01': 0.5}——qubit 1 根本没被纠缠进来。打印状态一眼看出「结果不对」，再回头看代码：cx(1, 0) 把控制位和目标位写反了——我们想用 qubit 0（叠加的那个）当控制去翻 qubit 1，却写成了用 qubit 1（还是 $\ket0$ ）当控制。控制位是 0，CNOT 什么都不做，自然没纠缠。改成 cx(0, 1) 就对了。

量子程序最高频的几类 bug，靠「打印中途状态」几乎都能抓到： ① qubit 顺序 / 控制目标写反（如上，也呼应小端序陷阱）；② 门作用在错的 qubit 上；③ 相位错误——这个最阴险，因为相位单独测不出，probabilities_dict() 也看不出来（它只看模平方）。要抓相位 bug，得看完整的 Statevector（含正负号 / 复数），或者故意加一段干涉把相位「逼」成概率差异再测。调相位问题，一定要看振幅本身，不能只看概率。

真机上怎么办

诚实地说：上面这套「打印状态向量」的调试法，只在模拟器上成立——真正的量子计算机给不了你状态向量（测量即坍缩）。所以标准工作流是：

先在模拟器上，用状态向量调到完全正确（逻辑对了）。
再拿到真机 / 含噪模拟器上跑，这时结果会因为噪声而偏离理想（后面专讲）——这已经不是「逻辑 bug」，而是「物理误差」，是另一类问题。

换句话说：「逻辑对不对」在模拟器上调；「真机上准不准」是噪声问题，两者分开对付。先在模拟器上把逻辑锤对，是省心的前提。

小结与下一章

量子程序 debug 的核心，是借模拟器的上帝视角：想看哪一步，就构造到那一步的线路、打印 Statevector / probabilities_dict()，和预期逐步核对；Operator 把整段线路压成矩阵看；高频 bug（顺序反、控制目标反、相位错）基本都能这么抓——但相位 bug 必须看完整振幅、不能只看概率。逻辑在模拟器上调，噪声问题另算。

调对了只是「看起来对」。作为工程师，你还想要自动化的、可复现的正确性保证——给量子线路写单元测试和断言。下一章讲怎么验证。👉 验证：给量子线路写断言和测试。

参考文献

[1] Qiskit 官方文档.「Statevector / Operator / visualization.」https://docs.quantum.ibm.com/api/qiskit/quantum_info —— 调试相关 API。
[2] Qiskit 官方文档.「Visualize circuits & states.」https://docs.quantum.ibm.com/guides/visualize-circuits —— 线路与状态可视化。
[3] IBM Quantum Learning.「Debugging quantum programs.」https://learning.quantum.ibm.com —— 调试工作流。

调试 · 量子程序怎么 debug