# SDK & API 文档

通过标准 C FFI 接口，将量子仿真能力集成到您的应用中。支持 Python / C/C++ / C# / Go / Rust 等多种编程语言。

C ABI 128+ 接口 零依赖 Windows x64
01 · Overview

## 概览

QuantumSim DLL 提供了一套完整的量子电路仿真 C FFI 接口，第三方开发者可以通过任何支持 C 调用约定的语言直接调用。 DLL 内部采用 Rust 原生实现，支持状态向量、稀疏态、MPS 张量网络三种仿真模式，兼容 OpenQASM 2.0/3.0 标准。

⚡

#### 高性能

Rust 原生实现，SIMD 向量化，GPU wgpu 加速，最高支持 28 量子比特。

🔌

#### 多后端

状态向量 / 稀疏态 / MPS 张量网络 / 混合模式，自动选择最优仿真策略。

📦

#### 零依赖

纯 DLL 部署，无需运行时，无需安装，复制即用。

🔐

#### 安全可靠

内置完整性校验、反调试保护、内存 DRM，30 天免费试用。

02 · Installation

## 安装部署

### 系统要求

项目 | 最低要求 | 推荐配置
--- | --- | ---
操作系统 | Windows 10 x64 | Windows 11 x64
内存 | 4 GB RAM | 16 GB RAM
GPU (可选) | 支持 DirectX 12 | NVIDIA RTX 2060+
磁盘 | 50 MB | 200 MB

### 部署方式

1

#### 下载 SDK 包

从 下载页面 获取最新版 QuantumSim SDK，包含 DLL、头文件、Python 绑定和示例代码。

2

#### 放置 DLL

将 `quantum_sim.dll` 放到可执行文件同目录，或加入系统 PATH。确保 DLL 与应用程序架构一致 (x64)。

3

#### 调用接口

使用您选择的编程语言通过 FFI 调用 DLL 导出函数。首次调用会自动初始化安全上下文和许可证验证。

许可证说明：DLL 首次运行时会自动联网验证并获取 30 天免费试用。试用期内功能完整，30 天后仿真功能锁定。如需商业授权请联系授权。

03 · Quick Start

## 快速上手

### Python 示例

    from quantum_sim import QuantumSim

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

    # 制备 GHZ 态
    sim.apply_h(0)
    sim.apply_cnot(0, 1)
    sim.apply_cnot(1, 2)

    # 测量
    result = sim.measure()
    print(f"测量结果: {result:#b}")

    # 获取概率分布
    for i in range(sim.dim):
        amp = sim.amplitude(i)
        p = amp.re * amp.re + amp.im * amp.im
        if p > 1e-9:
            print(f"  |{i:03b}⟩  P = {p:.4f}")

    del sim

### C 语言示例

    #include <stdio.h>
    #include "quantum_sim.h"

    int main() {
        QsimStateHandle state = qsim_state_new(2);
        if (!state) { printf("创建失败\n"); return 1; }

        // Bell 态制备
        qsim_state_apply_h(state, 0);
        qsim_state_apply_cnot(state, 0, 1);

        // 测量
        uint64_t result = qsim_state_measure(state);
        printf("测量结果: %llu\n", (unsigned long long)result);

        // 获取概率
        double p0 = qsim_state_prob_one(state, 0);
        printf("qubit 0 |1> 概率: %.4f\n", p0);

        qsim_state_free(state);
        return 0;
    }

04 · API Reference

## 状态向量 API

全状态向量仿真，精确表示 2n 维希尔伯特空间中的量子态。适用于中小规模电路的精确仿真。

### 基本操作

函数 | 说明 | 参数
--- | --- | ---
`qsim_state_new(n)` | 创建量子态 | n: 量子比特数
`qsim_state_free(h)` | 释放量子态 | h: 句柄
`qsim_state_n_qubits(h)` | 获取量子比特数 | h: 句柄
`qsim_state_measure(h)` | 测量全部量子比特 | 返回测量结果 (uint64)
`qsim_state_prob_one(h, q)` | 获取 |1> 概率 | q: 量子比特索引

### 单量子比特门

函数 | 说明
--- | ---
`qsim_state_apply_h(h, q)` | Hadamard 门
`qsim_state_apply_x(h, q)` | Pauli-X 门
`qsim_state_apply_y(h, q)` | Pauli-Y 门
`qsim_state_apply_z(h, q)` | Pauli-Z 门
`qsim_state_apply_s(h, q)` | S 门 (π/2 相位)
`qsim_state_apply_t(h, q)` | T 门 (π/4 相位)

### 多量子比特门

函数 | 说明
--- | ---
`qsim_state_apply_cnot(h, ctrl, tgt)` | CNOT 门
`qsim_state_apply_toffoli(h, c1, c2, tgt)` | Toffoli 门
`qsim_state_apply_swap(h, q1, q2)` | SWAP 门

05 · Sparse State

## 稀疏态 API

稀疏表示仅存储非零振幅的量子态。当量子态中大部分基矢振幅为零时（如低纠缠、近经典态）， 稀疏态相比全状态向量可大幅节省内存和计算时间。

📊

#### 内存高效

仅存储非零振幅，适合高维稀疏量子态表示。

⚡

#### 快速运算

稀疏矩阵运算避免零元素计算，门操作效率更高。

🎯

#### 精确振幅

支持获取任意基矢振幅和概率，Top-K 查询。

06 · MPS Tensor Network

## MPS 张量网络 API

矩阵乘积态 (Matrix Product State) 张量网络表示，适用于低纠缠大规模量子系统。 支持 10000+ 量子比特的高效仿真，内建 SVD 截断和键维度自适应调整。

函数 | 说明
--- | ---
`qsim_mps_new(n, max_bond)` | 创建 MPS 态
`qsim_mps_free(h)` | 释放 MPS 态
`qsim_mps_bond_dim(h)` | 当前最大键维度
`qsim_mps_compression_ratio(h)` | 压缩比
`qsim_mps_entropy(h, site)` | 指定位置纠缠熵

07 · Quantum Gates

## 量子门列表

原生支持 21 种量子门操作，涵盖单比特、两比特、三比特门以及连续参数门。

#### 单比特门 (8)

H, X, Y, Z, S, T, Rx, Ry, Rz, U3

#### 两比特门 (6)

CNOT, CZ, SWAP, CU, CRk, iSWAP

#### 三比特门 (3)

Toffoli, Fredkin, CCZ

#### 多比特门 (4)

MCX, MCZ, QFT, 全局相位

08 · OpenQASM

## OpenQASM 支持

完全兼容 OpenQASM 2.0 标准，支持 3.0 核心特性。可直接运行 QASM 字符串或文件， 也可以将电路导出为 QASM 格式。

    # Python 示例
    from quantum_sim import QuantumSim

    # 直接运行 QASM 代码
    qasm = """
    OPENQASM 2.0;
    include "qelib1.inc";
    qreg q[2];
    h q[0];
    cx q[0], q[1];
    """
    state = QuantumSim.from_qasm(qasm)
    result = state.measure()
    print(f"Bell 态测量: {result:#b}")

09 · Applications

## 应用场景

### 材料仿真

通过量子比特模拟晶格自旋系统，研究材料的磁性、超导、拓扑等量子物性。 使用 VQE (变分量子本征求解器) 计算材料基态能量和相图。

### 化学计算

模拟分子结构和化学反应路径。通过 Jordan-Wigner 或 Bravyi-Kitaev 变换将费米子哈密顿量映射到量子比特， 结合 VQE 计算分子基态能量、过渡态和反应速率。

### 优化问题

使用 QAOA (量子近似优化算法) 求解组合优化问题，如旅行商、调度、投资组合优化等。 支持自定义 cost Hamiltonian 和 mixer Hamiltonian。

### 密码学

Shor 算法整数因子分解、Grover 搜索算法密码分析。可用于密码学研究和后量子密码验证。

行业定制：如果您需要针对特定领域（材料、化学、金融等）的定制化量子仿真解决方案，请联系我们获取技术支持。

10 · Support

## 技术支持

如需技术支持或商业授权，请通过以下方式联系。我们提供 SDK 集成指导、性能优化建议和定制化开发服务。

📧

#### 邮件支持

support@epiphys.com

📚

#### 文档中心

完整 API 文档和示例代码

🤝

#### 商业合作

企业级授权和定制开发

↑