---
name: mindquantum-differentiable
description: 使用 华为 HiQ / 昇思生态 的 MindQuantum 在本地对用户定义量子线路计算原始态概率、Pauli 期望和指定旋转角的解析梯度。
---

# MindQuantum 可微分量子线路

当用户需要用 MindQuantum 计算线路期望、验证变分线路导数或与其他 SDK 交叉对照时，Agent 经 Harness 调用 `mindquantum_local` 提供的 `differentiate_mindquantum_circuit`。本 Skill 指导参数选择与结果解释；计算由 mqvector + adjoint gradient 完成。

- `numQubits` 与 `gates` 定义全零初态的理想酉线路。支持 H、X、Y、Z、S、T、RX、RY、RZ、CX、CZ、SWAP；双比特门的 targets 为 `[control,target]`（SWAP 为两个交换位），角度单位 rad。
- `observables` 是与量子位数同长的 I/X/Y/Z 字符串，最左字符对应 q0。例如 `ZI` 表示 Z0，`XY` 表示 X0Y1；输出期望保留输入顺序。加权 Hamiltonian 可由调用方按系数组合期望和 Jacobian，勿把 Pauli words 当作系数。
- `trainableGateIndices` 明确选择 gates 数组中需要求导的 RX/RY/RZ；每项是独立参数。可填空数组只做仿真。Jacobian 行对应 observables，列严格对应该索引数组的顺序，不是所有旋转门的隐含顺序。
- `amplitudes[k]` 为 `[real,imag]`，概率向量按 q0 在最左的二进制字典序排列。返回 SDK 原始数值，不裁剪、不归一化；`stateNormSquared` 用来检查数值漂移。这些是精确线路仿真的数值期望，不是 finite-shots 频数。
- 参数数量、量子位数和门数由调用方决定；完整输出按 2^N 增长，可寻址数组表示限制仍适用。资源预算通过独立 `execution` 参数设置，不改变线路语义。
- OpenQuantum Harness 对大结果自动返回 `openquantum-science-summary`：先查看 `summary.result` 中的期望、Jacobian、范数与单位；需要完整态矢量时，用已有文件或 shell Tool 读取会话工作区内的 `fullResult.path`，再取 JSON 的 `result.amplitudes` / `result.probabilities`。`omitted: true` 表示数据保存在文件中，不表示零值或计算缺失；不要为了获取被省略的数据重新计算。保存失败时仍返回完整输出，科学状态保持 `not_evaluated`。
- MindQuantum 0.12.0 使用 Python 3.11；本工具将上游 q0 为最低位的态向量转换为统一的 q0 最左顺序。
- 梯度仅对当前输入的理想线路有效，不自动构成优化收敛、抗噪声能力或硬件优势结论。对复杂电路先选择解析可核对例子，必要时与第二 SDK、参数移位或有限差分对照。
- 当前是 L1，`scientificValidation=not_evaluated`；成功计算与数值回归不等于最终科学 Acceptance。

首次使用前显式运行 `node scripts/setup-paper-tools.mjs mindquantum-differentiable` 准备固定依赖。计算不会安装依赖、提交云/QPU 或读取凭据，数值库可能写本地缓存。上游许可为 Apache-2.0，详细版本锁见本目录 `pyproject.toml` 和 `uv.lock`；[官方接口来源](https://www.mindspore.cn/mindquantum/docs/en/r0.12/simulator/mindquantum.simulator.Simulator.html)。