SparQSim / pysparq

pysparq —— 稀疏态量子电路模拟器的全功能 Python 框架（Register Level Programming、原生 QRAM、动态算子、RIR 解释器）

仓库分工

依赖方向：SparQSim → QRAM-Simulator。SparQSim 发布 pysparq 包并承载 SparQ C++ 框架 （SparQ/ 稀疏态模拟器 + SparQ_Algorithm/ 算法库 + 全部 Python 绑定与算法类实验）； QRAM 基座（Common + QRAM + ThirdParty）在 QRAM-Simulator 仓库独立发版， 本仓库以 git submodule（相对 URL ../QRAM-Simulator.git）引用并编译。

安装

pip install pysparq

要求：Python 3.10 – 3.13，NumPy。

需要 QRAM 电路级 Python API（QRAMCircuitQubit/QRAMCircuitQutrit 噪声 仿真工作流）时，另行安装 QRAM-Simulator 仓库发布的独立包：

pip install qram-simulator

GPU 支持：CUDA/GPU 后端当前在 CMake 中临时屏蔽，默认只构建 CPU 路径。

从源码构建

git clone --recurse-submodules <this-repo-url>
cd SparQSim
pip install .

5 分钟上手示例

import pysparq as ps

# 1. 创建稀疏态
state = ps.SparseState()

# 2. 定义寄存器（Register Level Programming 的核心）
addr_id = ps.AddRegister("addr", ps.UnsignedInteger, 4)(state)
data_id = ps.AddRegister("data", ps.UnsignedInteger, 8)(state)

# 3. 初始化叠加态（所有地址等概率）
ps.Hadamard_Int("addr", 4)(state)

# 4. 创建 QRAM 并加载数据
memory = [i * 2 for i in range(16)]
qram = ps.QRAMCircuit_qutrit(addr_size=4, data_size=8, memory=memory)

# 5. 执行 QRAM 加载：|addr⟩|0⟩ → |addr⟩|memory[addr]⟩
ps.QRAMLoad(qram, "addr", "data")(state)

# 6. 直接进行算术操作（无需编译成门！）
ps.Add_ConstUInt_InPlace("data", 5)(state)   # data = data + 5

# 7. 测量 / 概率查询
ps.set_seed(0)
outcome, prob = ps.MeasureZ("data")(state)
dist = ps.Probability.distribution(state, "addr")

Register Level 特性的关键 API

# 量子算术 - 直接寄存器操作（Register Level Programming 核心）
ps.Add_UInt_UInt(in1, in2, out)      # out = in1 + in2
ps.Add_UInt_ConstUInt(reg, const)    # reg = reg + const
ps.Mult_UInt_ConstUInt(in, c, out)   # out = in * c
ps.ShiftLeft(reg, n)                 # 左移 n 位
ps.ShiftRight(reg, n)                # 右移 n 位

# 基础量子门
ps.Hadamard_Int(reg, n_digits)       # 对整数寄存器应用 Hadamard
ps.X_Bool(reg, pos)                  # X 门（特定比特位）
ps.Z_Bool(reg, pos)                  # Z 门

# QRAM 操作
ps.QRAMLoad(qram, addr_reg, data_reg)      # QRAM 加载
ps.QRAMLoadFast(qram, addr_reg, data_reg)  # 快速版本

# 可播种的测量 / 复位 / 概率查询（面向动态执行器：mid-circuit MEASURE/RESET/QIF）
ps.set_seed(seed)                          # 播种全局随机数引擎，使采样结果可复现
outcome, prob = ps.MeasureZ(reg)(state)    # 投影式 Z 基测量：坍缩 + 重新归一化
measured = ps.Reset(reg, target=0)(state)  # 测量 + 经典条件翻转，强制复位到 target
p = ps.Probability(reg, value)(state)      # 只读 Born 概率查询，不改变状态
dist = ps.Probability.distribution(state, reg)  # 单寄存器完整结果分布（只读）

高层算法库（pysparq.algorithms）

纯 Python 实现的算法层，组合公开原语（Grover、Shor、QDA、CKS、态制备、块编码等）， 与 C++ 实验代码的逐一对应关系见 docs/algorithm-implementation.md。

项目结构

SparQSim/
├── SparQ/                  # SparQ C++ 稀疏态模拟器（伞形目标 SparQ 在根 CMake 定义）
├── SparQ_Algorithm/        # 高层算法 C++ 库（态制备、块编码、哈密顿模拟、QDA 等）
├── Experiments/            # 量子算法 C++ 实验（QDA/Grover/QFT/Shor/QCNN/CKS/GHZ 等）
├── test/                   # C++ 测试（SparQ 单测 + CommonTest 完整版；SPARQ_BUILD_TESTS 门控）
├── extern/qram-simulator/  # QRAM 基座 submodule（Common + QRAM + ThirdParty，相对 URL ../QRAM-Simulator.git）
├── PySparQ/
│   ├── core.cpp            # pybind11 富绑定（_core 模块）
│   ├── pysparq/            # Python 包（operators/ algorithms/ rir conformance dynamic_operator）
│   └── test/               # pytest 套件
├── docs/                   # Sphinx 文档 + 算法转译指南
├── examples/               # C++ 与 Python 示例（SPARQ_BUILD_EXAMPLES 门控 C++ 部分）
└── pyproject.toml          # pysparq 包（scikit-build-core + setuptools-scm）

发版流程

1. 在 Gitea（开发主仓）合并变更到 main；
2. 需要新版核心时，先等 QRAM-Simulator 发布对应 tag，然后 git submodule update --remote（或 checkout 到该 tag）提交 pin；
3. 同步到 GitHub 上游 IAI-USTC-Quantum/SparQSim；
4. 更新 CHANGELOG.md，打 tag vX.Y.Z（延续 pysparq 版本系列，下一版 v0.2.0）；
5. push tag 或创建 GitHub Release → pypi-publish 工作流自动构建 cp310–313 × (manylinux / win_amd64) wheel + sdist（sdist 内嵌核心源码，自包含） 并发布到 PyPI（Trusted Publishing / OIDC）。

外部消费者（qecc_lang、quantum_cfd QFVM）的 API 依赖冻结见 PySparQ/consumer_runtime_inventory.json，由 PySparQ/test/test_consumer_runtime_contract.py 强制。

论文与引用

见 QRAM-Simulator 仓库 README。

About Us

本项目由 IAI-USTC Quantum 开发（合肥综合性国家科学中心人工智能研究院量子人工智能团队）。

许可证

Apache-2.0 License