基于复旦大学曦源项目「量子真随机数生成」整理的研究代码：从 |+⟩ 测量出发，研究读出偏置与死时间相关性，进行一阶模型估熵、自适应压缩、Toeplitz 提取和统计回归验证。
本仓库重点是让每次后处理都能检查、回放和解释失败原因。默认运行 Qiskit Aer 经典仿真，用来验证算法流程；真实物理熵和密码学安全仍需要设备模型、原始采集证据及独立评估。
Python 3.10+；本次在 Windows / Python 3.12 上实际测试。
git clone https://github.com/Yukinodot/XiYuan-QRNG.git
cd XiYuan-QRNG
python -m venv .venv
# Windows PowerShell: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
python -m pip install -e ".[aer,plots]"
python -m xiyuan_qrng run --source aer-noisy --shots 8192 --simulator-seed 20261013 --detector-seed 20261013 --out runs/noisy --plots
python -m xiyuan_qrng replay runs/noisy
# 理想模式默认不注入死时间
python -m xiyuan_qrng run --source aer-ideal --shots 8192 --simulator-seed 20261013 --out runs/ideal --plots
python -m unittest discover -s tests -v每次使用新的输出目录。模拟器与死时间种子固定时原始流可复现；提取种子每次由操作系统独立生成，所以重新 run 的输出可能不同。要逐位复现已保存的结果，请用 replay，它无需 Qiskit 或云端账户：
python -m pip install -e .
python -m xiyuan_qrng replay examples/noisy
python -m xiyuan_qrng replay examples/idealflowchart LR
A[H门 + Z测量 / 有序文件] --> B[读出偏置 + 可选死时间模型]
B --> C[按块记录全部输入]
C --> D[源诊断 + 一阶熵代理]
D --> E[模型驱动的输出长度]
E --> F[独立公开种子 / Toeplitz GF2]
F --> G[保存全部候选输出]
G --> H[偏置与自相关诊断]
H --> I[通过诊断的研究输出]
H --> J[失败隔离 / 无换种子重试]
| 内容 | 来源与范围 |
|---|---|
| 偏置/死时间模型、估熵、Toeplitz、统计验证 | 用户提供的曦源项目 PPT 和原代码 |
| 历史阶段结果：8192 → 3575 bits | PPT 第 11 张报告；原始比特与当时提取种子未提供，不能逐位重现 |
| 原脚本和 README | 在 legacy/ 保留原始字节，SHA-256 见 来源记录 |
| 模块化、安装入口、单次提取、失败隔离、尾块记录 | 本次工程整理与修正 |
| 保存候选流/公开种子、清单校验、逐位回放、反例测试 | 本次新增的可复现机制 |
| 20 组 Aer 实验和图表 | 本次实际运行，详见 验证记录 |
项目材料将个人参与范围描述为数学基础、后处理与统计验证。仓库不据此声称独立完成了硬件随机源。个人面试 PPT 中的其他经历没有作为仓库内容发布。
下面是仓库中保存的两组新实验，均为 8192 shots、2048-bit 分块。它们与 PPT 历史结果分开记录，所有候选都保留，没有搜索更好看的提取种子。
| 本次保存的样例 | Raw P(1) | Exported P(1) | Raw max|ACF| | Exported max|ACF| | 输出 bits |
|---|---|---|---|---|---|
| 理想 Aer | 0.496338 | 0.500463 | 0.020696 | 0.024791 | 5405 |
| 带噪声 Aer + 死时间 0.18 | 0.422485 | 0.492366 | 0.095836 | 0.051937 | 3406 |
样例输出全部通过所设工程诊断；理想源样例的最大自相关略有增加，有限样本下无需每个指标都单调变好。完整 20 组 CSV 保留全部结果。PPT 的历史结果另见 项目说明。
| 文件 | 用途 |
|---|---|
measurements.npy / raw.npy |
逐 shot 测量流 / 注入可选死时间后的有序输入 |
candidate.npy |
全部提取候选，包括诊断失败块 |
exported.npy / exported.bin |
通过工程诊断的研究输出；大端位序，最后一字节补零 |
seeds.npz |
每个提取块的独立公开 Toeplitz 种子 |
report.json |
分块偏移、输入数、源诊断、模型估计、状态、有效输出位数、环境版本 |
manifest.json |
数据和报告的 SHA-256，检查意外改动；不提供数字签名认证 |
diagnostics.png |
从报告生成的统计图，需 --plots |
真实设备导出的输入必须是按采集顺序排列的 0/1 一维 .npy。计数直方图不能还原时间相关性。输入文件模式默认不添加人工死时间：
python -m xiyuan_qrng run --source file --input ordered_bits.npy --out runs/deviceIBM QPU 接口保留为可选实验路径，需要自己配置 IBM 账户，并同时明确传入 --backend 和 --submit-qpu；它会提交远程作业，可能消耗账户额度。本次未运行或验证真实 QPU。
python -m pip install -e ".[ibm]"
python -m xiyuan_qrng run --source ibm --backend YOUR_BACKEND --submit-qpu --shots 8192 --out runs/ibm一阶统计代理无法识别所有高阶依赖。测试中的周期序列 00110011... 可以得到正的一阶估计，但它是确定性的；新增的 1–4 阶确定性转移筛查能识别这一反例，也不能替代通用熵评估。报告始终标记 entropy_certified: false。
独立公开种子适用于 Toeplitz 哈希研究；epsilon 和压缩裕量只是借用了提取器理论形式。没有成立的条件最小熵界，不能把它解释成已实现的安全参数。诊断通过、失败隔离以及输出分布图也不能证明密码学均匀性；隔离策略会改变保留样本的分布。模型与安全边界 解释这些限制。
后续可接入带时间戳的真实探测数据、校准死时间模型、使用条件最小熵分析和 NIST 的非 IID 熵评估，并研究有限样本下的提取率与失败率。
src/xiyuan_qrng/ 算法、采集、CLI、保存/回放、作图
tests/ GF(2) 独立对照、周期反例、失败隔离、尾块与完整性测试
scripts/ 20 组固定协议实验
examples/ 两组完整可回放样例 + 全部实验汇总
docs/ 项目来源、数学机制、研究边界、验证记录
legacy/ 用户提供的未修改原始材料
参考：Qiskit Aer 逐 shot memory、IBM primitives 输出、Leftover Hashing Against Quantum Side Information、NIST SP 800-90B。