pyqpanda3 入门指南

本教程将引导你安装 pyqpanda3、验证安装是否成功，并编写你的第一个量子程序。完成本教程后，你将拥有一个可用的开发环境，并对 SDK 的组织方式有扎实的理解。

什么是 pyqpanda3？

pyqpanda3 是 QPanda3（本源量子的高性能量子计算框架）的 Python SDK。它提供了一套全面的工具，用于构建量子线路(quantum circuit)、在 CPU 或 GPU 上运行模拟(simulation)、建模噪声(noise)、优化变分量子线路(variational quantum circuit)，以及通过本源量子云服务连接到真实量子硬件。

该 SDK 围绕三个核心原则设计：

表达力 -- 使用直观的 QProg API 和 << 运算符构建量子程序，实现线路的组合。
高性能 -- 底层使用 C++ 引擎，以原生速度处理态矢量(statevector)模拟、密度矩阵(density matrix)演化和线路优化。
完整性 -- 从基本门操作到变分算法、转译(transpilation)和云执行，整个量子计算工作流在一个包中完成。

pyqpanda3 能做什么？

功能	描述
量子线路构建	37+ 内置门、自定义门、动态线路
模拟	CPU、GPU、密度矩阵、稳定器、部分振幅
噪声建模	7 种错误信道(error channel)，支持逐门、逐量子比特配置
变分线路	参数化门、自动梯度计算
量子信息	态矢量、密度矩阵、信道表示
转译	拓扑感知的门分解和优化
可视化	布洛赫球、线路图、概率图
云计算	向真实量子处理器提交作业

系统要求

在安装 pyqpanda3 之前，请确保你的系统满足以下要求。

Python 版本

pyqpanda3 支持 Python 3.10 到 3.14。你可以使用以下命令检查当前的 Python 版本：

bash

python --version

输出应显示 3.10.x 到 3.14.x 范围内的版本：

Python 3.11.8

必需依赖

pyqpanda3 依赖以下 Python 包，它们会自动安装：

包	最低版本	用途
`numpy`	>= 1.20	数值数组运算
`matplotlib`	>= 3.3	绘图和可视化
`scipy`	>= 1.7	科学计算
`Cython`	>= 0.29	C 扩展编译
`networkx`	>= 2.6	图论和网络分析
`mypy`	>= 1.14.0	静态类型检查
`setuptools`	>= 60.0	包构建和分发
`graphviz`	>= 0.17	图形可视化

操作系统支持

操作系统	支持级别	额外要求
Linux (x86_64)	完全支持	GCC >= 8.5
macOS (ARM64)	完全支持	Clang >= 15.0
Windows (x86_64)	完全支持	Microsoft Visual C++ Redistributable x64（2015-2022）

硬件说明

CPU 模拟 可在任何现代处理器上运行。
GPU 模拟 (GPUQVM) 需要支持 CUDA 的 NVIDIA GPU 并安装 CUDA 工具包。这是可选的，大多数教程不需要。

安装

你可以从 PyPI 安装 pyqpanda3。

从 PyPI 安装

安装 pyqpanda3 最简单的方法是使用 pip。它会下载预构建的二进制 wheel 包，无需编译。

安装最新稳定版：

bash

pip install pyqpanda3

如果要将现有安装升级到最新版本：

bash

pip install --upgrade pyqpanda3

安装特定版本：

bash

pip install pyqpanda3==0.3.5

使用虚拟环境（推荐）

我们强烈建议在虚拟环境中安装 pyqpanda3，以避免与其他 Python 包冲突。

创建并激活虚拟环境，然后安装 pyqpanda3：

bash

python -m venv qpanda3-env
source qpanda3-env/bin/activate
pip install pyqpanda3

在 Windows 上，激活命令略有不同：

bat

python -m venv qpanda3-env
qpanda3-env\Scripts\activate
pip install pyqpanda3

安装常见问题

ImportError: No module named 'pyqpanda3'

此错误表示 pyqpanda3 未安装在当前活动的 Python 环境中。请验证你使用的是正确的环境：

bash

# 检查正在使用的 Python
which python

# 重新安装 pyqpanda3
pip install pyqpanda3

如果你使用虚拟环境，请确保已激活：

bash

source qpanda3-env/bin/activate  # Linux/macOS
qpanda3-env\Scripts\activate     # Windows

ImportError: libstdc++.so.6: version not found

这发生在 C++ 标准库过旧的旧版 Linux 系统上。更新你的编译器工具链或安装更新的 libstdc++：

bash

# Ubuntu/Debian
sudo apt-get install libstdc++6

# 检查当前版本
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX | tail -5

macOS 缺少 libidn2（符号错误）

如果在导入 pyqpanda3 时遇到与 libidn2 相关的符号错误：

bash

# 安装缺失的库
brew reinstall libidn2

# 重新安装 pyqpanda3
pip install --force-reinstall pyqpanda3

pip install 因 wheel 错误失败

预构建的 wheel 包可能不适用于所有平台和 Python 版本组合。如果 pip install 失败，请联系 qcloud@originqc.com 获取安装支持。

验证安装

安装 pyqpanda3 后，运行以下快速检查以确认一切正常。

导入 pyqpanda3 并打印版本号，验证包是否可以正常导入：

python

import pyqpanda3
print(pyqpanda3.__version__)

你应该看到安装的版本号，例如：

0.3.5

接下来，验证核心模块能正常加载且模拟器可以实例化：

python

from pyqpanda3 import core

machine = core.CPUQVM()
print("CPUQVM created successfully")

预期输出：

CPUQVM created successfully

最后，运行一个最小的单量子比特线路以确认端到端功能：

python

from pyqpanda3 import core

prog = core.QProg()
prog << core.H(0)
prog << core.measure([0], [0])

machine = core.CPUQVM()
machine.run(prog, shots=1000)

counts = machine.result().get_counts()
print(counts)

你应该看到测量计数大致在 0 和 1 之间均分：

{'0': 503, '1': 497}

如果三个检查都通过，你的安装就可以开始量子编程了。

第一个量子程序：贝尔态(Bell State)

现在 pyqpanda3 已经安装并验证完毕，让我们编写一个完整的量子程序。贝尔态（也称为 EPR 对）是量子计算中最简单也最重要的示例之一。它展示了两个基本的量子现象：叠加(superposition) 和 纠缠(entanglement)。

什么是贝尔态？

贝尔态是一种最大纠缠的两量子比特态。最常见的一个是 $| Φ^{+} ⟩$ ，定义为：

| Φ^{+} ⟩ = \frac{1}{\sqrt{2}} (| 00 ⟩ + | 11 ⟩)

这个态有一个非凡的性质：当你测量两个量子比特时，它们总是产生相同的结果。你大约一半时间得到 00，一半时间得到 11，但永远不会得到 01 或 10。这种关联不依赖于量子比特之间的物理距离，是量子隐形传态(quantum teleportation)和量子密钥分发(quantum key distribution)的基础。

第 1 步：创建量子程序

QProg（量子程序）是 pyqpanda3 中量子操作的顶层容器。可以把它想象成一张空白画布，你可以在上面添加门和测量。

创建一个空的量子程序：

python

from pyqpanda3 import core

prog = core.QProg()

此时，prog 是一个没有任何操作的空程序。我们将在后续步骤中向它添加门。

第 2 步：应用 Hadamard 门

Hadamard 门（ $H$ ）是一个单量子比特门，它创建均匀叠加(superposition)。当应用于基态 $| 0 ⟩$ 时，它产生：

H | 0 ⟩ = \frac{1}{\sqrt{2}} (| 0 ⟩ + | 1 ⟩)

这意味着量子比特 0 现在处于一个态，测量它会以概率 $\frac{1}{2}$ 得到 0，以概率 $\frac{1}{2}$ 得到 1。

对量子比特 0 应用 Hadamard 门：

python

prog << core.H(0)

<< 运算符将门追加到程序中。core.H(0) 创建一个作用于量子比特索引 0 的 Hadamard 门。

第 3 步：应用 CNOT 门

CNOT（受控非）门是一个两量子比特门。当且仅当控制量子比特(control qubit)处于 $| 1 ⟩$ 态时，它翻转目标量子比特(target qubit)。其矩阵表示为：

C N O T = (\begin{matrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ 0 & 0 & 1 & 0 \end{matrix})

当控制量子比特处于叠加态时，CNOT 门创建纠缠。在量子比特 0 上应用 Hadamard 后，以 0 为控制、1 为目标应用 CNOT，产生：

C N O T_{01} \cdot (H \otimes I) \cdot | 00 ⟩ = \frac{1}{\sqrt{2}} (| 00 ⟩ + | 11 ⟩)

这正是贝尔态 $| Φ^{+} ⟩$ 。

以量子比特 0 为控制、量子比特 1 为目标应用 CNOT 门：

python

prog << core.CNOT(0, 1)

第 4 步：添加测量

量子测量(quantum measurement)将量子比特坍缩为经典比特。在 pyqpanda3 中，measure 将量子比特映射到经典比特。第一个参数是量子比特索引列表，第二个参数是经典比特索引列表。

测量两个量子比特并将结果存储在经典比特 0 和 1 中：

python

prog << core.measure([0, 1], [0, 1])

第 5 步：在模拟器上运行

CPUQVM 是一个在 CPU 上运行的态矢量模拟器(statevector simulator)。它通过跟踪完整的 $2^{n}$ 维态矢量来模拟量子线路，其中 $n$ 是量子比特数。

创建模拟器并以 10,000 次采样(shots)运行程序：

python

machine = core.CPUQVM()
machine.run(prog, shots=10000)

shots 参数决定线路执行的次数。每次采样模拟一次完整的运行，包括测量的概率性坍缩。采样次数越多，统计精度越高。

第 6 步：获取和显示结果

运行程序后，获取测量计数(measurement counts)：

python

counts = machine.result().get_counts()
print(counts)

完整程序

以下是完整的贝尔态程序。每个部分都有注释解释其用途：

python

# 导入核心模块，它提供门、模拟器和 QProg 线路构建器
from pyqpanda3 import core

# 创建一个空的量子程序。
# QProg 是量子操作的主要容器。
prog = core.QProg()

# 对量子比特 0 应用 Hadamard 门。
# 这将量子比特 0 置于 |0> 和 |1> 的等概率叠加态。
prog << core.H(0)

# 以量子比特 0 为控制、量子比特 1 为目标应用 CNOT 门。
# 这使两个量子比特纠缠，创建贝尔态 |Phi+>。
prog << core.CNOT(0, 1)

# 测量两个量子比特并将结果存储在经典比特 0 和 1 中。
# 没有测量，模拟器无法产生输出计数。
prog << core.measure([0, 1], [0, 1])

# 创建基于 CPU 的量子虚拟机（模拟器）。
# CPUQVM 执行精确的态矢量模拟。
machine = core.CPUQVM()

# 运行程序 10,000 次。
# 每次"采样"是线路的完整执行，包括概率性测量坍缩。
machine.run(prog, shots=10000)

# 以字典形式获取测量计数。
# 键是比特串（如 "00"、"11"），值是计数。
counts = machine.result().get_counts()
print("Measurement counts:", counts)

运行此程序时，你会看到类似以下的输出：

Measurement counts: {'00': 4973, '11': 5027}

由于量子测量固有的随机性，每次运行的确切数字会略有不同，但分布应该接近 00 和 11 之间 50/50 的比例。

打印线路图

pyqpanda3 可以使用 print() 显示线路的文本表示：

python

print(prog)

这会产生一个显示门序列的文本线路图：

qubit 0: ──H──*─M─
              │  │
qubit 1: ─────X─M─

在此图中：

H 代表量子比特 0 上的 Hadamard 门
* 是 CNOT 门的控制端（在量子比特 0 上）
X 是 CNOT 门的目标端（在量子比特 1 上）
M 标记两个量子比特上的测量操作

理解输出结果

让我们更详细地分析贝尔态的结果。

统计分布

运行贝尔态程序时，你应该观察到两个现象：

只出现 00 和 11 -- 永远不会观察到 01 和 10 的结果。
计数大致相等 -- 每个结果大约出现 shots / 2 次。

这是贝尔态的直接推论：

P (00) = | ⟨ 00 | Φ^{+} ⟩ |^{2} = \frac{1}{2}

P (11) = | ⟨ 11 | Φ^{+} ⟩ |^{2} = \frac{1}{2}

P (01) = P (10) = 0

期望计数与观测计数对比

使用 10,000 次采样，期望计数为：

结果	期望计数	观测计数（示例）
`00`	5,000	4,973
`11`	5,000	5,027
`01`	0	0
`10`	0	0

与精确 5,000/5,000 的小偏差源于统计采样。大数定律保证随着采样次数增加，观测频率会收敛到真实概率：

lim_{N \to \infty} \frac{n_{00}}{N} = \frac{1}{2}

可视化分布

你可以从原始计数计算并显示概率分布：

python

# 从计数计算概率
total = sum(counts.values())
probabilities = {state: count / total for state, count in counts.items()}

print("Probabilities:")
for state, prob in sorted(probabilities.items()):
    print(f"  |{state}>: {prob:.4f}")

预期输出：

Probabilities:
  |00>: 0.4973
  |11>: 0.5027

纠缠的作用

贝尔态的关键洞见是两个量子比特是纠缠的。这意味着它们的测量结果以一种经典概率论无法解释的方式关联。

如果量子比特 0 被测量并得到 0，量子比特 1 必定也得到 0。如果量子比特 0 得到 1，量子比特 1 必定得到 1。这种完美的关联正是纠缠与单纯统计巧合的区别所在。

这可以通过检查条件概率来验证：

P (q_{1} = 0 ∣ q_{0} = 0) = 1

P (q_{1} = 1 ∣ q_{0} = 1) = 1

线路流程

下图展示了数据通过贝尔态线路的完整流程：

包架构与模块结构

现在你已经运行了第一个量子程序，让我们了解 pyqpanda3 的完整模块体系。你不需要一次学习所有模块——从 core 开始，随着需要逐步探索其他模块。

pyqpanda3 被组织成独立的模块，每个模块负责量子计算的一个特定领域：

core 模块是基础。其他每个模块要么扩展核心功能，要么消费核心模块产生的数据结构。

pyqpanda3.core -- 基础模块

core 模块是 pyqpanda3 的核心。它提供了构建和模拟量子线路所需的一切。

线路构建：

QProg -- 顶层量子程序容器
QCircuit -- 可重用的子线路（支持嵌套组合）
<< 运算符 -- 将门、线路或控制流追加到程序中

量子门（37+）：

单量子比特：H、X、Y、Z、S、T、RX、RY、RZ、P、U1、U2、U3
两量子比特：CNOT、CZ、SWAP、CRX、CRY、CRZ、CP、CU
多量子比特：TOFFOLI
每个门都支持 .dagger()（共轭转置）、.control()（受控版本）和 .matrix()（酉矩阵）

模拟器：

CPUQVM -- CPU 上的精确态矢量模拟
GPUQVM -- CUDA 加速的态矢量模拟
DensityMatrixSimulator -- 用于混合态的密度矩阵演化
Stabilizer -- 高效的 Clifford 线路模拟
PartialAmplitudeQVM -- 用于大型线路的部分态矢量计算

噪声建模：

NoiseModel -- 量子错误规范的容器
7 种错误信道：Pauli X/Y/Z、去极化(depolarizing)、相位阻尼(phase damping)、振幅阻尼(amplitude damping)、退相干(decoherence)
逐门和逐量子比特的噪声分配

动态线路：

qif / qelse -- 基于测量结果的条件执行
qwhile -- 用于重复操作的循环结构

以下示例展示了一个稍复杂的线路：

python

from pyqpanda3 import core

# 创建一个稍微复杂的线路
prog = core.QProg()

# 应用一系列门
prog << core.H(0)          # 量子比特 0 的叠加
prog << core.H(1)          # 量子比特 1 的叠加
prog << core.CNOT(0, 2)    # 纠缠量子比特 0 和 2
prog << core.CNOT(1, 3)    # 纠缠量子比特 1 和 3

# 测量所有四个量子比特
prog << core.measure([0, 1, 2, 3], [0, 1, 2, 3])

# 运行模拟
machine = core.CPUQVM()
machine.run(prog, shots=1000)

counts = machine.result().get_counts()
print("4-qubit GHZ-like counts:", counts)

pyqpanda3.hamiltonian -- 算符和哈密顿量

hamiltonian 模块提供了处理泡利算符(Pauli operator)和构造哈密顿量(Hamiltonian)的工具，这对于变分算法（如 VQE 和 QAOA）至关重要。

关键类：

PauliOperator -- 表示泡利项之和（如 $0.5 \cdot Z_{0} Z_{1} + 0.3 \cdot X_{0}$ ）
PauliTerm -- 带系数的单个泡利项
Hamiltonian -- 用于变分算法的完整哈密顿量

泡利算符支持标准算术运算：

python

from pyqpanda3.hamiltonian import PauliOperator

# 在特定量子比特上定义泡利算符
z0 = PauliOperator({"Z0": 1.0})
z1 = PauliOperator({"Z1": 1.0})
x0 = PauliOperator({"X0": 1.0})

# 用算术组合算符
h = 0.5 * z0 * z1 + 0.3 * x0
print(h)

pyqpanda3.quantum_info -- 量子态分析

quantum_info 模块提供了分析量子态和信道的类。

关键类：

StateVector -- 纯量子态(pure state)的表示和操作
DensityMatrix -- 混合态(mixed state)的表示，支持熵和纯度计算
Unitary -- 酉算符表示
量子信道表示：Kraus、Chi、Choi、SuperOp、PTM
距离度量：保真度(fidelity)、迹距离(trace distance)、KL 散度(KL divergence)

python

from pyqpanda3.quantum_info import StateVector
import numpy as np

# 创建贝尔态矢量
bell = StateVector(np.array([1, 0, 0, 1]) / np.sqrt(2))
print(f"Purity: {bell.purity()}")
print(f"Dimension: {bell.dim()}")

pyqpanda3.vqcircuit -- 变分量子线路

vqcircuit 模块支持构建参数化线路用于变分算法。它提供使用伴随微分(adjoint differentiation)的自动梯度计算。

关键类：

VQCircuit -- 参数化量子线路
Parameter -- 可训练参数
具有可配置微分方法的梯度计算

pyqpanda3.transpilation -- 线路优化

transpilation 模块负责将抽象线路转换为硬件兼容的线路。它考虑设备拓扑（哪些量子比特物理上相连）并将不支持的门分解为原生门集(native gate set)。

关键类：

Transpiler -- 考虑拓扑和门约束来转换线路

pyqpanda3.intermediate_compiler -- IR 转换

intermediate_compiler 模块提供 pyqpanda3 线路与标准中间表示之间的双向转换。

支持的格式：

OriginIR -- 本源量子的原生中间表示
QASM -- OpenQASM 2.0

python

from pyqpanda3.intermediate_compiler import convert_qprog_to_originir
from pyqpanda3 import core

prog = core.QProg()
prog << core.H(0) << core.CNOT(0, 1)

# 转换为 OriginIR 字符串
ir_string = convert_qprog_to_originir(prog)
print(ir_string)

pyqpanda3.visualization -- 绘图和图表

visualization 模块产生量子态和线路的可视化表示。

功能：

单量子比特态的布洛赫球(Bloch sphere)渲染
文本、图像和 LaTeX 格式的线路图
测量结果的概率条形图
态城市图(state city plot)和密度矩阵可视化

pyqpanda3.qcloud -- 云量子计算

qcloud 模块连接到本源量子云平台，允许你将线路提交到真实量子处理器。

关键类：

QCloudService -- 云交互的主要接口
QCloudJob -- 表示已提交的作业，支持状态跟踪

pyqpanda3.profiling -- 线路分析

profiling 模块提供分析线路复杂度、深度、门计数和性能特征的工具。

python

from pyqpanda3.profiling import draw_circuit_features
from pyqpanda3 import core

circuit = core.QCircuit(2)
circuit << core.H(0) << core.CNOT(0, 1)

# 可视化线路特征（连通性、活性、并行性、纠缠、深度）
draw_circuit_features(circuit, save_fn="circuit_features.png")

模块总览

模块	关键类/函数	角色
`pyqpanda3.core`	`QProg`、`CPUQVM`、`NoiseModel`、`H`、`CNOT`	基础：门、模拟器、线路
`pyqpanda3.hamiltonian`	`PauliOperator`、`Hamiltonian`	算符代数、期望值
`pyqpanda3.quantum_info`	`StateVector`、`DensityMatrix`	量子态分析和信道
`pyqpanda3.vqcircuit`	`VQCircuit`、`Parameter`	变分线路和梯度
`pyqpanda3.transpilation`	`Transpiler`	硬件感知的线路优化
`pyqpanda3.intermediate_compiler`	`convert_qprog_to_originir`、`convert_qasm_string_to_qprog`	IR 转换（OriginIR、QASM）
`pyqpanda3.visualization`	`plot_bloch`、`circuit_summary`	线路和态的可视化输出
`pyqpanda3.qcloud`	`QCloudService`、`QCloudJob`	云量子计算
`pyqpanda3.profiling`	`draw_circuit_profile`、`draw_circuit_features`	线路性能分析

进阶示例：GHZ 态

在继续之前，让我们构建一个稍微复杂的程序——三量子比特的 Greenberger-Horne-Zeilinger (GHZ) 态。GHZ 态将纠缠的概念扩展到两个量子比特之外：

| G H Z_{3} ⟩ = \frac{1}{\sqrt{2}} (| 000 ⟩ + | 111 ⟩)

使用 CNOT 门链创建三量子比特 GHZ 态：

python

from pyqpanda3 import core

# 构建三量子比特 GHZ 态
prog = core.QProg()

# 第 1 步：将量子比特 0 置于叠加态
prog << core.H(0)

# 第 2 步：纠缠量子比特 0 和量子比特 1
prog << core.CNOT(0, 1)

# 第 3 步：纠缠量子比特 1 和量子比特 2
# 现在三个量子比特共享相同的叠加
prog << core.CNOT(1, 2)

# 测量所有三个量子比特
prog << core.measure([0, 1, 2], [0, 1, 2])

# 运行模拟
machine = core.CPUQVM()
machine.run(prog, shots=10000)

counts = machine.result().get_counts()
print("GHZ state counts:", counts)

预期输出（大约）：

GHZ state counts: {'000': 5003, '111': 4997}

与贝尔态一样，你应该只看到 000 和 111 结果，频率大致相等。不应出现 001、010、100、011、101 或 110 等结果。

GHZ 态展示了多量子比特纠缠。扩展到更多量子比特很简单——只需在链中添加更多 CNOT 门：

这种模式可以推广：对于 $n$ 量子比特 GHZ 态，应用一个 Hadamard 门后跟 $n - 1$ 个链式 CNOT 门。

使用噪声模型

真实量子硬件是有噪声的。pyqpanda3 允许你模拟这些噪声，以了解你的线路在真实设备上的行为。以下是使用前面的贝尔态进行噪声模拟的快速预览。

对 CNOT 门应用去极化噪声模型：

python

from pyqpanda3 import core

# 构建相同的贝尔态线路
prog = core.QProg()
prog << core.H(0)
prog << core.CNOT(0, 1)
prog << core.measure([0, 1], [0, 1])

# 创建在 CNOT 门上有 1% 去极化错误的噪声模型
noise = core.NoiseModel()
noise.add_quantum_error(
    core.depolarizing_error(0.01),
    core.GateType.CNOT,
    [0, 1]
)

# 使用噪声模型运行
machine = core.CPUQVM()
machine.run(prog, shots=10000, model=noise)

counts = machine.result().get_counts()
print("Noisy Bell state counts:", counts)

加入噪声后，你将看到 01 和 10 有少量但非零的计数：

Noisy Bell state counts: {'00': 4912, '11': 4953, '01': 72, '10': 63}

噪声模型注入偶尔翻转量子比特的错误，导致之前不可能的结果（01 和 10）以小概率出现。这是对真实量子硬件行为的现实模拟。

线路组合模式

pyqpanda3 提供了几种构建线路的模式。尽早理解这些模式将帮助你编写更清晰、更可重用的代码。

使用 << 运算符链式追加

最常见的模式是使用 << 链式追加门：

python

prog = core.QProg()
prog << core.H(0) << core.CNOT(0, 1) << core.measure([0, 1], [0, 1])

渐进式构建程序

你也可以逐步构建程序，这对于条件构建很有用：

python

prog = core.QProg()
prog << core.H(0)

# 条件性地添加门
n_qubits = 3
for i in range(1, n_qubits):
    prog << core.CNOT(i - 1, i)

prog << core.measure(list(range(n_qubits)), list(range(n_qubits)))

当线路结构依赖于运行时参数时，这种模式特别有用。

打印线路信息

你可以随时通过打印来检查线路：

python

print(prog)

这会显示线路的文本图，对于调试和验证线路是否具有预期结构非常有用。

性能考虑

理解模拟的计算成本有助于你选择正确的参数。

态矢量模拟的扩展性

CPUQVM 存储 $n$ 个量子比特的完整态矢量，包含 $2^{n}$ 个复数振幅。内存使用呈指数增长：

量子比特数 ( $n$ )	态矢量大小	内存（128 字节/振幅）
10	1,024	16 KB
20	1,048,576	16 MB
25	33,554,432	512 MB
30	1,073,741,824	16 GB
32	4,294,967,296	64 GB

对于超过 25-30 个量子比特的线路，请考虑：

PartialAmplitudeQVM -- 仅计算部分振幅
Stabilizer -- 仅 Clifford 线路的高效模拟（不含 T 门）
GPUQVM -- 将计算卸载到 GPU 以获得更快的态矢量更新

采样次数权衡

更高的采样次数提供更好的统计精度，但需要更多时间。实用指南：

采样次数	使用场景
100 - 1,000	快速测试和调试
1,000 - 10,000	标准模拟
10,000 - 100,000	高精度概率估计

开发工作流

以下是使用 pyqpanda3 开发量子程序的典型工作流：

这个迭代循环——构建、运行、分析、调整——是量子程序开发的基本节奏。从简单开始，验证每一步，然后逐步增加复杂度。

下一步

恭喜你完成了 pyqpanda3 的第一个量子程序！你现在拥有一个可用的开发环境，并理解了线路构建和模拟的基础知识。

学习基础知识

如果你刚接触量子计算，继续学习以下教程：

教程	你将学到什么
量子基础	量子比特、量子门、测量和布洛赫球
线路构建	使用 QProg、QCircuit 和 `<<` 运算符的高级线路模式
模拟	所有模拟器类型及其适用场景

探索特定功能

如果你已经了解量子计算基础并想探索特定功能：

主题	教程
真实硬件模拟	噪声模拟
参数化线路和梯度	变分线路
泡利算符和期望值	哈密顿量与泡利算符
态分析和信道理论	量子信息
线路绘图和布洛赫球	可视化
硬件感知优化	转译
真实量子处理器	云计算
态编码方法	量子态制备

尝试实际示例

How-To 部分包含常见量子算法的可运行示例：

Bell State -- 深入探索贝尔态
GHZ State -- 多量子比特纠缠
Quantum Teleportation -- 传送量子态
Deutsch-Jozsa Algorithm -- 预言机问题中的量子优势
Grover's Search -- 量子搜索算法
VQE Tutorial -- 变分量子本征求解器
QAOA Tutorial -- 量子近似优化

其他资源

API 参考 -- 所有模块的完整 API 文档
概念 -- 量子门、噪声和信息的理论背景
发布说明 -- 版本更新记录

在本教程中，你学到了：

什么是 pyqpanda3 -- 一个使用 C++ 后端的 Python 量子计算 SDK，支持线路构建、模拟、噪声建模和云执行。
系统要求 -- Python 3.10-3.14 及相关依赖。
安装与排查 -- 使用 pip install pyqpanda3 安装，以及常见安装问题的解决方案。
验证 -- 三个快速检查以确认安装正常工作。
贝尔态程序 -- 一个使用 QProg、H、CNOT、measure 和 CPUQVM 的完整量子程序。
输出分析 -- 理解测量计数、概率和纠缠。
模块概览 -- 构成 pyqpanda3 的九个模块及其各自的功能。

pyqpanda3 入门指南 ​

目录 ​

什么是 pyqpanda3？ ​

pyqpanda3 能做什么？ ​

系统要求 ​

Python 版本 ​

必需依赖 ​

操作系统支持 ​

硬件说明 ​

安装 ​

从 PyPI 安装 ​

使用虚拟环境（推荐） ​

安装常见问题 ​

ImportError: No module named 'pyqpanda3' ​

ImportError: libstdc++.so.6: version not found ​

macOS 缺少 libidn2（符号错误） ​

pip install 因 wheel 错误失败 ​

验证安装 ​

第一个量子程序：贝尔态(Bell State) ​

什么是贝尔态？ ​

第 1 步：创建量子程序 ​

第 2 步：应用 Hadamard 门 ​

第 3 步：应用 CNOT 门 ​

第 4 步：添加测量 ​

第 5 步：在模拟器上运行 ​

第 6 步：获取和显示结果 ​

完整程序 ​

打印线路图 ​

理解输出结果 ​

统计分布 ​

期望计数与观测计数对比 ​

可视化分布 ​

纠缠的作用 ​

线路流程 ​

包架构与模块结构 ​

pyqpanda3.core -- 基础模块 ​

pyqpanda3.hamiltonian -- 算符和哈密顿量 ​

pyqpanda3.quantum_info -- 量子态分析 ​

pyqpanda3.vqcircuit -- 变分量子线路 ​

pyqpanda3.transpilation -- 线路优化 ​

pyqpanda3.intermediate_compiler -- IR 转换 ​

pyqpanda3.visualization -- 绘图和图表 ​

pyqpanda3.qcloud -- 云量子计算 ​

pyqpanda3.profiling -- 线路分析 ​

模块总览 ​

进阶示例：GHZ 态 ​

使用噪声模型 ​

线路组合模式 ​

使用 << 运算符链式追加 ​

渐进式构建程序 ​

打印线路信息 ​

性能考虑 ​

态矢量模拟的扩展性 ​

采样次数权衡 ​

开发工作流 ​

下一步 ​

学习基础知识 ​

探索特定功能 ​

尝试实际示例 ​

其他资源 ​

pyqpanda3 入门指南

目录

什么是 pyqpanda3？

pyqpanda3 能做什么？

系统要求

Python 版本

必需依赖

操作系统支持

硬件说明

安装

从 PyPI 安装

使用虚拟环境（推荐）

安装常见问题

ImportError: No module named 'pyqpanda3'

ImportError: libstdc++.so.6: version not found

macOS 缺少 libidn2（符号错误）

pip install 因 wheel 错误失败

验证安装

第一个量子程序：贝尔态(Bell State)

什么是贝尔态？

第 1 步：创建量子程序

第 2 步：应用 Hadamard 门

第 3 步：应用 CNOT 门

第 4 步：添加测量

第 5 步：在模拟器上运行

第 6 步：获取和显示结果

完整程序

打印线路图

理解输出结果

统计分布

期望计数与观测计数对比

可视化分布

纠缠的作用

线路流程

包架构与模块结构

pyqpanda3.core -- 基础模块

pyqpanda3.hamiltonian -- 算符和哈密顿量

pyqpanda3.quantum_info -- 量子态分析

pyqpanda3.vqcircuit -- 变分量子线路

pyqpanda3.transpilation -- 线路优化

pyqpanda3.intermediate_compiler -- IR 转换

pyqpanda3.visualization -- 绘图和图表

pyqpanda3.qcloud -- 云量子计算

pyqpanda3.profiling -- 线路分析

模块总览

进阶示例：GHZ 态

使用噪声模型

线路组合模式

使用 << 运算符链式追加

渐进式构建程序

打印线路信息

性能考虑

态矢量模拟的扩展性

采样次数权衡

开发工作流

下一步

学习基础知识

探索特定功能

尝试实际示例

其他资源