正确性验证与排错

适用版本 · ArcQML 0.1.0

本页目录

13.1 推荐的正确性用例

用例	应验证的事实	适合定位的问题
X 门作用于全零态	最终概率全部落在翻转后的基态	`q0` 对应最低有效位的索引约定与单比特门。
Hadamard 门作用于全零态	两个单量子比特计算基结果等概率	Hadamard、振幅到概率。
Bell 态	仅全零与全一结果出现，且两者概率相等	CNOT 顺序、二进制字符串显示与抽样。
Y 轴旋转门与 Pauli-Z 测量	期望值及其梯度与解析结果一致	参数门、期望值与梯度。
共享 ParameterId	同一参数多处贡献相加	参数表与伴随梯度累积。
batch vs 单态逐样本	逐行输出与梯度一致	row-major batch 内核。
checkpoint 非法输入	失败后目标参数不改变	恢复原子性。
unitary loss	相同酉的损失为 0 或数值近零	整体酉布局、trace overlap 和梯度。

其中，Y 轴旋转门作用于全零初态后，Pauli-Z 期望值的解析结果为：

\langle Z\rangle=\cos\theta.

安装或升级 ArcQML 后，应先按第 2 章完成环境检查，再运行发行包 examples 目录中的 H₂ VQE 示例。该示例覆盖含参量子电路、Hamiltonian 期望值、损失函数、反向传播和 Adam 参数更新，可用于验证 Runtime 链接及完整训练链路。需要进一步验证索引约定时，可依次检查单比特 X 门、Hadamard 门、Bell 态以及 Y 轴旋转门的 Pauli-Z 期望值与梯度。闭源发行包的验收应以公开接口和随附示例为边界，不要求用户构建 Runtime 或运行内部 workspace 测试。

13.2 常见问题与排查方法

现象	真实原因	修复方向
Rust 链接时找不到 `arcqml_runtime_private`	未设置 `ARCQML_RUNTIME_LIB_DIR`，路径不是对应平台的 `libs` 子目录，或 Runtime 文件被移动。	按第 2.2 节重新设置绝对路径，并确认 `.lib` 或 `.a` 文件存在。
Rust 链接报文件格式或架构不兼容	使用了错误操作系统、工具链或 CPU 架构的 Runtime。	Windows x86_64 MSVC 使用 `x86_64-pc-windows-msvc`；Linux x86_64 GNU 使用 `x86_64-unknown-linux-gnu`。
程序在 ABI 调用处报告版本不匹配	接口层和 Runtime 来自不同版本的发行包。	恢复同一发行包中的 `crates` 与 `libs`，不要混合覆盖二进制库。
pip 提示 wheel 不受支持	Python 不是 CPython 3.11，或系统不是 Linux x86_64。	创建 `python=3.11` 的 Conda 环境并核对平台；不要改名强行安装。
Python 导入失败	wheel 未安装在当前解释器，或终端未激活 `arcqml-example`。	激活环境后使用 `python -m pip show arcqml` 与 `python -c "import arcqml"` 核对。
backward() 报错	输出非标量或不需要梯度，或计算图已释放。	对 loss 做标量归约；改用 backward_with_grad；必要时 retain_graph。
参数未更新	门为 _fixed、Parameter 已冻结、requires_grad=false 或 grad=None。	检查 Circuit 参数表、trainable、梯度生命周期和运行路径。
导入初态失败	dtype 不是 C64、非连续、shape 不匹配或范数偏离 1 超过 1e-10。	使用正确 shape/dtype/连续布局并归一化。
batch 创建失败	batch 大小为零或二维第二维不是状态空间维数。	构造非空 `[B, d]` C64 行主序数组，其中 `d` 见第 3.1 节。
抽样键看起来反了	混淆“`q0` 对应最低有效位”和“字符串从最高编号显示到 `q0`”两个顺序。	按本手册第 3.2 节检查索引与显示规则。
checkpoint 不兼容	量子比特数、参数名集合、dtype 或值校验失败。	用同构 Circuit 重建，再加载权重。

13.3 API 参考与版本兼容

本手册说明发行环境、数学约定、训练链路和典型组合方式。完整接口以发行包内与二进制版本配套的 Rust API（发行包内 api/rust.md）和 Python API（发行包内 api/python.md）为准；完整任务可参考 H₂ VQE 教程与 QNN 信用分类教程。不要用其他发行版本的 API 文档、crates、Runtime 或 wheel 替换当前文件。

bash

# Rust：先按第 2.2 节设置 ARCQML_RUNTIME_LIB_DIR
cargo run --release -p arcqml --example h2_vqe

# Python：在已安装 wheel 的 arcqml-example 环境中执行
python ./examples/python/h2_vqe.py

升级版本时应整体替换发行包，并重点核对 Runtime ABI、wheel 的 Python/平台标签、门的参数顺序、Tensor 的 shape 与 dtype、接口是否修改模拟器状态，以及返回值是否保留自动微分图。量子比特 q0 对应计算基索引的最低有效位，而抽样字符串按 q[n−1]...q0 显示；这两个约定在跨语言调用和结果对比时尤其重要。

下载完整 Markdown 技术手册 ↓