这份教程演示一个最小但完整的仿真流程：
- 构造
qubit-coupler-qubit三体系统。 - 给 tunable coupler 定义脉冲信号。
- 对含时哈密顿量做数值时间演化。
- 从演化算符中抽取两比特有效门。
- 计算 iSWAP 门保真度与泄漏。
配套脚本是 simulate_iswap.py。它只依赖 numpy、scipy 和 matplotlib，适合作为理解动力学的起点。
如果需要直接生成包含无退相干和含退相干结果的完整报告，运行：
python3 iswap_report.py报告和图表会输出到 results/。
iSWAP 门的理想矩阵为
U_iSWAP =
[[1, 0, 0, 0],
[0, 0, i, 0],
[0, i, 0, 0],
[0, 0, 0, 1]]
它的核心作用是在单激发子空间中完成
|10> -> i |01>
|01> -> i |10>
在超导电路里，常见做法是让两个 fixed-frequency qubit 通过一个 tunable coupler 间接相互作用。coupler 远失谐时，两个 qubit 基本解耦；对 coupler 施加 flux pulse 后，有效交换耦合增强，单激发会在两个 qubit 之间振荡。选择合适的脉冲时长，就能得到 iSWAP。
这里把每个器件都近似成二能级系统：
q1 -- c -- q2
使用旋波近似下的交换耦合哈密顿量：
H(t) / hbar =
omega_1 a_1^dag a_1
+ omega_c(t) a_c^dag a_c
+ omega_2 a_2^dag a_2
+ g_1c (a_1^dag a_c + a_1 a_c^dag)
+ g_2c (a_2^dag a_c + a_2 a_c^dag)
在脚本中，a 被二能级 lowering operator sigma_- 替代，因此总希尔伯特空间维度是 2 x 2 x 2 = 8。
更真实的 transmon 仿真通常需要三能级或更多能级，并加入非谐性项。这个最小模型先帮助你看清 iSWAP 的动力学机制。
脚本使用一个平顶脉冲：
omega_c(t): omega_c_idle -> omega_c_on -> omega_c_idle
上升沿和下降沿用 smoothstep 平滑：
smoothstep(x) = x^2 (3 - 2x)这样避免频率突变造成过强的非绝热激发。主要参数在 Params 中：
wq1 = 2pi * 5.000 GHz
wq2 = 2pi * 5.000 GHz
wc_idle = 2pi * 6.500 GHz
wc_on = 2pi * 5.450 GHz
g1c = 2pi * 0.080 GHz
g2c = 2pi * 0.080 GHz
rise = 4.0 ns
hold = 51.5 ns
dt = 0.02 ns这些参数不是某个真实芯片的标定值，而是为了让单激发交换清楚可见，并给出一个接近 iSWAP 的示例门点。
含时薛定谔方程为
dU(t)/dt = -i H(t) U(t)
脚本把时间离散成很多小步，在每一步中取中点哈密顿量：
U_step = expm(-1j * H(t + dt/2) * dt)
U = U_step @ U这相当于 piecewise-constant 近似。只要 dt 足够小，就能稳定地捕捉门演化。
完整演化算符 U 是 8 x 8。实际两比特门只关心 coupler 回到基态 |0_c> 的计算子空间：
|00> -> |0 0 0>
|01> -> |0 0 1>
|10> -> |1 0 0>
|11> -> |1 0 1>
脚本把这些行列取出来，得到一个 4 x 4 的投影映射 K。如果 coupler 或非计算态残留了人口，K 就不是严格酉矩阵，这部分会体现为 leakage。
平均泄漏定义为
L = 1 - Tr(K^dag K) / 4
对于可能有泄漏的投影映射 K，脚本使用
F_avg = [Tr(K^dag K) + |Tr(U_target^dag K)|^2] / [d(d+1)]
其中 d = 4，U_target = U_iSWAP。
实际实验中，iSWAP 脉冲还会积累单比特动态相位。因此脚本会优化两个 virtual-Z 角度：
K_corrected = [Rz(theta1) tensor Rz(theta2)] K
然后报告相位校正后的保真度。
在当前目录运行：
python3 simulate_iswap.py输出包括：
- 脉冲长度。
- coupler idle/on 频率。
- 原始保真度。
- virtual-Z 校正后的保真度。
- 平均泄漏。
- 投影两比特映射
K。 - 单激发初态
|100>的人口演化图iswap_population.png。
生成完整报告：
python3 iswap_report.py输出包括：
results/iswap_report.md：中文结果报告。results/summary.json：参数和保真度摘要。results/waveforms.png：量子比特和耦合器波形。results/coherent_population.png：无退相干动力学。results/decoherent_population.png：含退相干动力学。
最重要的两个参数是：
wc_on：决定 coupler 靠近 qubit 的程度，也决定有效交换强度和泄漏风险。hold：决定交换演化持续多久。
建议步骤：
- 固定
wc_on，扫描hold，观察|100>到|001>的交换峰值。 - 在交换接近完整时，计算 iSWAP fidelity。
- 再扫描
wc_on，寻找高保真、低泄漏的区域。 - 调整
rise，在速度和泄漏之间折中。
一个非常粗略的有效模型是：
H_eff / hbar ~= J_eff (|10><01| + |01><10|)
当
J_eff * T ~= pi / 2
时会接近 iSWAP。真实三体模型中还会有动态相位和泄漏，所以最终仍需要数值优化。
如果要向真实器件靠近，可以把每个模式从二能级扩展到三能级或四能级：
H / hbar =
sum_j [omega_j n_j - alpha_j n_j(n_j - 1)/2]
+ sum_<jk> g_jk (a_j^dag a_k + a_j a_k^dag)
然后检查：
|02>、|20>等非计算态泄漏。- coupler 高激发态残留。
- qubit 频率不完全相等时的 detuning。
- flux pulse 的频谱泄漏。
- decoherence 下的过程保真度。
这份最小教程的结构仍然适用：定义脉冲、构造含时哈密顿量、传播、投影、相位校正、计算保真度。