本地模拟 {#guide-simulation}¶

什么时候进入本页 {#guide-simulation-when-to-read}¶

当你已经有一条线路，想在本地验证结果、查看概率分布、做多次采样，或比较不同模拟后端时，进入本页。

本页解决的核心问题是：如何把已经写好的线路跑起来，并根据目标选择合适的模拟方式与后端。

本页解决的问题 {#guide-simulation-problems}¶

如何把已有线路送入模拟器
如何查看概率测量、状态向量、多次采样等不同输出
如何选择 Simulator、OpcodeSimulator 等不同模拟入口
如何根据目标选择 statevector、density matrix、density matrix_qutip 等后端
如何在本地验证时识别已知限制与风险
uniqc.simulator 与 Backend=dummy 有什么区别、该用哪个

前置条件¶

阅读本页前，默认你已经完成以下至少一项：

已经会使用 Circuit 构建基础线路
已经拿到了 originir 或 qasm 字符串
已经完成快速上手中的最小示例

如果你还不清楚如何创建线路、添加量子门或导出线路格式，建议先阅读构建量子线路。

本地模拟入口总览 {#guide-simulation-entry-overview}¶

在 UnifiedQuantum 中，“本地模拟”指的是不提交远端任务、直接在当前环境运行线路并查看结果。常见入口可以先按输入格式与验证目标来分：

本地模拟入口	输入形式	适合先看什么问题
`uniqc.simulator.Simulator`	`AnyQuantumCircuit`（`Circuit` 对象、`originir` 字符串或 `qasm` 字符串）	已经用 `uniqc.circuit_builder.Circuit` 构好线路，想先快速验证概率分布、状态向量或采样结果；也适用于 OpenQASM 2.0 输入，`Simulator` 会自动检测格式
`uniqc.simulator.OpcodeSimulator`	opcode 列表	需要更底层控制、特定后端或排查后端差异
`uniqc.simulator.NoisySimulator`	`AnyQuantumCircuit` + 噪声配置	想在本地模拟阶段加入噪声模型并观察结果变化
`MPSSimulator`（见 MPS 模拟器）	`AnyQuantumCircuit` + `MPSConfig`	比特数较多但纠缠/键维 (`χ`) 受控，`statevector` 装不下时使用
`TorchQuantumSimulator`（需要 `unified-quantum[pytorch]` 与 git 安装的 `torchquantum`）	`Circuit` / `originir`	想把模拟接入 PyTorch 计算图、做端到端可微分实验

MPSSimulator 与 TorchQuantumSimulator 也可通过统一工厂入口构造：create_simulator(backend='mps') / create_simulator(backend='torchquantum')。

如果你还在决定线路该如何表达，先回到构建量子线路；如果你已经完成本地验证，准备提交到云平台或真机执行，转到提交任务。

uniqc.simulator 与 Backend=dummy 的区别 {#guide-simulation-vs-dummy}¶

uniqc.simulator（Simulator / NoisySimulator）与 submit_task(backend='dummy:*') 都在本地用经典计算模拟量子线路，但面向不同场景。

维度	`uniqc.simulator`	`Backend=dummy`
入口方式	`Simulator().simulate_pmeasure(code)`	`submit_task(circuit, backend='dummy:*')`
工作流程	直接调用本地模拟方法	经过 submit → query → wait 任务管道（与真实后端一致）
噪声控制	通过 `NoisySimulator` + `ErrorLoader` 手动配置噪声参数	自动从 `chip_characterization` 校准数据派生噪声模型
输出类型	pmeasure / statevector / density_matrix / shots	`UnifiedResult`（与真实后端输出格式一致）
适用场景	快速调试、算法验证、查看中间态	验证编译→提交→查询的完整链路
后端选择	`statevector` / `density_matrix` / `density_matrix_qutip`	`dummy:local:simulator` 或 `dummy:<platform>:<backend>`

选择建议：

快速验证概率分布或状态向量 → 用 Simulator，可直接拿到 pmeasure、statevector 等中间结果。
验证从编译到结果获取的完整链路 → 用 submit_task(backend='dummy:*')，走与真实提交相同的管道。
需要噪声但想手动配置 → 用 NoisySimulator + ErrorLoader。
需要噪声且想模拟真实芯片特征 → 用 submit_task(backend='dummy:<platform>:<backend>')，噪声自动从 chip 校准数据派生。

Backend=dummy 的详细用法见提交任务 — Dummy 模式。

Simulator {#guide-simulation-originir}¶

最常用的模拟器，统一接受 Circuit 对象、originir 字符串或 qasm 字符串，并自动检测输入格式。无论是 OriginIR 还是 OpenQASM 2.0 线路，都可以直接使用同一个 Simulator 类。

from uniqc import Circuit
from uniqc.simulator import Simulator

circuit = Circuit()
circuit.h(0)
circuit.cnot(0, 1)
circuit.measure(0, 1)

sim = Simulator()

概率测量¶

prob = sim.simulate_pmeasure(circuit.originir)
# 返回各测量结果的概率分布

状态向量¶

sv = sim.simulate_statevector(circuit.originir)
# 返回状态向量

多次采样¶

result = sim.simulate_shots(circuit.originir, shots=1000)
# 返回 1000 次采样的统计结果

Opcode 模拟器与本地模拟后端 {#guide-simulation-opcode}¶

底层模拟器，直接操作 opcode 列表。支持多后端（每个后端都接受多种别名，便于在 CLI、Python API、文档之间互换）：

规范名 (canonical)	别名 (aliases)	说明
`statevector`	`state_vector`	状态向量（无噪声）
`density_operator`	`density_matrix`, `densitymatrix`, `densityoperator`, `density` (CLI)	密度矩阵（支持噪声）
`density_operator_qutip`	`density_matrix_qutip`	基于 QuTiP 的密度矩阵；需要 `unified-quantum[simulation]` extra（`qutip` + `qutip-qip`）

别名在 uniqc.simulator.backend_alias() 中统一解析；OpcodeSimulator、create_simulator 与 CLI uniqc simulate --backend 接受同一组别名。

from uniqc.simulator import OpcodeSimulator

sim = OpcodeSimulator(backend_type='statevector')

Opcode 的详细文档见 Opcode。

带噪声的本地模拟 {#guide-simulation-noisy}¶

from uniqc.simulator import NoisySimulator

sim = NoisySimulator(
    backend_type='density_matrix',  # 噪声模拟必须使用 density_matrix 后端
    error_loader=my_error_loader,
    readout_error={0: [0.01, 0.02], 1: [0.01, 0.02]}
)
prob = sim.simulate_pmeasure(circuit.originir)

噪声模拟必须显式指定 backend_type='density_matrix'；默认的 statevector 后端不支持噪声通道，调用 simulate_pmeasure 时会抛 ValueError。

噪声模型的详细配置见噪声模拟。

后端对比¶

后端	适用场景	噪声支持	性能
`statevector`	无噪声快速模拟，小规模线路（< 30 量子比特）	❌	最快
`density_matrix`	含噪声模拟，双比特门为主	✅	较慢（内存 O(4^n)）
`density_matrix_qutip`	复杂噪声模型，高精度需求	✅	较慢，依赖 Qutip

CLI 与 Python API 的别名一致性：CLI uniqc simulate --backend density 与 Python API 的 density_matrix / density_operator / densitymatrix / density 都是同一种密度矩阵后端的别名（在 uniqc.simulator.backend_alias() 内部归一化为 density_operator）。density_operator_qutip 与其别名 density_matrix_qutip 同理。