QRAM-Simulator

QRAM 电路模拟核心（C++ 基座仓）：Qutrit/Qubit 两种 QRAM 架构、噪声模型、QRAM 论文实验与 pybind11 Python 绑定

仓库分工

本仓库是 C++ 基座：QRAM 电路核心 + 论文实验 + pybind11 薄绑定（qram-simulator PyPI 包）；SparQ 框架（稀疏态模拟器、算法库、pysparq 富绑定、算法类实验）位于 SparQSim 仓库：

依赖方向：SparQSim → QRAM-Simulator。SparQSim 以 git submodule （相对 URL ../QRAM-Simulator.git）方式引用本仓库并编译 C++ 核心；两个仓库各自 独立 tag/发版，SparQSim 发版前将 submodule pin 到本仓库的对应 tag。

核心能力

• QRAM 电路模拟：Qutrit-based（qram_circuit_qutrit.h）与 Qubit-based （qram_circuit_qubit.h）两种实现
• 噪声模型：退极化（Depolarizing）与振幅阻尼（Damping），含概率参数范围校验
• 架构剪枝：qubit 架构 normal（剪枝）模式与 full（不剪枝）模式逐版本对拍
• 公共组件：稀疏/稠密矩阵、随机引擎、错误处理、state manipulator 等

C++ 快速开始

构建

git clone https://github.com/IAI-USTC-Quantum/QRAM-Simulator.git
cd QRAM-Simulator
mkdir build && cd build

# 配置（CPU 版本；GPU/CUDA 后端当前暂缓，CMake 会构建 CPU-only 版本）
cmake .. -DCMAKE_BUILD_TYPE=Release

make -j$(nproc)

构建开关（均可通过 -D...=ON/OFF 控制）：

核心用法

#include "qram_circuit_qubit.h"

using namespace qram_simulator;
using namespace qram_qubit;

// 1. 构造 QRAM 电路（addr_size=4, data_size=2）
QRAMCircuit qram(4, 2);
qram.set_memory_random();                     // 随机数据树

// 2. 注入噪声（可选；概率范围校验，Damping 要求 gamma < 1）
qram.set_noise_models({
    { OperationType::Depolarizing, 1e-3 },
    { OperationType::Damping, 1e-4 }
});

// 3. 运行（normal=架构剪枝 / full=不剪枝基准）
qram.set_input_uniform(100);
qram.run_normal();

// 4. 采样保真度
double fidelity = qram.sample_and_get_fidelity();

Python 快速开始

pip install qram-simulator

绑定层（bindings/python/，pybind11）导出核心工作类：QRAMCircuitQubit / QRAMCircuitQutrit（两套架构电路）、QRAMFullAmp（全振幅桥接）、TimeStep （时序与噪声调度）、OperationType 与全局随机种子控制，供外部库直接驱动 完整的"构造 → 设噪声 → 运行 → 保真度"工作流：

from qram_simulator import QRAMCircuitQubit, OperationType, set_seed

set_seed(42)
qram = QRAMCircuitQubit(4, 2)
qram.set_memory_random()
qram.set_noise_models({OperationType.Depolarizing: 1e-3,
                       OperationType.Damping: 1e-4})
qram.set_input_uniform(100)
qram.run_normal()
print(qram.sample_and_get_fidelity())

本地开发：pip install -v .（CMake ≥ 3.18 + C++17 + OpenMP）， 测试：pytest bindings/python/test。

作为 CMake 子项目消费（SparQSim 的方式）

# submodule: git submodule add ../QRAM-Simulator.git extern/qram-simulator
set(QRAM_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(QRAM_BUILD_EXPERIMENTS OFF CACHE BOOL "" FORCE)
add_subdirectory(extern/qram-simulator)   # 提供 SparQ_QRAMSimulator / SparQ_Common 目标与平铺头文件布局

运行实验

# QRAM 保真度实验（V2）
./build/bin/Experiment_QRAM_FidelityV2 ...

Python 侧（pysparq 全功能绑定与 qram_simulator 薄绑定）见 SparQSim 仓库。

论文与引用

本仓库由两篇论文分别驱动：

Paper 1: QRAM-Simulator — arXiv:2503.13832

Efficient Simulation of Quantum Random Access Memory

• QRAM 电路模拟：Qutrit-based 与 Qubit-based 两种 QRAM 实现（C++ API），支持退极化和振幅阻尼噪声模型
• 稀疏态优化：仅存储非零振幅，可实现 64+ 量子比特的结构化算法模拟
• 错误过滤：针对含噪 QRAM 的错误过滤方案

对应代码：QRAM/、Experiments/QRAM/（错误过滤实验在 SparQSim 仓库）

Paper 2: SparQ — arXiv:2503.15118

SparQ: A Sparse Quantum Circuit Simulator with Register-Level Abstraction

将 Register Level Programming 拓展为通用稀疏态量子模拟器（QFT、Grover、哈密顿量 模拟、QDA、QCNN 等算法与扩展算法库）。

对应代码：SparQ/、SparQ_Algorithm/ 与算法类实验已迁至 SparQSim 仓库。

BibTeX

@article{sun2025sparqsim,
  title={SparQSim: Simulating Scalable Quantum Algorithms via Sparse Quantum State Representations},
  author={Sun, Tai-Ping and Chen, Zhao-Yun and Wang, Yun-Jie and Xue, Cheng and Liu, Huan-Yu and Zhuang, Xi-Ning and Xu, Xiao-Fan and Wu, Yu-Chun and Guo, Guo-Ping},
  journal={arXiv preprint arXiv:2503.15118},
  year={2025}
}

@article{wang2025refined,
  title={Refined Criteria for QRAM Error Suppression via Efficient Large-Scale QRAM Simulator},
  author={Wang, Yun-Jie and Sun, Tai-Ping and Zhuang, Xi-Ning and Xu, Xiao-Fan and Liu, Huan-Yu and Xue, Cheng and Wu, Yu-Chun and Chen, Zhao-Yun and Guo, Guo-Ping},
  journal={arXiv preprint arXiv:2503.13832},
  year={2025}
}

复现论文结果

详细的实验复现指南见 docs/paper/ 目录：

• docs/paper/README.md - 论文关联文档
• docs/paper/reproduction.md - QRAM-Simulator 实验复现指南

项目结构

QRAM-Simulator/
├── QRAM/               # QRAM 电路实现（Qutrit/Qubit-based）
├── Common/             # 公共组件（矩阵、随机引擎、state manipulator 等）
├── bindings/python/    # pybind11 薄绑定（qram-simulator PyPI 包）
├── Experiments/        # QRAM 论文实验（QRAMFidelityV2、QubitPaper、ChannelCorrespondence 等）
├── test/               # C++ 测试（Common/QRAM 归属部分）
├── ThirdParty/         # vendored 依赖（Eigen、fmt、googletest、argparse）
└── docs/               # Sphinx 文档（breathe 吸入 Doxygen C++ API + autoapi Python API）

发版流程

1. 在 Gitea（开发主仓）合并变更到 main；
2. 同步到 GitHub 上游 IAI-USTC-Quantum/QRAM-Simulator；
3. 更新 CHANGELOG.md，打 tag（vX.Y.Z，注意历史上已有 v0.1.x，新系列从 v0.2.0 起）；
4. push tag 或创建 GitHub Release → pypi-publish.yml 自动构建 cp310–cp313 的 manylinux / win_amd64 wheel 与 sdist，经 PyPI trusted publishing 发布 qram-simulator 包；pysparq 仍由 SparQSim 仓库发布。

About Us

本项目由 IAI-USTC Quantum 开发。

• GitHub Organization: IAI-USTC-Quantum — 查看团队的所有开源项目
• Documentation: iai-ustc-quantum.github.io — 团队文档与项目主页

IAI-USTC Quantum 是合肥综合性国家科学中心人工智能研究院（Institute of Artificial Intelligence, Hefei Comprehensive National Science Center）量子人工智能团队。

主要开发者：Agony5757 (chenzhaoyun@iai.ustc.edu.cn)、RichardSun、Itachixc、YunJ1e、cilysad、TMYTiMidlY

相关项目

• SparQSim - SparQ 框架与 Python 生态（pysparq）
• UnifiedQuantum - 统一量子计算框架

许可证

Apache-2.0 License