Tensor 与自动微分

适用版本 · ArcQML 0.1.0

Tensor 的数据与元数据

Tensor 是用户直接操作的数值对象。它把 Storage、版本号、TensorMeta 和 AutogradMeta 组合在共享句柄中。TensorMeta 包含 shape、dtype、device、layout、strides 和 offset；公开查询包括 shape、ndim、numel、dtype、device、layout、is_contiguous、strides 和 offset。

Tensor::clone() 只复制句柄，仍共享底层 Storage、版本号和自动微分元数据。deep_clone() 复制数值、Tensor 元数据和已有梯度，保留 requires_grad 标志，但创建独立存储、独立版本计数的新叶子 Tensor，不继承原计算图；它不是可微复制算子。storage_mut() 取得写锁，并在 guard 释放时递增共享版本号；这个版本号用于在反向前检测前向数据被原地修改的情形。

自动微分图与梯度生命周期

只有叶子 Tensor 可以开启 requires_grad；可求导叶子 dtype 仅限 F32、F64、C64。由可微操作产生的输出会在当前线程的梯度记录开关开启且至少一个父节点需要梯度时记录图。默认只持久保存叶子梯度；中间 Tensor 必须显式调用 retain_grad() 才会保留。

backward() 只为 shape=[] 的标量输出自动构造上游梯度 1。非标量输出必须使用 backward_with_grad(gradient)，且上游梯度与输出在形状、dtype 等方面兼容。默认 backward 会释放本次遍历的图节点；若要复用图，应从第一次反向起使用 backward_with_grad_retain_graph，不能在图释放后补救。retain_grad() 只保留中间梯度，不保留计算图。梯度以累积方式写入，因此训练迭代必须显式调用 zero_grad。共享前向的多个损失优先合成一个标量后反向。

Parameter 的语义

Parameter 是 Tensor 的语义包装，是框架中可训练参数的主要数值对象。Parameter::new 要求底层 Tensor 是叶子且 dtype 为 F32、F64 或 C64，并会将其 requires_grad 置为 true；默认 trainable 为 true。非法输入会 panic，需要可恢复错误时使用 Parameter::try_new。Circuit 参数登记检查 numel=1 且为 F32/F64，训练时应使用 shape=[] 的标量参数；量子门角度训练不接受 C64 参数。

freeze() 将 trainable 设为 false，优化器随后会跳过该参数；它不会同时关闭底层 Tensor 的 requires_grad，因此该参数仍可能接收梯度。unfreeze() 会恢复 trainable=true，并确保底层 Tensor 开启梯度记录。换言之，requires_grad 控制是否参与反向传播，trainable 控制优化器是否更新参数。