uniqc-cppsimulator 1.0.0__tar.gz → 1.1.0__tar.gz

uniqc_cppsimulator-1.1.0/.github/workflows/docs-pages.yml

@@ -0,0 +1,83 @@
+name: Docs (GitHub Pages)
+
+# Build the Sphinx site and publish it to GitHub Pages on every push to main
+# that can change its content, plus manual runs.
+# First run: enable Pages in repo Settings -> Pages -> Source: GitHub Actions.
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'docs/**'
+      - 'doc/**'
+      - 'benchmark/**'
+      - 'UniqcCpp/**'
+      - 'README.md'
+      - 'CHANGELOG.md'
+      - 'pyproject.toml'
+      - 'setup.py'
+      - '.github/workflows/docs-pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One deployment at a time; a newer push supersedes the in-flight one.
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5.0.1
+      with:
+        fetch-depth: 0  # full history for setuptools_scm version in the docs
+
+    - name: Set up Python
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+      with:
+        python-version: '3.12'
+
+    - name: Configure GitHub Pages
+      id: pages
+      uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d  # v6.0.0
+
+    - name: Install docs dependencies
+      run: python -m pip install -r docs/requirements.txt
+
+    # autodoc imports the benchmark/ package (via sys.path in docs/conf.py)
+    # and the uniqc_cpp extension, so install the extension from source.
+    - name: Build and install the extension
+      run: python -m pip install .
+
+    - name: Copy markdown sources into the Sphinx tree
+      run: python docs/prepare.py
+
+    - name: Build HTML (warnings are errors)
+      run: python -m sphinx -W --keep-going -b html docs docs/_build/html
+
+    - name: Upload pages artifact
+      uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
+      with:
+        path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346  # v5.0.1

{uniqc_cppsimulator-1.0.0 → uniqc_cppsimulator-1.1.0}/.gitignore

@@ -70,6 +70,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+# Markdown sources copied in by docs/prepare.py at build time
+docs/includes/
 # Autogenerated per-module reference pages; regenerated by `sphinx-apidoc`
 # before every build (see docs/Makefile). `uniqc_api.rst` is hand-curated.
 docs/source/uniqc.rst
@@ -195,6 +197,11 @@ bad_circuits.txt
 # setuptools_scm generated version file
 uniqc/_version.py
 
+# Benchmark scratch env & runs (published snapshots live in doc/benchmark/)
+.venv-bench/
+benchmark/results*.json
+!doc/benchmark/*.png
+
 # CMake build artifacts
 UniqcCpp/CMakeCache.txt
 UniqcCpp/CMakeFiles/
@@ -210,3 +217,6 @@ UniqcCpp/src/cmake_install.cmake
 UniqcCpp/test/Makefile
 UniqcCpp/test/CMakeFiles/
 UniqcCpp/test/cmake_install.cmake
+
+# 本地并行开发交接资料
+/.agent-task/

uniqc_cppsimulator-1.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-11-09
+
+### Added
+
+- **内核全局多线程**：新增进程级全局开关与线程数 API（`uniqc_cpp.set_parallel_enabled` / `is_parallel_enabled` / `set_num_threads` / `get_num_threads`，默认关闭、单线程，与历史行为完全一致）。态矢量全部门内核（含受控门）与密度算符行循环按 `std::thread` 连续分块并行（无新依赖，CMake 仅链接 `Threads::Threads`）；门操作结果与单线程数值一致（不同编译器的浮点收缩可能有末位差异），概率类读出（`pmeasure`/`get_prob`）还可能有浮点求和顺序差异；`rand()` 决策保留在调用线程；态矢量小于 2^14 幅度时自动回落单线程，密度矩阵按行循环总工作量决定。类型存根与 `docs/usage.rst` 同步更新。
+- **benchmark 多线程基线接入内核线程**：`uniqc_sv` 后端改为 `option` 模式（threads 档位经全局 API 直接测内核门级并行，此前精确模式的 threads>1 档位被跳过）；新增 `uniqc_sv_batch` 后端保留原进程池 shot 级采样吞吐基线；`uniqc_dm` 同样改为 `option`。sampling 预设组加入 `uniqc_sv_batch`，相关文档（README / benchmark/README / docs）同步。
+
+### Fixed
+
+- **QRAM 原生入口的越界访问与高位静默丢失**：`StatevectorSimulator` 与 `DensityOperatorSimulator` 现在要求数据数组长度恰好为 `2^addr_size`，并拒绝超出 `data_size` 位宽的值，统一抛出 `ValueError`。此前过短数组会使两个后端段错误，超位宽值的高位会被静默忽略；有效调用语义与 UniQC `QRAM` 既有契约不变。新增 Python 参数化回归及 C++ 原生异常回归。
+- **`StatevectorSimulator::measure_single_shot` 标量重载死循环**：`measure_single_shot({ qubit })` 的花括号初始化列表在重载决议中选中了标量重载自身，完美尾递归被编译器优化为无限循环——表现为挂起而非崩溃，1.0.1 及此前所有发布版本均受影响（list 重载不受影响，故既有测试未暴露）。现改为显式 `std::vector{ qubit }` 转发（与 `pmeasure` 标量重载同一写法）。新增带子进程超时保护的回归测试（`tests/test_bindings.py`）：旧版本上该测试失败而非挂死套件。
+- **`benchmark.worker` 在 Windows 上不可导入**：顶层 `import resource`（Unix-only 标准库）改为带回退的守卫导入，无 `resource` 平台上峰值 RSS 记为 `null`；`python -m benchmark list` 等 CLI 与文档 autodoc 在 Windows 恢复可用。
+
+### Added
+
+- **Sphinx 文档（`docs/`）**：使用/构建/测试指南、基准套件使用、`benchmark` 包 API 参考（autodoc）与 `uniqc_cpp` 扩展 API 参考；补全 `benchmark` 包全部 docstring。构建：`python -m sphinx -b html docs docs/_build/html`（零告警）。
+- **文档发布到 GitHub Pages**：`.github/workflows/docs-pages.yml` 在 `main` 分支文档相关变更后自动构建部署（`-W` 零告警门禁）。README / CHANGELOG / `doc/benchmark.md` / `benchmark/README.md` 与基准图表由 `docs/prepare.py` 在构建开始时自动拷入站点并重写站内链接（myst-parser），主题换为 furo；站点地址 <https://iai-ustc-quantum.github.io/uniqc-cppsimulator/>。
+- **跨模拟器 CPU benchmark 套件（`benchmark/`）**：以 `uniqc_cpp` 为对象与主流 pip 可装 CPU 模拟器（Qiskit Aer、Cirq、qsim、Qulacs、PennyLane lightning、Qibo、quimb、QuTiP、Braket 本地模拟器等）对比；统一线路 IR + 注册表扩展点（线路族 / 噪声预设 / 后端适配器 / 矩阵预设 / 图表）；单线程 vs 多线程基线（外部模拟器走原生线程旋钮，`uniqc_cpp` 走进程池并行采样吞吐）；结果 JSON 落盘 + 图表 + 报告生成（`python -m benchmark run|plot|report`）。摘要见 [README"性能基准"](README.md#性能基准)，详情见 [doc/benchmark.md](doc/benchmark.md)，套件用法见 [benchmark/README.md](benchmark/README.md)。
+
+## [1.0.1] - 2026-08-23
+
+### Fixed
+
+- **`StatevectorSimulator::twoqubit_depolarizing` 去极化概率被进程内首次调用固化**：1.0.0 中 Kraus 概率向量被误声明为 `const static` 局部变量，只在首次调用时初始化，之后同进程内所有调用静默沿用第一次的 `p`（实测错误率被"钉死"，且密度算符实现无此问题，两后端行为不一致）。现改为每次调用按当前 `p` 构建。新增同进程交变 `p` 的回归测试（`tests/test_bindings.py`）。
+
+### Removed
+
+- 清理 `qopcode.cpp` 中整段注释掉的废弃代码（`string_to_UnitaryType` / `string_to_NoiseType` / `gate_qubit_count`）。
+
+## [1.0.0] - 2026-08-21
+
+初始独立版本。C++ 模拟器自 [UnifiedQuantum](https://github.com/IAI-USTC-Quantum/UnifiedQuantum) v0.0.17 拆分为独立仓库，import 名保持 `uniqc_cpp` 不变，API 与拆分前完全兼容。
+
+- `StatevectorSimulator`（态矢量，最多 30 量子比特）与 `DensityOperatorSimulator`（密度算符，最多 10 量子比特，含噪声通道）
+- QRAM 指令支持与参数校验
+- Release 构建安全加固（stack protector / FORTIFY / relro）
+- Python 绑定测试套件（`tests/`）与 C++ 原生冒烟测试
+- 类型存根 `uniqc_cpp.pyi` 随 wheel 一起发布

{uniqc_cppsimulator-1.0.0 → uniqc_cppsimulator-1.1.0}/CMakeLists.txt

@@ -29,5 +29,6 @@ endif()
 
 set(PYBIND11_FINDPYTHON ON)
 find_package(pybind11 CONFIG REQUIRED)
+find_package(Threads REQUIRED)
 
 add_subdirectory(UniqcCpp)

{uniqc_cppsimulator-1.0.0 → uniqc_cppsimulator-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uniqc-cppsimulator
-Version: 1.0.0
+Version: 1.1.0
 Summary: C++ quantum circuit simulators (statevector / density operator) with pybind11 bindings. The native simulation kernel of UnifiedQuantum.
 Author-email: Agony <chenzhaoyun@iai.ustc.edu.cn>
 License: Apache License
@@ -234,6 +234,8 @@ UnifiedQuantum 的 C++ 量子线路模拟内核，独立发版。
 
 *The native C++ simulation kernel of [UnifiedQuantum](https://github.com/IAI-USTC-Quantum/UnifiedQuantum), published as a standalone package.*
 
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://iai-ustc-quantum.github.io/uniqc-cppsimulator/)
+
 ## 定位
 
 本仓库提供两个高性能 C++ 模拟器，通过 pybind11 暴露为 **`uniqc_cpp`** Python 扩展模块：
@@ -241,7 +243,7 @@ UnifiedQuantum 的 C++ 量子线路模拟内核，独立发版。
 - `StatevectorSimulator` — 态矢量模拟器（最多 30 量子比特）
 - `DensityOperatorSimulator` — 密度算符模拟器（最多 10 量子比特，支持噪声通道）
 
-它原来是 [UnifiedQuantum](https://github.com/IAI-USTC-Quantum/UnifiedQuantum) 仓库的 `UniqcCpp/` 目录，自 v1.0.0 起拆分为独立仓库、独立版本、独立发布。UnifiedQuantum 通过 PyPI 依赖本包，二者接口保持兼容。
+它原来是 [UnifiedQuantum](https://github.com/IAI-USTC-Quantum/UnifiedQuantum) 仓库的 `UniqcCpp/` 目录，自 v0.0.18 起拆分为独立仓库、独立版本、独立发布。UnifiedQuantum 通过 PyPI 依赖本包，二者接口保持兼容。
 
 **安装本包后，import 名为 `uniqc_cpp`**（分发名 `uniqc-cppsimulator`，import 名 `uniqc_cpp`）。
 
@@ -265,7 +267,7 @@ sim.cnot(0, 1)
 print(sim.pmeasure([0, 1]))  # Bell 态: [0.5, 0, 0, 0.5]
 ```
 
-完整 API 见仓库根目录的类型存根 [`uniqc_cpp.pyi`](uniqc_cpp.pyi)（安装后随扩展一起发布，IDE / 类型检查器可直接使用）。
+完整 API 见仓库根目录的类型存根 [`uniqc_cpp.pyi`](uniqc_cpp.pyi)（安装后随扩展一起发布，IDE / 类型检查器可直接使用）。测量列表的第一个量子比特是返回整数的最低有效位；`measure_single_shot` 只采样、不坍缩状态，`measure_qubit` 才执行坍缩测量。两个后端均为稠密存储，30 比特态矢量仅状态本身即需 16 GiB，实际可用规模还受内存限制。
 
 ## 源码构建要求
 
@@ -293,10 +295,85 @@ cmake --build build-cpp --config Release
 ./build-cpp/bin/Release/UnifiedQuantumTest   # Windows: .\build-cpp\bin\Release\UnifiedQuantumTest.exe
 ```
 
+## 文档
+
+在线文档（GitHub Pages）：**<https://iai-ustc-quantum.github.io/uniqc-cppsimulator/>** ——
+安装/构建指南、基准套件使用、`benchmark` 包与 `uniqc_cpp` 扩展的 API 参考、基准结果
+与 CHANGELOG；`main` 分支相关变更推送后自动构建发布。
+
+本地构建（源在 [`docs/`](docs/)；README / CHANGELOG / 基准报告等 markdown 由
+`docs/prepare.py` 在构建开始时自动拷入 `docs/includes/`）：
+
+```bash
+uv venv .venv-docs --python 3.12
+uv pip install --python .venv-docs -r docs/requirements.txt .
+.venv-docs/bin/python -m sphinx -b html docs docs/_build/html   # 或 cd docs && make html PYTHON=../.venv-docs/bin/python
+```
+
+类型存根 `uniqc_cpp.pyi` 随 wheel 发布；基准结果文档见 [doc/benchmark.md](doc/benchmark.md)，一页纸摘要见 [doc/benchmark/README_summary.md](doc/benchmark/README_summary.md)。
+
+在 UnifiedQuantum 框架中调用本内核（`submit_task` / `Simulator` 等入口）的用法，见
+[UnifiedQuantum 文档的本地模拟章节](https://github.com/IAI-USTC-Quantum/UnifiedQuantum/blob/main/docs/source/1_basic_usage/simulation.md)。
+
+## 性能基准
+
+[`benchmark/`](benchmark/README.md) 提供跨模拟器 CPU 基准套件：以 `uniqc_cpp` 为对象，
+与主流 pip 可装 CPU 模拟器广泛对比（Qiskit Aer、Cirq、Google qsim、Qulacs、PennyLane
+lightning、Qibo、quimb、QuTiP、Braket 本地模拟器；未安装的自动跳过），覆盖：
+
+- **基线**：单线程 vs 多线程（现阶段仅 CPU）
+- **线路族 × qubit 数**：`ghz` / `qft` / 分层随机 / `qaoa`，4 → 24 量子比特
+- **噪声**：去极化、幅度阻尼、比特翻转（密度矩阵）与轨迹采样
+- **多线程机制**：外部模拟器走内核线程旋钮（OMP/选项）；`uniqc_cpp` 内核自带
+  全局多线程开关（`set_num_threads` / `set_parallel_enabled`），threads 档位直接
+  测内核门级并行；`uniqc_sv_batch` 另保留 shot 级进程并行采样吞吐基线
+
+```bash
+uv venv .venv-bench --python 3.12 && uv pip install --python .venv-bench/bin/python \
+    uniqc-cppsimulator matplotlib qiskit qiskit-aer cirq qsimcirq qulacs \
+    pennylane pennylane-lightning qibo qibojit quimb qutip qutip-qip amazon-braket-sdk
+.venv-bench/bin/python -m benchmark selftest                      # 适配器正确性检查
+.venv-bench/bin/python -m benchmark run --preset smoke            # ~2 分钟冒烟
+.venv-bench/bin/python -m benchmark run --preset standard --out benchmark/results.json
+.venv-bench/bin/python -m benchmark plot && .venv-bench/bin/python -m benchmark report
+```
+
+默认对比对象是 PyPI 上最新的 `uniqc-cppsimulator` release；本轮为验证内核多线程，
+从本地源码安装 dev 构建（`1.0.2.dev4`）。
+
+### 最近一轮结果（2026-09-22，Xeon Gold 5118 × 48 核，本地 dev 构建 `1.0.2.dev4`）
+
+理想态矢量、单线程、各线路最大可比规模（完整数据见 [`doc/benchmark.md`](doc/benchmark.md)）：
+
+| 线路 | 最大可比 qubits | 最快 | uniqc_sv | 倍差 |
+|---|---|---|---|---|
+| ghz | 24 | Qiskit Aer (4.9 ms) | 1.82 s | ×372 |
+| qaoa | 24 | Google qsim (3.21 s) | 69.7 s | ×22 |
+| qft | 20 | Google qsim (224 ms) | 13.3 s | ×59 |
+| random | 24 | Google qsim (3.15 s) | 27.3 s | ×9 |
+
+**内核多线程首次生效**（threads=8 档位，全局 `set_num_threads` 门级并行）：
+
+- 大规模加速 **×2.7–2.9**：ghz 24q 1.82 s → 0.67 s；random 24q 27.3 s → 10.2 s；
+  qaoa 24q 69.7 s → 24.2 s；20q 约 ×1.7–1.8。≤16q 受线程启动开销与访存带宽限制收益甚微。
+- threads=8 下 24q ghz：uniqc_sv（672 ms）已与 PennyLane lightning（655 ms）并肩，
+  仅次于 Aer 的线路专用优化（2.1 ms）。
+- 密度矩阵行循环同样并行：uniqc_dm 10q 去极化 **×1.7**（19.0 s → 11.0 s）。
+- 采样吞吐（1024 shots）：进程级并行仍是王道 —— uniqc_sv_batch 16q **×7.7**
+  （37.0 s → 4.8 s），8q 达 17.4k shots/s 超过 Aer 多线程（6.3k）；内核线程对
+  轨迹采样仅 ×1.1（每条轨迹规模小、且无跨轨迹并行），两种机制各司其职。
+- 小规模（≤8q）单线程：uniqc_sv 与 Qulacs 各拿下 8 个线路-规模组合中的 4 个。
+- 噪声密度矩阵（去极化）：4q 处 uniqc_dm 最快（1.7 ms，比 Qulacs-DM 快 ~2.5×），
+  10q 处落后 Aer（19.0 s vs 1.7 s）。
+
+> 数字来自共享开发机（本轮有其他用户进程占用约 21 核，多线程加速比被低估）、
+> 未做绑核等公平性控制，仅用于相对趋势；图表见
+> [doc/benchmark.md](doc/benchmark.md)，原始 JSON 见 `doc/benchmark/results-2026-09-22.json`。
+
 ## 版本与兼容
 
 - 本包版本与 UnifiedQuantum 独立演进。UnifiedQuantum 在其 `pyproject.toml` 中以 `uniqc-cppsimulator>=x.y,<z` 声明兼容区间。
-- 破坏性 API 变更会提升 major 版本并在 CHANGELOG 中标注。
+- 破坏性 API 变更会提升 major 版本并在 [CHANGELOG](CHANGELOG.md) 中标注。
 
 ## 许可证
 

uniqc_cppsimulator-1.1.0/README.md

@@ -0,0 +1,150 @@
+# uniqc-cppsimulator
+
+UnifiedQuantum 的 C++ 量子线路模拟内核，独立发版。
+
+*The native C++ simulation kernel of [UnifiedQuantum](https://github.com/IAI-USTC-Quantum/UnifiedQuantum), published as a standalone package.*
+
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://iai-ustc-quantum.github.io/uniqc-cppsimulator/)
+
+## 定位
+
+本仓库提供两个高性能 C++ 模拟器，通过 pybind11 暴露为 **`uniqc_cpp`** Python 扩展模块：
+
+- `StatevectorSimulator` — 态矢量模拟器（最多 30 量子比特）
+- `DensityOperatorSimulator` — 密度算符模拟器（最多 10 量子比特，支持噪声通道）
+
+它原来是 [UnifiedQuantum](https://github.com/IAI-USTC-Quantum/UnifiedQuantum) 仓库的 `UniqcCpp/` 目录，自 v0.0.18 起拆分为独立仓库、独立版本、独立发布。UnifiedQuantum 通过 PyPI 依赖本包，二者接口保持兼容。
+
+**安装本包后，import 名为 `uniqc_cpp`**（分发名 `uniqc-cppsimulator`，import 名 `uniqc_cpp`）。
+
+## 安装
+
+```bash
+pip install uniqc-cppsimulator
+```
+
+提供 Linux / Windows / macOS 的 cp310–cp314 预编译 wheel；其余平台自动从 sdist 源码编译，需要满足下方"源码构建要求"。
+
+## 快速上手
+
+```python
+import uniqc_cpp
+
+sim = uniqc_cpp.StatevectorSimulator()
+sim.init_n_qubit(2)
+sim.hadamard(0)
+sim.cnot(0, 1)
+print(sim.pmeasure([0, 1]))  # Bell 态: [0.5, 0, 0, 0.5]
+```
+
+完整 API 见仓库根目录的类型存根 [`uniqc_cpp.pyi`](uniqc_cpp.pyi)（安装后随扩展一起发布，IDE / 类型检查器可直接使用）。测量列表的第一个量子比特是返回整数的最低有效位；`measure_single_shot` 只采样、不坍缩状态，`measure_qubit` 才执行坍缩测量。两个后端均为稠密存储，30 比特态矢量仅状态本身即需 16 GiB，实际可用规模还受内存限制。
+
+## 源码构建要求
+
+- CMake >= 3.22
+- 支持 C++17 的编译器（MSVC / gcc / clang）
+- pybind11（构建隔离模式下由 `pyproject.toml` 自动提供）
+- 第三方库 [fmt](https://fmt.dev/) 已 vendored 在 `UniqcCpp/Thirdparty/`，无需额外安装
+
+```bash
+git clone https://github.com/IAI-USTC-Quantum/uniqc-cppsimulator.git
+cd uniqc-cppsimulator
+pip install .
+```
+
+## 测试
+
+```bash
+# Python 绑定测试
+pytest tests/
+
+# C++ 原生测试
+cmake -S . -B build-cpp -DCMAKE_BUILD_TYPE=Release \
+  -Dpybind11_DIR="$(python -c 'import pybind11; print(pybind11.get_cmake_dir())')"
+cmake --build build-cpp --config Release
+./build-cpp/bin/Release/UnifiedQuantumTest   # Windows: .\build-cpp\bin\Release\UnifiedQuantumTest.exe
+```
+
+## 文档
+
+在线文档（GitHub Pages）：**<https://iai-ustc-quantum.github.io/uniqc-cppsimulator/>** ——
+安装/构建指南、基准套件使用、`benchmark` 包与 `uniqc_cpp` 扩展的 API 参考、基准结果
+与 CHANGELOG；`main` 分支相关变更推送后自动构建发布。
+
+本地构建（源在 [`docs/`](docs/)；README / CHANGELOG / 基准报告等 markdown 由
+`docs/prepare.py` 在构建开始时自动拷入 `docs/includes/`）：
+
+```bash
+uv venv .venv-docs --python 3.12
+uv pip install --python .venv-docs -r docs/requirements.txt .
+.venv-docs/bin/python -m sphinx -b html docs docs/_build/html   # 或 cd docs && make html PYTHON=../.venv-docs/bin/python
+```
+
+类型存根 `uniqc_cpp.pyi` 随 wheel 发布；基准结果文档见 [doc/benchmark.md](doc/benchmark.md)，一页纸摘要见 [doc/benchmark/README_summary.md](doc/benchmark/README_summary.md)。
+
+在 UnifiedQuantum 框架中调用本内核（`submit_task` / `Simulator` 等入口）的用法，见
+[UnifiedQuantum 文档的本地模拟章节](https://github.com/IAI-USTC-Quantum/UnifiedQuantum/blob/main/docs/source/1_basic_usage/simulation.md)。
+
+## 性能基准
+
+[`benchmark/`](benchmark/README.md) 提供跨模拟器 CPU 基准套件：以 `uniqc_cpp` 为对象，
+与主流 pip 可装 CPU 模拟器广泛对比（Qiskit Aer、Cirq、Google qsim、Qulacs、PennyLane
+lightning、Qibo、quimb、QuTiP、Braket 本地模拟器；未安装的自动跳过），覆盖：
+
+- **基线**：单线程 vs 多线程（现阶段仅 CPU）
+- **线路族 × qubit 数**：`ghz` / `qft` / 分层随机 / `qaoa`，4 → 24 量子比特
+- **噪声**：去极化、幅度阻尼、比特翻转（密度矩阵）与轨迹采样
+- **多线程机制**：外部模拟器走内核线程旋钮（OMP/选项）；`uniqc_cpp` 内核自带
+  全局多线程开关（`set_num_threads` / `set_parallel_enabled`），threads 档位直接
+  测内核门级并行；`uniqc_sv_batch` 另保留 shot 级进程并行采样吞吐基线
+
+```bash
+uv venv .venv-bench --python 3.12 && uv pip install --python .venv-bench/bin/python \
+    uniqc-cppsimulator matplotlib qiskit qiskit-aer cirq qsimcirq qulacs \
+    pennylane pennylane-lightning qibo qibojit quimb qutip qutip-qip amazon-braket-sdk
+.venv-bench/bin/python -m benchmark selftest                      # 适配器正确性检查
+.venv-bench/bin/python -m benchmark run --preset smoke            # ~2 分钟冒烟
+.venv-bench/bin/python -m benchmark run --preset standard --out benchmark/results.json
+.venv-bench/bin/python -m benchmark plot && .venv-bench/bin/python -m benchmark report
+```
+
+默认对比对象是 PyPI 上最新的 `uniqc-cppsimulator` release；本轮为验证内核多线程，
+从本地源码安装 dev 构建（`1.0.2.dev4`）。
+
+### 最近一轮结果（2026-09-22，Xeon Gold 5118 × 48 核，本地 dev 构建 `1.0.2.dev4`）
+
+理想态矢量、单线程、各线路最大可比规模（完整数据见 [`doc/benchmark.md`](doc/benchmark.md)）：
+
+| 线路 | 最大可比 qubits | 最快 | uniqc_sv | 倍差 |
+|---|---|---|---|---|
+| ghz | 24 | Qiskit Aer (4.9 ms) | 1.82 s | ×372 |
+| qaoa | 24 | Google qsim (3.21 s) | 69.7 s | ×22 |
+| qft | 20 | Google qsim (224 ms) | 13.3 s | ×59 |
+| random | 24 | Google qsim (3.15 s) | 27.3 s | ×9 |
+
+**内核多线程首次生效**（threads=8 档位，全局 `set_num_threads` 门级并行）：
+
+- 大规模加速 **×2.7–2.9**：ghz 24q 1.82 s → 0.67 s；random 24q 27.3 s → 10.2 s；
+  qaoa 24q 69.7 s → 24.2 s；20q 约 ×1.7–1.8。≤16q 受线程启动开销与访存带宽限制收益甚微。
+- threads=8 下 24q ghz：uniqc_sv（672 ms）已与 PennyLane lightning（655 ms）并肩，
+  仅次于 Aer 的线路专用优化（2.1 ms）。
+- 密度矩阵行循环同样并行：uniqc_dm 10q 去极化 **×1.7**（19.0 s → 11.0 s）。
+- 采样吞吐（1024 shots）：进程级并行仍是王道 —— uniqc_sv_batch 16q **×7.7**
+  （37.0 s → 4.8 s），8q 达 17.4k shots/s 超过 Aer 多线程（6.3k）；内核线程对
+  轨迹采样仅 ×1.1（每条轨迹规模小、且无跨轨迹并行），两种机制各司其职。
+- 小规模（≤8q）单线程：uniqc_sv 与 Qulacs 各拿下 8 个线路-规模组合中的 4 个。
+- 噪声密度矩阵（去极化）：4q 处 uniqc_dm 最快（1.7 ms，比 Qulacs-DM 快 ~2.5×），
+  10q 处落后 Aer（19.0 s vs 1.7 s）。
+
+> 数字来自共享开发机（本轮有其他用户进程占用约 21 核，多线程加速比被低估）、
+> 未做绑核等公平性控制，仅用于相对趋势；图表见
+> [doc/benchmark.md](doc/benchmark.md)，原始 JSON 见 `doc/benchmark/results-2026-09-22.json`。
+
+## 版本与兼容
+
+- 本包版本与 UnifiedQuantum 独立演进。UnifiedQuantum 在其 `pyproject.toml` 中以 `uniqc-cppsimulator>=x.y,<z` 声明兼容区间。
+- 破坏性 API 变更会提升 major 版本并在 [CHANGELOG](CHANGELOG.md) 中标注。
+
+## 许可证
+
+Apache License 2.0，见 [LICENSE](LICENSE)。

{uniqc_cppsimulator-1.0.0 → uniqc_cppsimulator-1.1.0}/UniqcCpp/Pybinder/uniqc_cpp.cpp

@@ -16,6 +16,7 @@
 #include "simulator.h"
 #include "density_operator_simulator.h"
 #include "rng.h"
+#include "threading_control.h"
 using namespace std;
 using namespace pybind11::literals;
 namespace py = pybind11;
@@ -26,6 +27,15 @@ PYBIND11_MODULE(uniqc_cpp, m)
 	m.def("seed", &uniqc::seed);
 	m.def("rand", &uniqc::rand);
 
+	m.def("set_parallel_enabled", &uniqc::set_parallel_enabled, py::arg("enabled"),
+		"Turn the global multithreading switch on/off (default off).");
+	m.def("is_parallel_enabled", &uniqc::is_parallel_enabled,
+		"Whether the global multithreading switch is on.");
+	m.def("set_num_threads", &uniqc::set_num_threads, py::arg("n"),
+		"Set the global worker-thread count (>= 1, clamped to hardware concurrency).");
+	m.def("get_num_threads", &uniqc::get_num_threads,
+		"Current global worker-thread count.");
+
 	auto py_arg_global_controller = (py::arg("global_controller") = std::vector<size_t>{});
 	auto py_arg_dagger = (py::arg("dagger") = false);
 

{uniqc_cppsimulator-1.0.0 → uniqc_cppsimulator-1.1.0}/UniqcCpp/src/CMakeLists.txt

@@ -10,6 +10,8 @@ set(UniqcCppCoreSrc_H
     ${CMAKE_CURRENT_SOURCE_DIR}/simulator_density_op_impl.h
     ${CMAKE_CURRENT_SOURCE_DIR}/simulator_impl.h
     ${CMAKE_CURRENT_SOURCE_DIR}/simulator_statevector_impl.h
+    ${CMAKE_CURRENT_SOURCE_DIR}/threading.h
+    ${CMAKE_CURRENT_SOURCE_DIR}/threading_control.h
 )
 set(UniqcCppCoreSrc
     ${CMAKE_CURRENT_SOURCE_DIR}/basic_math.cpp
@@ -19,5 +21,7 @@ set(UniqcCppCoreSrc
     ${CMAKE_CURRENT_SOURCE_DIR}/simulator_common.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/simulator_density_op_impl.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/simulator_statevector_impl.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/threading.cpp
 )
 add_library(${PROJECT_NAME} STATIC ${UniqcCppCoreSrc_H} ${UniqcCppCoreSrc})
+target_link_libraries(${PROJECT_NAME} PUBLIC Threads::Threads)

{uniqc_cppsimulator-1.0.0 → uniqc_cppsimulator-1.1.0}/UniqcCpp/src/density_operator_simulator.cpp

@@ -832,6 +832,7 @@ namespace uniqc
             CHECK_QUBIT_RANGE(qn)
 
         check_qram_qubit_validity(addr_qubits, data_qubits, control_qubits);
+        check_qram_data_validity(addr_qubits.size(), data_qubits.size(), data_array);
 
         size_t controller_mask = make_controller_mask(control_qubits, total_qubit);
 

uniqc_cppsimulator-1.1.0/UniqcCpp/src/qopcode.cpp

@@ -0,0 +1,5 @@
+#include "qopcode.h"
+
+namespace uniqc {
+
+} // namespace uniqc

{uniqc_cppsimulator-1.0.0 → uniqc_cppsimulator-1.1.0}/UniqcCpp/src/simulator.cpp

@@ -1,4 +1,5 @@
-#include "simulator.h"
+#include "simulator.h"
+#include "threading.h"
 namespace uniqc {
 
     using namespace statevector_simulator_impl;
@@ -746,7 +747,7 @@ namespace uniqc {
         CHECK_QUBIT_RANGE2(qn2, qn2)
         CHECK_PROBABILITY_BOUND(p)
 
-        const static std::vector<double> p_(15, p / 15);
+        const std::vector<double> p_(15, p / 15);
         pauli_error_2q(qn1, qn2, p_);
     }
 
@@ -785,6 +786,7 @@ namespace uniqc {
             CHECK_QUBIT_RANGE(qn)
 
         check_qram_qubit_validity(addr_qubits, data_qubits, control_qubits);
+        check_qram_data_validity(addr_qubits.size(), data_qubits.size(), data_array);
 
         size_t controller_mask = make_controller_mask(control_qubits, total_qubit);
         qram_permutation_impl(state, addr_qubits, data_qubits, data_array, total_qubit, controller_mask);
@@ -804,14 +806,17 @@ namespace uniqc {
         double prob = (outcome == 0) ? p0 : (1.0 - p0);
         double norm = std::sqrt(prob);
 
-        for (size_t i = 0; i < state.size(); ++i)
-        {
-            size_t bit = (i >> qn) & 1ull;
-            if (bit != outcome)
-                state[i] = 0;
-            else if (norm > 1e-14)
-                state[i] /= norm;
-        }
+        const size_t n_state = state.size();
+        parallel_for(0, n_state, [&](size_t begin, size_t end) {
+            for (size_t i = begin; i < end; ++i)
+            {
+                size_t bit = (i >> qn) & 1ull;
+                if (bit != outcome)
+                    state[i] = 0;
+                else if (norm > 1e-14)
+                    state[i] /= norm;
+            }
+        });
         return outcome;
     }
 
@@ -861,17 +866,26 @@ namespace uniqc {
         std::vector<dtype> ret;
         ret.resize(pow2(measure_list.size()));
 
-        for (size_t i = 0; i < pow2(total_qubit); ++i)
-        {
-            size_t meas_idx = get_state_with_qubit(i, measure_map);
-            ret[meas_idx] += abs_sqr(state[i]);
-        }
+        const size_t n_state = pow2(total_qubit);
+        const size_t nchunk = parallel_worker_count(n_state);
+        std::vector<std::vector<dtype>> partial(nchunk, std::vector<dtype>(ret.size(), 0.0));
+        parallel_chunks(0, n_state, [&](size_t c, size_t b, size_t e) {
+            auto& local = partial[c];
+            for (size_t i = b; i < e; ++i)
+            {
+                size_t meas_idx = get_state_with_qubit(i, measure_map);
+                local[meas_idx] += abs_sqr(state[i]);
+            }
+        });
+        for (auto& p : partial)
+            for (size_t k = 0; k < ret.size(); ++k)
+                ret[k] += p[k];
         return ret;
     }
 
     size_t StatevectorSimulator::measure_single_shot(size_t qubit)
     {
-        return measure_single_shot({ qubit });
+        return measure_single_shot(std::vector{ qubit });
     }
 
     size_t StatevectorSimulator::measure_single_shot(const std::vector<size_t>& qubit)

{uniqc_cppsimulator-1.0.0 → uniqc_cppsimulator-1.1.0}/UniqcCpp/src/simulator_common.cpp

@@ -55,6 +55,44 @@ namespace uniqc {
         return mask;
     }
 
+    void check_qram_data_validity(
+        size_t addr_size,
+        size_t data_size,
+        const std::vector<size_t>& data_array)
+    {
+        constexpr size_t size_t_bits = sizeof(size_t) * 8;
+        if (addr_size >= size_t_bits || data_size > size_t_bits)
+        {
+            auto errstr = fmt::format(
+                "QRAM address/data sizes ({}/{}) exceed the native size_t representation ({} bits).",
+                addr_size, data_size, size_t_bits);
+            ThrowInvalidArgument(errstr);
+        }
+
+        const size_t expected_size = size_t{ 1 } << addr_size;
+        if (data_array.size() != expected_size)
+        {
+            auto errstr = fmt::format(
+                "QRAM data array size ({}) does not match 2^addr_size ({}).",
+                data_array.size(), expected_size);
+            ThrowInvalidArgument(errstr);
+        }
+
+        if (data_size == size_t_bits)
+            return;
+        const size_t value_limit = size_t{ 1 } << data_size;
+        for (size_t i = 0; i < data_array.size(); ++i)
+        {
+            if (data_array[i] >= value_limit)
+            {
+                auto errstr = fmt::format(
+                    "QRAM data value ({}) at index {} does not fit data_size = {}.",
+                    data_array[i], i, data_size);
+                ThrowInvalidArgument(errstr);
+            }
+        }
+    }
+
     void check_qram_qubit_validity(
         const std::vector<size_t>& addr_qubits,
         const std::vector<size_t>& data_qubits,

{uniqc_cppsimulator-1.0.0 → uniqc_cppsimulator-1.1.0}/UniqcCpp/src/simulator_common.h

@@ -54,6 +54,14 @@ namespace uniqc {
         const std::vector<size_t>& data_qubits,
         const std::vector<size_t>& control_qubits);
 
+    /* Requires exactly one value per address and rejects values that do not
+     * fit the data register instead of indexing out of bounds or dropping
+     * high bits. Throws InvalidArgument on any violation. */
+    void check_qram_data_validity(
+        size_t addr_size,
+        size_t data_size,
+        const std::vector<size_t>& data_array);
+
     // ============================================================
     // Inline 2x2 statevector (matrix × vector) operation
     // |ψ'⟩ = U |ψ⟩, where ψ = (a0, a1), U = [[u00,u01],[u10,u11]]