Demo 2：参数平移梯度

第 2 章 量子神经网络 · 本章演示 · 代码演示总索引

可视化：双图：曲线+误差柱 —— 解析 / 平移 / 有限差分梯度对比

对应教程：第 2 章 量子神经网络 中相关小节 · 依赖安装：pip install "unified-quantum[visualization,simulation]"

实现要点

核心：参数平移法则。对单参数线路 RY(θ)|0⟩ 后测 ⟨Z⟩， 解析梯度 = -sin(θ) 参数平移估计 = [f(θ + π/2) - f(θ - π/2)] / 2 = -sin(θ) 有限差分估计 = [f(θ + ε) - f(θ - ε)] / (2ε) 三者应当一致；本 demo 在多个 θ 值上验证该恒等式并绘图。

完整源码

demos/ch02-qnn/02_parameter_shift.py

"""
ch02-qnn demo 2: parameter-shift rule

对应教程：chenzhaoyun.com/quantum-tutorial/ch02-quantum-nn/parameter-shift-appendix.html
核心：参数平移法则。对单参数线路 RY(θ)|0⟩ 后测 ⟨Z⟩，
       解析梯度 = -sin(θ)
       参数平移估计 = [f(θ + π/2) - f(θ - π/2)] / 2 = -sin(θ)
       有限差分估计 = [f(θ + ε) - f(θ - ε)] / (2ε)
三者应当一致；本 demo 在多个 θ 值上验证该恒等式并绘图。

依赖：pip install unified-quantum[visualization]
运行：python demos/ch02-qnn/02_parameter_shift.py
"""
from __future__ import annotations

from pathlib import Path

import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
import numpy as np

from uniqc import Circuit, submit_task, wait_for_result

OUT = Path(__file__).parent

SHOTS = 4000
SHIFT = np.pi / 2.0   # 参数平移法则的标准步长
EPS = 1e-3            # 有限差分步长


def expectation_of_ry(theta: float, shots: int = SHOTS) -> float:
    """对线路 RY(θ)|0⟩ 测 ⟨Z⟩ = cos(θ)。"""
    c = Circuit()
    c.ry(0, float(theta))
    c.measure(0)
    r = wait_for_result(submit_task(c, backend="dummy:local:simulator", shots=shots))
    p = r.probabilities
    return float(p.get("0", 0.0) - p.get("1", 0.0))


# === 1. 在一组 θ 上同时算三种梯度 ===
thetas = np.linspace(0.1, 2 * np.pi - 0.1, 12)
analytic_grad = np.zeros_like(thetas)
param_shift_grad = np.zeros_like(thetas)
finite_diff_grad = np.zeros_like(thetas)

for i, theta in enumerate(thetas):
    f_plus = expectation_of_ry(theta + SHIFT)
    f_minus = expectation_of_ry(theta - SHIFT)
    f_eps = expectation_of_ry(theta + EPS)
    f_meps = expectation_of_ry(theta - EPS)

    analytic_grad[i] = -np.sin(theta)
    param_shift_grad[i] = (f_plus - f_minus) / 2.0
    finite_diff_grad[i] = (f_eps - f_meps) / (2.0 * EPS)

abs_err_shift = np.abs(param_shift_grad - analytic_grad)
abs_err_fd = np.abs(finite_diff_grad - analytic_grad)

# === 2. 绘图：理论曲线 vs 两种数值梯度 ===
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12.0, 4.8))

# 左图：梯度值对比
ax1.plot(thetas, analytic_grad, color="#1f77b4", lw=2.2, label=r"analytic $-\sin\theta$")
ax1.plot(thetas, param_shift_grad, "o", color="#2ca02c", ms=7, label="parameter shift (step π/2)")
ax1.plot(thetas, finite_diff_grad, "x", color="#d62728", ms=8, mew=2, label=f"finite diff (ε={EPS:g})")
ax1.axhline(0.0, color="#888", lw=0.7, ls="--")
ax1.set_xlabel(r"$\theta$ (rad)")
ax1.set_ylabel(r"$\partial \langle Z\rangle / \partial\theta$")
ax1.set_title("Gradient estimators on $R_Y(\\theta)|0\\rangle$")
ax1.set_xticks(np.linspace(0, 2 * np.pi, 5))
ax1.set_xticklabels([r"$0$", r"$\pi/2$", r"$\pi$", r"$3\pi/2$", r"$2\pi$"])
ax1.set_ylim(-1.2, 1.2)
ax1.grid(alpha=0.3)
ax1.legend(loc="upper right", fontsize=9)

# 右图：误差柱状图
x_idx = np.arange(len(thetas))
width = 0.38
ax2.bar(x_idx - width / 2, abs_err_shift, width=width, color="#2ca02c", alpha=0.85,
        label="|param-shift error|")
ax2.bar(x_idx + width / 2, abs_err_fd, width=width, color="#d62728", alpha=0.85,
        label="|finite-diff error|")
ax2.set_xticks(x_idx)
ax2.set_xticklabels([f"{t:.2f}" for t in thetas], rotation=45, fontsize=8)
ax2.set_xlabel(r"$\theta$ (rad)")
ax2.set_ylabel("absolute error vs $-\\sin\\theta$")
ax2.set_title("Estimator accuracy")
ax2.set_yscale("log")
ax2.grid(axis="y", alpha=0.3, which="both")
ax2.legend(loc="upper left", fontsize=9)

plt.suptitle("ch02-qnn demo 2: parameter-shift rule vs finite-difference gradient", y=1.02)
plt.tight_layout()
out_path = OUT / "02_parameter_shift.png"
plt.savefig(out_path, dpi=120, bbox_inches="tight")
plt.close()

# === 3. stdout 关键统计 ===
print("ch02-qnn-demo-2: parameter-shift rule")
print(f"  samples: {len(thetas)}, shots per evaluation: {SHOTS}")
print(f"  shift size: π/2, finite-difference ε: {EPS}")
print(f"  max |param-shift error|    = {abs_err_shift.max():.4f}")
print(f"  max |finite-diff error|    = {abs_err_fd.max():.4f}")
print(f"  mean |param-shift error|   = {abs_err_shift.mean():.4f}")
print(f"  mean |finite-diff error|   = {abs_err_fd.mean():.4f}")
print(f"  evaluations on quantum HW: {3 * len(thetas)} circuits submitted")
print(f"  PNG -> {out_path}")

运行结果

运行方式

# 仓库根目录执行；输出 PNG 到 demos/ch02-qnn/02_parameter_shift.png，关键统计到 stdout
.venv/bin/python3 demos/ch02-qnn/02_parameter_shift.py

---

← 本章演示 · ↑ 代码演示总索引 · ⌂ 教程门户