权重保存与酉矩阵拟合

适用版本 · ArcQML 0.1.0

权重检查点的文件契约

save_weights 写入格式化 JSON，固定 format 为 arcqml/weights。每个参数记录 name、dtype 与 value；记录先按名称排序，使相同状态得到稳定顺序。写入只接受 numel=1 的 F32/F64 Circuit Parameter。

{
  "format": "arcqml/weights",
  "num_qubits": 2,
  "parameters": [
    {"name": "ry_q0_theta_0", "dtype": "f64", "value": 0.36154268969437336}
  ]
}

load_weights 先校验 format、量子比特数、参数名集合、重复名称、dtype 和 JSON 解析出的有限 value，并预先构造替换 Tensor；然后写入参数并清空梯度。它不会比对门拓扑，因此调用方必须以预期的同构 Circuit 重建模型。

DenseUnitary 的数据契约

DenseUnitary 保存 num_qubits、dimension 和 row-major C64 数据。dimension 必须是 2 的幂；公开数据先使用输出计算基索引，再使用输入计算基索引。DenseUnitary::from_tensor 只检查 C64、二维方阵、连续复制后的长度和有限性；公共 unitary_from_tensor 在此基础上使用以下默认容差完整验证酉性：

unitary_from_circuit 通过对所有计算基初态组成的内部 batch 执行 Circuit，再转置为公开 row-major 布局。对于 n 个量子比特，其空间复杂度为：

单份矩阵数据约占 16 × 4^n 字节，内部计算还需额外缓冲区。因此，该功能适用于小规模电路比较和综合。

酉保真度、损失与解析梯度

目标整体酉矩阵与当前电路整体酉矩阵的迹重叠、整体酉保真度和损失分别定义为：

与状态分析与抽样的纯态 fidelity 不同，此处会显式执行从 0 到 1 的区间截断，以限制数值舍入造成的越界。

unitary_loss 返回可纳入统一自动微分的 F64 标量。其反向先按逆序恢复前向 StateBatch，再按照未截断目标的解析式累积每个参数的梯度，并乘上外层标量上游梯度：

该梯度实现不在前向截断区间外额外置零。对精确酉矩阵，未截断保真度理论上不超过 1；若把未经酉性验证的 DenseUnitary 当作目标，可能得到被截断的损失与上述梯度不一致的结果。unitary_loss 本身只检查与电路的量子比特数兼容，目标应通过 unitary_from_tensor 或显式 validate 验证。数值舍入导致的轻微越界仍需按该实现语义理解。