电路可视化

电路绘制、统计和汇总函数的 API 参考。提供量子电路的文本、图像和 LaTeX 输出，以及门/层分布分析。

circuit_summary

生成量子电路的统计摘要，包括按类别分类的门计数和层计数。

签名

circuit_summary(prog, show: bool = True) -> CircuitSummary

参数

参数	类型	说明
prog	QProg 或 QCircuit	要分析的量子电路
show	bool	是否立即显示饼图可视化（默认 True）

返回值

CircuitSummary -- 包含电路统计信息和可视化方法的对象。

示例

from pyqpanda3 import core as pq
from pyqpanda3.visualization import circuit_summary

q = pq.Qubit(0)
prog = pq.QProg()
prog << pq.H(q) << pq.CNOT(q, pq.Qubit(1))

summary = circuit_summary(prog, show=False)
print(summary)
print(f"Total gates: {summary.info.node_num}")
print(f"Total layers: {summary.info.layer_num}")

运行结果：

ProgInfo(single_gate_num=1, double_gate_num=1, multi_control_gate_num=0, node_num=2, single_gate_layer_num=1, double_gate_layer_num=1, layer_num=2)
Total gates: 2
Total layers: 2

CircuitSummary

由 circuit_summary 返回的电路统计信息容器。包含一个 ProgInfo 数据类并提供显示方法。

签名

class CircuitSummary

属性

属性	类型	说明
info	ProgInfo	包含门和层统计数据的数据类

ProgInfo 字段

字段	类型	说明
single_gate_num	int	单量子比特门的数量
double_gate_num	int	双量子比特门的数量
multi_control_gate_num	int	多控制门的数量
node_num	int	门节点的总数
single_gate_layer_num	int	单门层的数量
double_gate_layer_num	int	双门层的数量
layer_num	int	层的总数

方法

show()

显示门和层分布的饼图。

summary.show()

__str__()

返回 ProgInfo 数据类的字符串表示形式，显示按类别分类的门和层计数。

print(summary)

show_prog_info_count

显示量子电路中门节点和层分布的饼图。

签名

show_prog_info_count(prog) -> None

参数

参数	类型	说明
prog	QProg 或 QCircuit	要分析的量子电路

说明

使用 matplotlib 渲染两个饼图：

• 上方图表 -- 节点分布：单门节点、双门节点、多控制门节点、其他节点
• 下方图表 -- 层分布：单门层、双门层、其他层

示例

from pyqpanda3 import core as pq
from pyqpanda3.visualization import show_prog_info_count

q = pq.Qubit(0)
prog = pq.QProg()
prog << pq.H(q) << pq.CNOT(q, pq.Qubit(1))

show_prog_info_count(prog)

运行结果：

显示两个饼图：上方图表显示节点分布（单门节点、双门节点、多控制门节点、其他节点），下方图表显示层分布（单门层、双门层、其他层）。

draw（QProg / QCircuit 方法）

以文本、图像或 LaTeX 格式绘制量子电路。在导入时注入到 QProg 和 QCircuit 上。

签名

prog.draw(output='text', filename=None, scale=0.7, fold=30,
          with_logo=False, with_gate_params=False, line_length=100,
          NodeIter_first=None, NodeIter_second=None,
          console_encode_type='utf8') -> str | None

参数

参数	类型	默认值	说明
output	str	'text'	输出格式：'text'（ASCII）、'pic'（matplotlib 图像）或 'latex'
filename	str 或 None	None	输出文件路径。对于 'pic' 默认为 QCircuit_pic.jpg。对于 'latex' 默认为 QCircuit_latex.tex。对于 'text'，如果指定则将文本保存到文件
scale	float	0.7	图像缩放因子（仅用于 'pic' 输出）
fold	int	30	以门为单位的图像最大宽度（仅用于 'pic' 输出）
with_logo	bool	False	是否包含 logo（仅用于 'latex' 输出）
with_gate_params	bool	False	是否显示门参数
line_length	int	100	'text' 输出的行长度
NodeIter_first	迭代器或 None	None	部分绘制的电路起始位置
NodeIter_second	迭代器或 None	None	部分绘制的电路结束位置
console_encode_type	str	'utf8'	'text' 输出的控制台编码类型。支持的值：'utf8'、'gbk'

返回值

• 'text' 和 'latex' -- 返回 str
• 'pic' -- 返回 None（图像保存到文件）

示例

from pyqpanda3 import core as pq

q = pq.Qubit(0)
prog = pq.QProg()
prog << pq.H(q) << pq.CNOT(q, pq.Qubit(1))

# ASCII text output
text = prog.draw()
print(text)

# Save to image file
prog.draw('pic', filename='my_circuit.png')

# LaTeX source
latex = prog.draw('latex')
print(latex)

# Show gate parameters in text output
prog.draw('text', with_gate_params=True)

文本输出（可能因控制台编码略有不同）：

          ┌─┐        
q_0:  |0>─┤H├ ───*── 
          └─┘ ┌──┬──┐ 
q_1:  |0>──── ┤CNOT├ 
              └──┴──┘ 
 c :   / ═══════════

LaTeX 输出：

\documentclass[border=2px]{standalone}
\usepackage[braket, qm]{qcircuit}
\usepackage{graphicx}
\begin{document}

\scalebox{1.0}{
\Qcircuit @C = 1.0em @R = 0.5em @!R { \\
\nghost{} & \lstick{\ket{q_0}} & \gate{\mathrm{H}} & \ctrl{1} & \rstick{}\qw & \nghost{} \\
\nghost{} & \lstick{\ket{q_1}} & \qw & \targ\qw & \rstick{}\qw & \nghost{} \\
}}
\end{document}

另见

• 可视化概述 -- 完整的可视化模块概述
• QGate -- 量子门 API 参考