【创新应用】新增 QShadow：可观测量感知的经典阴影估计与置信预算控制

[1195214305]

概述

本 PR 新增 pyqpanda_alg/QShadow，用于从局域 Pauli 测量数据中同时估计多个 Pauli 可观测量。模块覆盖测量基规划、逐 shot 数据记录、无偏估计、同时置信区间和 shots 预算控制，并提供 NumPy 参考采样、PyQPanda3 CPUQVM 运行器及远程后端回调接口。

经典阴影和局域偏置 Pauli 阴影已有公开理论基础，本实现主要补充它们在 pyqpanda-algorithm 中的数据模型、规划器、后处理和后端接入流程。

新增模块 pyqpanda_alg/QShadow

文件	内容
observable.py	PauliTerm、PauliObservable 及状态向量精确期望值
planner.py	局域 X/Y/Z 测量概率优化、概率下限及测量计划采样
dataset.py	逐 shot 测量基、bitstring 和采样概率数据集
estimator.py	逆倾向无偏估计、同时经验 Bernstein 区间和预算控制
sampler.py	NumPy 参考采样、CPUQVM 运行器和远程 executor 接口

公共 API 由 QShadow/__init__.py 导出，并在 pyqpanda_alg/__init__.py 中注册。

实现要点

1. 明确的 q0-first 约定：Pauli 字符串第 q 个字符作用于量子比特 q；PyQPanda 常见的 MSB-first counts 会在运行器中转换。
2. 可观测量感知的测量规划：根据目标 Pauli 项及系数优化每个量子比特的 X/Y/Z 概率，并用 probability_floor 避免不可观测项和过大的逆倾向权重。
3. 异构轮次合并：ShadowDataset 保存每个 shot 当时的完整采样概率，因此不同测量轮次可以直接合并并保持估计无偏。
4. 同时置信区间与预算：多个可观测量使用 Bonferroni 分配失败概率；ShadowBudgetController 根据目标半宽、批大小和硬 shots 上限给出下一批预算，不会自行提交任务。
5. 远程任务保护：run_measurement_plan(..., max_jobs=N) 在调用 runner 前检查唯一测量基数量，超限时不会发起后端调用。

示例与文档

• example/QShadow/qshadow_observable_estimation.py：三比特 CPUQVM 端到端示例，包含概率规划、采样、估计及预算判断；
• example/QShadow/qshadow_planning_benchmark.py：固定种子的均匀/优化规划重复对照，以及顺序预算实验；
• Tutorials/source/QShadow.rst：Sphinx 教程；
• pyqpanda_alg/QShadow/README.md：API、约定、后端接入、限制和论文引用；
• 顶层中英文 README、Sphinx 索引和 pytest 配置已同步更新。

端到端示例中，规划代理损失从 24.54 降至 5.9645493525156965。在 4000 shots、26 个唯一测量基下，两个 CPUQVM 估计的同时区间均覆盖精确状态向量结果，预算控制返回 target_reached。

离线重复基准

基准脚本在相同状态、可观测量和 shots 下比较均匀规划与 QShadow 规划。固定种子 1000 轮、每轮 2000 shots 的结果为：

• 聚合 RMSE 降低 60.20%；两个可观测量的 RMSE 分别降低 61.72% 和 57.68%；
• 两个可观测量的平均区间半宽分别降低 62.35% 和 53.42%；
• 优化方案两个估计偏差的 z-score 为 0.28 和 -0.26，与零一致；
• 两种方案的单项和 family-wise 经验覆盖率均为 1.000，表明本实验中的区间较保守，而不是精确 95% 校准。

另一个 100 轮顺序预算实验使用相同 0.22 目标半宽。均匀规划平均需要 7284.9 shots，QShadow 规划平均需要 1892.8 shots，减少 74.02%；两种方案均 100% 达到目标，且没有硬上限违规。

这些结果只对应脚本中固定的状态、可观测量、概率下限和种子日程，不声称对所有问题都有相同比例的改善。

测试

PYTHONPATH=pyqpanda-algorithm python -m pytest test/QShadow -q -o addopts=""
PYTHONPATH=pyqpanda-algorithm python -m pytest test -q -o addopts=""

验证结果：

• QShadow：32 passed；
• 全部测试：50 passed；
• QShadow 6 个核心源文件及离线基准脚本通过 mypy；
• compileall、顶层导入和 CPUQVM 示例通过；
• Sphinx HTML 构建成功，QShadow 页面无新增 warning/error。

测试覆盖 Pauli 数据校验、规划损失与概率下限、逐 shot 逆倾向估计、异构轮次合并、同时区间、预算上限、counts 校验、端序转换和 max_jobs 提交前保护。

WK_C180 验证

2026-07-26 在 WK_C180 上运行了固定预算的单量子比特 X/Y/Z 测量：每个基 512 shots，共 3 个任务、1536 shots，没有自动重试或后端切换。任务 ID、OriginIR、原始概率、counts 和统计结果保存在：

• example/QShadow/qshadow_wukong_validation_20260726.json
• example/QShadow/qshadow_wukong_validation_20260726.md

这三个任务覆盖了真实 counts 归一化、q0-first 摄取、逐 shot 概率记录、X/Y/Z 同时估计、family-wise 经验 Bernstein 区间，以及 3-job/1536-shot/0-retry 预算约束，因此不只是云接口连通性测试。硬件 X/Y/Z 区间均未覆盖理想值，Bloch 向量范数为 1.539826 > 1；运行时启用了 is_amend=True，QShadow 没有读出误差缓解，所以不把结果解释为硬件精度成功。由于三个目标完全对称并采用均匀计划，这次运行也不用于比较偏置规划器与均匀规划的真机优势；规划器的代理损失和概率下限由 CPUQVM 示例及测试验证。

兼容性

• 本地测试环境：Python 3.12、pyqpanda3==0.3.5；
• 核心模块只使用标准库、仓库已有的 numpy 和按需导入的 pyqpanda3，不修改 requirements.txt；
• 真机记录中的 qpanda3_runtime==1.0.0 仅用于应用层后端适配，不是 QShadow 的安装依赖；
• 远程执行使用 executor(program, shots) -> counts 回调，QShadow 不接收或保存云端密钥。

限制

• 当前仅支持实系数 Hermitian Pauli 可观测量和局域 X/Y/Z 测量；
• 不包含读出误差缓解、零噪声外推或完整状态层析；
• 经验 Bernstein 区间只描述有限 shots 的统计不确定性，不覆盖门噪声、读出误差、平台修正或校准漂移；
• 规划目标是状态无关的二阶矩代理，代理损失下降不保证任意量子态上的实际方差都下降。

参考文献

1. H.-Y. Huang, R. Kueng, J. Preskill, Predicting many properties of a quantum system from very few measurements, Nature Physics 16, 1050–1057 (2020), arXiv:2002.08953.
2. C. Hadfield, S. Bravyi, R. Raymond, A. Mezzacapo, Measurements of Quantum Hamiltonians with Locally-Biased Classical Shadows, arXiv:2006.15788.
3. C. Hadfield, Adaptive Pauli Shadows for Energy Estimation, arXiv:2105.12207.

[Copilot]

Pull request overview

本 PR 在 pyqpanda_alg 中新增 QShadow 模块，提供面向局域 Pauli 测量数据的多可观测量经典阴影估计工作流，并配套了测量规划、逐 shot 数据模型、无偏估计、同时置信区间与 shots 预算控制，以及 NumPy/CPUQVM/远程 executor 的采样执行路径；同时补齐文档、示例与测试集成。

Changes:

• 新增 pyqpanda_alg/QShadow：Pauli 可观测量建模、规划器、数据集、估计器、采样/执行器与公共导出 API。
• 新增端到端示例与离线基准脚本，并补充真机验证证据文件。
• 将 QShadow 接入 Sphinx 教程/AutoAPI、pytest 测试路径与中英文 README 索引。

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
Tutorials/source/QShadow.rst	新增 QShadow 教程页（工作流、约定、预算、验证与引用）。
Tutorials/source/index.rst	将 QShadow 教程与 AutoAPI 索引接入 Sphinx toctree。
test/QShadow/Test_sampler.py	覆盖参考采样、端序转换、counts 校验、max_jobs guard、CPUQVM runner 与自定义 executor。
test/QShadow/Test_planner.py	覆盖均匀概率、floor 约束优化、loss 单调性与计划采样可复现性。
test/QShadow/Test_observable.py	覆盖 PauliTerm/Observable 校验、重复项合并与精确期望值参考路径。
test/QShadow/Test_estimator.py	覆盖逆倾向样本、无偏性回归、轮次合并、Bonferroni 同时区间与预算控制。
test/pytest.ini	将 testpaths 扩展到 QShadow。
README.md	顶层中文 README 增加 QShadow 模块条目。
README_EN.md	顶层英文 README 增加 QShadow 模块条目。
pyqpanda-algorithm/pyqpanda_alg/QShadow/init.py	定义并导出 QShadow 公共 API。
pyqpanda-algorithm/pyqpanda_alg/QShadow/observable.py	PauliTerm/PauliObservable 与状态向量精确期望值实现。
pyqpanda-algorithm/pyqpanda_alg/QShadow/planner.py	局域 X/Y/Z 概率优化、planning loss 与测量计划采样。
pyqpanda-algorithm/pyqpanda_alg/QShadow/dataset.py	逐 shot bases/outcomes/propensities 数据结构与拼接/切片。
pyqpanda-algorithm/pyqpanda_alg/QShadow/estimator.py	逆倾向无偏估计、经验 Bernstein 半宽、Bonferroni 同时区间与预算控制器。
pyqpanda-algorithm/pyqpanda_alg/QShadow/sampler.py	NumPy 参考测量采样、counts 归一化、计划执行与 PyQPandaRunner。
pyqpanda-algorithm/pyqpanda_alg/QShadow/README.md	QShadow 模块 README（API、约定、云接入、安全与方法说明）。
pyqpanda-algorithm/pyqpanda_alg/init.py	在顶层包初始化中注册导入 QShadow。
pyqpanda-algorithm/example/QShadow/qshadow_observable_estimation.py	CPUQVM 端到端示例（规划→测量→估计→预算评估）。
pyqpanda-algorithm/example/QShadow/qshadow_planning_benchmark.py	离线可复现对照基准（固定预算与顺序预算统计）。
pyqpanda-algorithm/example/QShadow/qshadow_wukong_validation_20260726.md	WK_C180 真机验证说明文档与披露。
pyqpanda-algorithm/example/QShadow/qshadow_wukong_validation_20260726.json	WK_C180 真机验证机器可读证据（counts/配置/分析结果）。

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.