【创新应用】新增基于QUBO的共享实验室最小扰动重排应用

.github/workflows/lab-scheduling.yml

@@ -0,0 +1,97 @@
+name: Laboratory scheduling application
+
+on:
+  push:
+    branches: [contest/qubo-scheduling-app]
+    paths:
+      - 'pyqpanda-algorithm/pyqpanda_alg/LabScheduling/**'
+      - 'pyqpanda-algorithm/pyqpanda_alg/QAOA/**'
+      - 'pyqpanda-algorithm/example/LabScheduling/**'
+      - 'test/LabScheduling/**'
+      - '.github/workflows/lab-scheduling.yml'
+  pull_request:
+    branches: [develop, main]
+    paths:
+      - 'pyqpanda-algorithm/pyqpanda_alg/LabScheduling/**'
+      - 'pyqpanda-algorithm/pyqpanda_alg/QAOA/**'
+      - 'pyqpanda-algorithm/example/LabScheduling/**'
+      - 'test/LabScheduling/**'
+      - '.github/workflows/lab-scheduling.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  cpu-tests:
+    name: CPU tests / Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python: '3.11'
+            constraints: constraints-py311.txt
+          - python: '3.12'
+            constraints: constraints-py312.txt
+          - python: '3.13'
+            constraints: constraints-py312.txt
+    env:
+      OMP_NUM_THREADS: '1'
+      OPENBLAS_NUM_THREADS: '1'
+      MPLBACKEND: Agg
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install tested dependencies inside project venv
+        run: |
+          python -m venv .venv
+          .venv/bin/python -m pip install -c pyqpanda-algorithm/example/LabScheduling/${{ matrix.constraints }} -e ./pyqpanda-algorithm -r pyqpanda-algorithm/example/LabScheduling/requirements-dev.txt
+          .venv/bin/python -m pip check
+      - name: Lint, format and type checks
+        run: |
+          .venv/bin/python -m ruff check --config test/LabScheduling/ruff.toml pyqpanda-algorithm/pyqpanda_alg/LabScheduling test/LabScheduling pyqpanda-algorithm/example/LabScheduling
+          .venv/bin/python -m ruff format --check --config test/LabScheduling/ruff.toml pyqpanda-algorithm/pyqpanda_alg/LabScheduling test/LabScheduling pyqpanda-algorithm/example/LabScheduling
+          .venv/bin/python -m mypy --config-file test/LabScheduling/mypy.ini --python-version ${{ matrix.python }} pyqpanda-algorithm/pyqpanda_alg/LabScheduling
+      - name: Mathematical and real CPU simulator tests
+        run: |
+          .venv/bin/python -m pytest -c test/LabScheduling/pytest.ini test/LabScheduling --timeout=60 --cov=pyqpanda-algorithm/pyqpanda_alg/LabScheduling --cov-fail-under=95
+      - name: End-to-end medium example
+        run: |
+          .venv/bin/python -m pyqpanda_alg.LabScheduling pyqpanda-algorithm/example/LabScheduling/data/medium.json --output reports/medium.json
+      - name: Existing upstream algorithm tests
+        run: |
+          .venv/bin/python -m pytest -c test/LabScheduling/pytest.ini -o 'python_files=Test_*.py' test --ignore=test/LabScheduling --timeout=60
+      - name: Booking cascade and unchanged control
+        run: |
+          .venv/bin/python pyqpanda-algorithm/example/LabScheduling/booking_demo.py
+      - name: Coupled booking tradeoff, unchanged control and weight sensitivity
+        run: |
+          .venv/bin/python pyqpanda-algorithm/example/LabScheduling/tradeoff_demo.py --sensitivity
+      - name: Arc pruning crosses the simulator resource boundary
+        run: |
+          .venv/bin/python -m pyqpanda_alg.LabScheduling pyqpanda-algorithm/example/LabScheduling/data/support-chain.json --reduce --pruning arc --output reports/support-chain.json
+      - name: Expected failure states remain explicit
+        run: |
+          .venv/bin/python - <<'PY'
+          import json
+          import subprocess
+          import sys
+          from pathlib import Path
+
+          data = Path('pyqpanda-algorithm/example/LabScheduling/data')
+          for name, code, status in [
+              ('support-chain', 5, 'resource_limit'),
+              ('infeasible', 3, 'infeasible'),
+          ]:
+              output = Path('reports') / (name + '-failure.json')
+              result = subprocess.run([
+                  sys.executable, '-m', 'pyqpanda_alg.LabScheduling',
+                  str(data / (name + '.json')), '--reduce', '--output', str(output),
+              ], check=False)
+              assert result.returncode == code, (name, result.returncode)
+              assert json.loads(output.read_text())['status'] == status
+          PY

.gitignore

@@ -44,3 +44,12 @@ pyqpanda-algorithm/pyqpanda_alg/QSolver/*.lib
 /pyqpanda-algorithm/pyqpanda_alg/QSolver/libcurl.dll
 
 .ccls-cache
+
+# Local scheduling development artifacts
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+allure-results/

AWARD_REVIEW.md

@@ -0,0 +1,165 @@
+# LabReschedule 竞争力复审与增强方案
+
+日期：2026-09-21。队伍：youshen。性质：本地评审建议，不是新增功能交付或获奖承诺。
+PR #92 已存在；本轮不推送、不更新 PR、不操作比赛平台。
+本文保留增强前的评审意见；后续已获批准的实现与验证见
+[增强教程](Tutorials/LabScheduling/ENHANCEMENTS.md)。
+
+## 先校准目标
+
+[官网奖项总览](https://qcloud.originqc.com.cn/learning/zh/2026ccf)目前将开源创新赛道
+列为 10 队获奖，每队 1000 元、价值 1.8 万元机时及证书，没有列出“特等奖”。
+官网的特等奖属于其他赛道，不能把它们套用到本作品。
+[赛题 #13](https://github.com/OriginQ/pyqpanda-algorithm/issues/13)要求完整创新应用、
+PR 到 develop、维护者评审，未给出可核实的分项评分权重。
+因此下文是争取本赛道领先作品的工程判断，不是官方评分表。
+
+## 当前判断
+
+当前版本是工程基础扎实、数学可核验的小规模完整应用。但仅凭两个手工样例、
+三种子和“均找到最优”，还不足以支撑领先竞争力。主要缺口是：
+
+1. 样例过易：中等例只有 4 个任务、81 种 one-hot 组合。
+2. 业务价值尚未验证：没有真实用户反馈或公开可追溯的业务数据；显式候选需要手工提供。
+3. 量子收益不稳定：成功样本掩盖了概率分布差异；可行率不等于最优命中率。
+4. 扩展边界硬：整体超过 16 比特即无法运行量子路径，没有问题分解与重建机制。
+5. 创新主要在场景组合；QUBO、W 初态、XY 混合器本身已有研究，不能列作原创算法。
+
+现有 56 项测试、98.46% 覆盖率、独立精确认证和诚实呈现失败仍是重要基础。
+其他开放作品已有多实例、资源审计或硬件证据；堆文档、加测试数量不能替代核心贡献。
+参照对象是 [PR #53](https://github.com/OriginQ/pyqpanda-algorithm/pull/53) 和
+[PR #60](https://github.com/OriginQ/pyqpanda-algorithm/pull/60) 的公开正文；未独立认证其全部实验。
+
+## 本轮实际复核的新证据
+
+复用归档的最终参数，在当前 PyQPanda3 CPU 模拟器中重新计算完整分布。
+均匀基线在每个任务域独立等概率选择。两例均只有一个全局最优排程。
+下表是给定已训练分布时、独立采样的理论命中指标，不含训练成本。
+
+| medium 方法 | 单次最优概率 | 达到至少 95% 最优命中率需要的 shots |
+|---|---:|---:|
+| 均匀 one-hot | 1.2346% | 242 |
+| XY，seed 7 | 4.6071% | 64 |
+| XY，seed 19 | 9.1657% | 32 |
+| XY，seed 42 | 0.3066% | 976 |
+
+计算公式为 `P(hit in S)=1-(1-p_opt)^S`。均匀基线在 512 shots 下已达
+99.8271%；因此原来的 512 shots 最优值对比区分度很低。
+simple 的 seed 19 同样存在退化：最优概率 1.4736%，低于均匀基线 11.1111%。
+原始复核数据保存在本地 `reports/award-review/lab-award-probe.json`。
+
+另做了不修改正式代码的线路实验：只在 XY 成本相位中删除 one-hot 惩罚，
+保留原惩罚缩放、初态和混合器。原因是整个演化都处于每任务恰选一次的子空间，
+该罚项在此处恒为零；其指数作用为恒等算符。
+
+| 实例，p=1 | CNOT 原始→简化 | 原生线路深度原始→简化 |
+|---|---:|---:|
+| simple | 34→22（降低 35.3%） | 36→24 |
+| medium | 78→54（降低 30.8%） | 45→35 |
+
+每例检查 15 组参数，覆盖 p=1/2/3；概率最大绝对差分别为 3.61e-16、1.18e-16。
+该探索验证不是正式回归测试，也不证明有噪声硬件执行等价。
+它沿用已有约束子空间思想，不是新发明的量子算法。
+原始数据：`reports/award-review/lab-award-circuit-probe.json`。
+背景参考：[Wang 等，XY-mixers](https://arxiv.org/abs/1904.09314)。
+
+## 推荐的主线
+
+把作品聚焦为：**把设备故障后的重排问题，经过有保证的约束化简，转成可在有限
+量子资源下求解的子问题，并对资源节省、解质量和失败边界给出完整证据。**
+优先保证可证明的节省与真实可用性，再研究随机优化收益。
+
+| 优先级 | 工作 | 价值 | 预计工作量 | 关键风险 |
+|---|---|---|---|---|
+| P0 | XY 成本线路删除恒零 one-hot 惩罚 | 已有确定门数节省证据 | 0.5–1 天 | 不可用于 X 分支；仍保留完整 QUBO 审计 |
+| P0 | 安全候选化简、冲突分量分解、原问题重建 | 从小演示走向受资源约束的工具 | 2–3 天 | 不得把启发式冻结称为全局等价 |
+| P0 | 多实例留出评测、低 shots 曲线、强经典基线 | 证明有效范围，暴露退化 | 1–2 天，可与实现交叉 | 调参泄漏、预算比较失真 |
+| P1 | 面向预约业务的数据入口与变更说明 | 用户可直接理解和复用 | 0.5–1 天 | 合成数据冒充真实需求 |
+
+### 化简必须守住的数学边界
+
+- 单候选任务固定，向相邻任务传播不兼容候选删除；空域是不可行证明。
+- 二元约束的无支持候选可以安全删除，但局部一致性不能证明全局可行。
+- 同任务候选支配可作为后续项：更低或相等成本、冲突邻域为子集时，可保留更优候选；
+  一般只保证最优值保留，不能声称所有可行排程都原样保留。实现须处理等价候选稳定保留。
+- 在任务冲突图上做连通分量分解。没有跨分量约束且目标可加时，子问题最优值可相加；
+  QAOA 子问题未最优时，组装解也没有全局最优保证。每个组件仍需实际检查可行性。
+- 固定变量必须回填，成本偏移必须累计，最终在原始输入上重新检查全部约束。
+- 某个分量仍超过资源上限时明确报告，不静默截断候选，不把任意切块叫精确分解。
+- “只重排直接受停机影响的任务”通常不保持最优：冲突会传播。
+  如增加固定其余预约的局部启发式，必须作为单独模式报告边界、失败和次优差距。
+
+### 实验设计与验收
+
+1. 先冻结生成器、实例清单和参数选择规则。建议 24 个留出实例，覆盖候选规模、
+   冲突密度、停机强度及链式工序；另设开发集，不看留出结果再调默认参数。
+2. 至少 10 个优化种子；shots 取 8/16/32/64/128/512。用固定训练分布作解析曲线，
+   再用独立采样种子核验；不要把同一分布的重复抽样当独立训练样本。
+3. 对照包括原始 XY、简化 XY、均匀 one-hot、业务贪心/修复，以及独立经典优化器。
+   可用已有 SciPy 的 MILP，从原始时段/日历/前序独立构建约束，避免复用 QUBO
+   编译后的冲突图及剪枝作为唯一输入；不借 QUBO 罚函数作唯一裁判。
+   超时输出 incumbent、bound 和 gap，不能冒充最优证书。
+4. 报告最优命中率、可行率、目标差距、变更预约数量、最大时间移动量、比特数、
+   二比特门数、深度、峰值内存和端到端时间。训练评估次数和模拟开销单独列出。
+   采样预算对齐不代表总计算预算对齐；不能把训练完成后的 shots 节省叫整体加速。
+5. 化简在至少 100 个小规模生成实例上用穷举核对最优值、可行性和重建；加入
+   连锁删除、不可行、完全连通、完全独立、单候选及相等成本等反例测试。
+6. 简化线路加入 p=1/2/3、随机参数、不同域大小和单候选的真实 CPU 回归，
+   建议分布误差阈值 1e-10，记录门数下降；原始 X 路径保留完整约束。
+7. 报告所有预先登记实例，包括未改善、资源超限和采样失败。
+   若量子效果不稳，收缩为“可证明资源压缩与可审计求解”，不包装成稳定优于经典。
+
+### 业务展示
+
+提供原预约→故障→调整后预约的离线甘特图，标出每个变更的原因及成本构成。
+补一个从时间窗、可用设备生成显式候选的入口，或先给出透明的导入模板。
+如没有可公开真实数据，就标为合成压力测试；需求访谈和匿名实际试用有价值，
+但不能由模型编造。保留成本权重解释，避免把加权成本最小误称为变更人数最少。
+
+## 截至 9 月 28 日的执行顺序
+
+- 9/21：完成复审，冻结原版本及评价口径；本轮仅本地文档和探索证据。
+- 9/22：线路简化正式实现与回归；冻结基准生成规则、开发/留出划分。
+- 9/23–24：安全化简、分解、重建；穷举反例和独立经典求解器。
+- 9/25–26：多实例盲测、全部失败记录、成本拆分和业务展示。
+- 9/27：干净环境复现、完整相关测试、最终 diff 与评委演示。
+- 9/28：展示增强版本与真实结果，再按用户最新授权决定是否更新已有 PR。
+
+若化简无法按时证明正确，缩减为单候选传播和严格独立分量；先交付确定可靠的收益。
+若 9/23 前分量分解仍不稳定，暂不加入，保底包为：XY 相位简化、独立 MILP、
+至少 12 个实例 × 10 个优化种子的探索性证据，以及一个连锁改约案例。
+不优先增加 Web/数据库、预测模型、新 QAOA 变体、复杂噪声模型或真机依赖。
+不为凑规模拼接互不相关小例后声称解决了同规模一般调度。
+
+## 独立审查记录
+
+本轮按用户要求委派一个子 agent 完成独立代码、实验和规则审查。
+详细原稿保存于本地 `reports/award-review/independent-review.md`，未提交到 Git。
+其中概率和门数复核由主 agent 实际运行后提供，子 agent 将其纳入综合评审。
+两个审查视角的共同结论及分歧后的优先级已在本文汇总。
+
+## 增强后的主工程师收敛判断（2026-09-21）
+
+上文是历史审查；本节依据已交付成果更新工程判断，不是官方评分或新增独立评审。
+
+| 原缺口 | 当前证据 | 仍然存在的边界 |
+|---|---|---|
+| 少量手工样例 | 36 个冻结异构实例、多种子、全部失败记录及完整重放 | 仍是小规模合成数据 |
+| 量子资源上限 | 精确分量回填、可选 AC-3、18→12 受控案例、可行集合保持证明 | 不解决一般大连通调度 |
+| 量子收益难解释 | 同总预算与均匀随机对照，低 shots 概率及退化公开 | 不存在已证实的端到端量子优势 |
+| 业务入口和解释 | CSV 时间窗、原预约变更表、成本阈值与并列最优 | 没有真实用户试用或经济收益证据 |
+| 可复现与交付 | 三版本 CI、独立 wheel 安装、源文件指纹、失败退出码 | 官方工作流仍需维护者批准 |
+
+再次审查找到并修复了一个实质边界：大量原始候选被日历剪枝后已可量子求解，
+却因独立 MILP 超过 2048 原始候选而丢失整个报告。现在显式记录该基线超预算，
+保留实际样本和可用的穷举证书；两个认证路径都不可用时不填写最优差距。
+五项新增回归在修复前四失败、一通过，修复后全部通过；五个既有案例的全部
+非计时报告字段与修复前一致。当前 113 项应用测试通过，核心覆盖率 98.92%。
+
+工程判断：已达到完整参赛交付和接受维护者实质评审的标准。现阶段再追加通用
+算法、重复 PR 或更大合成实验，预期价值低于处理评审意见和取得一次真实试用。
+本轮结束主动功能扩张；后续仅由可复现缺陷、实际需求或维护者意见触发代码修改。
+奖项由主办方决定，当前材料不能支持获奖概率或“必进前十”的判断。
+
+对外展示以 REVIEW_GUIDE 的五分钟路线与六个答辩问题为准。参赛平台回执、
+官方审核以及未获奖是否发证明仍应单独核验，不能由工程测试通过替代。