实验编辑指南

深入了解 Quatm 实验框架的核心 API，掌握从基础实验到高级控制的完整编写方法。

Experiment 基类

所有 Quatm 实验都继承自 Experiment 基类。该基类提供了完整的实验生命周期管理和设备控制接口。

核心方法

方法	调用时机	用途
`build()`	实验加载时执行一次	声明设备、定义参数
`run()`	每次点击运行按钮	实验主逻辑
`start_measurement()`	每次测量开始前	初始化操作（仅一次）
`start_sequence()`	每次扫描序列开始前	序列级初始化
`end_sequence()`	每次扫描序列结束后	序列级清理
`end_measurement()`	测量结束后	最后的清理操作

声明设备

使用 setattr_device() 将 device_db 中配置的设备引入实验：

def build(self):
    self.setattr_device("fpga")       # FPGA 控制器
    self.setattr_device("camera")      # 科学相机
    self.setattr_device("valon_5009")  # 频率合成器

设备名称必须与 configuration/device_db.py 中的键完全一致。

声明参数

使用 setattr_argument() 创建可在 GUI 中调整的实验参数：

from quatm.experiment import Experiment, NumberValue
from quatm.experiment.experiment import BoolValue, StringCombo

def build(self):
    # 数值参数
    self.setattr_argument(
        "exposure_time",
        NumberValue("exposure_time", ndecimals=2, step=0.01, value=1.0)
    )
    # 布尔开关
    self.setattr_argument("enable_cooling", BoolValue("enable_cooling", True))
    # 字符串选项
    self.setattr_argument("scan_type", StringCombo("scan_type", ["频率", "功率"]))

设备属性类型

设备接入后，根据 device_db 中的配置类型，呈现为不同的属性：

类型	对应类	用途
`attr`	`DAC` / `TTLOut`	直接映射到硬件通道
`generic_attr`	`genericAttr`	调用驱动上的任意函数
`local`	驱动类实例	完整驱动对象

实验生命周期

每个实验按以下层次结构执行：

测量 (measurement)
  └─ 序列 (sequence / repetition)
       └─ 运行 (run)

run：单次实验执行，每次调用 run() 方法
sequence：一组使用不同参数值的 run 集合（参数扫描）
measurement：一个或多个 sequence 的完整测量

时序控制

delay() 函数

delay(seconds) 在非实时模式下暂停指定秒数，在实时模式下仅递增内部计时器：

def run(self):
    self.cooling_laser.on()
    delay(0.1)   # 等待 100 毫秒
    self.camera.expose(1.0)

实验控制设备

使用 realtime 上下文管理器实现精确的硬件时序：

def run(self):
    with realtime(repetitions=3):
        self.ttl_channel = True
        delay(0.001)
        self.ttl_channel = False

数据管理

发送实验数据

通过 DataClient 将数据推送到数据管理器：

def run(self):
    result = measure_atoms()
    self._dataq.send({
        "atom_count": result,
        "temperature": T
    })

数据以 HDF5 格式自动保存，支持 InfluxDB 远程推送。

前馈控制

Feed_forward 类允许根据历史数据动态调整实验参数：

from quatm.experiment.feedforward import Feed_forward

def build(self):
    self.ff = Feed_forward(self)
    self.ff.set_refresh_time(refresh_time=1)

def run(self):
    # 根据历史斜率自动调整
    self.ff.set_yslope(self.measured_slope)

模拟模式

在无实际硬件时，可通过 simulation_class_decorator 装饰器启用模拟：

from quatm.experiment.simulation_decorator import simulation_class_decorator

@simulation_class_decorator
class TestExperiment(Experiment):
    def build(self):
        self.setattr_device("fpga")