Metadata-Version: 2.4
Name: deepquantum-operator
Version: 0.4.0
Summary: A quantum operator optimization agent with reusable domain libraries and reproducible measurements
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: deepquantum==4.5.0
Requires-Dist: torch==2.5.1
Requires-Dist: numpy==2.4.6
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Requires-Dist: PyYAML<7,>=6; extra == "dev"
Dynamic: license-file

# DeepQuantum Operator（dqop）

<!-- package-version -->
软件版本：**0.4.0** · [版本来源](pyproject.toml)
<!-- /package-version -->

**[Agent Quickstart](DEMO.md) · [Agent 输入输出](AGENT_IO.md) · [算子列表](OPERATORS.md) · [案例目录](examples/README.md) · [复用统计](#reuse) · [deepquantum-operator skill](.agents/skills/deepquantum-operator/SKILL.md)**

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

Agent 提供两项能力：

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

Agent 由 **Codex CLI + [deepquantum-operator skill](.agents/skills/deepquantum-operator/SKILL.md) + 行业算子库和验证、测量工具**组成：

| 组件 | 职责 |
|---|---|
| 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 官方安装器](https://github.com/conda-forge/miniforge#install)：

```bash
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、跑通案例

```bash
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 Å 几何；验收能量误差、粒子数及扇区泄漏。

<a id="skill"></a>

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

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

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

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

完整目标与预期交付见 [Agent Quickstart](DEMO.md#optimize)，非交互调用及结果读取见 [脚本集成](DEMO.md#integration)。官方说明：[CLI](https://learn.chatgpt.com/docs/codex/cli)、[登录](https://learn.chatgpt.com/docs/auth)、[skill 加载](https://learn.chatgpt.com/docs/build-skills)。

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

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

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

```text
$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，见 [环境指南](docs/ENVIRONMENTS.md)。模型负责源码分析和实现，工具负责执行、比较与记录结果。

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

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

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

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

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

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

<a id="optimize"></a>

## 功能 2：优化已有算子

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

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

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

**直接运行已有对照：**

```bash
# 双激发：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](AGENT_IO.md)。

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

```python
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](docs/API.md#benchmark-operator)。

**读取 `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 见 [双激发](evidence/optimization/double/result.json) 和 [能量](evidence/optimization/energy/result.json)。返回值不等价时拒绝候选、跳过对应计时；`improved` 仅表示实测中位数改善。性能实验本身不会切换公共实现，结果通过后仍由模型完成候选接入和回归；现有版本可用 `implementation="optimized"` 调用。

## 直接调用算子

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

```python
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。**[算子列表](OPERATORS.md)** 区分量子算子、经典辅助及工作流；**[API 文档](docs/API.md)** 说明参数与形状。`optimized` 不保证在每个规模上更快。

## 端到端教程与扩展

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

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

<a id="reuse"></a>

## 查看算子复用统计

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

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

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

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

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

下面是本次发布 [reuse.json](evidence/reuse.json) 的真实输出，从 `operators` 中截取双激发接口：

```json
{
  "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 如何把候选封装成公共模块，见 [算子扩展指南](docs/EXTENDING.md)。

## 功能与性能

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

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

<a id="release-version"></a>

## 开发与分发

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

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

```bash
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](THIRD_PARTY_NOTICES.md)。本次发布的验证记录见 [测试报告](TEST_REPORT.md) 和 [运行证据](evidence/README.md)。
