DeepQuantum Operator（dqop）

软件版本：0.4.0 · 版本来源

Agent Quickstart · Agent 输入输出 · 算子列表 · 案例目录 · 复用统计 · deepquantum-operator skill

DeepQuantum Operator（dqop）是一个量子算子优化 Agent。 你定义目标与约束，模型自主决定实现方法、验证和迭代安排，交付可运行代码、调用方式与实验结果。

Agent 提供两项能力：

• 复现论文／案例，积累算子：将其他量子框架的案例或有代码论文复现为 DeepQuantum 版本，比较源／目标结果，记录实际算子复用，并提炼可复用模块。
• 优化已有算子：根据指定负载与误差、性能目标，保留优化前实现，自主编写并验证候选，交付记录优化前后性能的 JSON；未达标也如实记录。

Agent 由 Codex CLI + deepquantum-operator skill + 行业算子库和验证、测量工具组成：

组件	职责
Codex CLI	接收自然语言任务，让模型阅读源码、编写代码、调用工具并根据结果迭代
deepquantum-operator skill	提供复现、优化与算子积累的任务约定、工具入口和交付要求
行业算子库	按领域提供可调用、复用和继续优化的标准模块，首个库为 QuChem
dqop 与 Python 测量接口	执行案例、比较数值、测量前后性能、统计复用并保存证据

“自行分析并实现候选”：Codex 阅读源码、编写新实现、补充验证，再调用 benchmark_operator 测量优化前后性能。

通过验证、在独立来源中重复使用的实现逐步封装为标准算子，供后续任务复用和优化。首个行业库是 QuChem（量子化学），其他行业随真实案例扩展。Conda 按需隔离 DeepQuantum、PennyLane、Qiskit 和 CUDA-Q 环境；Python 导入名为 deepquantum_operator，CLI 为 dqop，skill 为 deepquantum-operator，模型负责分析与实现，工具负责可重复的验证与测量。

新电脑：安装并运行

支持 Linux x86_64、macOS 14+ Apple silicon；Windows 使用 WSL2。首轮 CPU 案例无需 GPU。先安装 Git/curl，并为有访问权限的 GitHub 账号配置 SSH 或 HTTPS 凭据。本仓库为私有仓库。

1. 安装 Conda（已有则跳过）

使用 Miniforge 官方安装器：

DQOP_OS="$(uname)"
if [ "$DQOP_OS" = "Darwin" ]; then DQOP_OS="MacOSX"; fi
curl -fL -o Miniforge3.sh \
  "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-${DQOP_OS}-$(uname -m).sh"
bash Miniforge3.sh -b -p "$HOME/miniforge3"
source "$HOME/miniforge3/etc/profile.d/conda.sh"

已有同名安装目录时使用已有安装。长期使用可 conda init zsh（或 Linux 的 conda init bash），然后重启终端。

2. 克隆、安装 QuChem、跑通案例

git clone git@github.com:xiangmind/deepquantum-operator.git
cd deepquantum-operator
bash scripts/bootstrap.sh runtime
conda activate dqop-runtime
dqop doctor
dqop --version
dqop list --domain quchem
dqop demo h2-vqe

安装器创建 dqop-runtime，安装 DeepQuantum 4.5.0、Torch 2.5.1 和本包，执行依赖/Bell 态检查，保存环境快照。H₂ 示例应得到约 −1.136189454 Hartree，结果在 runs/h2-vqe/。这个内置数据使用 0.7 Å 几何；验收能量误差、粒子数及扇区泄漏。

3. 安装、登录 Codex CLI，启动 Agent

bash scripts/bootstrap.sh codex
export PATH="$HOME/.local/bin:$PATH"
codex login
codex login status
codex

登录需要本人在浏览器完成。仓库唯一的技能文件是 .agents/skills/deepquantum-operator/SKILL.md；从仓库根启动 Codex 自动发现，无需全局安装。.agents 是隐藏目录，也可通过本页顶部的 deepquantum-operator skill 链接直接打开。在 Codex 中向 Agent 提交任务：

$deepquantum-operator 按 DEMO.md 的“优化已有算子”任务，自行分析并实现候选，交付代码、验证和性能结果。

完整目标与预期交付见 Agent Quickstart，非交互调用及结果读取见 脚本集成。官方说明：CLI、登录、skill 加载。

环境、API、CLI、案例与 Agent 的实际验收见 测试报告，包含执行范围、原始性能 JSON 与复跑命令。

功能 1：复现论文／案例，积累算子

在 Codex 中向 Agent 提供源代码和要复现的具体实验：

$deepquantum-operator 将 <源代码URL>@<commit> 的 <具体实验或图表> 移植到 DeepQuantum。
保留科学输入和优化预算，优先复用 QuChem，比较源/目标结果，再提炼重复算子。
交付可运行代码、对比报告、调用方式和复用统计。

Agent 根据任务需要安装参考框架：bash scripts/bootstrap.sh pennylane、bash scripts/bootstrap.sh qiskit 或 bash scripts/bootstrap.sh cudaq，分别使用独立 Conda 环境。需要旧版依赖时指定专用环境/Python/requirements，见 环境指南。模型负责源码分析和实现，工具负责执行、比较与记录结果。

重跑已有的 PennyLane VQE 迁移案例：

bash scripts/bootstrap.sh pennylane
dqop reproduce run examples/pennylane_vqe --output runs/pennylane-vqe

工具校验源文件 commit/SHA-256，在 PennyLane 环境运行参考，再在当前 DeepQuantum 环境运行目标，比较全部参数/能量/梯度轨迹及最终态，保存报告与复用统计。示例采用 PennyLane VQE 教程 明确给出的本地 Hamiltonian 构建选项；参考端接口适配及完整范围见 迁移教程。重复实验使用新的输出目录。

LiH 手动自适应案例（同时验收两项能力）：

# 已有 dqop-runtime 和 dqop-pennylane；从仓库根运行，输出目录须不存在。
bash examples/lih_adaptive/run.sh runs/lih-adaptive-new

该入口固定 CPU 单线程及当前副本 PYTHONPATH=src，依次运行 PennyLane 参考、DeepQuantum 迁移、dqop mine 和新稀疏能量候选的 benchmark_operator。保留教程实际只优化双激发的最终分支，并单独标记修正后的全部已选 gates 分支。完整说明见 案例入口，本次实际结果见 中文验收报告。

功能 2：优化已有算子

在 Codex 中向 Agent 指定算子、工作负载和验收目标：

$deepquantum-operator 优化 quchem.energy 在 H₂ VQE 中的能量和梯度计算。
保留优化前实现与 API，使用 CPU complex128；数值误差不超过 1e-12，
目标至少加速 1.1 倍。实现并验证候选，保存到 runs/energy-candidate，
交付调用方式和记录优化前后性能的 result.json；未达标也保留结果。

算子可以换成 算子列表 中的名称或现有代码路径。Agent 自主选择优化方法和必要的验证，使用测量结果判断是否达到目标。

直接运行已有对照：

# 双激发：naive 通用矩阵 → optimized 稀疏更新；4/12/18 qubits
dqop optimize demo/optimization-request.json --output runs/double-optimization

# 能量：naive 即时构建 observable → optimized 缓存；包含能量与梯度阶段
dqop optimize demo/energy-optimization-request.json --output runs/energy-optimization

这两条命令测量已实现的版本。双激发默认只记录性能；能量示例要求两个测量阶段均达到 1.1×。可修改请求中的 required_qubits、min_speedup 和计时参数，完整字段见 AGENT_IO.md。

衡量模型新写的候选或其他已有算子：

from deepquantum_operator.experiment import benchmark_operator

result = benchmark_operator(
    before=lambda: old_operator(fixed_input),
    after=lambda: new_operator(fixed_input),
    operator="quchem.my_operator",
    scope="说明实际计时的计算阶段",
    output="runs/my-optimization",
    min_speedup=1.1,
)
print(result["accepted"], result["rows"][0]["speedup"])

这里的 old_operator/new_operator/fixed_input 替换为实际代码和相同输入。函数返回数值、Tensor，或 {"energy": ..., "gradient": ...}；接口先比较返回值，再交替多轮计时。该通用接口测同步 CPU，不要求登记算子或继承基类。可直接运行的完整示例：python examples/optimize_operator/run.py --output runs/custom-optimization。更多参数与验证范围见 API。

读取 runs/…/result.json：

字段	含义
rows[].before.median_us / after.median_us	优化前／后的每次调用耗时，中位数，单位 µs
rows[].speedup	前耗时 ÷ 后耗时；大于 1 表示本次测量更快
rows[].latency_reduction_pct	(1 − 后耗时 / 前耗时) × 100；负值表示变慢
rows[].before.samples_us / after.samples_us	各轮原始平均耗时
validation / accepted	正确性、指定性能门槛，以及本次请求是否通过
measurement / environment / source_sha256	计时条件、软件与设备环境、执行源码摘要

完整实测 JSON 见 双激发 和 能量。返回值不等价时拒绝候选、跳过对应计时；improved 仅表示实测中位数改善。性能实验本身不会切换公共实现，结果通过后仍由模型完成候选接入和回归；现有版本可用 implementation="optimized" 调用。

直接调用算子

QuChem 提供普通 Python API，可集成到自己的量子计算程序中。下面构建 H₂ 线路，并计算能量和参数梯度：

import torch
from deepquantum_operator import quchem

h = quchem.hamiltonian("h2", parameter=0.7)
theta = torch.tensor(0.37, dtype=torch.float64, requires_grad=True)
circuit = quchem.hartree_fock(4, [0, 1])
quchem.double_excitation(circuit, theta, [0, 1, 2, 3], implementation="optimized")
energy = quchem.energy(circuit, h)
gradient, = torch.autograd.grad(energy, theta)
print(energy.item(), gradient.item())

位序为 wire 0 = MSB。算子列表 区分量子算子、经典辅助及工作流；API 文档 说明参数与形状。optimized 不保证在每个规模上更快。

端到端教程与扩展

从 案例目录 选择 H₂、Hubbard、跨框架迁移或算子优化。每个案例的背景、环境、命令、预期结果和代码都在同一个 examples/<case>/ 目录中，打开其中的 README.md 即可开始。docs/ 保存 API、环境和架构等通用说明。

当前交付 QuChem；其他行业通过相同目录协议，按真实案例中的复用需求扩展。软件架构 描述模块边界。

查看算子复用统计

从仓库根运行，汇总自己已经完成的案例：

conda activate dqop-runtime
dqop mine runs --output runs/reuse.json

结果会打印到终端，并保存到 runs/reuse.json。命令递归读取输入目录下的 usage.json；这些记录由案例中的 UsageSession 产生。没有有效记录时，结果中的 operators 为空，不会自动扫描代码推测调用次数。

还没有运行案例时，可以直接统计仓库中 本次发布的实验记录，无需重新执行量子计算：

dqop mine evidence --output runs/reuse-archived.json

下面是本次发布 reuse.json 的真实输出，从 operators 中截取双激发接口：

{
  "id": "quchem.double_excitation",
  "distinct_sources": 3,
  "distinct_cases": 5,
  "calls": 6464,
  "source_ids": [
    "pennylane:demonstrations/tutorial_adaptive_circuits",
    "pennylane:h2-vqe-family",
    "project:hubbard-two-site"
  ],
  "registered": true,
  "reused_across_sources": true,
  "extraction_candidate": false
}

本次汇总共有 8 个接口、5 个案例、3 个来源族、25,154 次成功调用。双激发已登记且跨来源复用，因此不需要再次提炼。数字随有效运行记录变化。

字段	如何解读
calls	去重后有效记录中的成功 API 调用总次数
distinct_cases	不同 (source_id, case_id) 的数量
distinct_sources / source_ids	独立科学来源族的数量及标识
registered	是否已登记在当前安装的算子目录中
reused_across_sources	是否达到独立来源门槛，默认至少 2 个
extraction_candidate	尚未登记且达到来源门槛，值得交给 Agent 判断是否提炼

只统计验收通过的记录；同一来源／案例的重跑保留最新有效记录。循环次数、多个键长和同一来源的不同框架移植不会增加独立来源数。dqop mine 提供计数和复用标记，没有内置单一的“复用率”百分比；未被追踪的调用也不会计入。

需要提高来源门槛时，在命令末尾加 --min-sources 3。新案例如何记录调用、以及 Agent 如何把候选封装成公共模块，见 算子扩展指南。

功能与性能

环境安装、算子复用、源/目标差分验证和模块提炼使用同一套命令。双激发保留通用矩阵 naive、稀疏 optimized 与专用门序列 native；能量期望保留即时构建/缓存对照。

本次发布重新运行端到端案例和 naive／optimized 对照。各测量阶段的耗时、加速比、数值误差、设备与原始记录见 功能与性能比较 和 测试报告。性能结论限定于实际测量的输入、设备与计算阶段。

开发与分发

源码位置、数值约定与提交前检查见 AGENTS.md。

发布版本只在 pyproject.toml 的 project.version 修改。Python __version__、dqop --version 和内置算子的 version 读取安装包元数据；README、AGENT_IO 与算子目录的版本标注由现有文档生成器同步。修改版本后重新安装项目，更新 editable 安装的元数据，再运行：

conda activate dqop-runtime
python -m pip install -e '.[dev]'
python scripts/update_operator_docs.py
python -m pytest -q
python -m ruff check src tests scripts examples benchmarks
python scripts/update_operator_docs.py --check
python -m build
python scripts/check_distribution.py
dqop --version

CI 会拒绝过期的生成文档、包版本与安装产物不一致，以及不等于 v<project.version> 的发布标签。已发布标签保留原指向。JSON 的 schema_version 表示数据格式；历史报告和依赖版本记录保留原值。文档同步脚本只同步或检查版本，不自动升级版本。

wheel 提供 API、CLI、算子元数据和内置数据；Git clone 还提供 skill、环境脚本、教程与证据。源码按私有仓库分发，未自动授予开放源代码许可；来源归属见 THIRD_PARTY_NOTICES.md。本次发布的验证记录见 测试报告 和 运行证据。