这篇文章整理了 hf2li_duffing_heatmap.py 和 hf2li_frequency_sweep.py 两个实验脚本的用途、关键参数与推荐使用流程，适合在正式实验前快速对照。

适用文件

• hf2li_duffing_heatmap.py
• hf2li_frequency_sweep.py

项目目录：

D:\UMPhD\python\rc_daq

一、当前有哪两个脚本

hf2li_frequency_sweep.py

用于单个激励幅值下的正扫 / 反扫频率扫描，适合先看共振峰、找 Duffing 滞回窗口。

hf2li_duffing_heatmap.py

用于在固定频率窗口内，对多个激励幅值逐个执行正扫 / 反扫，并最终生成：

• 振幅热力图
• 相位热力图
• 滞回差值图

二、实验前需要确认的内容

• 设备为 Zurich Instruments HF2LI
• 本机可以正常连接 LabOne Data Server
• 本机已安装 zhinst-toolkit
• 设备选件包含 HF2LI-MF 和 HF2LI-MOD
• 实验连线已经完成：
  • HF2LI 激励输出 -> 器件
  • DC 电源 -> 偏置
  • 器件输出电流 -> TIA -> HF2LI 输入
• 当前设备 ID 为 dev18567，如果设备号变化，必须先修改脚本里的 device_id

三、这个项目里最关键的几个约定

• HF2LI 必须使用 HF2 专用连接方式：Session("localhost", hf2=True)
• 当前这台设备的 Output 1 使用 output_mixer_channel = 0，不要改成 6
• session.poll() 的 timeout 单位是秒，不是毫秒
• 扫频实验的主图是 R 对 frequency，其中 R = sqrt(X^2 + Y^2)
• 只要系统可能有滞回，就必须分正扫和反扫，不能混在一起采集

四、输出幅值怎么理解

在当前脚本配置里，output_range_vpk 通常设为 1.0。此时 output_amplitude_vpk 的数值可以直接理解为输出电压峰值。

如果后续修改了 output_range_vpk，就必须重新确认 output_amplitude_vpk 对应的真实输出电压。

五、hf2li_frequency_sweep.py 怎么用

用途：在单个固定激励幅值下做一轮正扫和反扫。

适合做什么：

• 先找线性共振峰
• 确认非线性起始阈值
• 观察滞回窗口

重点参数：

• f_start_hz
• f_stop_hz
• num_points
• output_amplitude_vpk
• settle_time_s
• sample_time_s
• bidirectional

运行结果：

• 实时显示正扫 / 反扫 R-f 曲线
• 保存 CSV 数据
• 保存扫频图

六、hf2li_duffing_heatmap.py 怎么用

用途：固定扫频窗口，对一系列激励幅值逐个进行正扫和反扫。

推荐流程：先粗扫，再精扫。

• 粗扫时可以把 amp_step_vpk 设大，例如 0.050，即 50 mV 一步
• 精扫时可以把 amp_step_vpk 设为 0.005，即 5 mV 一步
• 当前已经验证：5 mV 步长扫描可以得到符合预期的热力图结果

关键参数说明：

• amp_start_vpk：起始幅值，例如 0.100 表示 100 mV
• amp_stop_vpk：终止幅值，例如 0.440 表示 440 mV
• amp_step_vpk：幅值步长，例如 0.050 表示 50 mV，0.005 表示 5 mV
• f_start_hz / f_stop_hz：每轮扫频的频率范围
• num_points：每轮扫频点数，点数越大，热力图边界越细，但实验耗时越长
• detuning_reference_hz：热力图横轴参考频率，建议填写小信号 f0
• dc_bias_v：记录当前使用的 DC 偏置值
• note：记录真空度、温度或其他实验条件

七、推荐实验步骤

1. 先运行 hf2li_frequency_sweep.py，在少量几个驱动幅值下观察共振峰和滞回。
2. 得到小信号共振频率 f0 后，把 hf2li_duffing_heatmap.py 中的 detuning_reference_hz 改成真实 f0。
3. 先用较大的幅值步长做一轮粗扫，快速找到强非线性和滞回区域。
4. 再把步长改成 5 mV，对关键幅值区间做精扫。
5. 实验结束后优先查看正扫、反扫和差值热力图，再去看单个幅值下的切片曲线。

八、脚本会输出哪些文件

• metadata.txt：记录本次实验的参数和元数据
• sweep_amp_XXXmV.csv：某个固定幅值下的正扫 / 反扫数据
• sweep_amp_XXXmV.png：该幅值下的振幅和相位曲线图
• merged_duffing_all.csv：整组实验的合并总表
• D1_forward_amplitude_heatmap.png：正扫振幅热力图
• D2_reverse_amplitude_heatmap.png：反扫振幅热力图
• D3_hysteresis_difference_heatmap.png：滞回差值图
• D4_forward_phase_heatmap.png
• D4_reverse_phase_heatmap.png
• heatmap_matrices.npz：后续二次分析可直接读取的矩阵文件

九、merged_duffing_all.csv 里的关键字段

十、常见问题与处理建议

• 如果 HF2LI 前面板左边的 Amplitude 1(Vpk) 没有变化，先检查 output_mixer_channel 是否仍为 0
• 如果 poll 报 timeout 错误，首先检查 timeout 是否误按毫秒填写
• 如果热力图边界不清楚，优先检查频率步进是否过粗，或者每点等待时间是否过短
• 如果正扫和反扫差异异常大，先确认两者的扫频速率、锁相时间常数和每点等待时间完全一致
• 如果要让横轴严格表示 f - f0，就必须把 detuning_reference_hz 设置为真实小信号 f0
• 如果完整 5 mV 精扫耗时太长，先用 50 mV 粗扫锁定窗口，再回到 5 mV 精扫

效果示意

正扫振幅热力图

反扫振幅热力图

滞回差值热力图

440 mV 下的扫频曲线