电路与参数
适用版本 · ArcQML 0.1.0
本页目录
5.1 Circuit 的结构
Circuit 保存 num_qubits、按执行顺序排列的 Operation 列表，以及 Parameter 列表。add_gate 将 Gate 与 qubit 列表包装为 Operation；调用模拟器后，接口层才会校验和绑定参数，并由 ArcQML Runtime 将 Gate 作用到当前量子态。
Circuit::depth() 以量子比特资源为依据计算并行层数：每个 Operation 的层是其涉及各量子比特当前层的最大值加一，并把该层写回所有参与量子比特。
5.2 内置门范围
| 分类 | Rust Circuit 方法 | 参数行为 |
|---|---|---|
| 单比特固定 | i, x, y, z, h, s, sdg, t, tdg, sx, sxdg | 无训练参数。 |
| 单比特参数 | rx, ry, rz, phase, u1, u2, u3 | 默认创建新参数；部分门提供 _fixed 或 _param 变体。 |
| 受控门 | cnot/cx, cy, cz, ch, cs, ct, cp, crx, cry, crz | 输入的前两个 qubit 参数依次是控制位与目标位。 |
| 双/多比特 | swap, iswap, dcx, ecr, rxx, ryy, rzz, rzx, fsim, toffoli, cswap, mcx | 旋转类和 fSim 可训练；其余固定。 |
| 扩展 | Gate::custom_unitary(name, arity, matrix) | 传入 row-major C64 矩阵，创建时验证维度和酉性。 |
Python Circuit 当前提供 h、x、y、z、rx、ry、rz、phase、u3 和 cnot。其门集小于 Rust Circuit；需要其它受控门、多量子比特门或自定义酉门时，应使用 Rust API。
5.3 参数（含参门）的三种添加方式
| 方式 | 例子 | 参数表行为 | 适合场景 |
|---|---|---|---|
| 自动注册 | circuit.ry(0.3, 0) | 生成 F64 标量 Parameter 与稳定自动名称 | 一般可训练门。 |
| 固定参数 | circuit.ry_fixed(0.3, 0) | Gateparam::Fixed；不登记 Parameter | 编码常数、不可训练层。 |
| 显式共享 | id = add_parameter(...)；ry_param(id, 0) |
多个门指向同一个 ParameterId | 对称 ansatz 与共享权重。 |
自动门参数名称由 gate、角色、量子比特与参数表下标组成，例如 ry_q0_theta_0。手动 add_parameter_tensor 的默认名为 parameter_<index>。名称是 checkpoint 匹配依据的一部分，因此一旦模型需要长期持久化，改变建模顺序或门名称规则会影响加载兼容性。
5.4 共享参数与梯度累积
use arcqml::prelude::*;
let mut circuit = Circuit::new(1)?;
let theta = circuit.add_parameter(0.3)?;
circuit.ry_param(theta, 0usize)?;
circuit.rz_param(theta, 0usize)?;
// 反向时，两处操作对同一 theta 的贡献相加
每个参数化 Operation 只保留 ParameterId；执行前由接口层读取 Circuit 当前 Parameter Tensor 的数值并交给 Runtime。因此 optimizer 更新参数后，不必重建电路，下一次运行会自动使用新角度。伴随反向也按 ParameterId 累加多处门操作的梯度贡献，从而实现共享参数的梯度累积。
5.5 校验、复制、拼接
validate() 会检查电路量子比特数非零、Operation qubit 合法、Gate 参数引用属于当前参数表，以及参数名称非空且不重复。Circuit::clone() 调用 deep_clone()，所以复制出的 Circuit 不与原电路共享参数值或梯度。
append(right) 消费右电路并追加其操作，对未绑定参数做重映射；append_with_bindings(right, bindings) 可将右电路指定 ParameterId 显式绑定到左电路已有参数。两条电路的量子比特数必须相同，且成功追加后结果电路会清空参数梯度。
5.6 参数表达式的当前限制
当前版本的参数化门只能在参数槽位中保存固定标量或单个 ParameterId，尚不能直接保存由多个参数组成的表达式。因此，-x、x + y 等表达式不能作为门参数传入；同一个 ParameterId 可以被多个门共享，但不能在 Circuit 内声明参数之间的算术关系。
如果需要使用参数表达式，现阶段可在电路外部计算表达式的数值，再将结果作为固定参数或独立参数写入电路。需要注意的是，这种方式不会自动保留表达式与原始参数之间的依赖关系：例如把 x + y 的计算结果登记为新的 Parameter 后，量子伴随反向只会得到该新参数的梯度，不会自动按链式法则把梯度分配给 x 和 y。训练过程中还需要在每次前向计算前重新计算并更新该参数值。
在当前发行版中，建议优先使用单个 ParameterId 和参数共享表达模型。若确实需要参数算术关系，应在电路外通过 Tensor 可微运算构造所需计算，并明确检查结果是否仍位于目标自动微分链路上；若把运算结果仅作为固定数值写入门参数，原始参数不会自动获得量子电路侧的梯度。