📚 课程目录第3章量子门参数越界与非法角度诊断

3. 量子门参数越界与非法角度诊断

旋转门角度越界的典型触发方式

量子旋转门（RX、RY、RZ、U、PhaseGate 等）的参数是浮点角度，但不同框架对“合法角度”的约束并不相同。诊断前先明确三类越界来源：

数值越界：角度超出框架允许的区间，例如 Qiskit 的 ParameterExpression 在绑定后要求为实数，某些门（如 U 的 θ）要求 θ∈[0, π]；Cirq 的 rz 接受任意实数但会做模 2π 归一化。
类型错误：把字符串、None、复数或未绑定的 Parameter 直接传给门构造函数。
单位混淆：把角度制（如 90）当作弧度制传入，数值本身“合法”但语义错误，通常不报错却导致结果偏差。

下面用一段可运行的 Qiskit 示例复现前两类问题，并观察报错信息如何指向具体门与参数位置。

构造越界与类型错误案例

from qiskit import QuantumCircuit
from qiskit.circuit import Parameter
import math

# 案例 A：U 门 theta 超出 [0, pi]
qc_a = QuantumCircuit(1)
qc_a.u(theta=4.0, phi=0.0, lam=0.0, qubit=0)   # 4.0 > pi

# 案例 B：RX 传入字符串
qc_b = QuantumCircuit(1)
qc_b.rx("1.57", 0)

# 案例 C：RZ 传入未绑定 Parameter 后直接 simulate
theta = Parameter("theta")
qc_c = QuantumCircuit(1)
qc_c.rz(theta, 0)

# 案例 D：角度制误用（不报错，但语义错误）
qc_d = QuantumCircuit(1)
qc_d.rx(90, 0)   # 本意 90°，实际 90 rad

四个案例中，A、B 会在构造或转译阶段抛错，C 在未绑定参数时执行会报 ParameterExpression 相关错误，D 则静默通过——这正是最危险的一类。

不同框架的报错行为对照

案例	Qiskit 报错要点	Cirq 对应行为	定位线索
A：U 门 θ=4.0	`CircuitError: 'theta' must be in [0, pi]`，栈顶指向 `u()` 调用行	`cirq.QubitOrder` 无此约束，`cirq.u` 不校验 θ 范围	报错含门名与参数名
B：RX 传字符串	`TypeError: 'str' object cannot be interpreted as a real number`	`cirq.rx("1.57")` 抛 `TypeError`	类型名 + 参数位置
C：未绑定 Parameter	执行时 `QiskitError: Cannot unroll the circuit to the given basis` 或参数绑定错误	`cirq.resolve_parameters` 前调用会抛 `ValueError`	参数名 + 未绑定提示
D：角度制误用	无报错，结果与预期偏差	无报错	需靠结果比对发现

定位参数越界位置

报错栈通常给出三层信息：门构造函数（如 QuantumCircuit.u）、参数名（theta）、调用行号。定位时按以下顺序核对：

看报错中的参数名，确认是哪个门参数越界，而不是比特索引或寄存器名。
回到调用行，打印该参数的实际值与类型：print(type(theta), theta)。
若参数来自变量或表达式，向上追溯赋值链，检查是否在某处被字符串拼接或单位换算污染。
对 Parameter 对象，确认是否已通过 assign_parameters 绑定为实数。

Qiskit 的 u 门 θ 约束为 [0, π]，而 rx/ry/rz 接受任意实数并内部模 2π。若把 u 的 θ 写成 4.0，报错会明确提示范围；若写成 rx(4.0) 则不报错，需自行判断语义。

参数校验修复方案

在构造线路前插入一层轻量校验，把“静默错误”转成“显式报错”，并统一单位：

import math

def check_angle(value, name, unit="rad", lo=None, hi=None):
    if not isinstance(value, (int, float)):
        raise TypeError(f"{name} 必须为实数，实际为 {type(value).__name__}")
    if unit == "deg":
        value = math.radians(value)
    if lo is not None and value < lo:
        raise ValueError(f"{name}={value:.4f} 小于下限 {lo}")
    if hi is not None and value > hi:
        raise ValueError(f"{name}={value:.4f} 大于上限 {hi}")
    return value

# 修复案例 A
theta_a = check_angle(4.0, "theta", lo=0.0, hi=math.pi)   # 抛 ValueError
# 修复案例 B
theta_b = check_angle("1.57", "rx_theta")                  # 抛 TypeError
# 修复案例 D：显式声明角度制
theta_d = check_angle(90, "rx_theta", unit="deg")          # 返回 1.5708

校验函数返回归一化后的弧度值，再传给门构造函数，即可同时消除类型错误、范围越界与单位混淆。对含 Parameter 的参数化线路，应在 assign_parameters 之后、执行之前调用同一校验函数。

验证修复效果

修复后重新运行四个案例，预期行为：A、B 在构造前即抛出带参数名的异常；C 在绑定后通过校验；D 返回 1.5708 并得到与 rx(math.pi/2) 一致的结果。可用如下断言快速回归：

import pytest

def test_angle_guard():
    with pytest.raises(ValueError):
        check_angle(4.0, "theta", lo=0.0, hi=math.pi)
    with pytest.raises(TypeError):
        check_angle("1.57", "rx_theta")
    assert abs(check_angle(90, "rx_theta", unit="deg") - math.pi/2) < 1e-9

通过条件：三个断言全部通过，且参数化线路在绑定后不再出现未绑定参数错误。若仍报错，回到报错栈核对参数名与调用行，确认校验函数是否覆盖了该门的所有角度参数。