📚 课程目录第4章波形编程环境搭建

4. 波形编程环境搭建

在真正编写量子控制波形之前，需要先把“能生成波形、能下载到仪器、能观测到输出”这条链路搭通。AWG 的编程环境通常由三层组成：最底层是仪器驱动与通信层（VISA、USB/LAN 连接），中间是控制与编排层（厂商软件或 Python 库），最上层是波形数据与序列描述（采样率、幅度、偏置、标记等参数）。本节围绕这三层，给出可落地的配置方法，并用一个最小实验验证整条链路。

一、厂商软件：快速验证与波形编辑

Tektronix SourceXpress 与 Keysight IQtools 是两类典型的上位机软件。它们的价值在于：不写代码就能完成仪器发现、波形合成、序列编排与下载，非常适合在环境搭建阶段做“链路自检”。以 SourceXpress 为例，安装后通过 LAN 连接 AWG，软件会自动扫描仪器并显示型号与固件版本；在波形编辑界面中可直接用公式或分段方式定义波形，设置采样率（例如 10 GSa/s）、幅度（如 500 mVpp）、偏置与标记输出，然后点击下载到仪器通道。IQtools 则更偏向 IQ 基带信号的生成与上变频配置，适合需要复信号调制的场景。

厂商软件的第一个作用是确认“仪器可达、固件匹配、通道正常”。如果软件能发现仪器并成功下载一段正弦波，说明物理连接与基础驱动没有问题，后续 Python 环境的问题就可以聚焦在软件栈而非硬件。第二个作用是提供参数参照：软件里设置的采样率、幅度、偏置、标记延迟等，都可以作为 Python 脚本的对照基准，便于排查“代码写对了但输出不对”的问题。

二、Python 控制库：PyVISA 与 QCoDeS 的分工

PyVISA 是通信层库，负责把 SCPI 命令通过 VISA 后端（NI-VISA、R&S VISA 或 pyvisa-py）发送到仪器。它的典型用法是先枚举资源，再打开会话：

import pyvisa
rm = pyvisa.ResourceManager()
print(rm.list_resources())
# 例如 ('TCPIP0::192.168.1.20::inst0::INSTR',)
awg = rm.open_resource('TCPIP0::192.168.1.20::inst0::INSTR')
awg.timeout = 5000
print(awg.query('*IDN?'))

如果 list_resources() 返回空，问题通常在 VISA 后端或网络配置；如果 *IDN? 超时，则要检查 IP、子网掩码与仪器是否开启了远程控制。QCoDeS 则建立在 PyVISA 之上，提供参数化仪器驱动、实验循环与数据记录能力。对于量子控制场景，QCoDeS 的优势是把“波形参数”抽象成可扫描的参数对象，便于与后续的自动化测量衔接。实际工程中常见做法是：用 PyVISA 做底层调试与快速验证，用 QCoDeS 组织正式实验。

三、开发环境配置要点

建议使用独立的虚拟环境（conda 或 venv），固定 PyVISA、pyvisa-py 与厂商驱动的版本，避免升级导致后端不兼容。网络连接优先使用静态 IP，并在仪器端确认子网与端口开放；USB 连接则需安装对应厂商的 USB 驱动。一个常被忽略的点是超时与分块传输：大波形下载时单次写入数据量大，应适当增大 timeout，并确认仪器支持的分块大小。此外，建议在脚本开头统一记录仪器型号、固件版本与采样率，作为实验元数据。

四、第一个波形输出实验

下面给出一个最小可执行实验：向通道 1 下载一段 1 MHz 正弦波，采样率 10 GSa/s，幅度 500 mVpp，偏置 0 V，并用示波器观测。示例参数为教学设定，实际值需按仪器能力调整。

import numpy as np
import pyvisa

fs = 10e9          # 采样率 10 GSa/s
f  = 1e6           # 正弦频率 1 MHz
n  = 10000         # 每周期 10000 点，恰好 1 个周期
t  = np.arange(n) / fs
wave = 0.5 * np.sin(2 * np.pi * f * t)   # 归一化到 ±0.5

rm = pyvisa.ResourceManager()
awg = rm.open_resource('TCPIP0::192.168.1.20::inst0::INSTR')
awg.timeout = 10000
awg.write('*RST')
awg.write('SOUR1:FUNC:SHAP ARB')
awg.write(f'SOUR1:FREQ {fs}')
awg.write('SOUR1:VOLT 0.5')       # 500 mVpp
awg.write('SOUR1:VOLT:OFFS 0')
# 以 16 位整数形式下载波形数据（具体命令随厂商型号不同）
data = np.round(wave * 32767).astype(np.int16)
awg.write_binary_values('SOUR1:DATA ', data, datatype='h')
awg.write('OUTP1:STAT ON')

执行后应做三件事验证。第一，用 *IDN? 与 SYST:ERR? 确认无命令错误；第二，用示波器接通道 1，观察是否出现 1 MHz、约 500 mVpp 的正弦波，周期应为 1 μs；第三，回读关键参数（如 SOUR1:FREQ?、SOUR1:VOLT?）与设定值比对。若波形频率正确但幅度偏小，常见原因是负载匹配（50 Ω 与高阻）设置不一致；若完全没有输出，优先检查 OUTP1:STAT 是否打开、通道是否被其他序列占用。

建议把上述脚本封装成函数，参数（采样率、频率、幅度、点数）作为入参，并在每次运行后打印仪器型号、固件版本与回读参数。这样后续做多通道同步或复杂序列时，可以快速定位是“参数问题”还是“链路问题”。

完成这一实验后，环境搭建的核心目标就达成了：厂商软件提供图形化对照，PyVISA 打通命令通道，QCoDeS 为后续参数扫描预留接口，而示波器观测与参数回读构成了最基本的验证闭环。后续更复杂的脉冲序列、标记对齐与多通道同步，都可以在这个已验证的链路上逐步叠加。