Qiskit TwoLocal调用draw('mpl')打印量子电路显示异常

问题场景 #

基于VQE算法开展量子计算开发过程中，调用Qiskit内置的TwoLocal方法构建量子电路，执行ry.draw('mpl')代码打印电路时，无法输出正常的量子电路图示，生成的图像排版错乱、电路结构无法清晰辨识。

解决方法 #

按优先级依次排查以下常见诱因，对应操作即可修复：

• 依赖版本不兼容（最高发原因）
  绝大多数该类渲染故障都是qiskit相关包和matplotlib版本不匹配导致，旧版qiskit的绘图逻辑没有适配matplotlib 3.8及以上版本的接口变更，会直接造成元件位置计算错误、排版重叠。
  直接在终端执行以下命令重装兼容版本组合即可：

  pip uninstall -y qiskit qiskit-terra matplotlib
  pip install qiskit==0.45.0 matplotlib==3.7.3
  

  重装完成后必须重启当前Python运行内核（如果用Jupyter需要重启kernel，脚本运行则重新启动解释器），再重新执行绘图代码。
• 绘图参数设置不合理
  如果电路比特数多、迭代层数深，默认绘图参数会自动折叠电路行，容易造成元件堆叠错位。可以手动指定绘图参数关闭折叠、调整渲染缩放比例：

  ry.draw('mpl', fold=-1, scale=0.7)
  

  其中fold=-1表示关闭电路自动换行折叠，scale参数可以根据自己的电路规模在0.6-1.0区间调整，保证所有门元件、连线不重叠即可。
• matplotlib字体缓存异常
  部分本地环境会因为字体缓存损坏，导致Qiskit绘图依赖的特殊符号无法正常加载，出现标签错位、乱码挤占元件位置的问题。执行以下代码强制刷新matplotlib字体缓存后再绘图即可：

  import matplotlib
  matplotlib.font_manager._load_fontmanager(try_read_cache=False)
  

修复后可以先用最小测试用例验证渲染是否正常，避免跑完整业务代码浪费时间：

from qiskit.circuit.library import TwoLocal
test_circ = TwoLocal(2, "ry", "cz", reps=1)
test_circ.draw("mpl")

内容的提问来源于stack exchange，提问作者user48217