模拟器 -- CPUQVM, GPUQVM, DensityMatrixSimulator, Stabilizer, PartialAmplitudeQVM

pyqpanda3 中量子线路模拟器的 API 参考。

概述

pyqpanda3 提供五个模拟器后端用于执行量子程序：

模拟器	状态表示	噪声支持	适用场景
CPUQVM	态矢量	是	通用模拟
DensityMatrixSimulator	密度矩阵	是	混合态、部分迹、噪声分析
PartialAmplitudeQVM	态矢量（部分）	否	仅需特定振幅的大规模线路
Stabilizer	稳定器（Clifford）	是	大规模 Clifford 线路，高效采样
GPUQVM	态矢量（GPU）	是	使用 CUDA 的高性能模拟

---

CPUQVM

基于 CPU 的态矢量量子模拟器。这是通用量子线路模拟的主要模拟器。它存储量子系统的完整态矢量，并支持通过 NoiseModel 进行含噪声模拟。

签名

class CPUQVM:
    def __init__() -> None
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> QResult

CPUQVM.init

CPUQVM() -> None

使用默认参数构造新的 CPUQVM 实例。

参数

无。

返回

一个新的 CPUQVM 实例。

CPUQVM.run

CPUQVM.run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None

执行量子程序指定次数（shots）并将结果存储在内部。每次 shot 重新初始化状态并运行完整线路。如果程序中包含测量操作，结果将在所有 shot 中聚合。

参数

参数	类型	说明
prog	QProg	要执行的量子程序。
shots	int	重复执行的次数。测量结果在所有 shot 中聚合。
model	NoiseModel	执行期间应用的噪声模型。默认为理想（无噪声）模型。

返回

无。结果存储在内部，通过 result() 获取。

CPUQVM.result

CPUQVM.result() -> QResult

获取最近一次 run() 调用的结果。

参数

无。

返回

包含测量计数、态矢量和概率数据的 QResult 对象。

示例

运行 Bell 态线路并获取测量计数：

from pyqpanda3.core import CPUQVM, QProg, H, CNOT, measure

# 构建 Bell 态程序
prog = QProg()
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)

# 在 CPU 模拟器上运行
qvm = CPUQVM()
qvm.run(prog, shots=1000)
res = qvm.result()

# 打印测量计数
counts = res.get_counts()
print(counts)
# 示例输出: {'00': 503, '11': 497}

运行线路后获取态矢量：

from pyqpanda3.core import CPUQVM, QProg, H, CNOT

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

qvm = CPUQVM()
qvm.run(prog, shots=1)
res = qvm.result()

state = res.get_state_vector()
print(state)
# [0.707+0j, 0+0j, 0+0j, 0.707+0j]

使用去极化噪声模型运行：

from pyqpanda3.core import (
    CPUQVM, QProg, H, CNOT, measure,
    NoiseModel, depolarizing_error, GateType
)

prog = QProg()
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)

noise = NoiseModel()
noise.add_all_qubit_quantum_error(depolarizing_error(0.01), [GateType.CNOT])

qvm = CPUQVM()
qvm.run(prog, shots=1000, model=noise)
res = qvm.result()
print(res.get_counts())

expval_hamiltonian

计算哈密顿量的期望值。

已弃用: 推荐使用模块级函数 expval_hamiltonian()。

expval_hamiltonian(prog: QProg, hamiltonian: Hamiltonian, shots: int = 1000, noise_model: NoiseModel = NoiseModel()) -> float

expval_pauli_operator

计算 Pauli 算符的期望值。

已弃用: 推荐使用模块级函数 expval_pauli_operator()。

expval_pauli_operator(prog: QProg, pauli_operator: PauliOperator, shots: int = 1000, noise_model: NoiseModel = NoiseModel()) -> float

另见

• QResult -- 包含计数、态矢量和概率的结果对象
• NoiseModel -- 噪声模型配置
• QProg -- 量子程序构建
• expval_hamiltonian -- 哈密顿量期望值全局函数

---

DensityMatrixSimulator

基于密度矩阵的量子模拟器。与态矢量模拟器不同，此后端将量子态表示为密度矩阵，支持混合态、含噪声演化和部分迹计算。它原生支持所有噪声模型操作。

签名

class DensityMatrixSimulator:
    def __init__() -> None
    def run(prog: QProg, model: NoiseModel = NoiseModel()) -> None
    def state_prob(index: int) -> float
    def state_prob(index: str) -> float
    def state_probs() -> list[float]
    def state_probs(qubits: list[int]) -> list[float]
    def state_probs(bin_indices: list[str]) -> list[float]
    def density_matrix() -> matrixXcd
    def reduced_density_matrix(qubits: list[int]) -> matrixXcd

DensityMatrixSimulator.init

DensityMatrixSimulator() -> None

构造新的 DensityMatrixSimulator 实例。

参数

无。

返回

一个新的 DensityMatrixSimulator 实例。

DensityMatrixSimulator.run

DensityMatrixSimulator.run(prog: QProg, model: NoiseModel = NoiseModel()) -> None

使用可选噪声模型执行量子程序，相应地演化密度矩阵。

参数

参数	类型	说明
prog	QProg	要执行的量子程序。
model	NoiseModel	执行期间应用的噪声模型。默认为理想（无噪声）模型。

返回

无。密度矩阵在内部更新。

DensityMatrixSimulator.state_prob（按索引）

DensityMatrixSimulator.state_prob(index: int) -> float

返回给定整数索引处的计算基态概率。

参数

参数	类型	说明
index	int	计算基态的整数索引。

返回

指定状态的概率（float）。

DensityMatrixSimulator.state_prob（按二进制字符串）

DensityMatrixSimulator.state_prob(index: str) -> float

返回由给定二进制字符串标识的计算基态的概率。

参数

参数	类型	说明
index	str	基态的二进制字符串表示（例如 "01"）。

返回

指定状态的概率（float）。

DensityMatrixSimulator.state_probs（所有状态）

DensityMatrixSimulator.state_probs() -> list[float]

返回所有可能计算基态的概率。

参数

无。

返回

每个计算基态的概率列表。

DensityMatrixSimulator.state_probs（指定量子比特）

DensityMatrixSimulator.state_probs(qubits: list[int]) -> list[float]

返回指定量子比特子集的边际概率分布。

参数

参数	类型	说明
qubits	list[int]	要计算概率的量子比特索引。

返回

指定量子比特的概率列表。

DensityMatrixSimulator.state_probs（按二进制字符串）

DensityMatrixSimulator.state_probs(bin_indices: list[str]) -> list[float]

返回由二进制字符串列表指定的状态的概率。

参数

参数	类型	说明
bin_indices	list[str]	基态的二进制字符串表示列表。

返回

与给定状态对应的概率列表。

DensityMatrixSimulator.density_matrix

DensityMatrixSimulator.density_matrix() -> matrixXcd

返回当前量子态的完整密度矩阵。

参数

无。

返回

表示密度矩阵的复值矩阵（matrixXcd）。

DensityMatrixSimulator.reduced_density_matrix

DensityMatrixSimulator.reduced_density_matrix(qubits: list[int]) -> matrixXcd

返回通过对不在指定列表中的所有量子比特求迹获得的约化密度矩阵。

参数

参数	类型	说明
qubits	list[int]	要保留的量子比特索引。所有其他量子比特被求迹。

返回

表示指定量子比特的约化密度矩阵的复值矩阵（matrixXcd）。

示例

计算 Bell 态的密度矩阵并对一个量子比特求迹：

from pyqpanda3.core import DensityMatrixSimulator, QProg, H, CNOT

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

sim = DensityMatrixSimulator()
sim.run(prog)

# 完整密度矩阵
rho = sim.density_matrix()
print(rho)

# 量子比特 0 的约化密度矩阵（对量子比特 1 求迹）
rho_0 = sim.reduced_density_matrix([0])
print(rho_0)
# 期望值：最大混合态 [[0.5, 0], [0, 0.5]]

# 状态 |00> 的概率
p_00 = sim.state_prob(0)
print(f"P(|00>) = {p_00}")

# 通过二进制字符串获取概率
p_11 = sim.state_prob("11")
print(f"P(|11>) = {p_11}")

# 所有状态概率
probs = sim.state_probs()
print(probs)
# [0.5, 0.0, 0.0, 0.5]

使用振幅阻尼噪声模拟：

from pyqpanda3.core import (
    DensityMatrixSimulator, QProg, H, GateType,
    NoiseModel, amplitude_damping_error
)

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

noise = NoiseModel()
noise.add_all_qubit_quantum_error(amplitude_damping_error(0.1), GateType.H)

sim = DensityMatrixSimulator()
sim.run(prog, model=noise)

rho = sim.density_matrix()
print(rho)

另见

• CPUQVM -- 态矢量模拟器
• NoiseModel -- 噪声模型配置
• QProg -- 量子程序构建

---

PartialAmplitudeQVM

部分振幅模拟器。此后端专为大规模量子线路设计，由于内存限制，计算完整态矢量是不可行的。它不返回完整态矢量，而是计算由二进制字符串指定的特定计算基态的振幅。

签名

class PartialAmplitudeQVM:
    def __init__() -> None
    def run(prog: QProg) -> None
    def get_state_vector(amplitudes: list[str]) -> list[complex]

PartialAmplitudeQVM.init

PartialAmplitudeQVM() -> None

构造新的 PartialAmplitudeQVM 实例。

参数

无。

返回

一个新的 PartialAmplitudeQVM 实例。

PartialAmplitudeQVM.run

PartialAmplitudeQVM.run(prog: QProg) -> None

执行量子程序并准备模拟器进行部分振幅查询。注意：此模拟器不接受 shots 参数——它执行单次态矢量演化。

参数

参数	类型	说明
prog	QProg	要执行的量子程序。

返回

无。

PartialAmplitudeQVM.get_state_vector

PartialAmplitudeQVM.get_state_vector(amplitudes: list[str]) -> list[complex]

获取指定计算基态的复数振幅。

参数

参数	类型	说明
amplitudes	list[str]	二进制字符串列表，每个指定一个计算基态（例如 ["00", "11"]）。

返回

复数列表，每个是对应基态的振幅。

示例

从 Bell 态获取特定振幅：

from pyqpanda3.core import PartialAmplitudeQVM, QProg, H, CNOT

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

qvm = PartialAmplitudeQVM()
qvm.run(prog)

# 获取 |00> 和 |11> 的振幅
amps = qvm.get_state_vector(["00", "11"])
print(amps)
# [(0.707+0j), (0.707+0j)]

# 获取 |01> 的振幅
amp_01 = qvm.get_state_vector(["01"])
print(amp_01)
# [0j]

另见

• CPUQVM -- 完整态矢量模拟器
• QProg -- 量子程序构建

---

Stabilizer

基于 Clifford 群表示的稳定器模拟器。此模拟器高效地模拟仅由 Clifford 门（H、S、CNOT 和测量）组成的线路。它不存储完整态矢量，而是维护一个稳定器表，允许以多项式内存模拟大量量子比特。

签名

class Stabilizer:
    def __init__() -> None
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> StabilizerResult

Stabilizer.init

Stabilizer() -> None

构造新的 Stabilizer 模拟器实例。

参数

无。

返回

一个新的 Stabilizer 实例。

Stabilizer.run

Stabilizer.run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None

使用稳定器形式执行量子程序，进行指定次数的测量 shot。线路必须由 Clifford 门（H、S、CNOT、X、Y、Z、SWAP 和测量）组成。不支持非 Clifford 门（如 T 门）。

噪声模型支持仅限于 Clifford 兼容的噪声信道（比特翻转、相位翻转、比特相位翻转、相位阻尼、去极化）。

参数

参数	类型	说明
prog	QProg	要执行的量子程序。必须仅包含 Clifford 门和测量。
shots	int	测量重复次数。
model	NoiseModel	可选噪声模型（仅限 Clifford 兼容）。默认为理想模型。

返回

无。结果存储在内部，通过 result() 获取。

Stabilizer.result

Stabilizer.result() -> StabilizerResult

获取最近一次 run() 调用的结果。StabilizerResult 对象提供对测量计数和状态信息的访问。

参数

无。

返回

包含测量结果的 StabilizerResult 对象（QResult 的子类）。

示例

使用稳定器模拟器运行 Clifford 线路：

from pyqpanda3.core import Stabilizer, QProg, H, CNOT, measure

prog = QProg()
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)

sim = Stabilizer()
sim.run(prog, shots=1000)
res = sim.result()

counts = res.get_counts()
print(counts)
# 示例输出: {'00': 501, '11': 499}

另见

• CPUQVM -- 通用态矢量模拟器
• QResult -- 基础结果类
• StabilizerResult -- Stabilizer 专用结果类

---

GPUQVM

GPU 加速的态矢量模拟器。此后端使用 CUDA 在 NVIDIA GPU 上加速量子线路模拟。它提供与 CPUQVM 相同的接口，但利用 GPU 并行性在多量子比特线路上实现更快的执行。

可用性：此模拟器需要 pyqpanda3 使用 CUDA 支持编译（USE_CUDA 标志）。标准 CPU 版本不包含此功能。

签名

class GPUQVM:
    def __init__() -> None
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> QResult

GPUQVM.init

GPUQVM() -> None

构造新的 GPUQVM 实例。编译时需要 CUDA 支持。

参数

无。

返回

一个新的 GPUQVM 实例。

GPUQVM.run

GPUQVM.run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None

在 GPU 上执行量子程序指定次数的 shot。

参数

参数	类型	说明
prog	QProg	要执行的量子程序。
shots	int	重复执行的次数。
model	NoiseModel	执行期间应用的噪声模型。默认为理想模型。

返回

无。结果存储在内部，通过 result() 获取。

GPUQVM.result

GPUQVM.result() -> QResult

获取最近一次 run() 调用的结果。

参数

无。

返回

包含测量计数、态矢量和概率数据的 QResult 对象。

示例

在 GPU 模拟器上运行线路：

from pyqpanda3.core import GPUQVM, QProg, H, CNOT, measure

prog = QProg()
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)

qvm = GPUQVM()
qvm.run(prog, shots=1000)
res = qvm.result()

counts = res.get_counts()
print(counts)

另见

• CPUQVM -- 基于 CPU 的态矢量模拟器
• QResult -- 结果对象
• NoiseModel -- 噪声模型配置

---

QResult

由 CPUQVM.result() 和 GPUQVM.result() 返回的结果对象。包含测量结果、态矢量数据和概率分布。

签名

class QResult:
    def get_state_vector() -> list[complex]
    def get_counts() -> dict[str, int]
    def get_prob_list(qubits: list[int] = []) -> list[float]
    def get_prob_dict(qubits: list[int] = []) -> dict[str, float]
    def shots() -> int
    def print_results() -> None

QResult.get_state_vector

QResult.get_state_vector() -> list[complex]

返回最后一次 shot 执行后的量子系统态矢量。

返回

表示量子态矢量的复数列表。

QResult.get_counts

QResult.get_counts() -> dict[str, int]

返回聚合的测量结果，以比特串结果到其频率计数的字典形式。

返回

键为比特串（例如 "00"、"11"），值为观察到该结果的次数的字典。

QResult.get_prob_list

QResult.get_prob_list(qubits: list[int] = []) -> list[float]

返回指定量子比特（如果未指定则为所有量子比特）的概率分布列表。

参数

参数	类型	说明
qubits	list[int]	可选量子比特索引列表。如果为空，返回所有量子比特的概率。

返回

概率列表。

QResult.get_prob_dict

QResult.get_prob_dict(qubits: list[int] = []) -> dict[str, float]

返回指定量子比特的概率分布，以比特串到概率的字典形式。

参数

参数	类型	说明
qubits	list[int]	可选量子比特索引列表。如果为空，返回所有量子比特的概率。

返回

将比特串映射到其概率的字典。

QResult.shots

QResult.shots() -> int

返回执行的测量 shot 总数。

返回

以整数表示的 shot 数。

QResult.print_results

QResult.print_results() -> None

以 比特串: 计数 格式打印测量结果，每行一个。

另见

• CPUQVM -- 从 result() 返回 QResult
• GPUQVM -- 从 result() 返回 QResult
• StabilizerResult -- Stabilizer 结果的子类

---

StabilizerResult

由 Stabilizer.result() 返回的结果对象。扩展了 QResult，增加了额外的稳定器专用数据。

签名

class StabilizerResult(QResult):
    def get_state_vector() -> list[complex]
    def get_counts() -> dict[str, int]
    def get_prob_list(qubits: list[int] = []) -> list[float]
    def get_prob_dict(qubits: list[int] = []) -> dict[str, float]
    def shots() -> int
    def print_results() -> None

完整方法文档参见 QResult。

另见

• Stabilizer -- 产生此结果的模拟器
• QResult -- 基类