模拟器 -- CPUQVM, GPUQVM, DensityMatrixSimulator, Stabilizer, PartialAmplitudeQVM, SingleAmplitudeQVM, MPSQVM, SparseHeisenbergSimulator

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

概述

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

模拟器	状态表示	噪声支持	适用场景
CPUQVM	态矢量	是	通用模拟
DensityMatrixSimulator	密度矩阵	是	混合态、部分迹、噪声分析
PartialAmplitudeQVM	态矢量（部分）	否	仅需特定振幅的大规模线路
SingleAmplitudeQVM	张量网络	否	大规模线路中查询单个振幅
Stabilizer	稳定器（Clifford）	是	大规模 Clifford 线路，高效采样
MPSQVM	矩阵乘积态	是	弱纠缠的大规模线路
SparseHeisenbergSimulator	海森堡绘景（稀疏）	否	快速计算泡利哈密顿量期望值（非采样、无态矢量）
GPUQVM	态矢量（GPU）	是	使用 CUDA 的高性能模拟

---

CPUQVM

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

签名

class CPUQVM:
    def __init__(precision: str = "float64") -> None
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> QResult
    def init_state(state: numpy.ndarray[complex128]) -> None    # 无参调用恢复 |0...0>
    def current_state() -> numpy.ndarray                        # 原生精度状态（0.5.0）
    def expval_hamiltonian(prog: QProg, hamiltonian: Hamiltonian, shots: int = 1000, noise_model: NoiseModel = NoiseModel()) -> float  # deprecated
    def expval_pauli_operator(prog: QProg, pauli_operator: PauliOperator, shots: int = 1000, noise_model: NoiseModel = NoiseModel()) -> float  # deprecated

CPUQVM.init

CPUQVM(precision: str = "float64") -> None

构造新的 CPUQVM 实例。

参数

参数	类型	说明
precision	str	算术精度："float32" 或 "float64"（默认）。构造后不可变，可通过 precision 属性读回；非法值抛出 InvalidPrecisionError/UnsupportedPrecisionError（ValueError 子类）。

返回

一个新的 CPUQVM 实例。完整的精度家族、能力注册表与 SIMD 诊断见精度与能力。

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

# Build a Bell state program
prog = QProg()
prog << H(0) << CNOT(0, 1)
prog << measure(0, 0) << measure(1, 1)

# Run on the CPU simulator
qvm = CPUQVM()
qvm.run(prog, shots=1000)
res = qvm.result()

# Print measurement counts
counts = res.get_counts()
print(counts)
# Example output: {'00': 503, '11': 497}

运行结果：

{'00': 504, '11': 496}

运行线路后获取态矢量：

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]

运行结果：

[(0.7071067811865476+0j), 0j, 0j, (0.7071067811865476+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())

运行结果：

{'11': 487, '10': 11, '00': 497, '01': 5}

CPUQVM.init_state

CPUQVM.init_state(state: numpy.ndarray[complex128]) -> None

设置模拟器的初始量子态。模拟器会在每次 run()（以及每次 evolve()）调用之前重置为该初始态。无参调用可恢复默认的 |0...0> 初始态。

参数

参数	类型	说明
state	numpy.ndarray[complex128]	初始态矢量，包含 2^n 个复振幅。也接受 Python list 或 complex128/complex64/float64 的 NumPy 数组。省略时恢复默认 `

异常

• 若状态长度不是 2 的幂、未归一化或包含 NaN/Inf，抛出 RuntimeError。
• 若输入不是一维数组（如二维数组），抛出 ValueError。
• 若状态只有一个振幅（长度为 1），抛出 RuntimeError。

示例

import numpy as np
from pyqpanda3.core import CPUQVM, QProg, measure

qvm = CPUQVM()
qvm.init_state([1 / np.sqrt(2), 0, 0, 1 / np.sqrt(2)])

prog = QProg() << measure([0, 1], [0, 1])
qvm.run(prog, 1000)
print(qvm.result().get_counts())

qvm.init_state()  # 恢复默认 |0...0>
qvm.run(prog, 1000)
print(qvm.result().get_counts())

运行结果：

{'00': 524, '11': 476}
{'00': 1000}

CPUQVM.current_state

CPUQVM.current_state() -> numpy.ndarray

以模拟器原生精度的 NumPy 数组返回最近一次 init_state(...) 装入的状态：precision="float32" 时为 complex64，"float64" 时为 complex128。与 result().get_state_vector() 不同，不发生任何 dtype 转换。0.5.0 新增。

run() 不会填充该缓冲区：在调用 init_state(...) 之前，返回的是空数组（长度为 0，dtype 正确）。若要读取 run() 产生的状态，请使用 result().get_state_vector()。

import numpy as np
from pyqpanda3.core import CPUQVM, H, CNOT, QProg

qvm = CPUQVM(precision="float32")
qvm.run(QProg() << H(0) << CNOT(0, 1), 100)
print("before init_state:", len(qvm.current_state()))

qvm.init_state(np.array([0.5, 0.5, 0.5, 0.5], dtype=np.complex64))
print("after init_state:", qvm.current_state().dtype, qvm.current_state().shape)
print("via result():", len(qvm.result().get_state_vector()))

运行结果：

before init_state: 0
after init_state: complex64 (4,)
via result(): 4

参数

无。

返回

形状为 (2^n,) 的 numpy.ndarray。

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__(precision: str = "float64") -> 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() -> numpy.ndarray[complex128]
    def density_matrix_native() -> numpy.ndarray    # 原生 dtype（0.5.0）
    def reduced_density_matrix(qubits: list[int]) -> numpy.ndarray[complex128]

DensityMatrixSimulator.init

DensityMatrixSimulator(precision: str = "float64") -> None

构造新的 DensityMatrixSimulator 实例。

参数

参数	类型	说明
precision	str	算术精度："float32" 或 "float64"（默认）。构造后不可变。

返回

一个新的 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() -> numpy.ndarray[complex128]

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

参数

无。

返回

表示密度矩阵的复值 NumPy 数组（numpy.ndarray，dtype 为 complex128）。

DensityMatrixSimulator.density_matrix_native

DensityMatrixSimulator.density_matrix_native() -> numpy.ndarray

以模拟器原生 dtype（float32 对应 complex64，float64 对应 complex128）的 NumPy 数组返回密度矩阵；density_matrix() 恒返回 complex128。0.5.0 新增。

返回

形状为 (2^n, 2^n) 的 numpy.ndarray。

DensityMatrixSimulator.reduced_density_matrix

DensityMatrixSimulator.reduced_density_matrix(qubits: list[int]) -> numpy.ndarray[complex128]

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

参数

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

返回

表示指定量子比特的约化密度矩阵的复值 NumPy 数组（numpy.ndarray，dtype 为 complex128）。

示例

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

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

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

sim = DensityMatrixSimulator()
sim.run(prog)

# Full density matrix
rho = sim.density_matrix()
print(rho)

# Reduced density matrix for qubit 0 (trace out qubit 1)
rho_0 = sim.reduced_density_matrix([0])
print(rho_0)
# Expected: maximally mixed state [[0.5, 0], [0, 0.5]]

# Probability of state |00>
p_00 = sim.state_prob(0)
print(f"P(|00>) = {p_00}")

# Probability via binary string
p_11 = sim.state_prob("11")
print(f"P(|11>) = {p_11}")

# All state probabilities
probs = sim.state_probs()
print(probs)
# [0.5, 0.0, 0.0, 0.5]

运行结果：

[[0.5+0.j 0. +0.j 0. +0.j 0.5+0.j]
 [0. +0.j 0. +0.j 0. +0.j 0. +0.j]
 [0. +0.j 0. +0.j 0. +0.j 0. +0.j]
 [0.5+0.j 0. +0.j 0. +0.j 0.5+0.j]]
[[0.5+0.j 0. +0.j]
 [0. +0.j 0.5+0.j]]
P(|00>) = 0.5000000000000001
P(|11>) = 0.5000000000000001
[0.5000000000000001, 0.0, 0.0, 0.5000000000000001]

使用振幅阻尼噪声模拟：

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)

运行结果：

[[0.55      +0.j 0.47434165+0.j]
 [0.47434165+0.j 0.45      +0.j]]

另见

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

---

PartialAmplitudeQVM

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

签名

class PartialAmplitudeQVM:
    def __init__(precision: str = "float64") -> None
    def run(prog: QProg) -> None
    def get_state_vector(amplitudes: list[str]) -> numpy.ndarray

PartialAmplitudeQVM.init

PartialAmplitudeQVM(precision: str = "float64") -> 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"]）。

返回

以模拟器原生 dtype（float32 对应 complex64，float64 对应 complex128）的 NumPy 数组返回对应基态的振幅；自 0.5.0 起返回 NumPy 数组而非 Python 列表。

示例

从单量子比特叠加态获取特定振幅：

from pyqpanda3.core import PartialAmplitudeQVM, QProg, H

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

qvm = PartialAmplitudeQVM()
qvm.run(prog)

# Get amplitudes for specific basis states
amp_00 = qvm.get_state_vector(["00"])
amp_01 = qvm.get_state_vector(["01"])
print(f"|00>: {amp_00}")
print(f"|01>: {amp_01}")

运行结果：

|00>: [(0.7071067811865476+0j)]
|01>: [(0.7071067811865476+0j)]

另见

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

---

SingleAmplitudeQVM

单振幅模拟器。此后端基于张量网络，能够在不存储完整态矢量的情况下高效计算指定计算基态的振幅。它特别适合大规模量子线路中只需要查询少数几个振幅的场景。

签名

class SingleAmplitudeQVM:
    def __init__(precision: str = "float64") -> None
    def run(prog: QProg, max_rank: int = 30) -> None
    def pmeasure_bin_index(index: str) -> complex
    def pmeasure_dec_index(index: str) -> complex
    def PMeasure_bin_index(index: str) -> complex
    def PMeasure_dec_index(index: str) -> complex
    def stats() -> SingleAmplitudeStats                  #（0.5.0）

SingleAmplitudeQVM.init

SingleAmplitudeQVM(precision: str = "float64") -> None

构造新的 SingleAmplitudeQVM 实例。

参数

无。

返回

一个新的 SingleAmplitudeQVM 实例。

SingleAmplitudeQVM.run

SingleAmplitudeQVM.run(prog: QProg, max_rank: int = 30) -> None

使用张量网络方法执行量子程序。此模拟器不存储完整态矢量，而是构建内部张量网络表示，供后续振幅查询使用。

参数

参数	类型	说明
prog	QProg	要执行的量子程序。
max_rank	int	局部张量收缩时允许的最大张量秩。默认值 30 适用于大多数线路；更大的线路可能需要调高此值。

返回

无。模拟器状态在内部更新。

SingleAmplitudeQVM.pmeasure_bin_index

SingleAmplitudeQVM.pmeasure_bin_index(index: str) -> complex

按二进制基态索引返回单个振幅。

参数

参数	类型	说明
index	str	二进制基态索引字符串，长度必须与量子比特数匹配（例如 "0101"）。

返回

所选计算基态的复数振幅。

异常

• 如果 index 包含无效字符（非 0/1），抛出 RuntimeError。
• 如果 index 长度与程序量子比特数不匹配，抛出 RuntimeError。

SingleAmplitudeQVM.pmeasure_dec_index

SingleAmplitudeQVM.pmeasure_dec_index(index: str) -> complex

按十进制基态索引返回单个振幅。

参数

参数	类型	说明
index	str	十进制基态索引字符串（例如 "0"、"3"）。

返回

所选计算基态的复数振幅。

异常

• 如果 index 超出态空间维度，抛出 RuntimeError。

SingleAmplitudeQVM.PMeasure_bin_index / PMeasure_dec_index

这两个方法是 pmeasure_bin_index 和 pmeasure_dec_index 的 CamelCase 别名，功能完全等同。

SingleAmplitudeQVM.stats

SingleAmplitudeQVM.stats() -> SingleAmplitudeStats

返回只读记录，描述最近一次运行的振幅求值工作区行为：cache_hit_count、cache_miss_count 与 peak_workspace_bytes。0.5.0 新增。

示例

对 Bell 态查询特定振幅：

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

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

qvm = SingleAmplitudeQVM()
qvm.run(prog)

# 查询 |00> 和 |11> 振幅
amp_00 = qvm.pmeasure_bin_index("00")
amp_11 = qvm.pmeasure_bin_index("11")
amp_01 = qvm.pmeasure_bin_index("01")

print(f"|00> = {amp_00}")
print(f"|11> = {amp_11}")
print(f"|01> = {amp_01}")

运行结果：

|00> = (0.7071067811865476+0j)
|11> = (0.7071067811865476+0j)
|01> = 0j

大线路中使用十进制索引查询：

from pyqpanda3.core import SingleAmplitudeQVM, QProg, H, X

prog = QProg()
prog << H(0) << X(1) << H(2)

qvm = SingleAmplitudeQVM()
qvm.run(prog)

# |010> 的十进制索引为 2
amp = qvm.pmeasure_dec_index("2")
print(f"|010> = {amp}")

运行结果：

|010> = (0.5+0j)

另见

• PartialAmplitudeQVM -- 功能相似的批量振幅查询模拟器
• CPUQVM -- 完整态矢量模拟器
• QProg -- 量子程序构建

---

MPSQVM

矩阵乘积态（Matrix Product State）量子模拟器。MPSQVM 用 MPS 后端运行量子程序，对纠缠较弱的线路在比特数较大时仍能保持较低内存占用。运行后通过 result() 取测量结果。

说明：MPSQVM 的 C++ init_state 未在 Python 绑定中暴露（0.4.1），Python 侧请使用 CPUQVM.init_state。

签名

class MPSQVM:
    def __init__(precision: str = "float64", truncation_atol: float | None = None, max_bond_dimension: int | None = None) -> None
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> QResult
    def stats() -> MPSRunStats
    def current_state() -> numpy.ndarray

MPSQVM.init

MPSQVM(precision: str = "float64", truncation_atol: float | None = None, max_bond_dimension: int | None = None) -> None

构造新的 MPSQVM 实例。0.5.0 新增：精度关键字、截断控制、stats() 与 current_state()。

参数	类型	说明
precision	str	"float32" 或 "float64"（默认）。
truncation_atol	float 或 None	每次 SVD 后低于该权重的奇异值被丢弃。默认依精度而定：float32 为 1e-6，float64 为 1e-12。
max_bond_dimension	int 或 None	截断后保留键维的硬上限。None 表示仅按容差驱动截断。

MPSQVM.stats

MPSQVM.stats() -> MPSRunStats

返回只读记录，说明 SVD 截断的实际行为：discarded_weight（截断至今丢弃的总概率权重）与 max_bond_dimension_seen（至今物化过的最大键维）。

MPSQVM.current_state

MPSQVM.current_state() -> numpy.ndarray

以模拟器原生精度（"float32" 为 complex64，"float64" 为 complex128）返回 run() 之后的态矢量为稠密矢量。与镜像 init_state(...) 的 CPUQVM.current_state() 不同，此方法由 run() 填充。量子比特数很大时，建议改用 result() 获取测量结果。

MPSQVM.run

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

在 MPS 后端上运行量子程序。

参数	类型	说明
prog	QProg	需要运行的量子程序。
shots	int	采样次数。
model	NoiseModel	可选的噪声模型，默认为无噪声。

MPSQVM.result

MPSQVM.result() -> QResult

返回上次 run() 的测量结果。返回的 QResult 方法与 CPUQVM 一致。

示例

from pyqpanda3.core import H, MPSQVM, QProg, measure

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

qvm = MPSQVM()
qvm.run(prog, 1000)
result = qvm.result()

print(type(result).__name__)
print(sum(result.get_counts().values()) == 1000)

运行结果：

QResult
True

另见

• CPUQVM -- 通用态矢量模拟器，QResult 方法参考
• QProg -- 量子程序构建

---

SparseHeisenbergSimulator

稀疏海森堡绘景期望模拟器。SparseHeisenbergSimulator 用稀疏海森堡绘景算法计算泡利哈密顿量的期望值。它不是基于采样的 QVM，也不返回态矢量；适合门集受支持、初态为直积态时快速估算 <H>。

工作流程：构造模拟器 -> 设置直积初态 -> 添加可观测量（或哈密顿量）-> evolve_backward(prog) 反向演化线路 -> expectation() 取期望值。

签名

class SparseHeisenbergSimulator:
    def __init__(num_qubits: int, max_terms: object = None, truncation_norm: str = "none", atol: float = 1e-14, precision: str = "float64")
    def set_initial_product_state(state: list[tuple[complex, complex]]) -> None
    def clear_observable() -> None
    def add_observable(pauli: str, coeff: complex = 1+0j) -> None
    def set_hamiltonian(hamiltonian: Hamiltonian) -> None
    def set_pauli_operator(pauli_operator: PauliOperator) -> None
    def evolve_backward(prog: QProg) -> None          # 或 evolve_backward(circuit: QCircuit)
    def apply_gate(gate: QGate) -> None
    def expectation() -> float
    def stats() -> SparseHeisenbergStats

SparseHeisenbergSimulator.init

SparseHeisenbergSimulator(
    num_qubits: int,
    max_terms: object = None,
    truncation_norm: str = "none",
    atol: float = 1e-14,
    precision: str = "float64",
) -> None

参数	类型	说明
num_qubits	int	量子比特数。
max_terms	int 或 None	算符项数上限；None 表示不限制。
truncation_norm	str	截断范数，"none" 表示不截断，"l1" 表示按 L1 范数截断。
atol	float	截断时判断系数是否为零的绝对容差。
precision	str	算术精度："float32" 或 "float64"（默认）。0.5.0 新增。
atol	float	构造后亦可以只读属性读回（0.5.0 新增）。

set_initial_product_state

SparseHeisenbergSimulator.set_initial_product_state(state: list[tuple[complex, complex]]) -> None

设置直积初态，每个量子比特用 (alpha, beta) 表示其单比特态矢量（alpha 为 |0> 振幅，beta 为 |1> 振幅）。

参数	类型	说明
state	list[tuple[complex, complex]]	每个量子比特的单比特态矢量列表，长度等于比特数。

add_observable / set_hamiltonian / set_pauli_operator / clear_observable

SparseHeisenbergSimulator.add_observable(pauli: str, coeff: complex = 1+0j) -> None
SparseHeisenbergSimulator.set_hamiltonian(hamiltonian: Hamiltonian) -> None
SparseHeisenbergSimulator.set_pauli_operator(pauli_operator: PauliOperator) -> None
SparseHeisenbergSimulator.clear_observable() -> None

• add_observable(pauli, coeff)：累加一个泡利串可观测量（如 "ZZ"、"X0 Z1"）及其系数。
• set_hamiltonian(hamiltonian) / set_pauli_operator(pauli_operator)：整体替换可观测量的哈密顿量表示。
• clear_observable()：清空当前可观测量的所有项。

evolve_backward / apply_gate

SparseHeisenbergSimulator.evolve_backward(prog: QProg) -> None    # 重载 1
SparseHeisenbergSimulator.evolve_backward(circuit: QCircuit) -> None   # 重载 2
SparseHeisenbergSimulator.apply_gate(gate: QGate) -> None

反向演化线路，把可观测量变换到与初态同绘景。evolve_backward 接受完整程序或量子线路；apply_gate 逐门施加演化。

expectation / stats

SparseHeisenbergSimulator.expectation() -> float
SparseHeisenbergSimulator.stats() -> SparseHeisenbergStats

expectation() 返回当前可观测量在（演化后的）初态上的期望值 <H>。stats() 返回截断统计信息 SparseHeisenbergStats：

字段	类型	说明
active_terms	int	截断后保留的有效算符项数。
truncated_terms	int	被截断的算符项数。
truncated_l1	float	被截断项系数的 L1 范数之和。
coefficient_l1	float	全部（截断前）算符项系数的 L1 范数之和。

自由函数 sparse_heisenberg_expectation

sparse_heisenberg_expectation(
    prog: QProg,
    hamiltonian: Hamiltonian,
    initial_product_state: list[tuple[complex, complex]] = [],
    max_terms: object = None,
    truncation_norm: str = "none",
) -> float

一步完成上述流程：构造模拟器、设置初态、设置哈密顿量、反向演化并返回期望值。等价于显式调用各方法的简写。

示例

from pyqpanda3.core import QProg, CZ, SparseHeisenbergSimulator, sparse_heisenberg_expectation
from pyqpanda3.hamiltonian import Hamiltonian

zero = (1 + 0j, 0 + 0j)  # 每个比特的 (|0> 振幅, |1> 振幅)

prog = QProg() << CZ(0, 1)  # |00> 不变

sim = SparseHeisenbergSimulator(num_qubits=2)
sim.set_initial_product_state([zero, zero])
sim.add_observable("ZZ", 1.0)
sim.evolve_backward(prog)
print(round(sim.expectation(), 6))

# 自由函数等价写法
ham = Hamiltonian({"Z0 Z1": 1.0})
print(round(sparse_heisenberg_expectation(prog, ham, initial_product_state=[zero, zero]), 6))

运行结果：

1.0
1.0

<ZZ> 在 |00> 上的期望值为 1.0（两个比特都确定为本征态 +1），与解析值一致。

另见

• Hamiltonian -- 哈密顿量构造
• QProg -- 量子程序构建

---

Stabilizer

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

签名

class Stabilizer:
    # precision -> "exact"，supported_precisions -> ("exact",)，均只读（0.5.0）
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> StabilizerResult

Stabilizer.init

Stabilizer() -> None

构造新的 Stabilizer 模拟器实例。稳定子形式化是精确的：precision 恒为 "exact"，supported_precisions 为 ("exact",)；请求算术精度会抛出 UnsupportedPrecisionError（0.5.0 新增）。

参数

无。

返回

一个新的 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)
# Example output: {'00': 501, '11': 499}

运行结果：

{'00': 504, '11': 496}

另见

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

---

GPUQVM

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

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

签名

class GPUQVM:
    def __init__(precision: str = "float64") -> None
    def init_state(state: list[complex]) -> None
    def run(prog: QProg, shots: int, model: NoiseModel = NoiseModel()) -> None
    def result() -> QResult

GPUQVM.init

GPUQVM(precision: str = "float64") -> None

以给定算术精度构造 GPU 模拟器，支持 "float32" 与 "float64"（默认 "float64"）。GPUQVM 只在 USE_CUDA 构建中绑定；无 CUDA 构建中 pyqpanda3.core.GPUQVM 为 None（导入时发出 ImportWarning），不能构造。用 simulator_capabilities("GPUQVM").available 判断。

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

参数

无。

返回

一个新的 GPUQVM 实例。

GPUQVM.init_state

GPUQVM.init_state(state: list[complex]) -> None

设置后续 run() 使用的初态。init_state([]) 恢复默认 |0...0>；GPUQVM 没有无参重载。

• 长度必须是 2 的幂；空列表之外的尺寸小于 2、NaN/Inf、范数不为 1 都会抛出 RuntimeError（与 CPUQVM 共用同一套校验）。
• 需要在无 CUDA 构建上判断可用性时，使用 simulator_capabilities("GPUQVM").available。

示例（需 CUDA 构建，未本机执行）：

from pyqpanda3.core import GPUQVM, QProg, measure

qvm = GPUQVM()
qvm.init_state([0, 1])          # |1>
prog = QProg(1)
prog << measure(0, 0)
qvm.run(prog, 16)
print(qvm.result().get_counts())  # {'1': 16}

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 CPUQVM, QProg, H, CNOT, measure

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

# Use CPUQVM (GPUQVM requires CUDA compilation)
qvm = CPUQVM()
qvm.run(prog, shots=1000)
res = qvm.result()

counts = res.get_counts()
print(counts)

运行结果：

{'00': 504, '11': 496}

另见

• 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 -- 基类