QuantumSim V0.78 使用教程

1概述

QuantumSim 是一款纯 Rust 实现的量子电路仿真库,通过 C ABI (FFI) 对外提供服务。本发布包是 V0.78 最小化交付版,仅包含运行所需的二进制文件、Python 绑定和测试脚本,无源码、无构建工具链依赖。

2发布包文件清单 (9 个文件)

3快速开始 (3 步)

1. 放置 DLL:将 quantum_sim.dll 放在与 Python 脚本同一目录,或设置环境变量 QSIM_DLL_PATH 指向 DLL 所在目录。
2. 编写 Python 代码:from quantum_sim import QuantumSim,创建 QuantumSim(n_qubits) 实例,应用门,测量。
3. 运行:python your_script.py。DLL 加载顺序:环境变量 → 脚本同目录 → target/release → 系统 PATH。

# 最小示例: Bell 态
from quantum_sim import QuantumSim

with QuantumSim(2) as sim:        # 2 量子比特
    sim.apply_h(0)                 # H 门到 qubit 0
    sim.apply_cnot(0, 1)           # CNOT(0→1)
    result = sim.measure()         # 确定性测量
    print(f"结果: {result:#b}")    # 0b00 或 0b11
    print(f"P(q0=1) = {sim.prob_one(0):.4f}")  # 0.5000

4FFI 接口总览 (100 个导出函数)

DLL 导出 100 个 #[no_mangle] extern "C" 函数,按功能分为以下类别:

§3 StateVector 生命周期 (4 函数)

§4 StateVector 量子门 (17 函数)

§5 StateVector 测量 (6 函数)

§6 SparseStateVector (8 函数) — 1-64 量子比特

稀疏态向量后端,适用于稀疏电路 (大部分振幅为 0)。

§7 Matrix Product State (12 函数) — 1-100000 量子比特

MPS 后端,支持超大量子比特数 (10 万级),按需分解。

§8 数论加速 (3 函数)

§9 批量接口 + QASM 互通 (10 函数)

核心实战接口:一次 FFI 调用执行整个电路,消除逐门 FFI 开销。

#[repr(C)]
pub struct QsimGate {
    pub gate_type: c_int,   // QSIM_GATE_H=0, X=1, Y=2, Z=3, S=4, T=5, CNOT=6, CZ=7, Toffoli=8, SWAP=9, Rx=10, Ry=11, Rz=12, U3=13, iSWAP=14, XX=15, YY=16, CRx=17, CRy=18, CRz=19, Fredkin=20
    pub q: c_uint,          // 目标量子比特
    pub q2: c_uint,         // 控制量子比特 (CNOT/CZ/Toffoli/SWAP)
    pub q3: c_uint,         // 第二控制 (Toffoli)
    pub theta: c_double,    // 旋转角 (Rx/Ry/Rz/U3)
    pub phi: c_double,      // 相位 φ (U3)
    pub lambda: c_double,   // 相位 λ (U3)
}

§11 硬件感知 (12 函数)

§11.5 安全接口 (6 函数)

§13 Stabilizer 电路 (8 函数) — Clifford 电路,256 量子比特

Clifford 电路高效模拟器,多项式时间复杂度。

§V12.773 HybridAccelerator (6 函数) — GPU/CPU 自动切换

§V12.729 水印接口 (2 函数)

§14 License 远程验证 (4 函数)

§11.2 数论量子接口 (5 函数)

5内存释放规则 (重要)

6错误码 (16 个)

7Python 绑定用法

quantum_sim.py 是零依赖 Python 绑定 (仅用标准库 ctypes),无需 pip install 任何包。

7.1 QuantumSim 类 — 核心仿真器

from quantum_sim import QuantumSim, QuantumSimError

# 创建 4 量子比特态向量
sim = QuantumSim(4)

try:
    # 应用门
    sim.apply_h(0)              # Hadamard
    sim.apply_x(1)              # Pauli-X
    sim.apply_cnot(0, 2)        # CNOT(0→2)
    sim.apply_toffoli(0, 1, 3)  # Toffoli(0,1→3)

    # 查询
    print(f"qubits = {sim.n_qubits}")   # 4
    print(f"dim    = {sim.dim}")         # 16

    # 测量
    result = sim.measure()       # 确定性测量 (最大概率态)
    p0 = sim.prob_one(0)         # qubit 0 为 |1⟩ 的概率

    # 振幅
    amp = sim.amplitude(0)       # Cplx(re, im)
    print(f"|00...0⟩ = {amp.re} + {amp.im}i")
    print(f"|amp|² = {amp.abs_squared}")

    # 归一化
    sim.normalize()

except QuantumSimError as e:
    print(f"错误 [{e.code}]: {e.msg}")

finally:
    sim.close()  # 必须释放

# 推荐用 with 语句 (自动释放)
with QuantumSim(2) as sim:
    result = sim.bell_state()  # 便捷: Bell 态
    # sim 自动释放

with QuantumSim(5) as sim:
    result = sim.ghz_state()   # 便捷: GHZ 态

7.2 QuantumCircuit 类 — 链式电路构建器

from quantum_sim import QuantumSim, QuantumCircuit

# 链式 API 构建电路
circuit = (QuantumCircuit(3)
    .h(0)                 # H(0)
    .cnot(0, 1)           # CNOT(0→1)
    .cnot(1, 2)           # CNOT(1→2)
    .x(2)                 # X(2)
)

# 在 QuantumSim 上执行
with QuantumSim(3) as sim:
    result = circuit.run(sim)
    print(f"结果: {result:#b}")

7.3 VQEChemistry 类 — 量子化学 (Python 侧实现)

from quantum_sim import VQEChemistry

# 支持的分子: H2, LiH, H2O, N2
vqe = VQEChemistry(molecule="H2")
bench = vqe.benchmark()
print(f"H2 基态能量: {bench['estimated_energy_Ha']:.4f} Ha")
print(f"精确能量:   {bench['exact_energy_Ha']:.4f} Ha")
print(f"误差:       {bench['error_mHa']:.2f} mHa")
print(f"耗时:       {bench['runtime_ms']:.1f} ms")

7.4 Cplx 结构

from quantum_sim import Cplx

amp = sim.amplitude(3)
print(amp)              # Cplx(0.707107 + 0.000000i)
print(amp.re, amp.im)   # 0.707107 0.0
print(amp.abs_squared)  # 0.5

8benchmark.py — 基准测试套件

9 节性能基准测试,覆盖单/双比特门、电路吞吐、Bell 态、Grover 算法、测量、振幅、算法验证。

8.1 命令行用法

# 全部测试 (默认 200 次重复)
python benchmark.py

# 快速模式 (50 次重复)
python benchmark.py --quick

# 指定测试 (逗号分隔)
python benchmark.py --only 1,3,5

# 导出 JSON 报告
python benchmark.py --json report.json

# 跳过算法验证 (只测性能)
python benchmark.py --no-verify

8.2 测试节列表

9circuit_test.py — 电路测试套件

30 个内置电路测试 + JSON 外部导入,覆盖 10 个类别。

9.1 命令行用法

# 全部测试 (30 个)
python circuit_test.py

# 列出所有测试用例
python circuit_test.py --list

# 按类别过滤 (逗号分隔)
python circuit_test.py --only bell,ghz

# 导入外部 JSON 电路
python circuit_test.py --import my_circuit.json

# 导出 JSON 报告
python circuit_test.py --json report.json

# 安静模式 (只打印失败)
python circuit_test.py --quiet

9.2 测试类别 (10 类, 30 个用例)

9.3 JSON 电路导入格式

支持两种顶层结构:数组或对象。门类型支持 7 种:H/X/Z/S/T/CNOT/Toffoli。

// 格式 1: 数组 (直接是门列表)
[
  {"gate": "H", "q": 0},
  {"gate": "CNOT", "q": 0, "q2": 1},
  {"gate": "X", "q": 2}
]

// 格式 2: 对象 (含元数据)
{
  "name": "Bell 态",
  "n_qubits": 2,
  "gates": [
    {"gate": "H", "q": 0},
    {"gate": "CNOT", "q": 0, "q2": 1}
  ],
  "expected": "00|11"
}

10C/C++ 对接示例

C/C++ 用户通过 quantum_sim.dll.lib 导入库链接,或用 LoadLibrary 动态加载。

// C 示例: Bell 态
#include <windows.h>
#include <stdio.h>

typedef void* QsimHandle;
typedef int (*qsim_state_new_t)(unsigned int);
typedef int (*qsim_state_apply_h_t)(void*, unsigned int);
typedef int (*qsim_state_apply_cnot_t)(void*, unsigned int, unsigned int);
typedef unsigned long long (*qsim_state_measure_t)(void*);
typedef void (*qsim_state_free_t)(void*);

int main() {
    HMODULE dll = LoadLibraryA("quantum_sim.dll");

    qsim_state_new_t  state_new  = (qsim_state_new_t)GetProcAddress(dll, "qsim_state_new");
    qsim_state_apply_h_t apply_h = (qsim_state_apply_h_t)GetProcAddress(dll, "qsim_state_apply_h");
    qsim_state_apply_cnot_t cnot = (qsim_state_apply_cnot_t)GetProcAddress(dll, "qsim_state_apply_cnot");
    qsim_state_measure_t meas   = (qsim_state_measure_t)GetProcAddress(dll, "qsim_state_measure");
    qsim_state_free_t  free_fn  = (qsim_state_free_t)GetProcAddress(dll, "qsim_state_free");

    QsimHandle h = state_new(2);
    apply_h(h, 0);
    cnot(h, 0, 1);
    unsigned long long result = meas(h);
    printf("结果: %llu\n", result);
    free_fn(h);

    FreeLibrary(dll);
    return 0;
}

# 编译 (MSVC)
cl /Fe:bell.exe bell.c /link quantum_sim.dll.lib

# 编译 (MinGW)
gcc -o bell.exe bell.c -L. -lquantum_sim

11支持的功能

12注意事项

13FAQ

14声明

QuantumSim V0.78.0 — HappyFace Quantum Simulator — 学习教学版