这是本节的多页打印视图。点击此处打印.

欢迎使用Quatm

欢迎来到 Quatm 用户指南！无论你是刚开始搭建实验控制系统，还是希望从 LabView、Matlab 迁移到开源方案，这里都能帮你快速上手。

什么是 Quatm？

Quatm 是一个专为量子物理实验设计的开源控制框架。它把设备驱动、时序管理、数据采集和分析这些常见需求整合在一起，让你只需关注实验本身，而不是底层的软件细节。了解更多 →

Quatm 不提供：

硬件：Quatm 是纯软件框架，实验所需的仪器设备需要你自行采购和维护。
实验方案：Quatm 提供控制的工具，具体的实验逻辑和物理方案由你定义。

Quatm 提供：

完整的控制架构：设备驱动、时序控制、参数管理和数据分析，开箱即用。
灵活的部署方式：单机运行、控制端—客户端分离、浏览器远程控制，随需选择。
活跃的社区支持：持续迭代、问题追踪和用户交流。

Quatm 适合我吗？

如果你的实验涉及 超冷原子、离子阱、量子光学、量子化学 等领域，需要精确控制多个仪器设备和全自动化实验测量，Quatm 会是理想的选择。

特别适合以下场景：

🧪 长期使用 LabView 或 Matlab，想迁移到开源、可定制的方案
🔌 多种厂商硬件混杂，需要一个统一的控制层
🚀 希望将实验流程自动化，解放科研精力

系统架构

Quatm 采用 分布式微服务架构，每个组件（硬件驱动、分析例程、GUI 面板）作为独立操作系统进程运行，经网络与进程间通道（TCP / IPC）通信：

🖥️ 控制层

桌面 GUI

· 实验浏览器

· 参数编辑器

· 图像监视器

· 任务暂存器

· 任务循环器

Web 控制台（quatm.web）

· 数据分析

· 手机移动端

· 任务队列 / 扫描 / 属性管理

· 双向同步管理

发布/订阅（TCP/IPC） · RPC · HTTP/WebSocket

🌐 通信层（quatm.servers）

📡 数据节点 🖼️ 图像节点 ⌨️ 命令节点 🗂️ 属性管理 🔁 通信代理 🌐 网页服务

消息分发

🧪 实验层

· Experiment 基类

· realtime() 时序控制

· 参数扫描与队列管理

📊 分析层

· 吸收成像

· 高斯拟合

· 亮斑检测

· 图像切片

· 数据平均

· 拟合加速

设备调用 / 数据读写

🔌 驱动层

FPGA Andor BlackFly Rigol Valon Thorlabs DDS Toptica PI Stage 监控设备（温度/磁场/真空）

各层职责

层级	模块	职责
GUI 层	`quatm.GUI`	Qt 图形界面，实验管理、设备控制、数据可视化
Web 层	`quatm.web`	浏览器端控制台（webhub）：九个功能页、移动端、与桌面 GUI 双向同步
通信层	`quatm.servers`	发布/订阅消息（TCP/IPC）、RPC 远程调用、分布式属性同步
实验层	`quatm.experiment`	声明式实验时序、参数扫描、设备属性管理
分析层	`quatm.analysis`	实时图像处理、曲线拟合、离子检测（Cython 加速）
物理层	`quatm.physics`	光偶极阱建模、Stark 位移、散射率、Feshbach 共振
驱动层	`quatm.drivers`	统一硬件抽象，支持 300+ 种实验室仪器
监控层	`quatm.monitor`	温度、磁场、真空等环境参数持续监测

这种架构确保：故障隔离（一个组件崩溃不影响全局）、并行处理（图像分析与实验时序同时运行）、网络透明（组件可分布在不同机器）。

文档导航

系统学习 Quatm 的最佳路径：

章节	你将学到
快速开始	安装 Python 环境，配置 device_db.py 接入设备，编写并运行第一个实验
实验编辑指南	Experiment 基类的完整生命周期，NumberValue/BoolValue/StringCombo 参数类型，delay() 和 realtime 时序控制
设备与驱动	TTLOut/DAC/genericAttr 三种属性模式，校准文件使用，自定义驱动开发
数据与分析	DataClient/ImageClient 通信，HDF5 存储结构，图像分析、离子检测等内置模块
通信层	发布/订阅通信（TCP/IPC）、DataClient/ImageClient/CommandClient、分布式属性系统
GUI 组件	实验浏览器、参数编辑器、序列编辑器、图像监视器的使用与定制
Web 远程控制	浏览器端实验控制台（quatm.web）：九个功能页、手机移动端、与桌面 GUI 队列/扫描/暂存/逻辑循环双向同步
物理模型库	原子数据库、光偶极阱建模、Stark 位移与散射率计算
监控设备	温度控制器、高斯计、波长计、真空规等环境监测设备
部署指南	单机、客户端—控制端分离、多控制端集群的部署架构
最佳实践	单一职责、Mixin 复用、设备状态检查、异常安全关闭
应用案例	MOT 装载优化、吸收成像、Rabi 振荡等完整案例
代码贡献	提交 Issue、发起 Pull Request、代码审查流程

🚀 建议路径：快速开始 → 实验编辑指南 → 设备与驱动 → 应用案例。其余章节可按需查阅。

1 - 快速开始

从零开始搭建 Quatm 实验控制环境，只需几分钟即可运行第一个实验。

欢迎！下面几步就能让 Quatm 在你的机器上跑起来。

完成本指南后，你将能够：

✅ 在本地安装并验证 Quatm 环境
✅ 理解 device_db.py 的设备配置方式
✅ 编写一个带有参数面板的完整实验脚本
✅ 在模拟模式下运行和调试实验

环境要求

Python：3.9 及以上版本
操作系统：Windows 7 以上、Linux（内核版本 5.10.261 及以上）、macOS 10.12 及以上
硬件：模拟模式无需硬件；实际实验需要支持 TTL/DAC 的控制器，实时控制需要 FPGA 模块

安装

git clone https://github.com/quatm/quatm.git
cd quatm
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

验证

from quatm.experiment import Experiment

class HelloQuatm(Experiment):
    def build(self):
        print("Quatm 就绪！")
    def run(self):
        print("Hello, Quatm!")

HelloQuatm().run()

下一步

配置仪器设备 — 编辑 device_db.py 接入你的实验设备
编写第一个实验 — 学习实验类的基本结构和运行方式
常见问题 — 安装和使用中的问题排查

1.1 - 编写第一个实验

从零开始编写你的第一个 Quatm 实验脚本，学习实验类的基本结构和运行方式。

实验的基本结构

每个 Quatm 实验都是一个继承自 Experiment 的 Python 类。只需定义 build() 和 run() 两个核心方法：

from quatm.experiment import Experiment, NumberValue
from quatm.experiment.experiment import delay

class MyFirstExperiment(Experiment):
    def build(self):
        # 声明设备
        self.setattr_device("fpga")
        # 声明参数
        self.setattr_argument(
            "target_voltage",
            NumberValue("target_voltage", ndecimals=2, step=0.01, value=4.00)
        )

    def run(self):
        # 设置 DAC 通道输出并等待后切换
        self.my_dac = 1.0
        delay(0.5)
        self.my_dac = self.target_voltage

build() — 声明阶段

build() 在实验加载时执行一次，用于声明实验中使用的设备和参数。

设备声明模式

# DAQ/控制器设备（type: local）
self.setattr_device("fpga")

# 属性设备（type: attr），直接作为实验属性使用
self.setattr_device("cooling_ttl")

# 通用属性设备（type: generic_attr）
self.setattr_device("Li_frequency")

参数类型

类型	类	使用场景
数值	`NumberValue`	电压、频率、时间等连续量
布尔	`BoolValue`	开关、使能等二值选项
选项	`StringCombo`	模式选择、扫描类型等固定选项

self.setattr_argument("b_field", NumberValue("b_field", ndecimals=1, step=0.5, value=5.0))
self.setattr_argument("cooling", BoolValue("cooling", True))
self.setattr_argument("scan", StringCombo("scan", ["完整扫描", "快速扫描"]))

run() — 执行阶段

run() 是实验的主体逻辑，每次运行按钮点击时执行。

设备控制

def run(self):
    # 模拟量输出
    self.trap_dac = 3.5        # 设置 DAC 输出
    
    # TTL 数字输出
    self.aom_ttl = True        # 打开 AOM
    delay(0.1)
    self.aom_ttl = False       # 关闭 AOM

数据采集

def run(self):
    self.camera.expose(0.1)
    img = self.camera.last_image
    
    # 发送到数据管理器
    self._dataq.send({"atom_count": analyze(img)})

运行实验

将 .py 文件放入 experiments/ 目录，然后在**实验浏览器（Browser）**中打开并运行（浏览器由进程管理器启动，也可在代码中 Browser().show()）。

设备接入见配置仪器设备。

1.2 - 常见问题

Quatm 安装和使用中的常见问题及解决方案。

Windows 系统

FPGA 控制器驱动

需安装厂商提供的 SDK，FPGA 需要按照实际需求定义和烧录timetable。模拟模式下无需实际硬件。

Linux 系统

Qt 图形库依赖

sudo apt install libxcb-cursor0 libxcb-xinerama0 libegl1-mesa

相机权限

Andor / BlackFly 需配置 udev 规则。

Windows Subsystem for Linux (WSL)

WSL 用户请确保在 Linux 文件系统挂载上运行，避免在 Windows 文件系统上操作导致意外错误。

Web 远程控制平台（quatm.web）

旧版本安装缺少 quatm.web 子包

从旧版本升级时 Web Hub 启动报错并提示缺少子包：重新执行 pip install -e . 即可（quatm.web 随 quatm 核心一起安装）。

与桌面 GUI 同时操作同一进程

桌面进程管理器与 Web 进程页同时管理同一批服务/GUI。任一入口启动条目前会先终止另一入口管理的实例，避免双开；若发现进程被意外重启，检查是否在另一端执行了启动操作。

1.3 - 配置仪器设备

通过 device_db.py 将实验仪器接入 Quatm 框架。

Quatm 通过 configuration/device_db.py 管理所有实验仪器。该文件定义一个名为 device_db 的字典，每个键对应一个可在实验中使用的设备名称。

设备类型

device_db 支持三种设备类型：

type	说明	使用场景
`local`	驱动类实例	FPGA 控制器、相机等需要完整驱动对象的设备
`attr`	属性映射	将驱动的某个通道映射为实验属性（如 DAC、TTL）
`generic_attr`	通用属性	调用驱动的任意函数，实现灵活的功能映射

配置示例

device_db = {
    # 驱动设备：加载完整的控制器驱动实例（此处用软件模拟控制器，无需硬件）
    "fpga": {
        "type": "local",
        "module": "quatm.drivers.controllers.software",
        "class": "SoftwareController",
        "arguments": {"immediate": False},
    },
    # 属性设备：TTL 通道映射
    "cooling_aom": {
        "type": "attr",
        "module": "quatm.experiment.attributes",
        "class": "TTLOut",
        "arguments": {"channel": 5, "logic": "a"},
    },
    # 属性设备：DAC 通道映射
    "trap_coil_x": {
        "type": "attr",
        "module": "quatm.experiment.attributes",
        "class": "DAC",
        "arguments": {"channel": 2},
    },
}

控制器驱动位于 quatm/drivers/controllers/：SoftwareController 为软件模拟（无硬件跑通 TTL/DAC 链路）；FPGA 硬件用 RegmapController 等 RealtimeController 实现。

属性设备参数

TTLOut — 数字输出

参数	说明
`channel`	FPGA 控制器 TTL 通道编号
`logic`	`"l"` 为正逻辑，`"a"` 为反逻辑

DAC — 模拟输出

参数	说明
`channel`	FPGA 控制器 DAC 通道编号
`gauge`	校准文件路径（可选）

通用属性配置

对于需要灵活映射的驱动功能，使用 genericAttr：

"Li_frequency": {
    "type": "generic_attr",
    "module": "quatm.experiment.attributes",
    "class": "genericAttr",
    "driver": "lithium_dds_0",
    "function": "set_frequency",
    "arguments": {
        "function_kwargs": {"channel": [0]},
        "minval": 40, "maxval": 90,
        "multiplier": 1E6, "display_unit": "MHz",
    },
}

校准文件

对于非线性响应的设备，可使用两列空格分隔的文本文件进行校准：

2.2  4.0
2.0  3.8
1.8  3.6
1.6  3.34

在 DAC 配置中通过 gauge 参数引用：

"rf_power": {
    "type": "attr",
    "module": "quatm.experiment.attributes",
    "class": "DAC",
    "arguments": {"channel": 3, "gauge": "configuration/gauge-rf-power.txt"},
}

自定义驱动接入

编写自定义驱动类后，在 device_db 中以 type: "local" 注册：

"my_laser": {
    "type": "local",
    "module": "my_lab.my_laser_driver",
    "class": "MyLaserDriver",
    "arguments": {"port": "/dev/ttyUSB0"},
}

然后在实验中通过 self.setattr_device("my_laser") 使用。

2 - 实验编辑指南

深入了解 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")

模拟模式下所有设备操作被拦截并记录，不会产生实际硬件输出。

3 - 设备与驱动

Quatm 原生支持 50+ 品牌、100+ 种实验仪器：涵盖科学相机、信号源、激光器、运动平台、DAQ 与环境监测。

Quatm 通过 configuration/device_db.py 统一管理所有仪器设备，支持三种接入模式。

设备接入模式

type	行为	适用场景
`local`	实例化驱动类，作为完整对象使用	FPGA 控制器、相机等需要方法调用的设备
`attr`	将通道映射为 Python 属性	DAC 输出、TTL 数字信号
`generic_attr`	调用驱动的任意函数	DDS 频率设置等灵活映射

驱动分类

Quatm 内置 50+ 品牌 的实验仪器驱动，分为以下 7 个类别：

类别	品牌数	典型设备
📷 科学相机	15	Andor EMCCD/sCMOS、FLIR Blackfly、Basler、Hamamatsu ORCA、Thorlabs TSI
📡 信号源与射频	8	Valon 5009、DDS AD9959、Agilent 33500、Rigol DG1020Z
🔬 激光器与光学	9	Cobolt、Toptica iBeam、Sirah Matisse、M² Solstis、HighFinesse 波长计
🎯 运动与定位	8	PI 纳米台、Attocube、Newport Picomotor、Thorlabs APT
🔌 DAQ 与电源	9	NI DAQ/SWITCH/Digital、Rigol DP1116A、EA PS2000B、Keithley 2110、示波器
🌡️ 环境监测	9	Lakeshore 218、Cryocon、Pfeiffer TPG2xx、Leybold ITR、液氦液位计
⚡ 实验控制	3	ADwin FPGA、NI-FPGA、Red Pitaya

属性设备详解

TTLOut — 数字输出

映射硬件控制器的 TTL 通道为实验属性，支持正/反逻辑：

"cooling_aom": {
    "type": "attr",
    "module": "quatm.experiment.attributes",
    "class": "TTLOut",
    "arguments": {"channel": 5, "logic": "a"},
}

实验中直接赋值：self.cooling_aom = True

DAC — 模拟输出

映射硬件控制器的 DAC 通道，支持校准曲线：

"trap_x": {
    "type": "attr",
    "module": "quatm.experiment.attributes",
    "class": "DAC",
    "arguments": {"channel": 2, "gauge": "gauge-trap-x.txt"},
}

校准文件

非线性设备使用两列文本文件校准。第一列为期望物理量，第二列为实际 DAC 值，系统自动线性插值。

自定义驱动

"my_laser": {
    "type": "local",
    "module": "my_lab.laser_driver",
    "class": "LaserController",
    "arguments": {"port": "/dev/ttyUSB0"},
}

通信协议

协议	典型设备
VISA / SCPI	信号发生器、万用表、示波器、电源
串口 (RS232/RS485)	激光器、真空计、位移台、温控器
Modbus RTU	Omron/Lumel 温控器
TCP/IP (Telnet/JSON)	M² 激光器、Attocube 控制器
原生 SDK DLL	Andor、Basler、Hamamatsu 等相机
NI-DAQmx	NI 数据采集卡
USB HID	ANC350 纳米定位器
SPI	AD9959 DDS

3.1 - 科学相机

Andor、Basler、Hamamatsu、FLIR 等 15 品牌科学相机与图像采集驱动。

概述

Quatm 为全球 15 个主流科学相机品牌提供统一的 ICamera 接口封装，覆盖 EMCCD、sCMOS、高速 CMOS 和工业相机。

Andor 系列：iXon EMCCD / Zyla sCMOS / Shamrock 光谱仪

概述

Quatm 提供两套 Andor 相机驱动，通过原生 SDK 实现高性能成像控制：

驱动类	SDK	适用型号	接口
`AndorSDK2Camera`	atmcd32d.dll (SDK2)	iXon EMCCD, Luca, Clara	PCIe / USB
`AndorSDK3Camera`	atcore.dll (SDK3)	Zyla, Neo, Marana (sCMOS)	USB3 / CameraLink
`ShamrockSpectrograph`	ShamrockCIF.dll	SR-303i, SR-500i 等光谱仪	USB

所有类继承自 io.camera 接口，支持 ROI、binning、曝光控制和帧缓冲管理。

Andor SDK2 (EMCCD) `AndorSDK2Camera`

⚙️ iXon EMCCD Andor SDK2 系列

通信	DLL (atm32cd32)
读出模式	EM/传统
ADC 频率	1/5/10 MHz
像素深度	16-bit
制冷	TEC（≤ -100°C）

适用于极低光信号场景（单原子/离子荧光），通过电子倍增（EM Gain）实现单光子级灵敏度。

驱动模块：AndorSDK2Camera

初始化

from quatm.drivers.andor.AndorSDK2 import AndorSDK2Camera

# 连接第一台相机
cam = AndorSDK2Camera(cam_id=0)

# 配置采集参数
cam.setup_acquisition(
    exposure=0.1,       # 曝光时间 (s)
    em_gain=200,        # EM 增益 (0-1000)
    readout_rate="5MHz",# 读出速率
    pre_amp_gain=2,     # 前置放大增益
    hsspeed=0,          # 水平转移速率
    temperature=-70,    # 目标温度 (°C)
)

# 采集单帧
cam.start_acquisition(nframes=1)
image = cam.read_multiple_images(nframes=1)

关键参数

参数	说明	典型范围
`exposure`	单帧曝光时长	0.001 – 3600 s
`em_gain`	电子倍增增益	0 – 1000（线性或真实增益模式）
`readout_rate`	ADC 读出频率	1MHz / 5MHz / 10MHz
`temperature`	传感器目标温度	-60 至 -100°C（取决于冷却器）
`pre_amp_gain`	前置放大器增益	1× – 4×

Andor SDK3 (sCMOS) `AndorSDK3Camera`

⚙️ Zyla / Neo sCMOS Andor SDK3 系列

通信	DLL (atcore)
传感器	sCMOS
接口	USB3 / CameraLink
像素深度	12/16-bit
帧率	最高 100 fps（全分辨率）

适用于快速序列成像和需要大视场的场景。基于 GenAPI 属性模型配置曝光、ROI 和触发。

驱动模块：AndorSDK3Camera

初始化

from quatm.drivers.andor.AndorSDK3 import AndorSDK3Camera

cam = AndorSDK3Camera(cam_id=0)
cam.setup_acquisition(
    exposure=0.05,
    pixel_format="Mono16",
    trigger_mode="Internal",
)

Andor Shamrock 光谱仪 `ShamrockSpectrograph`

控制光栅选择、中心波长和狭缝宽度：

from quatm.drivers.andor.Shamrock import ShamrockSpectrograph

spec = ShamrockSpectrograph(idx=0)
spec.set_wavelength(780.24)      # 中心波长 (nm)
spec.set_grating(2)              # 选择光栅
spec.set_slit_width(50, port=1)  # 入口狭缝 (µm)

设备配置

"emccd": {
    "type": "local",
    "module": "drivers.andor.AndorSDK2",
    "class": "AndorSDK2Camera",
    "arguments": {"cam_id": 0},
}

校准提示

EMCCD 增益需针对定量荧光测量进行校准。过高增益会引入时钟感应电荷（CIC）噪声和非线性。建议使用荧光珠或标准光源建立增益-信号关系曲线。

FLIR / Teledyne / Blackfly S / Grasshopper3

概述

Quatm 通过 TeledyneSpinnakerCamera 类封装 Spinnaker SDK，支持所有兼容 GenICam/GenAPI 的 FLIR/Teledyne USB3/GigE 相机。

⚙️ Blackfly S / Grasshopper3 FLIR Spinnaker 系列

通信	Spinnaker SDK
接口	USB3 / GigE
像素格式	Mono8/16, Bayer
触发	硬件/软件
帧率	取决于型号

用于实验室通用成像：MOT 监测、对准光束成像、设备状态监控。

驱动模块：TeledyneSpinnakerCamera

初始化

from quatm.drivers.teledyne.spinnaker import TeledyneSpinnakerCamera

# 列出所有可用相机
cam_list = TeledyneSpinnakerCamera.list_cameras()

# 连接指定相机（序列号或索引）
cam = TeledyneSpinnakerCamera(cam_id="serial_xxx")
# 或使用索引
cam = TeledyneSpinnakerCamera(cam_id=0)

# 配置并开始采集
cam.setup_acquisition(
    exposure=0.02,          # 20 ms 曝光
    pixel_format="Mono8",
    width=1920, height=1200,
    offset_x=0, offset_y=0,
)

关键方法

方法	说明
`list_cameras()`	枚举系统中所有 Spinnaker 相机
`setup_acquisition(**kwargs)`	配置 ROI、曝光、像素格式等
`start_acquisition(nframes)`	开始采集指定帧数
`read_multiple_images(nframes)`	读取已采集图像
`get_device_info()`	获取相机序列号、型号、固件版本

常用属性操作

通过 GenAPI 节点名称直接读写相机参数：

# 设置增益
cam.set_attribute("Gain", 10.0)
# 启用自动曝光
cam.set_attribute("ExposureAuto", "Continuous")
# 获取传感器温度
temp = cam.get_attribute("DeviceTemperature")

设备配置

"monitor_cam": {
    "type": "local",
    "module": "drivers.teledyne.spinnaker",
    "class": "TeledyneSpinnakerCamera",
    "arguments": {"cam_id": 0},
}

多相机同步

Spinnaker SDK 支持多相机硬件触发同步。设置 TriggerMode = On 和 TriggerSource = Line0 即可通过外部 TTL 信号实现纳秒级同步曝光。

stop(): Stop capturing images.
quatm.drivers.blackfly.bfly.Camserver(name, serial)
```
class quatm.drivers.blackfly.bfly.Camserver(object):
    def __init__(self, name, serial):
        pass

    def generateImageIndex(self):
        pass

    def run(self):
        pass

    def sendimage(self, im):
        pass

    def updateBusInfo(self):
        pass
```
- generateImageIndex(): In the current measurement, count the images. If the next run has started (either task, repetition or run changes), reset the counter (imgindex).
- run(): Run loop running forever. Sends images from the camera to the imagestream and initiates reconfiguration of the camera in case properties have changed.
- sendimage(im): Send Blackfly camera image via the imagestream. The image is converted to numpy array, additional information like binning, timestamp, etc., is added to a dictionary and both are sent to the imagestream.
  - Args: im - Blackfly image object.
  - Returns: None
- updateBusInfo(): Detect cameras on the bus and update info in properties if new camera has been found.
quatm.drivers.blackfly.bfly.pc2
```
class quatm.drivers.blackfly.bfly.pc2(object):
    pass
```
- Dummy class in case driver is not installed.

Function:

quatm.drivers.blackfly.bfly.run(name)
```
def quatm.drivers.blackfly.bfly.run(name):
    pass
```
- Initialize a Camserver and run it.

Thorlabs TSI / uc480 科学相机

TLCamera `ThorlabsTLCamera`

⚙️ TSI 系列 Thorlabs 科学相机

通信	TLCamera SDK
接口	USB3
传感器	sCMOS / CCD
支持	ROI, binning

适用于 SDK 级控制的高帧率科学成像。

驱动模块：ThorlabsTLCamera

from quatm.drivers.thorlabs.TLCamera import ThorlabsTLCamera
cam = ThorlabsTLCamera(serial="12345678")
cam.setup_acquisition(exposure=0.01, width=1024, height=768)

概述

Quatm 为全球 15 个主流科学相机品牌提供统一的 io.camera 接口封装，覆盖 EMCCD、sCMOS、高速 CMOS 和工业相机。所有驱动通过原生 SDK 实现高性能采集。

Andor 系列：EMCCD / sCMOS / 光谱仪

概述

Quatm 提供两套 Andor 相机驱动，通过原生 SDK 实现高性能成像控制：

驱动类	SDK	适用型号	接口
`AndorSDK2Camera`	atmcd32d.dll (SDK2)	iXon EMCCD, Luca, Clara	PCIe / USB
`AndorSDK3Camera`	atcore.dll (SDK3)	Zyla, Neo, Marana (sCMOS)	USB3 / CameraLink
`ShamrockSpectrograph`	ShamrockCIF.dll	SR-303i, SR-500i 等光谱仪	USB

所有类继承自 io.camera 接口，支持 ROI、binning、曝光控制和帧缓冲管理。

Andor SDK2 (EMCCD) `AndorSDK2Camera`

⚙️ iXon EMCCD Andor SDK2 系列

通信	DLL (atm32cd32)
读出模式	EM/传统
ADC 频率	1/5/10 MHz
像素深度	16-bit
制冷	TEC（≤ -100°C）

适用于极低光信号场景（单原子/离子荧光），通过电子倍增（EM Gain）实现单光子级灵敏度。

驱动模块：AndorSDK2Camera

初始化

from quatm.drivers.andor.AndorSDK2 import AndorSDK2Camera

# 连接第一台相机
cam = AndorSDK2Camera(cam_id=0)

# 配置采集参数
cam.setup_acquisition(
    exposure=0.1,       # 曝光时间 (s)
    em_gain=200,        # EM 增益 (0-1000)
    readout_rate="5MHz",# 读出速率
    pre_amp_gain=2,     # 前置放大增益
    hsspeed=0,          # 水平转移速率
    temperature=-70,    # 目标温度 (°C)
)

# 采集单帧
cam.start_acquisition(nframes=1)
image = cam.read_multiple_images(nframes=1)

关键参数

参数	说明	典型范围
`exposure`	单帧曝光时长	0.001 – 3600 s
`em_gain`	电子倍增增益	0 – 1000（线性或真实增益模式）
`readout_rate`	ADC 读出频率	1MHz / 5MHz / 10MHz
`temperature`	传感器目标温度	-60 至 -100°C（取决于冷却器）
`pre_amp_gain`	前置放大器增益	1× – 4×

Andor SDK3 (sCMOS) `AndorSDK3Camera`

⚙️ Zyla / Neo sCMOS Andor SDK3 系列

通信	DLL (atcore)
传感器	sCMOS
接口	USB3 / CameraLink
像素深度	12/16-bit
帧率	最高 100 fps（全分辨率）

适用于快速序列成像和需要大视场的场景。基于 GenAPI 属性模型配置曝光、ROI 和触发。

驱动模块：AndorSDK3Camera

初始化

from quatm.drivers.andor.AndorSDK3 import AndorSDK3Camera

cam = AndorSDK3Camera(cam_id=0)
cam.setup_acquisition(
    exposure=0.05,
    pixel_format="Mono16",
    trigger_mode="Internal",
)

Andor Shamrock 光谱仪 `ShamrockSpectrograph`

控制光栅选择、中心波长和狭缝宽度：

from quatm.drivers.andor.Shamrock import ShamrockSpectrograph

spec = ShamrockSpectrograph(idx=0)
spec.set_wavelength(780.24)      # 中心波长 (nm)
spec.set_grating(2)              # 选择光栅
spec.set_slit_width(50, port=1)  # 入口狭缝 (µm)

设备配置

"emccd": {
    "type": "local",
    "module": "drivers.andor.AndorSDK2",
    "class": "AndorSDK2Camera",
    "arguments": {"cam_id": 0},
}

校准提示

EMCCD 增益需针对定量荧光测量进行校准。过高增益会引入时钟感应电荷（CIC）噪声和非线性。建议使用荧光珠或标准光源建立增益-信号关系曲线。

FLIR / Teledyne Spinnaker 系列

概述

Quatm 通过 TeledyneSpinnakerCamera 类封装 Spinnaker SDK，支持所有兼容 GenICam/GenAPI 的 FLIR/Teledyne USB3/GigE 相机。

⚙️ Blackfly S / Grasshopper3 FLIR Spinnaker 系列

通信	Spinnaker SDK
接口	USB3 / GigE
像素格式	Mono8/16, Bayer
触发	硬件/软件
帧率	取决于型号

用于实验室通用成像：MOT 监测、对准光束成像、设备状态监控。

驱动模块：TeledyneSpinnakerCamera

初始化

from quatm.drivers.teledyne.spinnaker import TeledyneSpinnakerCamera

# 列出所有可用相机
cam_list = TeledyneSpinnakerCamera.list_cameras()

# 连接指定相机（序列号或索引）
cam = TeledyneSpinnakerCamera(cam_id="serial_xxx")
# 或使用索引
cam = TeledyneSpinnakerCamera(cam_id=0)

# 配置并开始采集
cam.setup_acquisition(
    exposure=0.02,          # 20 ms 曝光
    pixel_format="Mono8",
    width=1920, height=1200,
    offset_x=0, offset_y=0,
)

关键方法

方法	说明
`list_cameras()`	枚举系统中所有 Spinnaker 相机
`setup_acquisition(**kwargs)`	配置 ROI、曝光、像素格式等
`start_acquisition(nframes)`	开始采集指定帧数
`read_multiple_images(nframes)`	读取已采集图像
`get_device_info()`	获取相机序列号、型号、固件版本

常用属性操作

通过 GenAPI 节点名称直接读写相机参数：

# 设置增益
cam.set_attribute("Gain", 10.0)
# 启用自动曝光
cam.set_attribute("ExposureAuto", "Continuous")
# 获取传感器温度
temp = cam.get_attribute("DeviceTemperature")

设备配置

"monitor_cam": {
    "type": "local",
    "module": "drivers.teledyne.spinnaker",
    "class": "TeledyneSpinnakerCamera",
    "arguments": {"cam_id": 0},
}

多相机同步

Spinnaker SDK 支持多相机硬件触发同步。设置 TriggerMode = On 和 TriggerSource = Line0 即可通过外部 TTL 信号实现纳秒级同步曝光。

stop(): Stop capturing images.
quatm.drivers.blackfly.bfly.Camserver(name, serial)
```
class quatm.drivers.blackfly.bfly.Camserver(object):
    def __init__(self, name, serial):
        pass

    def generateImageIndex(self):
        pass

    def run(self):
        pass

    def sendimage(self, im):
        pass

    def updateBusInfo(self):
        pass
```
- generateImageIndex(): In the current measurement, count the images. If the next run has started (either task, repetition or run changes), reset the counter (imgindex).
- run(): Run loop running forever. Sends images from the camera to the imagestream and initiates reconfiguration of the camera in case properties have changed.
- sendimage(im): Send Blackfly camera image via the imagestream. The image is converted to numpy array, additional information like binning, timestamp, etc., is added to a dictionary and both are sent to the imagestream.
  - Args: im - Blackfly image object.
  - Returns: None
- updateBusInfo(): Detect cameras on the bus and update info in properties if new camera has been found.
quatm.drivers.blackfly.bfly.pc2
```
class quatm.drivers.blackfly.bfly.pc2(object):
    pass
```
- Dummy class in case driver is not installed.

Function:

quatm.drivers.blackfly.bfly.run(name)
```
def quatm.drivers.blackfly.bfly.run(name):
    pass
```
- Initialize a Camserver and run it.

Thorlabs TSI / uc480

Thorlabs 科学相机

Quatm 支持多类 Thorlabs 设备，包含位移台、光学测量仪器与相机。

TLCamera 科学相机 `ThorlabsTLCamera`

⚙️ TSI 系列 Thorlabs 科学相机

通信	TLCamera SDK
接口	USB3
传感器	sCMOS / CCD
支持	ROI, binning

适用于需要 SDK 级别控制的高帧率科学成像。

驱动模块：ThorlabsTLCamera

from quatm.drivers.thorlabs.TLCamera import ThorlabsTLCamera
cam = ThorlabsTLCamera(serial="12345678")

---

## Basler — Pylon SDK 系列


  
    
      ⚙️
      Basler ace / dart
      Pylon SDK 系列
    

    
    
      
        
        
        
        
          通信
          Pylon SDK (GenICam)
        
        
        
        
        
        
          接口
          USB3 / GigE
        
        
        
        
        
        
          传感器
          CMOS
        
        
        
        
        
        
          像素格式
          Mono8/16, Bayer
        
        
        
        
        
        
          功能
          ROI, Binning, 硬件触发
        
        
        
      
    
    

    工业级 CMOS 相机，适合 MOT 荧光监测、对准光束成像等常规实验室成像任务。

    
    驱动模块：BaslerPylonCamera
    
  



```python
from quatm.drivers.Basler.pylon import BaslerPylonCamera

# 枚举全部相机
cams = BaslerPylonCamera.list_cameras()
cam = BaslerPylonCamera(cam_id=cams[0])

cam.setup_acquisition(exposure=0.02)
cam.start_acquisition(nframes=1)

Hamamatsu ORCA 系列 sCMOS

⚙️ ORCA-Fusion / ORCA-Flash4.0 Hamamatsu DCAM

通信	DCAM SDK (DLL)
传感器	sCMOS
像素	2048×2048 (Fusion)
帧率	最高 100 fps
读出噪声	< 1.6 e⁻

超低噪声 sCMOS，适用于单原子/单离子荧光定量成像。

驱动模块：DCAMCamera

from quatm.drivers.DCAM.DCAM import DCAMCamera

cam = DCAMCamera(idx=0)
cam.setup_acquisition(exposure=0.1, pixel_format="Mono16")

Photometrics Prime / Evolve 系列

⚙️ Prime BSI / Evolve EMCCD Photometrics PVCAM

通信	PVCAM SDK (DLL)
传感器	背照式 sCMOS / EMCCD
接口	PCIe / USB3
像素深度	16-bit

背照式 sCMOS 提供高量子效率；EMCCD 型号支持单光子灵敏度。

驱动模块：PVCAMCamera

from quatm.drivers.Photometrics.pvcam import PVCAMCamera

cam = PVCAMCamera(cam_name="Prime_BSI_95B")
cam.setup_acquisition(exposure=0.05)

Princeton Instruments PIXIS / ProEM

⚙️ PIXIS / ProEM / IsoPlane Princeton PICam

通信	PICam SDK (DLL)
传感器	CCD / EMCCD
制冷	液氮 / TEC
接口	PCIe / USB

光谱学级 CCD/EMCCD，常与 Acton/IsoPlane 光谱仪配合使用。

驱动模块：PicamCamera

from quatm.drivers.PrincetonInstruments.picam import PicamCamera

cam = PicamCamera(cam_id=0)
cam.setup_acquisition(exposure=1.0)  # 长曝光光谱采集

PCO edge / dimax 高速相机

⚙️ edge / dimax / pco.panda PCO SC2

通信	SC2 SDK (DLL)
接口	CameraLink HS / USB3 / GigE
帧率	最高数千 fps
传感器	sCMOS / 高速 CMOS

适合快速动力学过程：MOT 装载动态、离子晶体重排实时观测。

驱动模块：PCOSC2Camera

from quatm.drivers.PCO.SC2 import PCOSC2Camera

cam = PCOSC2Camera(interface="USB 3.0")
cam.setup_acquisition(exposure=0.001)  # 1 ms 高速采集

Allied Vision Alvium / Mako

⚙️ Alvium / Mako / Bonito Allied Vision Vimba X

通信	VimbaX SDK (GenICam)
接口	USB3 / GigE / CameraLink
传感器	CMOS

紧凑型工业相机，适合空间受限的光路集成。

驱动模块：AlliedVisionVimbaXCamera

from quatm.drivers.AlliedVision.VimbaX import AlliedVisionVimbaXCamera

cam = AlliedVisionVimbaXCamera(cam_id=0)

IDS uEye+ / Ensenso

⚙️ uEye+ / Ensenso 3D IDS peak

通信	IDS peak SDK
接口	USB3 / GigE
传感器	CMOS

通用 USB/GigE 相机，包括 Ensenso 3D 立体相机。

驱动模块：GenericIDSPeakCamera

from quatm.drivers.IDS.peak import GenericIDSPeakCamera

cam = GenericIDSPeakCamera(cam_id=0)

通用配置范式

所有相机通过 device_db.py 以 type: "local" 注册：

"imaging_cam": {
    "type": "local",
    "module": "drivers.Basler.pylon",
    "class": "BaslerPylonCamera",
    "arguments": {"cam_id": 0},
}

帧采集卡

对于 Camera Link 接口的相机，Quatm 还内置 NI IMAQ、BitFlow 和 Silicon Software 帧采集卡驱动，用法与相机驱动一致：所有采集卡同样继承 io.camera 接口。

3.2 - 信号源与射频

Valon 5009、DDS AD9959、Agilent、Rigol 等频率合成器与射频仪器驱动。

概述

Quatm 支持从通用函数发生器到矢量网络分析仪的多种射频仪器，涵盖频率合成、任意波形和 S 参数测量。

Valon 5009 双通道微波频率合成器

概述

Valon 5009 是一款双通道频率合成器（23.5 MHz – 6 GHz），通过串口控制。Quatm 通过 valon 封装，支持独立设置两路输出频率和功率。

⚙️ Valon 5009 Dual RF Synthesizer

通信	串口 (RS232)
频率范围	23.5 MHz – 6 GHz
通道数	2
输出功率	-30 ~ +10 dBm
频率分辨率	0.1 Hz

广泛应用于离子阱实验中驱动微波跃迁（如 Ba⁺ 9.9 GHz 超精细跃迁）或作为 AOM 驱动源。

驱动模块：valon

初始化

from quatm.drivers.valon.valon_quatm import valon

# 连接 Valon（默认 /dev/ttyUSB0）
valon = valon(port="/dev/ttyUSB0")

# 设置通道 1 频率为 500 MHz
valon.set_frequency(freq=500e6, source=1)

# 设置通道 2 频率为 9.925 GHz（需外部倍频）
valon.set_frequency(freq=9.925e9, source=2)

# 发送原始指令
valon.sendRaw("LOCK 1 ON\r\n")

关键方法

方法	说明
`set_frequency(freq, source)`	设置通道 1 或 2 输出频率 (Hz)
`sendCommand(source, command, value)`	发送格式化 SCPI 命令
`sendRaw(cmd)`	发送原始字符串命令

串口通信

Valon 驱动底层通过 VSerialPort（serial.Serial 子类）通信，典型参数：

# 串口参数（驱动默认）
port = "/dev/ttyUSB0"
baudrate = 115200
timeout = 0.1

🔬 Ba⁺ 微波跃迁扫描 Ba⁺

使用 Valon 5009 驱动 9.925 GHz 超精细跃迁，扫描频率测量 Rabi 振荡。

关键参数

起始频率	`9.924 GHz`
终止频率	`9.926 GHz`
步进	`10 kHz`
每点重复	`100 次`

# 实验片段：频率扫描
import numpy as np
frequencies = np.arange(9.924e9, 9.926e9, 10e3)
for f in frequencies:
    valon.set_frequency(freq=f, source=2)
    # ... 执行探测序列 ...

参考：参见离子阱实验 → 量子态检测

频率精度

Valon 5009 内部参考频率稳定性有限。对于高精度光谱或量子操控实验，建议：

外接 10 MHz 铷钟参考信号
或使用 HighFinesse 波长计 / 频谱分析仪实时监测输出频率

class quatm.drivers.valon.valon_prog.Valon_Standalone(name='Valon')

Bases: object

Standalone driver for the Valon frequency generator. Commands can be sent via the Commandhub and are processed in parallel to the experiment, thereby the experiment is not delayed by the Valon.
- run()
function quatm.drivers.valon.valon_prog.run()

DDS AD9959 四通道直接数字合成

概述

AD9959 驱动封装 AD9959 评估板，通过 SPI 总线控制 4 个独立 DDS 通道，实现精密频率、幅度和相位控制。

⚙️ AD9959 评估板 4 通道 DDS

通信	SPI
通道数	4
频率分辨率	32-bit (0.12 Hz @ 500 MHz 时钟)
相位分辨率	14-bit
幅度控制	10-bit DAC

广泛应用于冷原子/离子实验中的 AOM 驱动、边带生成和相干操控。

驱动模块：AD9959

初始化

from quatm.drivers.dds import AD9959

dds = AD9959()

# 配置通道 0 — 冷却光 AOM
dds.set_frequency(0, 80e6)       # 80 MHz
dds.set_amplitude(0, 0.5)        # 50% 幅度
dds.set_phase(0, 0)              # 0° 相位

# 配置通道 1 — 再泵浦光 AOM（+0.1 MHz 差频）
dds.set_frequency(1, 80.1e6)
dds.set_amplitude(1, 0.3)

关键方法

方法	说明
`set_frequency(ch, freq_hz)`	设置通道频率 (Hz)
`set_amplitude(ch, amp)`	设置通道幅度 (0–1 分数)
`set_phase(ch, phase_deg)`	设置通道相位 (°)
`update_all()`	一次性更新所有通道

同步更新

AD9959 支持同步更新模式：先对 4 个通道分别调用 set_* 方法（缓冲区），再调用 update_all() 统一写入硬件。这确保了多通道之间的相位一致性，对边带冷却等需要精确相位关系的实验至关重要。

设备配置

"aom_dds": {
    "type": "local",
    "module": "drivers.DDS",
    "class": "AD9959",
}

dds.set_amplitude(1, 0.5)


## 典型应用

| 应用 | 配置 |
|------|------|
| AOM 驱动 | 单通道固定频率 |
| 拉曼跃迁 | 双通道差频锁定 |
| 阱驱动 | 多通道相位控制 |
| 边带冷却 | 频率调制 |

## 替代驱动

还提供基于串口（AT 命令）接口的 AD9959 板替代驱动：

```python
from quatm.drivers.dds.alibaba import AD9959Board

Rigol DG1020Z 双通道函数发生器

DG1020Z

⚙️ DG1020Z Rigol 函数发生器

通信	VISA (USB/LAN)
通道数	2
频率范围	1 µHz – 25 MHz
幅度	1 mVpp – 10 Vpp
采样率	200 MSa/s

用于生成 AOM/EOM 驱动信号、调制波形和自定义任意波形。

驱动模块：RigolDG1020Z

from quatm.drivers.AWG.specific import RigolDG1020Z
fg = RigolDG1020Z(addr="USB0::...")
fg.set_frequency(80e6)
fg.set_amplitude(1.0)       # 1.0 Vpp
fg.enable_output(channel=1, enable=True)
fg.set_function(channel=1, function="SIN")

=== Agilent 信号源扩展内容 ===

run()

DDS AD9959

概述

AD9959 驱动封装 AD9959 评估板，通过 SPI 总线控制 4 个独立 DDS 通道，实现精密频率、幅度和相位控制。

⚙️ AD9959 评估板 4 通道 DDS

通信	SPI
通道数	4
频率分辨率	32-bit (0.12 Hz @ 500 MHz 时钟)
相位分辨率	14-bit
幅度控制	10-bit DAC

广泛应用于冷原子/离子实验中的 AOM 驱动、边带生成和相干操控。

驱动模块：AD9959

初始化


dds = AD9959()

# 配置通道 0 — 冷却光 AOM
dds.set_frequency(0, 80e6)       # 80 MHz
dds.set_amplitude(0, 0.5)        # 50% 幅度
dds.set_phase(0, 0)              # 0° 相位

# 配置通道 1 — 再泵浦光 AOM（+0.1 MHz 差频）
dds.set_frequency(1, 80.1e6)
dds.set_amplitude(1, 0.3)

关键方法

方法	说明
`set_frequency(ch, freq_hz)`	设置通道频率 (Hz)
`set_amplitude(ch, amp)`	设置通道幅度 (0–1 分数)
`set_phase(ch, phase_deg)`	设置通道相位 (°)
`update_all()`	一次性更新所有通道

同步更新

设备配置

"aom_dds": {
    "type": "local",
    "module": "drivers.DDS",
    "class": "AD9959",
}

dds.set_amplitude(1, 0.5)


## 典型应用

| 应用 | 配置 |
|------|------|
| AOM 驱动 | 单通道固定频率 |
| 拉曼跃迁 | 双通道差频锁定 |
| 阱驱动 | 多通道相位控制 |
| 边带冷却 | 频率调制 |

## 替代驱动

还提供基于串口（AT 命令）接口的 AD9959 板替代驱动：

```python

Rigol DG1020Z

DG1020Z 双通道函数/任意波形发生器

⚙️ DG1020Z Rigol 函数发生器

通信	VISA (USB/LAN)
通道数	2
频率范围	1 µHz – 25 MHz
幅度	1 mVpp – 10 Vpp
采样率	200 MSa/s

用于生成 AOM/EOM 驱动信号、调制波形和自定义任意波形。

驱动模块：RigolDG1020Z

from quatm.drivers.awg.specific import RigolDG1020Z

fg = RigolDG1020Z(addr="USB0::0x1AB1::0x0642::DG1ZA123456789::INSTR")
fg.set_frequency(80e6)     # 80 MHz
fg.set_amplitude(1.0)      # 1.0 Vpp
fg.enable_output(channel=1, enable=True)
fg.set_function(channel=1, function="SIN")

DP1116A 可编程直流电源

⚙️ DP1116A Rigol 直流电源

通信	VISA
输出	16V/10A 或 32V/5A
通道数	1
分辨率	1 mV / 1 mA

用于线圈电流控制、激光二极管驱动和电路板供电。

驱动模块：DP1116A

from quatm.drivers.rigol.power_supply import DP1116A

ps = DP1116A(addr="USB0::0x1AB1::0x0E11::DP1A123456789::INSTR")
ps.set_voltage(12.0)       # 12V
dc.set_current(0.5)        # 500 mA 限流
ps.enable_output(True)

示波器

Rigol DS 系列示波器兼容 Tektronix SCPI 指令集，通过 ITektronixScope 驱动控制：

from quatm.drivers.tektronix.base import ITektronixScope

scope = ITektronixScope(addr="USB0::0x1AB1::0x04CE::DS123456789::INSTR", nchannels=4)
scope.set_timebase(scale=1e-6)     # 1 µs/div
scope.set_vertical(channel=1, scale=0.5)  # 0.5 V/div
waveform = scope.acquire(channel=1)

关键方法（信号发生器）

Agilent / Keysight 33500 系列任意波形发生器

⚙️ 33500B / 33220A / 33250A Agilent/Keysight

通信	VISA (USB/LAN/GPIB)
通道数	1–2
频率	最高 120 MHz (33500B)
分辨率	14-bit
采样率	250 MSa/s
波形	正弦/方波/锯齿/脉冲/噪声/ARB

实验室标准信号源，用于 AOM 驱动、调制信号和参考时钟生成。

驱动模块：Agilent33500 / Agilent33220A

from quatm.drivers.awg.specific import Agilent33500

awg = Agilent33500(addr="USB0::0x0957::0x2C07::MY52801234::INSTR")

# 配置 80 MHz 正弦波
awg.set_function(channel=1, function="SIN")
awg.set_frequency(80e6)
awg.set_amplitude(1.0)      # 1 Vpp
awg.enable_output(channel=1, enable=True)

# 脉冲串模式 — 生成 N 个周期后自动关闭
awg.enable_burst(channel=1, ncycles=100)

支持型号

驱动类	适用型号
`Agilent33500`	33500B、33510B、33520B、33522B
`Agilent33220A`	33220A、33250A
`RigolDG1000`	DG1022、DG1032
`RigolDG1020Z`	DG1022Z、DG1032Z

Instek AFG2000 / AFG2225 双通道

⚙️ AFG-2225 / AFG-2100 Instek

通信	VISA
通道数	1 (AFG2000) / 2 (AFG2225)
频率	最高 25 MHz
采样率	200 MSa/s

性价比高的双通道任意波形发生器。

驱动模块：InstekAFG2225 / InstekAFG2000

from quatm.drivers.awg.specific import InstekAFG2225

awg = InstekAFG2225(addr="USB0::...")
awg.set_frequency(10e6)
awg.set_amplitude(2.0)
awg.enable_output(channel=1, enable=True)
awg.enable_output(channel=2, enable=True)

Tektronix AFG1000 任意波形发生器

⚙️ AFG1022 / AFG1062 Tektronix

通信	VISA
通道数	2
频率	最高 60 MHz (AFG1062)
采样率	300 MSa/s
任意波形	64 MB 存储

双通道高性能 AWG，支持大容量自定义波形。

驱动模块：TektronixAFG1000

from quatm.drivers.awg.specific import TektronixAFG1000

awg = TektronixAFG1000(addr="USB0::...")
awg.set_function(channel=1, function="ARB")
# 加载自定义波形...

Tektronix DPO/MSO 系列示波器

⚙️ DPO2000 / MSO4000 系列 Tektronix 示波器

通信	VISA
带宽	100 MHz – 1 GHz
通道数	2–4
采样率	最高 5 GS/s

通过 SCPI 自动化波形采集和参数测量。常用于实验调试和脉冲序列验证。

驱动模块：ITektronixScope

from quatm.drivers.tektronix.base import ITektronixScope

scope = ITektronixScope(
    addr="USB0::0x0699::0x0401::C012345::INSTR",
    nchannels=4
)

# 配置触发
scope.set_trigger(source=1, level=0.5, slope="POS")
scope.set_timebase(scale=1e-6)          # 1 µs/div
scope.set_vertical(channel=1, scale=0.1) # 0.1 V/div

# 采集波形
waveform = scope.acquire(channel=1)

Agilent E5071C 矢量网络分析仪

⚙️ E5071C Agilent VNA

通信	VISA
频率	9 kHz – 20 GHz
端口	2–4
功能	S 参数、阻抗、史密斯圆图

用于 RF 器件特性表征：滤波器、放大器、天线和传输线的 S 参数测量。

驱动模块：AgilentE5071C

from quatm.drivers.Agilent.vna import AgilentE5071C

vna = AgilentE5071C(addr="TCPIP::192.168.1.100::INSTR")
vna.set_frequency_range(start=1e6, stop=1e9, points=1001)
vna.set_if_bandwidth(100)       # 100 Hz IFBW
vna.set_averaging(count=10)

# 读取 S21 参数
freq, s21 = vna.read_S_parameters(parameter="S21")

PicoVNA 便携式矢量网络分析仪

⚙️ PicoVNA Pico Technology

通信	TCP/SCPI (端口 5025)
频率	300 kHz – 8.5 GHz
端口	2
动态范围	100 dB

紧凑型 USB 控制 VNA，适合实验室桌面 RF 调试。

驱动模块：PicoVNA

from quatm.drivers.PicoTech.vna_scpi import PicoVNA

vna = PicoVNA(addr="localhost")  # 或 IP 地址
vna.set_frequency_range(start=10e6, stop=500e6)
s_params = vna.read_S_parameters(parameter="S21")

通用 SCPI 设备配置

"function_gen": {
    "type": "local",
    "module": "drivers.awg.specific",
    "class": "Agilent33500",
    "arguments": {"addr": "USB0::..."},
}

3.3 - 激光器与光学

Cobolt、Toptica、Sirah Matisse、M² Solstis、HighFinesse 波长计等激光器与光学测量驱动。

概述

Quatm 支持半导体激光器、泵浦激光器、可调谐环形激光器及光学测量仪器。激光器类设备通过串口控制；SCPI 仪器继承标准接口。

概述

Quatm 支持半导体激光器、泵浦激光器、可调谐环形激光器及光学测量仪器。激光器类设备通过串口和SCPI协议通信。

Hubner Cobolt MLD / DPL 单频激光器

⚙️ Cobolt 06-01 系列 Hubner Cobolt

通信	串口 (115200 baud)
波长	405/445/488/515/532/561/594/633/660/780/1064 nm
功率	25–300 mW
调制	模拟 + 数字 TTL (高达 5 MHz)

紧凑型 DPSS/半导体激光器，适合离子/原子冷却光、再泵浦光和荧光激发。

驱动模块：Cobolt

from quatm.drivers.Hubner.Cobolt import Cobolt

laser = Cobolt(conn="/dev/ttyUSB0")

# 开启激光
laser.set_autostart(True)
laser.set_power(50e-3)         # 50 mW

# 数字调制（TTL）
laser.set_digital_modulation(True)
laser.set_modulation_power(100e-3)  # 调制时的高功率

# 读取运行参数
hours = laser.get_operating_hours()
temp = laser.get_base_temperature()

Toptica iBeam 智能半导体激光器

⚙️ iBeam 系列 Toptica

通信	串口 (115200 baud)
波长	375–1550 nm

带内置控制器的智能激光头，支持自动电流/功率校准和状态诊断。

驱动模块：TopticaIBeam

from quatm.drivers.Toptica.ibeam import TopticaIBeam

laser = TopticaIBeam(conn="/dev/ttyUSB0")
laser.set_power(channel=0, power=10e-3)
laser.enable(channel=0, enable=True)

Laser Quantum Finesse 泵浦激光器

⚙️ Finesse Laser Quantum

通信	串口 (19200 baud)
功率	4–16 W (532 nm)
噪声	< 0.1% RMS
应用	钛宝石/染料激光器泵浦

超低噪声连续波 DPSS 激光器，用于泵浦 Sirah Matisse 等可调谐环形激光器。

驱动模块：Finesse

from quatm.drivers.LaserQuantum.base import Finesse

pump = Finesse(conn="/dev/ttyUSB0")
pump.set_power(10.0)           # 10 W
pump.enable(True)
actual_power = pump.get_power()

Lighthouse Photonics Sprout G

⚙️ Sprout G Lighthouse Photonics

通信	串口 (19200 baud)
波长	532 nm
功率	6–18 W
噪声	< 0.2% RMS

高功率 532 nm 固态泵浦激光器，适用于钛宝石激光器和光偶极阱。

驱动模块：SproutG

from quatm.drivers.LighthousePhotonics.base import SproutG

sprout = SproutG(conn="/dev/ttyUSB0")
sprout.set_power(15.0)
sprout.enable(True)

Sirah Matisse 可调谐环形激光器

⚙️ Matisse Sirah Lasertechnik

通信	VISA 或 TCP/IP
波长范围	可见光–近红外 (取决于染料/钛宝石)
线宽	< 50 kHz (锁定)
调谐元件	双折射滤波器 + 薄/厚标准具 + 压电

精密可调谐环形激光器系统。MatisseTuner 协调激光器与 HighFinesse 波长计，实现自动波长调谐和扫描拼接。

驱动模块：SirahMatisse / MatisseTuner

from quatm.drivers.Sirah.Matisse import SirahMatisse

matisse = SirahMatisse(addr="TCPIP::192.168.1.10::INSTR")

# 设置波长
matisse.set_birefringent_filter(wavelength=780.24)  # nm
matisse.set_thin_etalon(wavelength=780.24)
matisse.set_thick_etalon(wavelength=780.24)

# 压电扫描
matisse.set_piezo_voltage(50.0)   # 0–100 V

# 自动调谐（需配合波长计）
from quatm.drivers.Sirah.tuner import MatisseTuner

tuner = MatisseTuner(laser=matisse, wavemeter=wlm)
tuner.tune_to(wavelength=780.24)  # 自动搜索并锁定
tuner.scan(start=780.20, stop=780.30, speed=0.01)  # nm/s

M² Solstis 窄线宽可调谐激光器

⚙️ Solstis M² Lasers

通信	TCP/IP JSON + WebSocket
波长范围	700–1000 nm (钛宝石)
线宽	< 50 kHz
功能	标准具锁定、腔参考锁定、波长计反馈

全数字可调谐激光系统，通过 TCP/IP JSON 接口完全远程控制。支持 WebSocket 实时状态流。

驱动模块：Solstis (ICE Bloc)

from quatm.drivers.M2.solstis import Solstis

solstis = Solstis(addr="192.168.1.20", port=8080)

# 波长调谐
solstis.set_wavelength(780.24)
# 标准具锁定
solstis.lock_etalon()
# 太赫兹扫描（与 EMM 模块配合）
solstis.set_terahertz_scan(start_freq=0, stop_freq=100e9)

光功率计 & 波长计

Thorlabs PM100/PM400 光功率计

Thorlabs 光功率计详情见本页下方。

Ophir Vega 激光功率/能量计

⚙️ Vega Ophir

通信	串口
探头	热电堆/光电二极管/热释电
功率	µW – kW
能量	µJ – J

多功能激光测量仪，支持连续波功率和脉冲能量测量。

驱动模块：VegaPowerMeter

from quatm.drivers.Ophir.base import VegaPowerMeter

pm = VegaPowerMeter(conn="/dev/ttyUSB0")
power = pm.get_power()

HighFinesse WS6/WS7 精密波长计

⚙️ WS6 / WS7 HighFinesse

通信	原生 wlmData.dll
精度	2–200 MHz (取决于型号)
通道数	1–8
测量速率	最高 500 Hz
波长范围	350–1120 nm

用于精密激光频率测量和反馈控制的 Fizeau 干涉仪波长计。多通道型号可同时监测多台激光器频率。

驱动模块：WLM

from quatm.drivers.HighFinesse.wlm import WLM

wlm = WLM(version=7, dll_path="C:\\wlm\\wlmData.dll")

# 读取通道 1 当前频率
freq = wlm.get_frequency(channel=1)    # THz
wavelength = wlm.get_wavelength(channel=1)  # nm

# 曝光控制（自动适应光强）
wlm.set_exposure(channel=1, mode="auto")

Matisse 自动调谐

HighFinesse 波长计 + Sirah Matisse 的组合是 Quatm 中典型的激光频率反馈控制系统。MatisseTuner 驱动协调两者，实现闭环自动调谐和宽范围无跳模扫描。

Thorlabs 光功率计

光功率计 `GenericPM`

⚙️ PM100 / PM400 系列 Thorlabs 功率计

通信	VISA (USB)
支持探头	光电二极管/热电堆/热释电
波长范围	取决于探头
功率范围	nW – W 级

通过 SCPI 命令与 Thorlabs 功率计表头通信，支持多种探头类型。

驱动模块：GenericPM

from quatm.drivers.thorlabs.misc import GenericPM

pm = GenericPM(addr="USB0::0x1313::0x8078::P1234567::INSTR")

# 设置工作波长（用于探头校准）
pm.set_wavelength(780.0)    # 780 nm

# 读取功率
power = pm.get_power()      # 返回当前功率 (W)

TLCamera 科学相机 `ThorlabsTLCamera`

Thorlabs 光功率计 PM100 / PM400

⚙️ PM100 / PM400 系列 Thorlabs 功率计

通信	VISA (USB)
支持探头	光电二极管/热电堆/热释电
波长范围	取决于探头
功率范围	nW – W 级

通过 SCPI 命令与 Thorlabs 功率计表头通信，支持多种探头类型。

驱动模块：GenericPM

from quatm.drivers.Thorlabs.misc import GenericPM
pm = GenericPM(addr="USB0::0x1313::0x8078::P1234567::INSTR")
pm.set_wavelength(780.0)    # 780 nm 校准
power = pm.get_power()      # 当前功率 (W)

3.4 - 运动与定位

PI 纳米定位台、Attocube、Newport Picomotor、Thorlabs APT 等精密运动与定位驱动。

概述

Quatm 支持从压电纳米定位到步进电机长行程的多种运动平台，统一 IMultiaxisStage 接口。

Physik Instrumente (PI) 压电纳米定位

概述

GenericPIController 封装 PI 通用控制器串口通信，通过 ASCII 命令集控制多种 PI 压电定位平台。

⚙️ PI 压电控制器 E-xxx 系列

通信	串口 (RS232)
协议	PI ASCII 命令集
轴数	取决于控制器型号
精度	亚纳米级

典型应用包括高 NA 物镜精密对焦、光纤耦合自动对准、干涉仪光路调节和光偶极阱束腰位置控制。

驱动模块：GenericPIController

初始化

from quatm.drivers.PhysikInstrumente.base import GenericPIController

# 串口连接
stage = GenericPIController(conn="/dev/ttyUSB0")

# 归零
stage.home(axis=0)

# 绝对定位（µm）
stage.move_to(axis=0, position=50.0)

# 相对移动
stage.move_by(axis=1, delta=10.0)

# 查询当前位置
pos = stage.get_position(axis=0)

关键方法

方法	说明
`home(axis)`	指定轴归零
`move_to(axis, position)`	绝对定位 (µm)
`move_by(axis, delta)`	相对移动 (µm)
`get_position(axis)`	查询当前位置
`stop(axis)`	紧急停止

设备配置

"objective_z": {
    "type": "local",
    "module": "drivers.PhysikInstrumente.base",
    "class": "GenericPIController",
    "arguments": {"conn": "/dev/ttyUSB0"},
}


## 使用示例

```python
# 在 Experiment 类中
self.pi_stage = self.get_device("pi_stage")

# 移动到指定位置 (μm)
self.pi_stage.move_absolute(x=50.0, y=25.0, z=10.0)

# 相对移动
self.pi_stage.move_relative(dx=1.0, dy=0.0, dz=0.0)

注意：压电平移台有行程限制，超出范围会触发硬件保护。使用前请查阅设备手册确认最大行程。

Thorlabs APT/Kinesis 位移台

KDC101 / K10CR1 系列

⚙️ KDC101 / K10CR1 / 滤光轮 Thorlabs APT/Kinesis

通信	串口 (FTDI)
协议	APT (二进制)
适用设备	直流伺服电机、步进电机、滤光轮、快门

统一封装 Thorlabs APT 协议设备。

驱动模块：BasicKinesisDevice

from quatm.drivers.Thorlabs.kinesis import BasicKinesisDevice
stage = BasicKinesisDevice(conn="27200001")
stage.home()
stage.move_to(position=25.0)    # mm

Elliptec 压电谐振电机

⚙️ ELLx 系列 Thorlabs Elliptec

通信	串口 (9600 baud)
行程	取决于滑块
精度	µm 级

紧凑型压电谐振电机，适合空间受限的光学调整架。

驱动模块：ElliptecMotor

from quatm.drivers.Thorlabs.elliptec import ElliptecMotor
motor = ElliptecMotor(conn="/dev/ttyUSB0", addrs=[0])
motor.move_to(axis=0, position=10.0)

电动滤光轮 FW102/FW212

from quatm.drivers.Thorlabs.serial import FW
fw = FW(conn="/dev/ttyUSB0")
fw.set_position(position=2)    # 切换到第 2 个滤光片位置

Physik Instrumente (PI)

概述

GenericPIController 封装 PI 通用控制器串口通信，通过 ASCII 命令集控制多种 PI 压电定位平台。

⚙️ PI 压电控制器 E-xxx 系列

通信	串口 (RS232)
协议	PI ASCII 命令集
轴数	取决于控制器型号
精度	亚纳米级

典型应用包括高 NA 物镜精密对焦、光纤耦合自动对准、干涉仪光路调节和光偶极阱束腰位置控制。

驱动模块：GenericPIController

初始化

from quatm.drivers.PhysikInstrumente.base import GenericPIController

# 串口连接
stage = GenericPIController(conn="/dev/ttyUSB0")

# 归零
stage.home(axis=0)

# 绝对定位（µm）
stage.move_to(axis=0, position=50.0)

# 相对移动
stage.move_by(axis=1, delta=10.0)

# 查询当前位置
pos = stage.get_position(axis=0)

关键方法

方法	说明
`home(axis)`	指定轴归零
`move_to(axis, position)`	绝对定位 (µm)
`move_by(axis, delta)`	相对移动 (µm)
`get_position(axis)`	查询当前位置
`stop(axis)`	紧急停止

设备配置

"objective_z": {
    "type": "local",
    "module": "drivers.PhysikInstrumente.base",
    "class": "GenericPIController",
    "arguments": {"conn": "/dev/ttyUSB0"},
}


## 使用示例

```python
# 在 Experiment 类中
self.pi_stage = self.get_device("pi_stage")

# 移动到指定位置 (μm)
self.pi_stage.move_absolute(x=50.0, y=25.0, z=10.0)

# 相对移动
self.pi_stage.move_relative(dx=1.0, dy=0.0, dz=0.0)

注意：压电平移台有行程限制，超出范围会触发硬件保护。使用前请查阅设备手册确认最大行程。

Thorlabs 位移台与电机

Quatm 支持多类 Thorlabs 设备，包含位移台、光学测量仪器与相机。

APT/Kinesis 位移台 `BasicKinesisDevice`

⚙️ KDC101 / K10CR1 / 滤光轮 Thorlabs APT/Kinesis

通信	串口 (FTDI)
协议	APT (二进制)
适用设备	直流伺服电机、步进电机、滤光轮、快门

统一封装 Thorlabs APT 协议设备，通过串口（FTDI 芯片）通信。

驱动模块：BasicKinesisDevice

from quatm.drivers.thorlabs.kinesis import BasicKinesisDevice

# 连接指定序列号的设备
stage = BasicKinesisDevice(conn="27200001")  # 序列号

# 归零
stage.home()

# 绝对定位（mm）
stage.move_to(position=25.0)

# 读取当前位置
pos = stage.get_position()

Elliptec 压电谐振电机 `ElliptecMotor`

⚙️ ELLx 系列 Thorlabs Elliptec

通信	串口 (9600 baud)
行程	取决于滑块长度
精度	µm 级
真空兼容	可选

紧凑型压电谐振电机，适合空间受限的光学调整架。

驱动模块：ElliptecMotor

from quatm.drivers.thorlabs.elliptec import ElliptecMotor

motor = ElliptecMotor(conn="/dev/ttyUSB0", addrs=[0])
motor.move_to(axis=0, position=10.0)   # mm

电动滤光轮

from quatm.drivers.thorlabs.serial import FW

fw = FW(conn="/dev/ttyUSB0")          # FW102 / FW212
fw.set_position(position=2)            # 切换到第 2 个滤光片位置

KDC101 电机平移台

通过 .NET SDK 控制 Thorlabs KDC101/T-Cube 系列电机平移台。

from quatm.drivers.thorlabs.kdc101 import KDC101

stage = KDC101("26001234")   # 序列号
stage.home()                  # 回零
stage.move_absolute(10.0)     # 移动到 10.0 mm
pos = stage.get_position()    # 读取当前位置

功能	说明
回零	自动寻找限位开关
绝对移动	移动到指定位置 (mm)
相对移动	相对当前位置移动
位置读取	实时读取当前位置

##概述

Quatm 支持从压电纳米定位到步进电机长行程的多种运动平台。所有平台继承 io.stage 接口，提供统一的 move_to / get_position / home API。

Attocube ANC300 / ANC350 纳米定位

⚙️ ANC300 Attocube

通信	TCP/IP (端口 7230)
轴数	最多 7 轴
行程	mm 级
精度	nm 级
适用	低温 / 真空

模块化纳米定位控制器，通过 TCP/IP 远程控制。广泛用于低温恒温器内物镜和样品的精确定位。

驱动模块：ANC300

from quatm.drivers.Attocube.anc300 import ANC300

anc = ANC300(conn=("192.168.1.30", 7230))

# 归零
anc.home(axis=0)

# 纳米级步进
anc.move_by(axis=0, delta=0.1)  # 100 nm

# 连续扫描模式
anc.set_continuous_mode(axis=1, enable=True)
anc.set_continuous_speed(axis=1, speed=100.0)  # nm/s

⚙️ ANC350 Attocube (USB)

通信	USB HID (PyUSB)
轴数	最多 3 轴
控制	USB 直接连接

USB 版本，适合桌面应用。

驱动模块：ANC350

from quatm.drivers.Attocube.anc350 import ANC350

anc = ANC350(conn=0)  # 第一台 USB 设备
anc.move_to(axis=0, position=50.0)

Newport Picomotor 8742 4 轴控制器

⚙️ Picomotor 8742 Newport

通信	USB (PyUSB) 或 TCP/IP Telnet (端口 23)
轴数	4
步长	< 30 nm
真空兼容	可选

压电惯性电机控制器，支持 USB 直连或网络控制。真空兼容型号可直接用于真空腔内的光学元件调整。

驱动模块：Picomotor8742

from quatm.drivers.Newport.picomotor import Picomotor8742

# USB 连接
pico = Picomotor8742(conn=0)

# 或 TCP/IP
pico = Picomotor8742(conn="192.168.1.40", multiaddr=(0, 1))

pico.move_to(axis=0, position=5.0)  # mm
pico.home(axis=0)

SmarAct MCS2 / SCU3D 高精度定位

⚙️ MCS2 SmarAct

通信	原生 MCS2 SDK
轴数	最多 18 轴
精度	nm 级
速度	最高 20 mm/s
真空/低温	可选模块

模块化高精度定位系统，支持多轴协调运动和复杂轨迹。

驱动模块：MCS2

from quatm.drivers.SmarAct.MCS2 import MCS2

mcs = MCS2(locator="usb:sn:12345678")
mcs.move_to(axis=0, position=10.0)  # mm
mcs.get_position(axis=0)

⚙️ SCU3D SmarAct 3 轴

通信	SCU3DControl SDK
轴数	3

一体化 3 轴控制器，适合紧凑空间。

驱动模块：SCU3D

from quatm.drivers.SmarAct.scu3d import SCU3D

scu = SCU3D(idx=0)
scu.move_to(axis=1, position=25.0)

Standa 8SMC 步进电机控制器

⚙️ 8SMC4 / 8SMC5 Standa

通信	串口 (115200 baud)
轴数	1–4
步进分辨率	取决于电机/丝杠
应用	长行程位移台、旋转台

经济型步进电机控制器，适合光学平台上的长行程粗定位。

驱动模块：Standa8SMC

from quatm.drivers.standa.base import Standa8SMC

stage = Standa8SMC(conn="/dev/ttyUSB0")
stage.move_to(position=50.0)  # mm
stage.home()

Arcus Performax 多轴步进控制

⚙️ Performax Arcus Technology

通信	USB (DLL) 或 RS485 串口
轴数	最多 4 轴
功能	加减速曲线、限位检测

高性能步进电机控制器，提供平滑的 S 曲线加减速。

驱动模块：GenericPerformaxStage

from quatm.drivers.arcus.performax import GenericPerformaxStage

stage = GenericPerformaxStage(idx=0, conn="USB")
stage.move_to(axis=0, position=100.0)
stage.set_acceleration(axis=0, accel=50.0)   # mm/s²

Trinamic TMCM-1110 一体化步进电机

⚙️ TMCM-1110 Trinamic

通信	串口 (9600 baud, TMCL 协议)
功能	StallGuard 失速检测、CoolStep 节能

一体化步进电机模块，内置控制器和驱动器。适合简单旋转/平移任务和光路快门。

驱动模块：TMCM1110

from quatm.drivers.trinamic.base import TMCM1110

motor = TMCM1110(conn="/dev/ttyUSB0")
motor.move_to(position=180.0)  # 旋转 (°)
motor.set_velocity(500.0)      # °/s

Thorlabs Elliptec 压电谐振电机

Thorlabs 位移台详情见本页下方。

通用运动平台配置

"objective_z": {
    "type": "local",
    "module": "drivers.Attocube.anc300",
    "class": "ANC300",
    "arguments": {"conn": ("192.168.1.30", 7230)},
}

多轴协调

所有 io.multiaxisstage 驱动支持独立的轴向映射。通过 muxaxis 工具可将物理轴组合为逻辑坐标系，实现倾斜校正、坐标变换等高级功能。

3.5 - DAQ 与电源

NI DAQ、Rigol/EA 电源、Keithley/Voltcraft 万用表、示波器等数据采集与电学测量驱动。

概述

数据采集和电源设备是实验自动化的基础设施。Quatm 提供统一的 NI-DAQmx 封装和 SCPI/Modbus 仪器驱动。

Rigol DP1116A 可编程直流电源

⚙️ DP1116A Rigol 直流电源

通信	VISA
输出	16V/10A 或 32V/5A
通道数	1
分辨率	1 mV / 1 mA

用于线圈电流控制、激光二极管驱动和电路板供电。

驱动模块：DP1116A

from quatm.drivers.rigol.power_supply import DP1116A

ps = DP1116A(addr="USB0::0x1AB1::0x0E11::DP1A123456789::INSTR")
ps.set_voltage(12.0)       # 12V
dc.set_current(0.5)        # 500 mA 限流
ps.enable_output(True)

Rigol DP932 可编程直流电源

用于为各种实验室设备提供可编程直流电源。

from quatm.drivers.rigol.dp932 import RigolDP932

psu = RigolDP932("USB0::...")
psu.set_voltage(1, 5.0)     # 通道 1: 5.0 V
psu.set_current(1, 1.0)     # 通道 1: 1.0 A 限流
psu.output_on(1)

NI-SWITCH 矩阵/多路复用开关

⚙️ PXI-25xx / SCXI-11xx 系列 NI-SWITCH

通信	NI-SWITCH API
拓扑	矩阵/多路复用/通用
通道	取决于模块
切换速度	ms 级
最大电压	300 V (取决于模块)

NI 开关模块通过 niswitch Python API 控制。适用于实验中的信号路由切换、校准多路复用和线圈极性翻转。

驱动模块：ni_switch

from quatm.drivers.NI.ni_switch import NISwitch

sw = NISwitch(resource_name="PXI1Slot2")
sw.connect(channel1="ch0", channel2="com0")
sw.disconnect(channel1="ch0", channel2="com0")
all_relays = sw.get_relay_count()

NI-Digital 数字波形发生器/分析仪

⚙️ PXIe-657x / PXIe-655x 系列 NI-Digital

通信	NI-Digital Pattern API
通道	32–128
速率	最高 200 MHz
电压	1.2–5.5 V (可编程)
功能	Pattern 生成/采集、PMU 参数测量

NI 数字波形仪器通过 nidigital Python API 控制。生成和采集高速数字波形，适用于自定义 TTL 时序协议和芯片级数字测试。

驱动模块：ni_digital

from quatm.drivers.NI.ni_digital import NIDigital

dig = NIDigital(resource_name="PXI1Slot3")
dig.configure_voltage_levels(voltage=3.3)
pattern = [0b10101010] * 100  # 100 周期数字波形
dig.burst_pattern(pattern, frequency=10e6)

NI-DAQmx 多功能数据采集卡

⚙️ PCIe-63xx / USB-63xx / PXI 系列 NI DAQ

通信	NI-DAQmx
模拟输入	16-bit, 最高 2 MS/s
模拟输出	16-bit
数字 I/O	TTL, 最高 10 MHz
计数器	2–4 通道

通用多功能数据采集卡，用于模拟信号记录、时序数字 I/O 和光子计数。

驱动模块：NIDAQ

from quatm.drivers.NI.daq import NIDAQ

daq = NIDAQ(
    dev_name="Dev1",
    rate=100_000,         # 100 kS/s
    buffer_size=10_000,
)

# 模拟输入（连续采集）
daq.configure_ai(channels=["ai0", "ai1"], voltage_range=(-10, 10))
daq.start_ai()
data = daq.read_ai(samples=1000)

# 模拟输出
daq.configure_ao(channels=["ao0"], voltage_range=(0, 5))
daq.write_ao(channel="ao0", voltage=3.3)

# 数字 I/O
daq.configure_di(lines=["port0/line0"])
daq.configure_do(lines=["port0/line1"])
daq.write_do(line="port0/line1", value=True)

# 计数器（光子计数 / 频率测量）
daq.configure_counter(
    counter="ctr0",
    mode="edge_count",
    source="PFI0",
)
counts = daq.read_counter("ctr0")

Conrad 继电器板控制器

⚙️ Relay Board Conrad

通信	串口 (19200 baud, 二进制协议)
通道	每板 8 继电器，支持菊花链
触点	AC/DC 切换

经济型多通道继电器控制器，适合粗粒度开关控制：磁阱线圈极性切换、设备供电开关、激光快门控制。

驱动模块：RelayBoard

from quatm.drivers.Conrad.base import RelayBoard

# 单板
rb = RelayBoard(conn="/dev/ttyUSB0", start_addr=0)
rb.set_relay(relay=0, state=True)   # 闭合第 1 个继电器
rb.set_relay(relay=3, state=False)  # 断开第 4 个继电器

# 字节写入（同时控制 8 路）
rb.write_byte(0b10101010)

Elektro Automatik PS2000B 高功率电源

⚙️ PS2000B 系列 Elektro Automatik

通信	串口 (115200 baud)
功率	640 W – 15 kW (取决于型号)
电压	最高 1500 V
电流	最高 510 A
功能	恒压/恒流/恒功率模式

高功率可编程直流电源，用于磁阱线圈大电流驱动和 Feshbach 共振磁场线圈供电。

驱动模块：PS2000B

from quatm.drivers.ElektroAutomatik.base import PS2000B

ps = PS2000B(conn="/dev/ttyUSB0", remote_mode=True)

# 恒流模式 — 磁场线圈
ps.set_current(50.0)      # 50 A
ps.set_voltage_limit(20.0) # 20 V 限压
ps.enable_output(True)

# 读取实际值
actual_v = ps.get_voltage()
actual_i = ps.get_current()

Keithley 2110 台式数字万用表

⚙️ 2110 Keithley

通信	VISA (USB/LAN)
功能	DCV/ACV/DCI/ACI/电阻/电容/频率/温度
精度	5½ 位
采样率	最高 50 kS/s

精密台式万用表，用于电学特性表征和传感器校准。

驱动模块：Keithley2110

from quatm.drivers.Keithley.multimeter import Keithley2110

dmm = Keithley2110(addr="USB0::0x05E6::0x2110::1234567::INSTR")

# DC 电压测量
voltage = dmm.measure_voltage(range="10V")

# 4 线电阻测量
resistance = dmm.measure_resistance_4wire(range="100Ω")

# 温度（热电偶）
temp = dmm.measure_temperature(tc_type="K")

Voltcraft VC7055 双通道台式万用表

⚙️ VC7055 Voltcraft

通信	串口 (115200 baud, SCPI)
通道数	2
功能	DCV/ACV/DCI/ACI/电阻/频率/电容
蓝牙	可选 (VC7055BT)

双通道台式万用表，内置蓝牙的 BT 型号支持无线数据采集。

驱动模块：VC7055

from quatm.drivers.Voltcraft.multimeter import VC7055

dmm = VC7055(addr="/dev/ttyUSB0")

# 双通道同时测量
v1 = dmm.measure_voltage(channel=1)
v2 = dmm.measure_voltage(channel=2)

设备配置

"daq": {
    "type": "local",
    "module": "drivers.NI.daq",
    "class": "NIDAQ",
    "arguments": {"dev_name": "Dev1", "rate": 100_000},
},
"coil_ps": {
    "type": "local",
    "module": "drivers.ElektroAutomatik.base",
    "class": "PS2000B",
    "arguments": {"conn": "/dev/ttyUSB0", "remote_mode": True},
},
"dmm": {
    "type": "local",
    "module": "drivers.Keithley.multimeter",
    "class": "Keithley2110",
    "arguments": {"addr": "USB0::..."},
},

3.6 - 环境监测

Lakeshore、Cryocon、Pfeiffer、Leybold 等温度、真空、低温监测驱动。

概述

实验室环境监测是量子实验稳定性的基础。Quatm 内置温度、真空和低温液位监测驱动，支持实时数据记录和异常告警。

Lakeshore 218 温度监测器

⚙️ 218 Lakeshore

通信	串口 (9600 baud, 7E1)
通道数	8
传感器	二极管 (Si/GaAs)、铂电阻 (Pt100/1000)、Cernox、RuO₂
温度	1.4 K – 1500 K (取决于传感器)

低温物理实验标准温度监测器。8 通道独立配置，支持二极管、电阻温度计和 Cernox 薄膜电阻。

驱动模块：Lakeshore218

from quatm.drivers.Lakeshore.base import Lakeshore218

ls = Lakeshore218(conn="/dev/ttyUSB0")

# 配置通道 1 为硅二极管
ls.set_sensor_type(channel=1, sensor_type="DT-670")

# 读取温度
temp = ls.get_temperature(channel=1)   # Kelvin
all_temps = ls.get_all_temperatures()  # 全部 8 通道

# 读取传感器原始值（电压/电阻）
raw = ls.get_reading(channel=1)

Cryocon 12C / 14C / 18C 温度控制器

⚙️ 12C / 14C / 18C Cryocon

通信	串口 (9600 baud)
通道数	2–4 (取决于型号)
支持传感器	二极管/Pt/Cernox

带 PID 加热输出的低温温度控制器，用于精密温度稳定。

驱动模块：Cryocon1x

from quatm.drivers.Cryocon.base import Cryocon1x

cryo = Cryocon1x(conn="/dev/ttyUSB0", nchannels=4)

# 读取通道 1 温度
temp = cryo.get_temperature(channel=1)

# PID 设定点
cryo.set_setpoint(channel=1, temperature=4.2)  # 4.2 K
cryo.set_heater_range(channel=1, range="low")
cryo.enable_heater(channel=1, enable=True)

Lumel RE72 · Omron E5_C 温控器

⚙️ RE72 / E5_C Lumel / Omron

通信	RS485 Modbus RTU
功能	PID 自整定、斜坡/保持程序
应用	光学平台温度稳定、激光晶体温控

工业级 PID 温度控制器，通过 Modbus RTU 协议通信。常用于激光器晶体温度控制和光学平台环境温控。

驱动模块：LumelRE72Controller / OmronE5xCController

from quatm.drivers.Lumel.base import LumelRE72Controller
from quatm.drivers.Omron.base import OmronE5xCController

# Lumel RE72
lumel = LumelRE72Controller(conn="/dev/ttyUSB1", daddr=1)
temp = lumel.get_temperature()
lumel.set_setpoint(25.0)

# Omron E5_C
omron = OmronE5xCController(conn="/dev/ttyUSB1", daddr=2)
omron.set_setpoint(30.0)
omron.enable_heater(True)

Pfeiffer TPG2xx 高真空计

⚙️ TPG2xx 系列 Pfeiffer Vacuum

通信	串口 (9600 baud)
通道数	2
支持规管	Pirani / Cold Cathode / 复合规
量程	大气压 – 10⁻¹⁰ mbar

紧凑型双通道真空计控制器，同时支持粗真空（Pirani）和超高真空（冷阴极）规管。

驱动模块：TPG2xx

from quatm.drivers.Pfeiffer.base import TPG2xx

tpg = TPG2xx(conn="/dev/ttyUSB0")

# 读取两路压力
p1 = tpg.get_pressure(channel=1)  # mbar
p2 = tpg.get_pressure(channel=2)

# 规管类型识别
gauge_type = tpg.get_gauge_type(channel=1)

Leybold ITR 宽量程真空计

⚙️ ITR 系列 Leybold

通信	串口 (9600 baud, 二进制协议)
量程	大气压 – 5×10⁻¹⁰ mbar
输出	持续压力数据流

宽量程皮拉尼/冷阴极复合真空计，主动推送压力数据。

驱动模块：GenericITR

from quatm.drivers.Leybold.base import GenericITR

itr = GenericITR(conn="/dev/ttyUSB0")
pressure = itr.get_pressure()  # mbar

Agilent XGS-600 多通道真空控制器

⚙️ XGS-600 Agilent

通信	串口 (RS485)
通道数	最多 6 路规管
规管类型	Hot Filament / Cold Cathode / Pirani / Convection

大型真空系统的多规管控制器，通过 RS485 串联地址访问。

驱动模块：XGS600

from quatm.drivers.Agilent.pressure import XGS600

xgs = XGS600(conn="/dev/ttyUSB0", addr=1)

# 读取所有通道压力
pressures = xgs.get_all_pressures()
p1 = xgs.get_pressure(channel=1)

低温液位监测

Cryomagnetics LM500 液氦/液氮液位计

⚙️ LM500 / LM510 Cryomagnetics

通信	串口 (9600 baud)
功能	He/N₂ 液位、温度、样品室温度
通道	1–2 液位 + 4 温度

超导磁体杜瓦液位监测标准设备。同时监测液氦/液氮液位和样品室温度。

驱动模块：LM500

from quatm.drivers.Cryomagnetics.base import LM500

lm = LM500(conn="/dev/ttyUSB0")

helium_level = lm.get_helium_level()    # %
nitrogen_level = lm.get_nitrogen_level() # %
sample_temp = lm.get_temperature()

American Magnetics 1700 液位监测器

⚙️ 1700 American Magnetics

通信	串口或 TCP/IP (端口 7180)
功能	He / N₂ 液位、继电器控制

支持串口和网络双接口的液位监测器。

驱动模块：AM1700

from quatm.drivers.AmericanMagnetics.base import AM1700

am = AM1700(conn="192.168.1.50")  # TCP/IP
# 或串口: am = AM1700(conn="/dev/ttyUSB0")
level = am.get_helium_level()

通用环境监测配置

"chamber_pressure": {
    "type": "local",
    "module": "drivers.Pfeiffer.base",
    "class": "TPG2xx",
    "arguments": {"conn": "/dev/ttyUSB0"},
},
"cryo_temp": {
    "type": "local",
    "module": "drivers.Lakeshore.base",
    "class": "Lakeshore218",
    "arguments": {"conn": "/dev/ttyUSB1"},
},

自动化监控

结合 Quatm 的 DataStreamMonitor 和 UpdatingPlot 组件，可实时可视化真空、温度和液位数据，并设置阈值告警自动暂停实验。

3.7 - 实验控制与其他

ADwin、NI-FPGA、Red Pitaya 等 FPGA 控制器与辅助设备驱动，覆盖从纳秒级实时时序到通用开关逻辑的全谱实验控制需求。

概述

FPGA 控制器和辅助设备是实验自动化的重要组成：从纳秒级实时时序到继电器开关，Quatm 提供统一的控制接口。目前已支持 ADwin、NI-FPGA、Red Pitaya 等多个品牌。

ADwin

概述

ADwin 是 Jaeger Computergesteuerte Messtechnik 公司的实时控制器系列，基于 FPGA/DSP 架构，独立于 PC 操作系统执行实时任务。

⚙️ ADwin Gold II / Pro II

通信	PCI / USB
处理器	DSP + FPGA
时序精度	纳秒级
模拟输入	16-bit
数字 I/O	TTL (5V)
内存	32 MB DRAM

运行 ADbasic 编译的实时进程，与 Quatm 通过共享内存或寄存器读写通信。典型应用包括激光冷却时序、MOT 磁场开关和光子计数采集。

驱动模块：ADwin

工作原理

PC (Quatm)                    ADwin (实时)
┌──────────┐    PCI/USB    ┌──────────────┐
│ experiment│ ←──────────→ │ ADbasic 进程   │
│   .py     │  Par/Data    │ 纳秒时序 + 采集 │
└──────────┘               └──────────────┘

Quatm 实验脚本通过 ADwin 驱动读写参数和数据数组，与 ADwin 上运行的 ADbasic 进程交互。时序关键部分在 ADwin 硬件上执行，Python 侧负责参数设置和结果读取。

初始化

from quatm.drivers.fpga import ADwin

# 连接 ADwin（PCI 总线）
adw = ADwin(device_number=1)

# 加载并启动 ADbasic 进程
adw.load_process("experiment_sequence.TB1")
adw.start_process()

# 设置实验参数
adw.set_par(1, 100_000)     # Par_1 = 100 µs 冷却时间
adw.set_par(2, 50)          # Par_2 = 50 次循环
adw.set_par(3, 10_000)      # Par_3 = 10 ms 探测时间

# 启动一次实验序列（ADbasic 中通过事件触发）
adw.trigger()

# 读取采集数据
photons = adw.get_data(1, data_length=1000)  # 从 Data_1 读取光子计数

关键方法

方法	说明
`load_process(binary_path)`	加载 ADbasic 编译的二进制进程
`start_process()`	启动已加载的进程
`stop_process()`	停止运行中的进程
`set_par(index, value)`	写入整型参数（1–80）
`set_fpar(index, value)`	写入浮点参数（1–80）
`get_par(index)`	读取整型参数
`get_data(index, data_length)`	读取数据数组（1–200）
`set_data(index, values)`	写入数据数组
`trigger()`	发送软件触发事件

典型 ADbasic 进程结构

' ADbasic 代码片段 — 实验时序
Init:
  Par_1 = 100000   ' 冷却时间 (µs)
  Par_2 = 50       ' 循环次数
Event:
  For i = 1 To Par_2
    P2_DAC(1, 5000)   ' 设置 AOM 功率
    P2_DAC(2, 800)    ' 设置磁场
    ' ... 等待、采集、切换 ...
  Next i

设备配置

"fpga": {
    "type": "local",
    "module": "quatm.drivers.fpga",
    "class": "ADwin",
    "arguments": {"device_number": 1},
}

开发调试

开发阶段可使用 FPGADummy 模拟器（无硬件）测试实验逻辑。模拟器提供相同的 API 接口但不执行实际硬件操作，适合在办公电脑上开发和验证实验脚本。

Exception:

quatm.drivers.fpga.adwin.AdWinDriverError(message)

class quatm.drivers.fpga.adwin.AdWinDriverError(Exception):
    pass

quatm.drivers.fpga.client module

Class:

quatm.drivers.fpga.client.AdWinClient(experiment, simulating=None)

class quatm.drivers.fpga.client.AdWinClient(object):
    def filter_cmdlist(self, combinetime=1e-08):
        pass

    def push(self, time, command, value, combinetime=1e-09):
        pass

    def start_realtime(self, processortime=0, repetitions=1):
        pass

    def stop(self):
        pass

quatm.drivers.fpga.units module

NI-FPGA LabVIEW FPGA 模块化仪器

⚙️ PXIe-78xxR / PCIe-78xxR 系列 NI-FPGA

通信	NI-FPGA Interface Python API
FPGA	Xilinx Kintex/Virtex
数字 I/O	最高 1 Gb/s
模拟 I/O	最高 3.2 GS/s
编程	LabVIEW FPGA + Python 运行时控制

通过 nifpga Python API 在运行时控制 LabVIEW FPGA 位流。适合需要极高吞吐量和确定性时序的自定义数字信号处理。

驱动模块：ni_fpga

from quatm.drivers.NI.ni_fpga import NIFPGA

fpga = NIFPGA(resource_name="RIO0", bitfile="custom_logic.lvbitx")
fpga.run()
fpga.write_control("pulse_width", 100)        # ns
fpga.write_control("trigger_delay", 50)
fpga.read_indicator("photon_count")

与 ADwin 的对比

特性	ADwin	NI-FPGA
编程语言	ADbasic (类 BASIC)	LabVIEW FPGA (图形化)
Python 控制	参数/数据数组读写	控件/指示器读写
适用场景	纳秒时序、光子计数	高速 DSP、自定义协议
硬件生态	独立控制器	NI PXI 平台集成

Conrad 继电器板

⚙️ Relay Board Conrad

通信	串口 (19200 baud)
通道	8 继电器/板
支持	菊花链扩展

经济型多通道继电器控制器，适合磁阱线圈极性切换、设备供电开关和激光快门控制。

驱动模块：RelayBoard

from quatm.drivers.Conrad.base import RelayBoard

rb = RelayBoard(conn="/dev/ttyUSB0", start_addr=0)
rb.set_relay(relay=0, state=True)
rb.set_relay(relay=3, state=False)
rb.write_byte(0b10101010)

开发调试

开发阶段可使用 FPGADummy 模拟器测试实验逻辑，无需连接实际硬件。

4 - 数据与分析

数据分析与实时监视：拟合、吸收成像、图像处理、离子检测与数据管理。

概述

分析进程（quatm/analysis/）以独立子进程运行：订阅数据/图像流 → 处理 → 把结果发回数据流或图像流，由分析管理器（AnalysisManager）勾选启动。本目录覆盖各分析进程，以及配套的实时监视、订阅与数据管理 GUI 工具。

分析进程

页面	模块	功能
1D 高斯拟合	`analysis/gaussfit`	每帧一维数据高斯拟合
2D 高斯拟合	`analysis/2D_gauss_fit`(+`_fast`)	ROI 内二维高斯拟合
偏斜高斯拟合	`analysis/gaussfit_skewed`	偏态正态拟合
吸收成像	`analysis/imagedivider`	Beer-Lambert 光学密度
离子检测	`analysis/ion_state` 等	亮斑/单离子/离子态判别
图像处理	`analysis/hot_pixel_*` 等	热像素、旋转、切片、选帧、背景扣除

数据管理与监视

页面	模块	用途
数据管理分析模块	`servers/datamgr` + `GUI/h5storage`	run 级数据汇总与 HDF5 管理
数据实时监视器	`GUI/alignment/plotter`	多 y 轴测量数据绘图
图表动态显示器	`GUI/entries/updating_plot`	实时更新曲线
数据流图片流监视器	`GUI/entries/live_plot`	数据流滚动绘图
数据流订阅管理	`GUI/entries/scrollwindow`	滚动窗口订阅/显示
数据订阅编辑器	`GUI/editors/subscription_editor`	订阅列表增删
图像查看器	`GUI/entries/image_group`	图像查看主窗口
图像监视器	`GUI/entries/image_monitor`	图像/掩码流显示
图形ROI管理器	`GUI/widgets/ROI`	远程同步 ROI
属性更新管理器	`analysis/props_check`	属性时间戳看门狗
属性编辑器	`GUI/entries/property_editor`	属性树编辑
数据图像和相机编辑器	GUI widgets（演进）	数据/图像/相机显示框
表格组件	`GUI/widgets/table_parameter`	record array 表格编辑

运行方式

分析进程通常作为独立子进程由分析管理器启动（脚本 + 输入流 + 类别在分析管理器中配置）；监视/编辑类 GUI 工具可作独立进程启动或嵌入其它窗口，具体见各页面。

4.1 - 2D 高斯拟合

图像流每帧 ROI 内二维高斯拟合：输出拟合参数与 1/e、1/e² 等高线掩膜。

概述

quatm/analysis/2D_gauss_fit.py 提供 二维高斯拟合分析（TwoDGaussFit）：订阅图像流，收到图像后在 ROI 内做二维高斯拟合（astropy Gaussian2D + Const2D， Levenberg-Marquardt 迭代），把拟合参数发到数据流，把 1/e、1/e² 等高线掩膜发回图像流。

另有快速版 quatm/analysis/2D_gauss_fit_fast.py：以 Cython 扩展完成核心拟合，接口与功能相同。

输出参数：中心 x0 / y0、宽度 sigma_x / sigma_y、幅度与背景。

用法

from quatm.analysis.2D_gauss_fit import TwoDGaussFit

fitter = TwoDGaussFit(name="gauss2d")   # 订阅 imagestreams 图像流
fitter.run()

分析进程由分析管理器（AnalysisManager）勾选启动。

4.2 - 1D 高斯拟合

对数据流每帧一维数据做高斯拟合，发布拟合参数与拟合曲线。

概述

quatm/analysis/gaussfit.py 提供 一维高斯拟合分析（Gaussfit）：作为独立分析进程订阅数据流，对每一帧一维数据做高斯拟合并把结果发布到数据流。

拟合函数形如：

f(x) = A0 / (sqrt(2*pi) * sigma) * exp(-(x - pos)^2 / (2*sigma^2)) + offset

输出参数含 A0（面积）、sigma（宽度）、pos（中心）、offset（背景）与 height（峰高 = A0/(sqrt(2π)·σ)）。

配置属性

属性	说明
`datastreams`	输入数据流列表（每帧可为 1D 数组，或 x/y 两行的 2D 数组）

用法

from quatm.analysis.gaussfit import Gaussfit

gf = Gaussfit(name="gauss")   # name 作为属性/数据流命名空间
gf.run()

分析进程由分析管理器（AnalysisManager）勾选启动；输入流与参数在属性树中配置。

4.3 - 表格组件

以表格形式显示/编辑 numpy record array 的参数类型。

概述

quatm/GUI/widgets/table_parameter.py 提供表格组件（table_parameter）：扩展参数树，使参数能以表格形式显示和编辑 NumPy 记录数组，并可通过 registerParameterType 注册为可复用的自定义参数类型。

组件

组件	说明
`table_parameterItem`	编辑 record array 的表格控件参数项（`WidgetParameterItem` 子类）
`table_parameter`	表格参数类型（`Parameter` 子类），配合上面的控件项

关键方法

方法	说明
`makeWidget`（table_parameterItem）	按 recArray 的 dtype 创建 `QTableWidget` 编辑器
`value` / `setValue`（table_parameterItem）	从表格逐格读回 / 把数组逐格写入
`valueChanged`（table_parameterItem）	参数值变化时刷新表格与标签
`setValue` / `valueIsDefault`（table_parameter）	设置参数值 / 判断是否为默认值

用法

from quatm.GUI.widgets.table_parameter import table_parameter

param = table_parameter(name="记录", value=recarray)   # 放入参数树

更完整说明见表格参数。

4.4 - 数据订阅编辑器

管理程序对数据/图像流的订阅：显示、添加、删除与属性热更新。

概述

quatm/GUI/editors/subscription_editor.py 提供数据订阅编辑器（SubscriptionEditor）：管理程序对数据流或图像流的订阅。界面显示当前订阅列表，提供下拉框选择新流并添加，可删除订阅；变更即时同步到属性库并广播信号，供绘图/ 监视组件热更新。

关键方法

方法	说明
`loadSubscriptions`	从属性库读取已保存的订阅并载入列表
`handle_property_changes`	监听属性变更：本订阅键变化时刷新列表并广播
`update_streamlist`	按当前可用数据流列表重建下拉候选
`add`	把下拉框选中的流加入订阅并同步属性
`deletemarked`	移除标记删除的订阅流并同步属性

用法

from quatm.GUI.editors.subscription_editor import SubscriptionEditor

editor = SubscriptionEditor(props=props, category="Data", parent=parent)

构造参数：category 为 Image / Data / List；可用 propprefix、streamkey 与 fullList（List 模式）调整属性键与候选流。更完整说明见订阅编辑器。

4.5 - 数据管理分析模块

数据汇总与存储管理：DataSummary 收集每 run 数据并写 HDF5，配套 h5 管理界面。

概述

数据管理分析模块负责把实验产生的数据流汇总成“每次运行（run）”的完整记录并持久化。quatm/servers/datamgr.py 的 DataSummary 是数据汇总内核：订阅若干数据通道加实验开始/结束事件，把各 run 的数据整理成完整字典，可写入 HDF5、回读与清空。 quatm/GUI/h5storage/ 则提供基于它的数据管理界面（订阅、定时保存与绘图）。

核心组件

组件	模块	说明
`DataSummary`	`servers/datamgr.py`	汇总多通道数据流，整理为每个 run 的完整字典
`H5StorageDataMgr`	`GUI/h5storage/data_manager.py`	汇总/单流/图像数据管理器宿主
`H5StorageGui`	`GUI/h5storage/main_window.py`	数据管理主窗口（数据/绘图/事件标签页）
`H5DataPlotter` / `EventPlotter`	`GUI/h5storage/plotters.py`	测量数据 / 事件数据绘图

关键方法（DataSummary）

方法	说明
`initDataq`	（重新）订阅属性里配置的通道与实验开始/结束事件
`recvData` / `processIncomingData`	接收数据并归并到最近的 run 记录
`savetoFile`	把收集的 run 字典写入 HDF5 结构化数据集
`loadFromFile`	从 HDF5 读回一组已存的 run 字典
`clear`	清空已收集的全部数据
`run_forever`	阻塞式循环持续接收数据

用法

from quatm.servers.datamgr import DataSummary

summ = DataSummary(name="sum")
summ.initDataq()      # 订阅属性中配置的通道
summ.run_forever()    # 阻塞式收数；随后 savetoFile 把 run 字典写入 .h5

输入通道与保存路径在属性树中配置；界面侧操作见数据存储。

4.6 - 数据流订阅管理

滚动数据查看主窗口：ScrollPlot 订阅数据流滚动显示，PlotDataEditor 选择数据源。

概述

quatm/GUI/entries/scrollwindow.py 提供数据流订阅管理（ScrollWindow）：多通道滚动数据查看主窗口，按数量排布 ScrollPlot 子图（每两个换一行），统一把数据块分发到对应子图并刷新；PlotDataEditor 提供数据/图像流的下拉选择。

组件

组件	说明
`ScrollWindow`	主窗口：按数量创建子图、分发数据并刷新
`ScrollPlot`	滚动子图：订阅数据流，环形缓冲 + 定时刷新
`PlotDataEditor`	数据源选择面板：下拉候选并写回属性 ydata

关键方法

方法	说明
`initPlots` / `feedData` / `updatePlot`（ScrollWindow）	建子图 / 喂数据 / 批量刷新
`setnewData`（ScrollPlot）	定时拉取数据并刷新曲线
`dataSelectDialog` / `subscribe_window` / `configureWindow`（ScrollPlot）	选通道 / 改订阅 / 配置本图
`updateDatachannel`（PlotDataEditor）	下拉变化时把选中流写入属性 ydata

用法

from quatm.GUI.entries.scrollwindow import ScrollWindow

win = ScrollWindow(name="PMT 滚动监视", parent=parent, n_plots=2)

在每个子图上通过右键菜单完成数据流订阅、通道选择与配置；更完整说明见滚动波形窗口。

4.7 - 图表动态显示器

订阅数据流并持续更新的实时绘图：UpdatingPlot 与 LivePlot 容器。

概述

quatm/GUI/entries/updating_plot.py 提供 图表动态显示器：UpdatingPlot 是 PlotItem 子类，订阅数据流后定时拉取新数据并刷新曲线；LivePlot 则是内嵌一个 UpdatingPlot 的控件容器，可附带图像流名，方便作为停靠面板嵌入其它窗口。

组件

组件	说明
`UpdatingPlot`	实时绘图项：订阅数据流并持续更新曲线
`LivePlot`	控件容器：内嵌一个 `UpdatingPlot`，可附带图像流

关键方法（UpdatingPlot）

方法	说明
`setnewData`	定时拉取新数据；一维数组自动补 x 轴后更新曲线
`updateConfiguration`	取消旧订阅，按属性里配置的流列表重新订阅并建曲线
`subscribe_window`	打开订阅编辑器勾选数据流并重新应用配置
`configureWindow`	打开属性编辑对话框调整显示设置

用法

from quatm.GUI.entries.updating_plot import UpdatingPlot, LivePlot

plot = UpdatingPlot(name="PMT 信号")        # 直接作为绘图项
host = LivePlot(name="PMT 信号", parent=parent)  # 或作为容器嵌入界面

更完整说明见实时绘图。

4.8 - 图形ROI管理器

通过中心属性库同步位置/尺寸/颜色的可远程 ROI。

概述

quatm/GUI/widgets/ROI.py 提供 ROI：继承 ROI，以唯一名称通过中心属性库通信其颜色、位置与尺寸，适合在图形界面中显示和管理多个兴趣区域，并让远程客户端同步查看与调整。

方法

方法	说明
`update_from_properties`	按属性里的颜色/位置/尺寸刷新 ROI 画笔颜色与几何形状

用法

from quatm.GUI.widgets.ROI import ROI

roi = ROI(name="分析区域", parent=view)   # name 需唯一，重名会共享属性
roi.update_from_properties()

更完整说明见远程 ROI。

4.9 - 偏斜高斯拟合

对数据流一维数据做偏斜高斯（偏态正态）拟合，额外给出偏度与峰值位置。

概述

quatm/analysis/gaussfit_skewed.py 提供 偏斜高斯拟合分析（GaussfitSkewed）：对数据流中每一帧一维数据做偏态正态分布拟合并把结果发布到数据流。相比普通高斯拟合，偏斜高斯在峰形不对称（拖尾）时给出更好描述，结果中额外包含偏度参数与峰值位置等。

用法

from quatm.analysis.gaussfit_skewed import GaussfitSkewed

gs = GaussfitSkewed(name="skewed")   # name 作为属性/数据流命名空间
gs.run()

输入数据流在属性 datastreams 中配置；分析进程由分析管理器（AnalysisManager）勾选启动。

4.10 - 属性编辑器

基于 ParameterTree 的属性树查看与编辑工具。

概述

quatm/GUI/entries/property_editor.py 提供属性编辑器：把属性库的键值树展示成可展开/可编辑的参数树，修改即写回；支持按子树浏览、搜索、保存/加载与删除所选节点。

组件

组件	说明
`TreeEdit`	从 `Properties` 提取信息并整理成树视图结构
`PropEdit`	属性编辑主窗口（`ParameterTree`）：子树浏览、搜索、保存/删除
`ScalableGroup`	特殊参数组：自动生成两个互为倒数的子参数
`PropSelector`	键列表选择器：从属性树勾选并维护键列表

用法

from quatm.GUI.entries.property_editor import PropEdit

editor = PropEdit(name="设备状态", props=props, subtree="/", parent=parent)

以 subtree 限定展示某一路径下的属性。更完整说明见属性编辑器。

4.11 - 属性更新管理器

属性时间戳看门狗：检查属性是否持续更新，超时按 Deadman 方式报警。

概述

quatm/analysis/props_check.py 提供属性更新管理器（PropsCheck）：作为独立分析进程运行的看门狗，周期读取属性路径 _prop_path_abs 指定的时间戳属性，若超过 _deadman_delay_sec 仍未更新，则经 send_error（可配 Mattermost）报警。

关键方法

方法	说明
`run`	周期检查时间戳属性是否新鲜，超时则按 Deadman 方式报警

用法

from quatm.analysis.props_check import PropsCheck

pc = PropsCheck(name="props_watchdog")   # 属性命名空间
pc.run()

GUI 侧另有同用途的属性检查器（PropertiesChecker），验证属性中心确实在分发更新（置标记再读回，未传播则弹窗并告警），见属性检查器。

4.12 - 数据流图片流监视器

实时滚动绘图窗口：订阅数据流/图像流滚动显示，运行平均与右键配置。

概述

quatm/GUI/entries/live_plot.py 提供数据流/图片流滚动监视（ScrollPlot）：多子图滚动窗口 ScrollWindow 内，每个 ScrollPlot 订阅一条数据流的若干通道，维护环形缓冲并滚动显示散点与滑动平均曲线；PlotDataEditor 提供数据源选择下拉。

组件

组件	说明
`ScrollWindow`	多子图滚动主窗口：`restorePlots` 恢复/`addPlot` 追加子图
`ScrollPlot`	滚动子图：环形缓冲、散点与滑动平均，右键菜单操作
`PlotDataEditor`	数据源选择面板：下拉候选并写回属性/父图

关键方法（ScrollPlot）

方法	说明
`feedData` / `setnewData`	新数据块入缓冲 / 定时拉取并刷新
`updatePlot` / `clearPlot`	刷新曲线 / 清空重建本图
`running_mean`	用累积和差分高效计算 N 点滑动平均
`dataSelectDialog` / `subscribe_window` / `configureWindow`	选通道 / 改订阅 / 配置
`deletePlot` / `updateTitle`	移除本图 / 同步标题与数据源

用法

from quatm.GUI.entries.live_plot import ScrollWindow

host = ScrollWindow(name="PMT 滚动监视", parent=parent, n_plots=2)

更完整说明见实时滚动图。

4.13 - 数据实时监视器

绘制测量数据的实时绘图：数据源/多 y 轴、过滤/分箱/拟合与导出。

概述

quatm/GUI/alignment/plotter.py 提供数据实时监视器（DataPlotterWidget）：绘制测量过程中采集到的数据。支持数据源切换、x 轴与多个 y 轴选择器，每个 y 轴经一条可配置的数据链（缩放系数 → 过滤器 → 分箱/拟合）处理后画入图区，并可导出 PDF。

组件

组件	说明
`DataPlotterWidget`	主绘图：数据源下拉、x 轴选择器、若干 y 轴选择器（右键开关配置面板）
`YAxisWidgetHelper`	y 轴数据链：缩放系数、过滤器、分箱与拟合处理

关键方法

方法	说明
`setDataSource`	设置或更换数据源
`checkForNewData` / `updateDatasources`	检查新增数据/新数据源并刷新
`plotData`	把一组 x/y 数据作为新曲线加入图区
`toggleConfig`	切换数据源与 y 轴配置面板显示
`exportpdf`	把当前绘制导出为适合归档的 PDF
`clear`	清空数据汇总与图区全部曲线

Y 轴链（YAxisWidgetHelper）：updateYscale 设置缩放系数，右键菜单可 addBinning 分箱、addFitting 拟合（如高斯/线性），reevaluateData 在过滤器等变化后重跑整条数据链。

用法

from quatm.GUI.alignment.plotter import DataPlotterWidget

plotter = DataPlotterWidget(
    axis_name="myaxis",
    prop_root="...",
    datastream_names=[".../data"],
    n_yaxis=1,
    parent=parent,
)
plotter.toggleConfig()   # 展开数据源 / x、y 轴选择配置

更完整说明见辅助绘图。

4.14 - 数据图像和相机编辑器

显示/编辑数据流、图像与相机属性：相关能力现由参数框、图像监视器与属性编辑器承担。

概述

早期的统一界面曾提供 ParameterBox / ImageDataBox / CamPropsBox / DataBox 一组小部件，用于把单个数据流值、图像数据与相机属性显示为紧凑小框，并支持右键订阅与数据选择。随着 GUI 拆分演进，这些能力已由当前组件分别承担：

旧组件	功能	现对应实现
`ParameterBox`	单个数据流值的紧凑显示	参数框控件（`widgets/arg_boxes` 等）
`ImageDataBox`	图像数据小框显示	图像监视器（`entries/image_monitor.ImageDisplay`）
`CamPropsBox`	相机属性显示与编辑	属性树编辑器（`PropEdit`）+ 订阅
`DataBox`	简单的标签-值小框	GUI 基础框（`BFrame` / `BWidget`）

4.15 - 图像查看器

科学图像查看主窗口：中央图像显示器加行/列线剖面与直方图色标面板。

概述

quatm/GUI/entries/image_group.py 提供图像查看窗口（ImageWindow）：以中央 ImageDisplay 图像显示器为主控件，四周停靠行/列线剖面与直方图色标等面板，用于成像实验的实时监视与分析。

布局结构

停靠区	控件	用途
中央	`ImageDisplay`	订阅并自动刷新图像流，可叠加掩码
顶部	`LivePlot`（行剖面）	图像行的强度分布曲线
右侧	`LivePlot`（列剖面）	图像列的强度分布曲线
左侧	`HistogramLUTWidget`	直方图色标：电平范围与伪彩色映射

显示参数（Viewer/ 命名空间：min/max levels、gradient、tick_position）构造时从属性恢复、关闭时保存。

用法

from quatm.GUI.entries.image_group import ImageWindow

win = ImageWindow(name="吸收成像")   # 独立主窗口
win.show()

更完整说明见图像查看器。

4.16 - 图像监视器

自动更新的图像显示窗口：订阅图像/掩码流，降噪、亮斑检测与保存。

概述

quatm/GUI/entries/image_monitor.py 提供图像监视器（ImageDisplay）：自动更新的图像显示窗口，定时从属性中订阅的图像流拉取最新帧，按分辨率与偏移变换后刷新显示，并同步叠加掩码流；内置降噪、亮斑检测、当前帧保存与属性配置（显示级别、ROI 等）功能。

方法

方法	说明
`update_image` / `update_mask`	定时拉取图像流/掩码流并刷新显示与叠加层
`noise_filter`	按属性参数做双边滤波 + 中值滤波降噪
`spot_detector`	按阈值把图像二值化以检测亮斑
`saveCurrentImage`	把当前显示帧保存为 PNG（按时间命名）
`subscribe_window` / `subscribe_mask`	打开订阅对话框勾选图像流/掩码流后重订阅
`configureWindow`	打开属性编辑对话框调整显示级别、ROI 等

用法

from quatm.GUI.entries.image_monitor import ImageDisplay

view = ImageDisplay(imagestreams=["camera/image"], parent=parent)
view.configureWindow()   # 调整显示级别、ROI 等

更完整说明见图像监视器。

4.17 - 吸收成像

用含原子/无原子/背景帧按 Beer-Lambert 定律计算光学密度（柱密度）。

概述

quatm/analysis/imagedivider.py 提供 吸收成像分析（ImageDivider）：按 imgindex 收集含原子（atom）、无原子（no-atom）与背景（background）图像，结合散射截面等物理参数，按 Beer-Lambert 定律计算光学密度（二维原子柱密度）并发布。

光强关系 I = I₀·exp(−n·σ)，因此柱密度 n = ln(I₀/I)/σ；失谐与线宽等物理参数在实验开始时经事件消息更新。

配置属性

属性	说明
`_atomindex` / `_noatomindex` / `_backgroundindex`	含原子/无原子/背景帧的 imgindex
失谐 / 线宽等	成像激光与跃迁参数（实验事件更新）

用法

from quatm.analysis.imagedivider import ImageDivider

div = ImageDivider(name="od")   # 订阅相应图像流
div.run()

分析进程由分析管理器（AnalysisManager）勾选启动。

4.18 - 离子检测系列

亮斑/单离子检测与离子态判别：BrightSpots、SingleIonPresent 与 IonState 分析进程。

模块概览

模块	类	检测方式	用途
`ion_blob`	`BrightSpots`	阈值分割 + 连通域计数	统计每帧图中的离子数
`bright_spots`	`BrightSpots`	skimage `blob_dog`	检测亮斑，输出位置掩膜与 bloblist
`single_ion_present`	`SingleIonPresent`	计数 + 高斯拟合参数多标准	判断单个离子是否出现
`ion_state`	`IonState`	按 imgindex 的多图序列	离子产物态判别

判别流程

IonState 按各 imgindex 收集 check / survival / hot / shelved 系列图像，逐图检测离子是否出现，汇总后给出产物态结果：

按 imgindex 归类各帧图像（check / survival / hot / shelved）
        ↓ 每帧用 blob 检测离子是否存在
     汇总 → 发布产物态结果

用法

from quatm.analysis.ion_state import IonState

det = IonState(name="ionstate")   # 订阅图像流并按 imgindex 归类
det.run()

各进程均由分析管理器（AnalysisManager）勾选启动；图像流、阈值与 imgindex 等在属性树中配置。

4.19 - 图像处理工具

热像素过滤/查找、旋转、切片、帧选择与背景扣除等图像处理分析进程。

模块列表

以下均为订阅图像流的独立分析进程，位于 quatm/analysis/：

模块	类	功能
`hot_pixel_filter`	`HotFilter`	按属性 hotpixels 坐标列表把热像素过滤/替换后发回
`hot_pixel_finder`	`HotFilter`	统计找出热像素坐标并写入属性（供过滤脚本使用）
`rotate_image`	`ImageRotate`	按角度旋转图像并同步旋转坐标偏移
`imageslice`	`ImageSlice`	按 ROI 计算行列投影（求和/截断/积分）与子区域图
`imageselector`	`ImageSlice`	从图像流中选出指定 imgindex 的那一帧转发
`substract_image`	`ImageSubstract`	减去固定背景图（自动适配转置）输出差值

用法

from quatm.analysis.hot_pixel_filter import HotFilter

f = HotFilter(name="hotfix")   # 订阅图像流，按属性热像素列表过滤
f.run()

各进程均由分析管理器（AnalysisManager）勾选启动，输入流与参数在属性树中配置。

5 - GUI 组件

Quatm 的图形界面组件：实验浏览、参数编辑、任务调度、数据可视化与设备监控。

Quatm 提供了完整的可视化图形界面。以下是所有 GUI 组件的详细文档。

组件索引

组件	文档	简介
🔍 实验浏览器	→	主窗口：文件树、队列/准备台/循环器与 MDI 实验窗口
⚙️ 实验管理器	→	核心执行引擎：测量→序列→单次运行的生命周期管理
📋 实验队列	→	任务队列表格：优先级排序、状态跟踪、暂停/终止/重启
📝 准备台	→	参数暂存、复制、循环构建后推入队列
🔁 循环器	→	条件循环：根据测量结果自动切换实验组
🪟 实验窗口	→	单实验控制：动态参数网格、提交/扫描与 JSON 参数
🎛️ 参数系统	→	FloatBox/BoolBox/ComboBox：参数 GUI 控件体系
🌲 属性编辑器	→	基于 ParameterTree 的键值浏览
📈 实时绘图	→	实时一维数据流：多曲线、缩放、订阅管理
💡 LED指示灯	→	红/绿 LED 状态灯：径向渐变动画
🧱 GUI基础类	→	BWidget/BMainWindow/BFrame，窗口持久化
📷 图像监视器	→	自动刷新图像显示：订阅图像/掩码流、降噪与亮斑检测
📊 分析管理器	→	分析进程的启动/停止/状态监控
📡 数据流监视器	→	多类型数据流：曲线/图像/消息三合一监视
✏️ 序列编辑器	→	代码编辑 + 解析模拟与输出通道时序可视化
⚡ 进程管理器	→	五类后台进程（Server/Driver/GUI/Viewer/Monitor）
🔌 设备管理器	→	PyVISA 设备发现与驱动绑定
💾 数据存储	→	HDF5 存储/加载 + 定时自动保存
⏱️ 自动保存	→	定时保存时间表编辑器
📈 实时滚动图	→	实时滚动折线/散点图：运行平均 + 多曲线
📐 数据模型	→	DictSyncModel：字典/列表到 Qt 表格映射
🔧 实验辅助	→	ODT 对准 + 电场补偿 + 压电镜 + Verdi 对准
🎚️ 参数框	→	紧凑型标签-数值实时参数显示
🗂️ 可折叠组件	→	手风琴式可折叠面板对话框
🧩 实验参数面板	→	实验参数控制面板
🔌 DAC 控制器	→	FPGA DAC 手动设置工具
🧵 后台工作线程	→	QRunnable 后台工作线程：信号驱动
⏱️ 时序浏览器	→	实验时序可视化（DAC+TTL 图表）
📊 滚动波形窗口	→	多通道实时滚动波形显示
📡 订阅编辑器	→	数据/图像流订阅管理
📋 表格参数	→	实验参数树表格编辑节点
🎯 远程 ROI	→	可远程同步的 ROI 组件
🖼️ 图像查看器	→	科学图像查看器（线剖面+LUT）
🔔 属性检查器	→	属性健康轮询+异常告警
📐 辅助绘图工具	→	通用测量数据绘图（多Y轴+滤波+拟合）

架构总览

┌──────────────────────────────────────┐
│            Browser（主窗口）            │
├────────────────┬─────────────────────┤
│ FileSelector   │    QMdiArea          │
│ （实验文件树）    │   ExperimentWindow   │
│                │   （单实验控制窗口）    │
├────────────────┴─────────────────────┤
│  顶部停靠：实验队列 / 准备台 / 循环器      │
├──────────────────────────────────────┤
│       ExperimentManager（执行引擎）     │
└──────────────────────────────────────┘

启动

主程序 实验浏览器 与各独立工具通常由进程管理器（ProcessManager）按类别启动，也可在程序中直接实例化对应主窗口类（见各组件页面用法）。

5.1 - 实验浏览器

Quatm 主窗口：实验浏览、队列管理、多窗口 MDI 工作区。

概述

quatm/GUI/browser/main_window.py 提供 实验浏览器（Browser）：Quatm 的主应用窗口，基于 QMainWindow + QMdiArea 多文档界面。左侧文件选择器浏览实验脚本，顶部停靠实验队列、准备台与循环器，中央 MDI 区内每个实验一个子窗口。

布局

┌─────────────┬───────────────────────────────┐
│ FileSelector │   QMdiArea（实验子窗口区）      │
│ （实验文件树） │   ┌─────────────────────┐   │
│             │   │  ExperimentWindow    │   │
├─────────────┤   └─────────────────────┘   │
│ 队列 / 准备台 │                               │
│ / 循环器停靠  │                               │
└─────────────┴───────────────────────────────┘

核心组件

组件	模块	描述
`FileSelector`	`browser/file_selector.py`	实验目录树，双击打开实验/模拟窗口
`ExperimentWindow`	`browser/experiment_window.py`	中央 MDI 中单个实验的控制面板
`ExperimentQueue`	`experiment/experiment_queue.py`	表格化任务队列
`ExperimentManager`	`experiment/experiment_manager.py`	从队列取任务并执行
`PrepStation`	`experiment/prepstation.py`	任务发往队列前的暂存与编辑
`Looper`	`looper/ui.py`	按测量结果条件循环运行一组任务

上述组件的细节见本目录的对应页面。

生命周期

init_ui / create_dock_widgets：按屏幕适配默认几何，创建 MDI 画布与两侧停靠部件（左侧文件选择器；顶部队列/准备台/循环器）。
open_experiment：打开实验窗口；已打开则从最小化恢复并置前。
closeEvent：先保存主窗口几何与全部实验子窗口状态，再停止队列/循环等 worker 线程，最后交给基类完成关闭。
moveEvent / resizeEvent：防抖保存几何，下次启动时恢复窗口位置与尺寸。

用法

from quatm.GUI.browser.main_window import Browser

browser = Browser()
browser.show()

实验浏览器是运行除 Helper 之外所有实验的界面，通常作为主进程由进程管理器启动。

5.2 - 实验管理器

核心实验执行引擎：从实验队列取任务并按测量/序列/运行层级调度。

概述

quatm/GUI/experiment/experiment_manager.py 提供实验管理器（ExperimentManager ）：从实验队列（ExperimentQueue）取出任务并执行的引擎。其队列轮询运行在 worker 线程，任务按 测量（measurement）→ 重复（repetition）→ 序列/扫描（sequence）→ 单次运行（run） 的层级结构调度。

执行流程

queue_fn（worker 线程持续轮询队列）
  └─→ run（任务包装：任何结束方式都保证收尾）
       ├─→ start_measurement（测量开始钩子）
       ├─→ start_sequence（序列/扫描开始钩子）
       │     └─→ … 多次带变化参数的 run …
       ├─→ end_sequence（序列结束钩子）
       └─→ end_measurement（测量结束钩子并清理任务表）

关键方法

方法	说明
`queue_fn`	持续轮询队列任务字典：按优先级、任务号与预约时间挑选任务
`run`	任务运行包装：无论 Done/Terminated/Failed/删除都正常收尾
`pause`	暂停当前实验；再次调用恢复
`terminate_experiment`	优雅终止：让当前这一次 run 自然跑完再停止
`start_measurement` 等	调用实验的 start/end 各阶段钩子
`set_dict`	把单个参数写入实验对象实例属性
`set_run_nr` / `set_rep_nr`	同步运行/重复序号到任务字典并刷新表格
`due_check`	判断任务是否到预约执行时间
`start_queue` / `shutdown`	启动 / 停止常驻队列 worker
`update_table`	通知 GUI 刷新任务表显示

用法

from quatm.GUI.experiment.experiment_manager import ExperimentManager

manager = ExperimentManager(browser)   # browser 提供队列与界面
manager.start_queue()                  # 启动常驻队列 worker

任务在独立 worker 线程中执行，不阻塞 GUI；浏览器关闭时调用 shutdown 停止队列 worker 以便进程干净退出。

5.3 - 实验队列

任务队列表格面板：维护实验任务的优先级排序、状态跟踪与生命周期管理（暂停/终止/休眠/删除）。

概述

ExperimentQ（quatm/GUI/experiment/experiment_queue.py）是 实验浏览器（Browser） 主窗口里的「实验队列」面板：一个由队列表格模型 ScheduleModel（模块 quatm/GUI/widgets/models.py）驱动的任务表格。任务字典以 任务号 为主键存放，每个任务是一条含运行所需信息的记录；表格按优先级 priority（数值小者优先）→ 任务号排序。

任务状态

实验管理器（ExperimentManager） 与面板共同维护每个任务的状态：

状态	含义
`Queued`	已入队、等待执行
`Waiting`	设置了到期时间（due），未到期前暂不执行
`Sleeping`	休眠中，管理器暂时忽略（可再次点击唤醒）
`Running`	正在执行单次运行
`Scanning`	正在执行序列/扫描
`Paused`	已暂停，可恢复继续
`Terminating` / `Termination Pending`	正在优雅终止（允许当前运行跑完）
`Done`	执行完成
`Failed`	执行失败

操作与快捷键

按钮栏（由 create_buttons 创建）：暂停/恢复、终止选中任务、终止全部等图标按钮。
右键菜单与单键快捷键（init_table_actions）：e 编辑参数、v 只读预览、删除、休眠/唤醒、暂停等。
删除正在运行的任务：自动转为优雅终止（delete_clicked）。
终止（terminate_clicked / terminate_all）：优雅停止，让正在进行的运行先跑完再结束。

主要方法

方法	功能
`submit(taskDict)`	唯一的入队入口（运行在界面线程）：集中分配任务号；循环器（Looper）也经 `submitItem` 信号走到这里
`pause()`	暂停/恢复当前正在运行的实验
`set_sleeping()`	把所选任务标记为休眠或唤醒
`delete_item(k)` / `delete_clicked()`	按任务号删除，或删除所选行（正在运行则优雅终止）
`terminate_clicked()` / `terminate_all()`	优雅终止所选任务 / 全部任务
`update_item(k, v)`	按任务号更新模型条目并复位锁
`open_editor()` / `open_viewer()`	编辑 / 只读预览所选任务的参数（快捷键 `e` / `v`）

数据模型

# 任务字典结构（主键 = 任务号）
expDict = {
    1: {
        "expName": "Rabi 扫描",
        "filepath": "experiments/ion/rabi.py",
        "status": "Queued",
        "priority": 1,
        "args": {},
        "due": "",
    },
}

排序规则：priority（数值小者优先）→ 任务号（先入先出）。

与循环器的关系

循环器（Looper） 的任务条目提交也统一经 ExperimentQ.submit() 入队，因此桌面界面与循环调度共用同一条“集中分配任务号”的入队通道。

5.4 - 准备台

实验参数暂存与编辑区：在推入队列前预览、排序和微调任务。

概述

PrepStation 是实验浏览器（Browser）顶部 dock 中的一个标签页，作为实验队列的 “暂存区”：把尚未准备就绪的任务先存放于此，确认无误后再推入 ExperimentQ 排队执行。任务列表持久化在 configuration/browser/prepfile.json，并可在浏览器端实验控制台（Web 远程控制）中查看与操作。

功能

操作	说明
📋 暂存	实验窗口点击 Prep 按钮，把当前参数（含扫描定义）暂存到任务列表
➡️ 推送	把选中任务复制到 `ExperimentQ`（队列保留任务编号、优先级、扫描参数等完整信息）
🔁 加入循环	把选中任务加入 Looper 循环组（`push_to_looper`）
↕️ 排序	上移/下移调整任务顺序
💤 休眠	标记为 `Sleeping` 后暂不参与推送
✏️ 编辑/查看	打开任务参数编辑器或只读视图
💾 保存/加载	参数集另存为 JSON（`experiment_params/<实验>/<日期>/`）

任务数据结构

每个暂存任务与队列任务同构（由实验窗口 setup_task_dict() 生成）：

task = {
    'task': 12,                 # 任务编号
    'expName': 'Absorption',    # 实验名
    'label': 'scan: freq 2:1',  # 标签（含扫描前缀）
    'priority': 0,
    'args': {'count': 5},       # 实验参数
    'nRuns': 21,                # 扫描点数
    'scanpars': ['freq'],       # 扫描参数
    'scanvals': [[...]],        # 扫描值
    'scansequence': [...],      # 扫描顺序（随机化后）
    'nReps': 1,
    'status': 'Queued',         # Queued / Sleeping / Waiting
    'filepath': '.../absorption.py',
}

持久化与共享

任务列表保存在 configuration/browser/prepfile.json，浏览器重启后自动恢复；
桌面 GUI 与 Web 远程控制平台共用 同一份文件，任意一端暂存/推送/排序/休眠的任务在另一端立即可见。

5.5 - 循环器

条件循环执行器：根据测量结果自动决定是否重复、跳转或终止实验循环。

概述

Looper（循环器）是实验浏览器（Browser）顶部 dock 的标签页（quatm/GUI/looper/），管理实验任务组，按顺序执行组内条目，并根据测量结果决定跳转或终止。循环定义持久化在 configuration/browser/looper/loopfile.json，与浏览器端实验控制台（Web 远程控制）共用 同一份文件。

核心逻辑

LoopManager.run_loop()：从起始组开始，无限循环直到 terminate
  └─→ 按顺序执行组内条目
       ├─ Task：提交任务到实验队列，等待完成后推进
       │        （可设最大次数 / 最大连续次数，达到即终止循环）
       └─ Conditional：读取数据流字段 → 比较（> >= == != =< <）
                ├─ 满足 → 跳转到指定条目 / 组尾 / 结束循环
                └─ 不满足 → 跳转到 else 条目

组件

组件	说明
`LoopGroup`	循环组（一个标签页），内含条目列表与循环构建器
`LoopItem`	条目基类（删除/上移/下移/运行计数/指示灯）
`TaskItem`	任务条目：指向暂存器任务，支持最大次数/最大连续/skip
`ListItem`	任务列表条目：逐个展开任务列表运行
`ConditionalItem`	数据条件条目：字段比较后跳转（if/else）
`ConditionalReachedItem`	到达序号条件条目：当前时刻达到第 N 次周期 h5 保存时刻后跳转
`ConditionalDateTimeItem`	时间条件条目
`CallerItem` / `GroupItem`	组间跳转与组尾条目
`DataManager`	订阅数据流、累积最新测量值
`LoopManager`	循环执行器（`run_loop()` / `terminate()`，后台线程运行）
`AutoSaveEditor`	自动 HDF5 保存计划配置

使用方式

在 实验浏览器（Browser） 中通过循环器（Looper）标签页交互操作：

添加组：新建标签页（New Tab #N），可重命名；
添加条目：每个组内可添加 Task / List / Conditional / ConditionalDateTime / ConditionalReached / Caller 等条目；
配置条目：Task 选择暂存器任务编号并设置最大次数；Conditional 选择数据字段、比较符与阈值，配置 if/else 跳转目标（条目序号 / end box / end loop）；
运行：选择起始组，点击运行；LoopManager 在后台线程执行，终止按钮随时停止。

# 核心类（GUI 内部使用）
from quatm.GUI.looper import Looper, LoopManager

looper = Looper(parent=browser)
looper.loopManager.run_loop()      # 从起始组开始循环
looper.loopManager.terminate()     # 终止循环

持久化与共享

循环定义自动保存到 configuration/browser/looper/loopfile.json （{组名: [条目字典, ...]}），浏览器重启后自动恢复；
桌面 GUI 与 Web 远程控制平台共用同一份文件，任意一端的修改另一端立即可见；浏览器端同样支持组管理、Task/Conditional 条目编辑与循环启停。

5.6 - 实验窗口

单实验控制窗口：动态参数网格、提交/扫描与参数持久化。

概述

quatm/GUI/browser/experiment_window.py 提供 实验窗口（ExperimentWindow）：每个实验脚本在浏览器 MDI 区对应一个由 ExperimentSubWindow 承载的控制窗口，按实验声明的参数对象自动生成参数网格，负责提交队列/预备、扫描构建与 JSON 参数存取。

组件

组件	说明
`ExperimentSubWindow`	图形容器：保存窗口几何并把窗口钳制在可视区内
`ExperimentWindow`	单实验控制面板：参数网格 + 提交/扫描/保存控件
`SequenceEditor`	扫描序列对话框：逐维设定起止与步数生成 nD 扫描

关键方法（ExperimentWindow）

方法	说明
`submit_to_queue`	把当前实验提交到实验队列执行（各提交入口的统一入口）
`submit_next`	以最高优先级提交，排在所有已有任务之前
`submit_to_prepper`	提交到准备台（PrepStation）暂存
`setup_scan`	按扫描定义构建扫描序列（参数值与随机运行顺序）
`setup_task_dict`	构造存入队列/准备台的任务字典
`build_argument_dict`	由参数网格各控件取值生成完整参数字典
`save_params` / `load_params`	参数存为 JSON（按日期/时间命名，可备份）与回载
`adaptive_columns`	按窗口宽度自动重排参数网格列数（约每 200 px 增一列）
`edit_sequence`	打开扫描序列编辑窗口并应用新序列

用法

from quatm.GUI.browser.experiment_window import ExperimentWindow

# 通常由 Browser.open_experiment 打开；也可自行构造
win = ExperimentWindow(filepath=..., props=props, parent=subwindow, browser=browser)

实验脚本声明的参数对象（如 NumberValue / BoolValue / StringCombo）会自动生成带标签、单位与范围的编辑控件；参数组可保存为 json 并在以后加载复用。

5.7 - 参数系统

BasicManager 参数管理器体系：把实验属性映射为数值/布尔/下拉/频率控件。

概述

quatm/GUI/entries/dashboard.py 提供一套“参数管理器”控件体系：每个管理器把一个实验参数（存于属性库，内部一律用 SI 单位）映射为一个带标签的输入控件，并在界面与属性库之间双向同步。

控件类体系

BasicManager（数值类参数条目的基类）
├── IntManager        → 整数微调框
├── FloatManager      → 浮点微调框（可带单位/步进/小数位）
├── BoolManager       → 勾选框
├── ComboManager      → 下拉框（字符串列表）
└── FrequencyManager  → DDS 频率微调框（属性存 Hz，界面显示 MHz）

用法（示意）

from quatm.GUI.entries.dashboard import IntManager, FloatManager, BoolManager

# 每个管理器绑定属性库 props 与实验 exp，按参数名读写
mgr = IntManager(props=props, exp=exp, parname="my_int")
fmgr = FloatManager(props=props, exp=exp, parName="cooling_time", unit="µs")
bmgr = BoolManager(props=props, exp=exp, parName="enable")

界面改动会换算成 SI 写回属性库；属性库变化也会由各控件周期同步到界面显示（updateValue / updateSpin）。

另见「实验参数面板」：Dashboard 主面板据此把整台设备的参数自动排布成可调控制面板。

5.8 - 属性编辑器

基于 ParameterTree 的属性查看与编辑工具。

概述

quatm/GUI/entries/property_editor.py 提供基于 parametertree 的属性编辑工具：把属性库的键值树展示成可展开/可编辑的参数树，支持搜索过滤，修改即写回。

组件

组件	说明
`TreeEdit`	从 `Properties` 提取信息并整理成树视图结构
`PropEdit`	属性编辑主窗口（`ParameterTree`）：子树浏览、搜索、保存/删除所选节点

用法

from quatm.GUI.entries.property_editor import PropEdit

editor = PropEdit(name="设备状态", props=props, subtree="/", parent=parent)

注：以 subtree 限定只展示某一路径下的属性；TreeEdit 负责把属性字典转换为 Parameter 节点树。

5.9 - 实时绘图

订阅数据流并持续更新的实时绘图项及其控件容器。

概述

quatm/GUI/entries/updating_plot.py 提供 实时绘图：UpdatingPlot 是 PlotItem 子类，订阅数据流后定时拉取新数据并刷新曲线；LivePlot 则是内嵌一个 UpdatingPlot 的控件容器，方便作为停靠面板嵌入其它窗口。

组件

组件	说明
`UpdatingPlot`	实时绘图项：订阅数据流并持续更新曲线
`LivePlot`	控件容器：内嵌一个 `UpdatingPlot`，可附带图像流名

关键方法（UpdatingPlot）

方法	说明
`setnewData`	定时拉取新数据；一维数组自动补 x 轴，再按旋转标志更新曲线
`updateConfiguration`	取消旧订阅，按属性里配置的流列表重新订阅并建曲线
`subscribe_window`	打开订阅编辑器勾选数据流，关闭后重新应用订阅配置
`configureWindow`	打开属性编辑对话框调整设置并重新应用显示配置

用法

from quatm.GUI.entries.updating_plot import UpdatingPlot, LivePlot

plot = UpdatingPlot(name="PMT 信号")        # 直接作为绘图项使用
host = LivePlot(name="PMT 信号", parent=parent)  # 或作为容器嵌入界面

订阅在绘图项的右键菜单中完成；LivePlot 也用作图像查看器中行/列剖面图的容器。

5.10 - LED 指示灯

LED 状态指示灯：支持绿/红/青配色、径向渐变与亮灭两种外观。

概述

LedIndicator（quatm/GUI/widgets/qled.py）是一个可选中切换亮/灭外观的 LED 指示按钮：双层圆形外壳加中心渐变，选中（亮）时用高亮配色，未选中（暗）时呈暗色。常用于显示设备连接状态、实验运行状态与循环条目执行反馈。

颜色模式

方法	说明
`set_green()`	绿色系：选中亮绿、未选中暗绿，通常表示正常/就绪
`set_red()`	红色系：选中亮红、未选中暗红，通常表示错误/警告
`set_cyan()`	青色系：循环器条件条目等待数据时使用

亮/灭（勾选）状态可用 setChecked(True/False) 控制；onColor1/onColor2、 offColor1/offColor2 属性可自定义亮态与暗态的主/辅颜色。

用法

from quatm.GUI.widgets.qled import LedIndicator

led = LedIndicator(parent=parent)
led.set_green()      # 设备就绪
led.setChecked(True) # 点亮
# ...
led.set_red()        # 设备异常

5.11 - GUI 基础类

BWidget、BMainWindow、BFrame：带几何持久化和属性通信的 Qt 基类。

概述

quatm/GUI/widgets/quatmQt.py 定义了 Quatm 图形界面各组件的基类与常用控件：提供窗口几何持久化、Properties 属性命名空间，以及带补全的下拉框等。

类层次

QWidget  → BWidget
QFrame   → BFrame
QMainWindow → BMainWindow

基类与混入

组件	说明
`GeometrySaveMixin`	把窗口几何持久化到 `QSettings`（按窗口名分键）；关闭、移动、缩放时（防抖）保存
`BWidget`	Quatm 控件基类：带 `Properties` 命名空间与几何持久化
`BFrame`	对应 `QFrame` 的基类，行为同 `BWidget`
`BMainWindow`	带几何持久化与属性句柄的主窗口基类

from quatm.GUI.widgets.quatmQt import BWidget, BMainWindow

widget = BWidget(name="my_widget", parent=None)
window = BMainWindow(name="MainWindow", parent=None)

搜索与补全控件

组件	说明
`CustomCompleter`	带匹配模式的补全器（`contains` 前缀包含 / `begins` 前缀开头）
`SearchComboBox`	启用自动补全、可输入搜索的下拉框；`add_if_new()` / `find_or_add()` 便捷维护条目
`SearchLineEdit`	供搜索框使用的编辑框：聚焦全选、失焦/回车记录、Escape 还原

from quatm.GUI.widgets.quatmQt import SearchComboBox

box = SearchComboBox(parent=parent)
box.add_if_new("my_stream")

5.12 - 图像监视器

自动更新的图像显示控件：订阅图像/掩码流、降噪与亮斑检测、级别与 ROI 配置。

概述

quatm/GUI/entries/image_monitor.py 提供自动更新的图像显示窗口（ImageDisplay ）：定时从属性中订阅的图像流拉取最新帧，按分辨率与偏移变换后刷新显示，并可同步叠加掩码流；内置降噪、亮斑检测、当前帧保存与属性配置（显示级别、ROI 等）等功能。

方法

方法	说明
`update_image`	定时拉取图像流，逐帧按分辨率/偏移变换后刷新显示
`update_mask`	拉取掩码流，按掩码分辨率/偏移更新叠加层几何位置
`noise_filter`	按属性参数做双边滤波 + 中值滤波降噪
`spot_detector`	按阈值把图像二值化以检测亮斑
`saveCurrentImage`	把当前显示帧保存为 PNG（按时间命名）
`subscribe_window`	打开订阅对话框勾选图像流后重新订阅
`subscribe_mask`	打开订阅对话框勾选掩码流后重新订阅
`configureWindow`	打开属性编辑对话框调整显示级别、ROI 等参数

用法

from quatm.GUI.entries.image_monitor import ImageDisplay

view = ImageDisplay(imagestreams=["camera/image"], parent=parent)
view.configureWindow()   # 调整显示级别、ROI 等

说明：ImageDisplay 既是ImageWindow 的中央显示器，也可单独嵌入其它界面。图像流与掩码流列表保存在属性中，右键菜单提供订阅、掩码订阅与配置入口。

5.13 - 分析管理器

树形视图面板：管理分析脚本的启动、停止、状态监控与自动重启。

概述

quatm/GUI/entries/analysismanager.py 提供 分析管理器：以可勾选树表列出各分析脚本（名称 / 脚本 / 类别 / 输入流），负责启停子进程、监视与自动重启，并支持新增、删除与配置分析条目。

组件

组件	说明
`AnalysisManager`	主面板：装载并组织分析条目，提供删除/配置入口
`TreeViewWidget`	分析脚本管理树：勾选即启停、监视自动重启、增删改
`addAnalysisWidget`	新增分析条目的工具栏（名称 / 类别 / 脚本 / 输入流）

功能

操作	说明
▶️ 勾选启动	勾选某条目即启动对应分析子进程；取消勾选即停止
⏹ 停止	`endProcess`：先终止、短等退出，超时再强制结束
🔄 状态刷新	`updateStatus`：周期检查进程是否仍在运行
🧹 清理游离进程	`killVagabonding`：结束上一轮遗留的同脚本进程
➕ 新增 / 配置 / 删除	工具栏注册新条目；选中行可配置属性或删除

用法

from quatm.GUI.entries.analysismanager import AnalysisManager

mgr = AnalysisManager(name="AnalysisManager", parent=parent)

分析脚本是独立进程：勾选某条目后，管理器用当前解释器拉起脚本并把项目环境变量注入子进程，因此分析代码与主程序相互隔离，脚本崩溃不会影响实验。

5.14 - 数据流监视器

数据流监控：数据/图像/命令/消息多标签监控与单流面板。

概述

quatm/GUI/streammonitor/ 提供 数据流监视器：MainWindow 以标签页容纳数据流（Data）、图像流（Image）、命令（Command）、消息日志（Message）与历史（History）等监控；每个监控标签由 StreamMonitor 订阅单一数据流并实时展示。

组件

组件	说明
`MainWindow`	监控主窗口：多标签页容器 + 菜单
`StreamMonitor`	单流监控面板：订阅某一数据流并实时展示
`MessageTableModel`	消息日志表格模型（时间戳/来源/级别/内容，按级别着色）
`ImageTableModel`	图像流元数据表格（固定时间/来源列 + 动态键列）
`AutoSortProxyModel`	按时间戳降序的自动排序代理模型

监控类型

标签页	内容
Data	数值数据流的实时曲线/表格
Image	科学图像流及其元数据
Command	命令 / 指令流
Message	消息日志（时间戳/来源/级别/内容）
History	历史记录

用法

from quatm.GUI.streammonitor import MainWindow, StreamMonitor

win = MainWindow(parent=parent)   # 多标签监控主窗口
panel = StreamMonitor(name="PMT", stream_type="Data", parent=parent)  # 单流面板

该监控界面通常作为独立进程启动，也可在其它窗口中嵌入单流 StreamMonitor 面板。

5.15 - 序列编辑器

实验代码编辑与序列模拟：语法高亮、解析与输出通道时序可视化。

概述

quatm/GUI/editors/editor_sequencer.py 提供 编辑并模拟 工具（旧称 Combi / “打开模拟窗口”）：CodeEditorParser 组合主窗口把左侧 CodeEditor 代码编辑器与右侧序列可视化组合起来：编辑实验脚本后可一键模拟运行，把各输出通道的时序画成阶梯图，便于调试实验序列。

组件

组件	说明
`CodeEditor`	简易代码编辑器：行号、Python 高亮、自动缩进与补全
`PythonHighlighter`	轻量 Python 语法高亮器
`LineNumberArea`	编辑器左侧行号边距控件
`ExperimentParser`	解析实验：`buildExperiment` / `simulateExperiment` 返回命令栈
`ExperimentSequencer`	把序列按各输出通道随时间画成阶梯图
`CodeEditorParser`	组合主窗口：Save / Simulate / Clear 工具栏 + Dock 布局

关键方法

方法	说明
`saveFile`（CodeEditor）	把当前文本保存到文件（成功返回 True）
`simulateExperiment`（CodeEditorParser）	模拟当前版本实验并把命令栈交给序列可视化
`buildExperiment` / `simulateExperiment`（ExperimentParser）	构建 / 模拟运行实验并返回命令栈
`plotSequence`（ExperimentSequencer）	把序列字典画成各通道时序阶梯图

用法

from quatm.GUI.editors.editor_sequencer import CodeEditorParser

win = CodeEditorParser(parent=parent, filename="experiments/my_experiment.py")

说明：参数扫描（nD 扫描、随机化等）的编辑入口在实验窗口的 Edit 按钮（SequenceEditor，见实验窗口），扫描定义保存于实验属性树并与远程控制平台共享。

5.16 - 进程管理器

分布式进程面板：按 Servers/Driver/GUI/Viewer/Monitor 分类启停后台进程。

概述

quatm/GUI/entries/processmanager.py 提供 进程管理器：按 Servers / Driver / GUI / Viewer / Monitor 分类读取配置，为每个脚本条目生成一个 SingleProcess 启停按钮面板，统一管理整套实验软件的运行。进程以当前解释器按脚本或模块（python -m）方式启动，携带项目根与父进程看门狗环境。

进程类别

类别	说明	典型进程
Servers	通信 / 属性 / 数据服务	数据中心、属性服务等
Driver	硬件驱动进程	FPGA 等设备驱动
GUI	图形界面进程	实验浏览器、数据管理器等
Viewer	数据查看进程	实时绘图、滚动窗口、图像查看器等
Monitor	监控 / 检查进程	属性检查器、消息监控等

组件

组件	说明
`ProcessManager`	分类面板：读取配置为每个条目生成启停按钮
`SingleProcess`	单条目面板：启动/异步终止/状态轮询着色
`resolve_script`	把配置里的 script 条目解析为启动目标（文件路径或模块）

关键方法（SingleProcess）

方法	说明
`startProcess`	停掉旧实例后以当前解释器启动子进程
`stopProcess`	异步终止子进程，不阻塞 GUI 线程
`updateStatus`	周期轮询退出状态并着色（运行中/正常退出/崩溃）

用法

from quatm.GUI.entries.processmanager import ProcessManager

pm = ProcessManager(parent=parent)
pm.show()

待管理条目由配置文件中的 scripts 定义；各条目的启动/停止通过对应的按钮面板完成。

5.17 - 设备管理器

PyVISA 设备发现与驱动绑定：枚举、查询、选择仪器并关联驱动文件。

概述

quatm/GUI/entries/device_manager.py 提供 设备管理器（VISADeviceLister）：通过 PyVISA 扫描系统中的 VISA 仪器，查询设备标识（*IDN?）并选择驱动文件绑定，把设备加入已选列表生成 DeviceInfo，供设备配置使用。

组件

组件	说明
`VISADeviceLister`	VISA 设备列表工具：左右两栏（枚举/查询 + 已选设备/驱动文件）
`DeviceInfo`	设备描述：名称、类型、驱动文件与附加参数

工作流

1. refresh_devices()      → 扫描 VISA 总线，填充设备列表
2. query_device_info()    → 对选中设备发送 *IDN? 查询
3. select_driver_file()   → 选取并绑定驱动文件
4. add_device_to_selected() → 加入已选设备列表（去重）

用法

from quatm.GUI.entries.device_manager import VISADeviceLister

dl = VISADeviceLister(parent=parent)
dl.refresh_devices()   # 列表显示 USB/GPIB/LAN 等 VISA 设备

5.18 - 数据存储

HDF5 数据管理：订阅、定时/手动保存与历史回读，含绘图一体化面板。

概述

quatm/GUI/h5storage/ 提供 HDF5 数据存储 GUI（由旧单文件拆出的包，公开符号在包级再导出）：汇总 / 单流 / 图像三类数据管理器订阅数据，按预约时刻、周期或 Looper 指令自动保存，也可手动把当前快照后台写入 .h5 文件并从文件回读历史测量。

组件

组件	模块	说明
`H5StorageGui`	`main_window.py`	主窗口：数据标签页、保存/定时保存控件与 plot 管理
`H5StorageDataMgr`	`data_manager.py`	三类数据管理器宿主：订阅管理、保存/回读、清空
`H5SaveWorker`	`workers.py`	工作线程写 `.h5`，磁盘 I/O 不阻塞 Qt 事件循环
`H5DataPlotter` / `EventPlotter`	`plotters.py`	测量数据 / 事件数据的绘图标签页
`XAxisWidget` / `YAxisWidget`	`axes.py`	x 轴与各 y 轴的数据选择、过滤链配置
`BinningWidget` / `FilterWidget` / `FittingWidget`	`widgets.py` / `fitting.py`	binning、过滤与 ODR 拟合处理链

保存方式（H5StorageDataMgr）

方法	说明
`toggle_scheduled_save`	开关预约时刻保存（到时自动保存并提示）
`toggle_regular_save`	开关每 N 小时的周期自动保存
`scheduled_save_by_looper`	响应 Looper 的保存指令（final / intermittent）
`savetoFile`	把当前数据快照后台写入 `.h5` 文件
`loadFromFile`	从既有 `.h5` 文件加载历史测量并刷新界面
`selectDatadir`	自选 h5 目标文件（避免回滚到每日默认名）
`clear`	清空三类数据管理器的全部缓存

用法

from quatm.GUI.h5storage import H5StorageGui   # 包级再导出

win = H5StorageGui(parent=parent)
win.show()

数据保存由后台 H5SaveWorker 完成：GUI 线程先拷贝数据快照再交给 worker，因此 HDF5 磁盘写入不会卡住界面。

5.19 - 实时滚动图

实时滚动绘图：环形缓冲、滑动平均与数据流订阅。

概述

quatm/GUI/entries/live_plot.py 提供 实时滚动绘图：ScrollWindow 为多子图主窗口，每个 ScrollPlot 子图订阅一条数据流的若干通道，维护环形缓冲并滚动显示散点/曲线与滑动平均；PlotDataEditor 提供数据源下拉面板。

组件

组件	说明
`ScrollWindow`	多子图滚动主窗口：按属性恢复/新建子图，工具条可追加子图
`ScrollPlot`	滚动子图：环形缓冲、散点与滑动平均曲线，右键菜单操作
`PlotDataEditor`	数据源选择面板：下拉候选并写回属性/父图

关键方法（ScrollPlot）

方法	说明
`feedData`	把新数据块压入缓冲数组
`setnewData`	定时拉取新数据喂给缓冲并刷新曲线
`updatePlot`	把缓冲内有效数据刷到散点与滑动平均曲线
`running_mean`	用累积和差分高效计算 N 点滑动平均
`dataSelectDialog`	选择本图显示的数据通道
`subscribe_window`	打开订阅编辑器重新订阅数据流
`configureWindow`	暂停刷新，内嵌属性编辑修改本图属性
`deletePlot`	从父窗口移除本图并清除属性

用法

from quatm.GUI.entries.live_plot import ScrollWindow

host = ScrollWindow(name="PMT 滚动监视", parent=parent)
host.addPlot()   # 追加一个滚动子图

之后在子图右键菜单中订阅数据流、选择通道并调整显示。缓冲长度、滑动平均开关与窗口大小等配置保存在属性中，重启后自动恢复。

5.20 - 自动保存编辑器

自动保存时间点列表编辑器：配置一组（勾选 + 日期时间）的周期保存时刻。

概述

AutoSaveEditor（quatm/GUI/editors/auto_save_editor.py）是一个弹窗编辑器，用来维护 周期 h5 自动保存 的“时间点列表”：每一行 = 一个（勾选标记 + 日期时间），勾选的行会按对应时刻触发一次自动保存。它由数据存储相关面板调用。

组件

组件	说明
`AutoSaveEditor`	编辑列表的对话框：加载/写回属性、每行增删改、确认（Accept）
`DateTimeWidget`	单条自动保存时间的编辑行：序号 + 勾选框 + 日期时间选择

主要方法

方法	功能
`load_AutoSaveEditor_props(props, prop_name)`	从属性读取已保存的日期时间与勾选标记，补齐到最大条目数
`update_datetime(idx, datetime_save)`	保存某一行的新日期时间
`update_ticked(idx, ticked)`	保存某一行的勾选状态
`accept()`	确认：把列表写回属性并关闭

用法

from quatm.GUI.editors.auto_save_editor import AutoSaveEditor

editor = AutoSaveEditor(props=props, max_items=24, parent=parent)
editor.load_AutoSaveEditor_props(props, "H5Storage/auto_save_times")

5.21 - 实验辅助工具

光镊对准、杂散场补偿：实验自动化校准与优化工具集。

概述

Quatm 将日常实验校准任务封装为对准/辅助工具，模块位于 quatm/GUI/alignment/，配以若干独立入口控件，实现一键运行与自动优化。

ODT 对准辅助 — `OdtAlignmentHelper`

quatm/GUI/alignment/odt_helper.py — 对 xODT/cODT 各压电镜轴建单轴控制块，提供整体运行/终止与补偿电压、BA 激光参数设置。每轴完整对准序列为：激光关的全范围扫描 → 离子附近精细扫描 → 发布拟合结果 → 移到目标位置。

from quatm.GUI.alignment.odt_helper import OdtAlignmentHelper

helper = OdtAlignmentHelper(parent=parent)
helper.run_all()   # 执行完整对准流程（线程池保证逐轴进行）
helper.terminate_all()   # 安全停止全部轴

杂散场补偿 — `CompensationHelper`

quatm/GUI/alignment/comp_helper.py — 通过沿各阱轴的电压扫描与两拟合线交点求补偿电压，自动最小化杂散场。

组件	说明
`PlotWidget`	每个阱轴一个标签页的绘图控件
`ControlWidget`	各轴控制区加共享参数区
`SingleAxisWidget`	扫描参数与“找补偿电压”（求两拟合线交点）
`CompVoltageScan`	在高低两个 rf 约束上执行电压扫描

from quatm.GUI.alignment.comp_helper import CompensationHelper

comp = CompensationHelper(parent=parent)

压电镜控制 — `PiezoMirrorControl`

quatm/GUI/entries/piezo_mirror_controler.py — 用箭头/按键界面操纵直线促动器反射镜方向的简易面板，W/A/S/D 对应上/左/下/右。

from quatm.GUI.entries.piezo_mirror_controler import PiezoMirrorControl

mirror = PiezoMirrorControl()   # 独立窗口；WASD 或点击方向键控制
mirror.show()

5.22 - 数据模型

DictSyncModel/ListSyncModel：将 Python 字典/列表自动映射为 Qt 表格。

概述

quatm/GUI/widgets/models.py 提供把 Python 字典 / 列表映射为 Qt 表格模型的基类（源自 ARTIQ 的 models）。实验队列、准备台与循环器的表格界面均基于此构建。

核心类

类	说明
`_SyncSubstruct`	包装底层容器的字典操作辅助：append/insert/pop 后触发刷新回调
`DictSyncModel`	字典→表格模型基类：按 `headers`/`dataNames` 列映射 `backing_store`
`ListSyncModel`	列表→表格模型基类（底层为列表）
`ScheduleModel`	实验队列（ExperimentQueue）模型：任务按优先级再按任务号排序
`PrepModel`	准备台 / 循环器模型：底层为列表，顺序可自由调整

用法

from quatm.GUI.widgets.models import DictSyncModel

model = DictSyncModel(
    headers=["名称", "值", "单位"],
    dataNames=["name", "value", "unit"],
    init={"name": "param1", "value": 100, "unit": "µs"},
)

具体业务模型通过子类实现三个钩子定制行为：convert 把键/值/列转成单元格内容，sort_key 返回排序键，flags 决定各单元格可编辑等标志。

5.23 - 可折叠组件

CollapsibleDialog：可折叠/展开的树形对话框。

概述

quatm/GUI/widgets/theexpandables.py 提供可折叠/展开的树形对话框 CollapsibleDialog：每个“面板”由一个带展开/折叠按钮的树条目与一个内容控件组成，适合配置界面与高级参数设置。

组件

组件	说明
`SectionExpandButton`	可展开/折叠某个 section 的按钮
`CollapsibleDialog`	对话框容器；子类覆写 `define_sections()` 定义全部面板

CollapsibleDialog 提供 add_section(title, widget) 直接添加面板；子类也可覆写 define_sections() 用 add_button / add_widget 细粒度组织树形结构。

用法

from quatm.GUI.widgets.theexpandables import CollapsibleDialog

class SetupDialog(CollapsibleDialog):
    def define_sections(self):
        self.add_section("相机设置", some_widget)
        self.add_section("触发设置", trigger_widget)

5.24 - 参数框

与实验参数绑定的输入控件：浮点、布尔与下拉参数框，改动即写回参数。

概述

quatm/GUI/widgets/arg_boxes.py 提供把实验参数类与 Qt 输入控件绑定的小部件：用户改值即回写实验参数（内部以 SI 单位存储，界面可按需换算显示）。它们常由 “实验参数面板/参数系统”按参数类型自动创建。

控件

控件	参数类型	说明
`FloatBox`	数值参数	浮点输入框；用 `unit` 与 `display_multiplier` 做单位换算后写回
`BoolBox`	布尔参数	勾选框，值以布尔形式写回
`ComboBox`	字符串列表	下拉框，按选中下标从字符串列表取值

用法（示意）

from quatm.GUI.widgets.arg_boxes import FloatBox, BoolBox, ComboBox

# 数值参数：界面按 kHz 显示，底层以 SI（Hz）存储
fbox = FloatBox(argument=param_freq, unit="kHz", display_multiplier=1e3)

bcheck = BoolBox(parName="enable", value=param_enable)
cbox = ComboBox(parName="source", argument=param_source)  # 参数类内含 stringlist

通常这些控件由参数系统按实验声明自动生成，无需手工实例化。

5.25 - 实验参数面板

DefaultExp + Dashboard：从设备数据库自动构建的整机参数控制面板。

概述

Dashboard（quatm/GUI/entries/dashboard.py）是由 默认实验（DefaultExp） 驱动的“控制面板”主部件：DefaultExp 按设备数据库自动装配整机参数，Dashboard 再把这些参数按整数/浮点/布尔分段、以分组网格排布成可调的参数控制界面。

类体系

DefaultExp（实验基类：自动装配设备属性并分组）
     └─ Dashboard（控制面板：分段 + 分组网格 + 自适应列数）
            └─ 管理器控件（IntManager / FloatManager / BoolManager / ComboManager …）

关键特性

自动装配：DefaultExp.build() 遍历设备库，为每个 attr/generic_attr 设备建立参数对象并按其分组归类。
按类型分段：界面按整数 / 浮点 / 布尔等类型分段，段内再按参数分组。
自适应列数：adaptive_columns() 依据窗口宽度重排（4 列起，每约 200 px 加一列），窄窗口也不挤压。
就地生效：改动微调框即写回属性并直达硬件（运行体 run() 为空，适合纯手动调参）。

用法（示意）

from quatm.GUI.entries.dashboard import Dashboard, DefaultExp

# DefaultExp 自动装配设备参数；Dashboard 负责界面排布与分组
page = Dashboard(parent=parent)

“参数系统”页描述了其内部的管理器控件体系。

5.26 - FPGA DAC 控制

FPGA 的简易手动控制界面：16 路 DAC 电压与 32 路 TTL 位掩码设置。

概述

quatm/GUI/entries/fpga_controller.py 提供用于调试与校准的 FPGA 简易手动控制：用带标签的 -10 … +10 V 数值框逐路设置 DAC 电压，用勾选框网格设置 32 路 TTL 输出。

组件

组件	说明
`dacv(v)`	把 `-10..+10 V` 换算为 FPGA 使用的 16 位原始 DAC 码
`DACsingle`	单个 DAC 通道：带标签的 `-10..+10 V` 数值框，写入即生效
`DACvalues`	纵向堆叠的全部 16 个 DAC 通道
`TTLQW`	32 路 TTL 输出：8×4 勾选框网格，整体作为一个 32 位掩码写入
`simple_page`	DAC + TTL 手动控制页面
`centralWidget` / `mainQMW`	标签容器与简易主窗口（含 File/退出菜单）

用法

from quatm.GUI.entries.fpga_controller import DACvalues, TTLQW

# 先经设备数据库取得底层 FPGA 驱动句柄 controller
page = DACvalues(controller)

# TTL：勾选框状态经“Apply/状态变化”回调合成掩码写入 FPGA
ttl = TTLQW(controller)

硬件缺失或写入失败时只打印错误、不崩溃，便于无硬件环境下的界面调试。

5.27 - 后台工作线程

Worker/WorkerSignals：通用 QRunnable 后台线程封装。

概述

quatm/GUI/widgets/browser_workers.py 与 helper_workers.py 提供基于 QRunnable 的通用后台线程封装：把耗时任务放到线程池执行，并经信号把结果/异常/进度传回界面线程。

信号

信号	说明
`finished`	任务完成（无数据）
`error(tuple)`	`(异常类型, 值, traceback 字符串)`
`result(object)`	处理返回的结果，任意类型
`progress(int)`	进度百分比

用法

from quatm.GUI.widgets.browser_workers import Worker

worker = Worker(callback=my_long_task, arg1, kw=...)   # 透传给回调函数
worker.signals.finished.connect(on_done)
worker.signals.error.connect(on_error)
QThreadPool.globalInstance().start(worker)

两处实现大同小异：helper_workers.py 供辅助/分析类后台任务复用，browser_workers.py 供浏览器类面板复用。

5.28 - 实验时间线

FPGA 实验时序可视化：DAC 与 TTL 输出通道随时间变化的图表查看器。

概述

quatm/GUI/entries/experiment_timeline.py 提供 实验时间线（Timeline）：加载实验时序 JSON 文件（experiment.json），把各 DAC/TTL 输出通道随时间的变化绘制成阶梯子图，并提供输出通道勾选面板决定哪些曲线可见，方便调试与验证实验时序逻辑。

组件

组件	说明
`Timeline`	时序查看主窗口：加载文件、绘图与通道控制
`TimelinePlotter`	时序可视化控件：随时间绘制每个在用输出的状态
`SelectorWidget`	输出通道勾选面板：全选 / 全不选决定可见曲线

关键方法（Timeline）

方法	说明
`load_file`	加载并解析时序 JSON，构造时间序列并刷新通道选择器
`plot_experimental_sequence`	按通道勾选状态为每个输出建独立子图并绘阶梯图
`decode_ttl_bitmask`	把 32 位 TTL 位掩码拆成各通道的 set/clear 命令
`construct_time_sequences`	把步骤式时序转成按通道组织的 times/vals 序列
`reverse_device_db_transformation`	设备库反变换：内部名映射回可读名（含 gauge 校准表）

用法

from quatm.GUI.entries.experiment_timeline import Timeline

tl = Timeline()
tl.load_file("experiment.json")   # 加载时序文件并绘图
tl.show()

5.29 - 滚动波形窗口

多通道实时滚动数据查看窗口：子图缓冲、数据流订阅与动态刷新。

概述

quatm/GUI/entries/scrollwindow.py 提供 滚动波形窗口（ScrollWindow）： BMainWindow 子类的多通道实时滚动数据查看主窗口，按指定数量排布 ScrollPlot 子图（每两个换一行），统一把数据块分发到对应子图并刷新；PlotDataEditor 提供数据/图像流的选择下拉。

组件

组件	说明
`ScrollWindow`	主窗口：按数量创建子图、分发数据并刷新
`ScrollPlot`	滚动子图：订阅数据流，环形缓冲 + 定时刷新
`PlotDataEditor`	数据源选择面板：下拉候选并写回属性 ydata

关键方法

方法	说明
`initPlots`	按数量创建滚动子图并排入布局（每两个一行）
`feedData`	把新数据块喂给缓冲数据数组
`updatePlot`	把缓冲中已填充区间批量刷新到各子图曲线
`setnewData`（ScrollPlot）	定时器驱动拉取数据并刷新曲线
`dataSelectDialog`（ScrollPlot）	弹出对话框选择要绘制的数据通道
`subscribe_window`（ScrollPlot）	弹出订阅编辑器更换数据流
`configureWindow`（ScrollPlot）	暂停刷新并内嵌属性编辑修改本图配置

用法

from quatm.GUI.entries.scrollwindow import ScrollWindow

win = ScrollWindow(name="PMT 滚动监视", parent=parent, n_plots=2)

在每个子图上通过右键菜单完成数据流订阅、数据通道选择与显示配置；该窗口也可作为独立进程启动。

5.30 - 订阅编辑器

管理数据/图像流的订阅列表：添加、删除与热更新已订阅的数据源。

概述

SubscriptionEditor（quatm/GUI/editors/subscription_editor.py）管理程序对数据流/ 图像流的订阅：从属性库加载已存订阅、列出可用流供选择，支持添加/删除，并在属性变更时热更新列表。它常作为实时绘图/监视类面板的数据源选择组件。

主要方法

方法	功能
`loadSubscriptions()`	从属性库读取已保存的订阅并载入列表
`update_streamlist()`	按当前可用数据流重建下拉候选
`add()`	把下拉框选中的流加入订阅列表并同步属性
`deletemarked()`	移除列表中被标记删除的订阅项并同步属性
`handle_property_changes(changes)`	监听属性变更，刷新列表并广播

用法

from quatm.GUI.editors.subscription_editor import SubscriptionEditor

editor = SubscriptionEditor(props=props, category="Data", parent=parent)
editor.loadSubscriptions()

5.31 - 表格参数

基于 QTableWidget 的 numpy 结构化数组编辑器，用于参数树。

概述

quatm/GUI/widgets/table_parameter.py 提供 ParameterTree 的表格编辑节点：table_parameter 参数类型配合 table_parameterItem 控件项，可在参数树中直接编辑 numpy 结构化数组（如校准表、扫描序列）。

组件

组件	说明
`table_parameter`	参数类型：接受一个 numpy 结构化数组作为 `value`
`table_parameterItem`	对应控件项：按数组 dtype 创建 `QTableWidget` 作为编辑器

table_parameterItem 会按数组 dtype 建列（含字段名/类型），单元格改动即时回写数组； valueIsDefault() 用于判断是否需要单独持久化该值。

用法

from quatm.GUI.widgets.table_parameter import table_parameter
import numpy as np

dt = np.dtype([("freq", float), ("amp", float)])
param = table_parameter(name="扫描表", value=np.zeros(10, dtype=dt))

5.32 - 远程 ROI

通过中心属性库发布颜色/位置/尺寸、可远程同步的 ROI 组件。

概述

quatm/GUI/widgets/ROI.py 提供 ROI：继承 ROI，以唯一名称通过中心属性库通信其颜色、位置与尺寸，使远程客户端能同步查看与调整 ROI 区域。

方法

方法	说明
`update_from_properties`	按属性里的颜色/位置/尺寸刷新 ROI 画笔颜色与几何形状

用法

from quatm.GUI.widgets.ROI import ROI

roi = ROI(name="分析区域", parent=view)   # name 需唯一，重名会共享属性
roi.update_from_properties()

说明：name 是该 ROI 在中心属性库中的键，务必确保不与属性字典中的任何名字冲突；属性变化后调用 update_from_properties 即同步刷新 ROI 外观与位置。

5.33 - 图像查看器

科学图像查看主窗口：中央图像显示器加行/列线剖面与直方图色标停靠面板。

概述

quatm/GUI/entries/image_group.py 提供 图像查看窗口（ImageWindow）：以中央 ImageDisplay 图像显示器为主控件，四周停靠 行/列线剖面 与 直方图色标 等面板，用于成像实验的实时监视与分析。

布局结构

停靠区	控件	用途
中央	`ImageDisplay`	订阅并自动刷新图像流，可叠加掩码
顶部	`LivePlot`（行剖面）	图像行的强度分布曲线
右侧	`LivePlot`（列剖面）	图像列的强度分布曲线
左侧	`HistogramLUTWidget`	直方图色标：电平范围与伪彩色映射

其中每个剖面图是一个 LivePlot 容器，内部由 UpdatingPlot 订阅对应数据流实时刷新（详见实时绘图）。

显示参数持久化

显示参数存放在属性库 Viewer/ 命名空间下，构造时按属性恢复，关闭时自动保存：

属性	含义
`Viewer/minlevels` / `Viewer/maxlevels`	直方图显示电平范围
`Viewer/gradient`	伪彩色渐变预设（如 magma）
`Viewer/tick_position`	色标刻度位置（0–1 归一化列表）

拖动直方图电平或色标刻度后，分别经 update_min_max 与 get_tick_position 把当前值写回属性，closeEvent 在关闭前统一保存视图范围与刻度。

方法

方法	说明
`update_min_max`	把直方图当前电平范围写回属性（min/max levels）
`get_tick_position`	遍历色标刻度并归一化到 0–1 区间返回
`closeEvent`	关闭前把视图范围与色标刻度保存到属性

用法

from quatm.GUI.entries.image_group import ImageWindow

win = ImageWindow(name="吸收成像")   # 独立主窗口，parent 可省略
win.show()

该窗口常作为独立进程启动，也可作为 BMainWindow 实例嵌入其它界面。图像流与行/列剖面流的订阅，在各子面板（图像显示器 / 剖面图）的右键菜单中完成。

5.34 - 属性检查器

属性分发看门狗：验证 Properties 中枢确实在广播更新。

概述

PropertiesChecker（quatm/GUI/entries/properties_checker.py）是一个属性分发看门狗：它通过一个属性句柄设置标记，再用第二个句柄读回；若中枢没有把该变化传播过来，就弹出告警，说明属性服务可能已停摆。检查在定时器上周期运行，因此窗口正常显示且界面事件循环保持响应。

用法

from quatm.GUI.entries.properties_checker import PropertiesChecker

checker = PropertiesChecker(parent=parent)
checker.check_once()   # 手动执行一次看门狗检查

面板自身会周期调用 check_once()（每次把标记置真再置假并读回验证）。

5.35 - 辅助绘图

通用测量数据绘图组件：数据源/多 y 轴、过滤、分箱与拟合。

概述

quatm/GUI/alignment/plotter.py 提供 辅助绘图（DataPlotterWidget）：订阅并绘制测量过程中采集的数据。支持数据源切换、x 轴与多个 y 轴选择器，每个 y 轴经一条可配置的数据链（缩放系数 → 过滤器 → 分箱/拟合）处理后画入图区，并可导出 PDF。

组件

组件	说明
`DataPlotterWidget`	主绘图：数据源下拉、x 轴选择器、若干 y 轴选择器（右键开关配置面板）
`YAxisWidgetHelper`	y 轴数据链：缩放系数、过滤器、分箱与拟合处理

关键方法

方法	说明
`setDataSource`	设置或更换数据源
`checkForNewData` / `updateDatasources`	检查新增数据/新数据源并刷新
`plotData`	把一组 x/y 数据作为新曲线加入图区
`toggleConfig`	切换数据源与 y 轴配置面板显示
`exportpdf`	把当前绘制导出为适合归档的 PDF
`clear`	清空数据汇总与图区全部曲线

用法

from quatm.GUI.alignment.plotter import DataPlotterWidget

plotter = DataPlotterWidget(
    axis_name="myaxis",
    prop_root="...",
    datastream_names=[".../data"],
    n_yaxis=1,
    parent=parent,
)
plotter.toggleConfig()   # 展开数据源 / x、y 轴选择配置

6 - 通信层

Quatm 分布式通信与数据管理系统：基于 TCP/IPC 的进程间通信框架

概述

通信层是 Quatm 框架的通信骨干。所有进程间通信（设备驱动、分析脚本、GUI 面板之间的数据交互）都经 TCP/IPC 通道以 发布/订阅（PUB/SUB） 模式进行，命令与控制则通过 RPC 实现。这确保了：

故障隔离：某个相机驱动崩溃不会导致整个实验中断
并行处理：图像处理与实验时序可同时运行
网络透明：各组件可以运行在不同的机器上

实验脚本
     │
     ▼
[with realtime():]  ──→  FPGA  ──→  DAC/TTL 输出
     │
     ▼
分析脚本  ◄──  图像/数据流 (TCP/IPC PUB/SUB)
     │
     ▼
结果发布  ──→  DataManager  ──→  HDF5 存储

客户端类型

quatm.servers 提供了四种标准客户端，用于处理不同类型的进程间通信：

客户端	用途	适用场景
`CommandClient`	控制驱动和进程	向设备发送指令、启停驱动
`DataClient`	传输小数据	1D 曲线、标量值、元数据
`ImageClient`	传输大数据块	相机图像（2D 数组）
`MessageClient`	日志消息传递	错误、警告、信息、调试消息

基础客户端 — `GenericClient`

所有客户端的基类，封装了 TCP/IPC 连接与数据收发逻辑。

from quatm.servers.clients import GenericClient

client = GenericClient("my_channel")
client.subscribe("data_stream_name")
# 发送数据
client.send({"temperature": 25.0, "timestamp": 12345})
# 接收数据
if client.has_new_data():
    data = client.recv()

方法	说明
`subscribe(name)`	订阅指定的数据流
`unsubscribe(name)`	取消订阅
`send(data)`	发送数据
`recv()`	接收数据
`has_new_data()`	检查是否有新数据到达

数据客户端 — `DataClient`

专为小数据集设计的客户端，数据以 JSON 格式序列化，支持 NumPy 数组附件。

from quatm.servers.clients import DataClient

data_client = DataClient("analysis_result")
data_client.send({
    "fit_params": {"A0": 1.5, "sigma": 0.3, "pos": 10.2},
    "fit_curve": numpy_array
})

图像客户端 — `ImageClient`

优化用于传输相机图像等大型 2D 数据块。

from quatm.servers.clients import ImageClient

img_client = ImageClient("camera_output")
img_client.send(image_array)  # 发送 NumPy 图像数组

命令客户端 — `CommandClient`

用于向驱动程序发送控制命令，使用独立通道以确保命令不被数据流阻塞。

消息客户端 — `MessageClient`

标准化的消息传递接口，所有消息带有时间戳和来源信息。

from quatm.servers import send_error, send_warning, send_info, send_debug

send_info("实验开始执行")
send_warning("激光功率偏低，请检查")
send_error("相机连接失败")

分布式属性系统

Quatm 通过分布式属性树管理所有运行时配置参数，支持跨进程实时同步。

配置层级

层级	说明	示例
Configuration	深层、基础系统属性	运行哪些硬件、可用驱动列表
Properties	对象特定参数	ROI 位置、校准值、拟合参数
Preferences	不影响数据的次要选择	鼠标指针形状、窗口位置

PropertyAttribute

将分布式属性映射为 Python 属性，读写操作自动同步到属性树。

from quatm.servers.properties import PropertyAttribute, Properties

class MyComponent:
    # 声明分布式属性，默认值为 42.0
    _my_param = PropertyAttribute('/MyComponent/param', 42.0)

    def __init__(self):
        self._props = Properties('MyComponent')

    def do_something(self):
        # 读取属性值
        x = self._my_param.value
        # 写入属性值，自动同步到分布式树
        self._my_param.value = 99.0

Properties

管理组件内部属性的同步副本，后台守护线程经发布/订阅（TCP/IPC）连接到中央属性中心。

from quatm.servers.properties import Properties

props = Properties('MyProcess')
props.set('/path/to/property', value)
current_value = props.get('/path/to/property')

配置读取器

读取静态配置文件 configuration/configfile.json，提供系统级别的运行时配置。

from quatm.servers.configreader import ConfigReader

reader = ConfigReader()
config = reader.getConfiguration()

常用路径常量

quatm.servers 导出以下路径常量，方便定位工作目录：

常量	说明
`workpath`	工作根目录
`driverpath`	驱动文件目录
`iconpath`	图标资源目录
`datapath`	数据存储目录
`experiment_path`	实验脚本目录
`configpath`	配置文件目录

6.1 - 客户端

Data/Image/Command 客户端：发布/订阅通信（TCP/IPC），连接目标由中央配置。

概述

quatm/servers/clients.py 提供通信客户端：连接目标由中央配置决定（Data / Image / Command Hub）。GenericClient 提供标准收发接口，适用于小数据（<10k）；大尺寸数据（图像）请用 ImageClient。

客户端类

类	连接	说明
`GenericClient`	由配置决定	通用收发（含 numpy 数组），subscribe/unsubscribe
`DataClient`	Data Hub	普通数据的发布与订阅
`ImageClient`	Image Hub	图像级大数据发送（send 直接收 numpy 数组）
`CommandClient`	Command Hub	向驱动发送控制命令（命令名拼入主题）
`NpEncoder`	—	numpy 类型 JSON 序列化

关键方法（GenericClient）

方法	说明
`send(datadict, arr=None)`	发布数据（可附带一个 numpy 数组）
`recv()`	接收一帧：(主题, 字典[, 数组])；超时返回 None
`subscribe` / `unsubscribe`	订阅 / 取消订阅通道
`has_new_data`	非阻塞检查是否有新数据
`close`	关闭 PUB/SUB socket（幂等）

用法

from quatm.servers.clients import DataClient

dc = DataClient(name="pmt")
dc.send({"pmt": 1234}, arr=numpy_array)
topic, data = dc.recv()

6.2 - 属性树

分布式分层属性树：本地副本经 Property Hub 与 Propertylogger 双向同步。

概述

quatm/servers/properties.py 提供属性树（Properties）：管理控制中心的配置与属性，维护属性字典的同步副本。本地 set / get 会发布到 Property Hub，中央的变更也推送回本地副本。属性寻址类似文件系统（如 Drivers/xxx 或以 / 开头的绝对路径）。

关键方法

方法	说明
`set(key, value)`	设置属性并发布变更到 Property Hub
`get(key, default=...)`	读取值（总是返回深拷贝；缺失时创建默认值）
`delete(key)`	删除条目（含全部子条目）并广播
`changes()`	返回自上次调用以来的变更键
`close` / `close_all`	关闭 socket 与后台线程

PropertyAttribute 把属性树中的一个属性当作普通 Python attribute 读写（宿主需有 _props）。

用法

from quatm.servers.properties import Properties

props = Properties()
props.set("laser/power", 50e-3)
power = props.get("laser/power")

6.3 - 数据管理

多流数据汇总：按实验运行对齐，缺失超时补零后写 HDF5。

概述

quatm/servers/datamgr.py 提供数据管理（DataSummary）：汇总多个输入通道的数据流，整理成每个 run 的完整字典。收到数据先累积在 incompleteData，当所有订阅通道的数据都到达时整条记录移入 completeData；若 run 结束超时仍有数据未到，缺失部分以零补齐。

关键方法

方法	说明
`initDataq`	（重新）订阅属性里配置的通道与实验开始/结束事件
`recvData` / `processIncomingData`	接收数据并归并到最近的 run 记录
`savetoFile`	把收集的 run 字典写入 HDF5 结构化数据集
`loadFromFile`	从 HDF5 读回一组已存的 run 字典
`clear`	清空已收集的全部数据
`run_forever`	阻塞式循环持续接收数据

用法

from quatm.servers.datamgr import DataSummary

summary = DataSummary(name="sum")
summary.initDataq()     # 订阅属性中配置的通道
summary.run_forever()   # 持续收数；savetoFile 把 run 字典写入 .h5

6.4 - 消息系统

标准化消息流客户端：把带时间戳/来源的消息发到 Message Hub。

概述

quatm/servers/messageclient.py 提供消息系统：MessageClient 是标准化的消息流客户端，把带时间戳与来源文件的消息发到 Message Hub（PUB）。日常代码一般不要直接构造，而是使用模块级发送函数。

发送函数

函数	说明
`send_info(msg)`	Info 级：进入消息流作为普通通知
`send_warning(msg)`	Warning 级：进入消息流并触发警告通知
`send_error(msg)`	Error 级：进入消息流并触发错误通知
`send_debug(msg)`	Debug 级：仅在调试通道显示

用法

from quatm.servers.messageclient import send_info, send_error

send_info("实验启动完成")
send_error("相机连接超时")

6.5 - 配置与属性持久化

configreader + propertylogger：JSON 配置读取与属性树落盘、活跃流监视。

模块

模块	功能
`configreader.ConfigReader`	只读封装：读取 `configfile.json`（`getConfiguration()`）
`configreader.Config()`	读取 configfile.json 并返回配置字典
`configreader.Properties()`	读取属性盘文件 `properties.json` 并返回字典
`propertylogger.run_propertylogger()`	属性树落盘 + INIT 应答（Property Logger 服务）
`datalogger.DataStreamLogger`	监视活跃数据流并写入属性树
`imagelogger.ImageStreamLogger`	监视活跃图像流并写入属性树

用法

from quatm.servers.configreader import ConfigReader

cfg = ConfigReader()
config = cfg.getConfiguration()   # 完整配置字典

6.6 - 外围服务模块

InfluxDB、通知推送、图像网络服务、Web Hub 与 XSUB/XPUB 代理等外围服务。

服务列表

模块	功能
`influxdb`	InfluxDB 客户端封装：硬件状态写入（`data2db`）与历史查询（`query_data`），可作 RPC 服务
`notifications`	通知推送：配置服务、`push_message` 推送、`post_to_mattermost` 兼容入口
`image_network_server`	图像网络服务：把各图像流最新帧刷到 Web figure
`webhub`	Web 远程控制平台的服务器入口（`quatm.web`，自 configfile Servers 段取 host/port）
`xsub_xpub`	XSUB/XPUB 转发服务器（`run_server`）
`experiment_status`	实验状态监控 / 预警通知
`propertylogger` / `datalogger` / `imagelogger`	属性树落盘与活跃数据/图像流监视（见配置系统）

用法

from quatm.servers.notifications import push_message

push_message("实验完成")   # 经已启用的推送服务发出（绝不抛异常）

7 - 部署指南

在实际实验环境中部署和运行 Quatm 框架的指南。

部署架构

Quatm 的通信基于通用 TCP/IPC 通道，支持灵活的网络拓扑：

┌──────────────────┐        TCP/IPC       ┌──────────────────┐
│  控制端 (实验室)   │ ◄──────────────────► │  客户端 (办公)    │
│  • 设备驱动        │                      │  • GUI 浏览器     │
│  • 实验引擎        │                      │  • 参数编辑器     │
│  • 数据采集        │                      │  • 数据监视器     │
└──────────────────┘                      └──────────────────┘

核心服务

服务	模块	功能
数据管理	`datamgr.DataSummary`	接收、存储实验数据为 HDF5
数据记录	`datalogger`	实时数据流记录
图像记录	`imagelogger`	图像数据存储
属性管理	`properties.Properties`	分布式属性同步
配置读取	`configreader`	路径和配置管理
消息转发	`xsub_xpub`	XSUB/XPUB 消息代理
Web 服务	`webhub`	浏览器端实验控制台（quatm.web，含移动端适配）

单机部署

所有组件在同一台计算机上运行：

git clone https://github.com/quatm/quatm.git
cd quatm
pip install -r requirements.txt
# 编辑 configuration/device_db.py
python -m quatm.GUI.browser

分离部署

控制端运行实验引擎，客户端远程连接：

# 控制端（实验室计算机）
python -m quatm.servers.experiment_server --port 7777

# 客户端（办公计算机）
python -m quatm.GUI.browser --connect 192.168.1.100:7777

系统服务（Linux）

[Unit]
Description=Quatm Experiment Server
After=network.target

[Service]
Type=simple
User=labuser
WorkingDirectory=/home/labuser/quatm
ExecStart=/home/labuser/.venv/bin/python -m quatm.servers.experiment_server
Restart=always

[Install]
WantedBy=multi-user.target

数据存储

本地：HDF5 格式，保存在 Data/年-月-日/ 目录
远程：支持 InfluxDB 推送（配置 properties.json）

Web 远程控制平台

实验 PC 上启动 Web Hub 服务后，局域网内任何设备（含手机）通过浏览器即可控制实验，与桌面 GUI 共享同一套 Hub 与属性系统：

# 随 quatm 核心安装，命令行直接启动
python -m quatm.web --project <用户项目> --port 8000
# 浏览器打开 http://<实验PC>:8000

远程（实验室外）访问推荐 SSH 隧道，Hub 本身无认证、仅建议内网使用：

ssh -L 8000:localhost:8000 user@experiment-pc

详见 Web 远程控制。

8 - 实验框架

实验运行体系：任务队列/执行引擎、循环、序列编辑、时序查看与运行监视。

概述

实验框架覆盖实验从编写、调度到运行的完整链条：

实验脚本：继承 Experiment 并实现 build / run（入门见编写第一个实验，设备映射见配置仪器设备）；
调度执行：实验队列（ExperimentQueue）→ 执行引擎（ExperimentManager）按优先级/预约时间取任务执行，准备台与循环器参与入队；
编辑与监视：序列编辑/模拟、FPGA 时序查看、运行监视、多线程任务框架与基础窗口控件。

调度与执行

页面	模块	说明
实验队列管理器	`experiment/experiment_queue`	表格化任务队列
实验任务运行管理器	`experiment/experiment_manager`	执行引擎（测量/序列/运行）
实验运行调度管理器	`experiment/`	调度机制综述
实验预处理	`experiment/prepstation`	准备台（暂存/推送）
实验任务循环管理器	`looper/`	条件循环执行
实验集合管理器	`entries/processmanager`	进程启停面板

编辑、时序与监视

页面	模块	说明
实验序列编辑器	`editors/editor_sequencer`	代码编辑 + 序列模拟
实验时间线查看器	`entries/experiment_timeline`	FPGA 时序可视化
实验运行监视器	`streammonitor/`	数据/消息监视
实验控制浏览器	`browser/`	主程序浏览器

控件与工具

页面	模块	说明
数据类控件	`widgets/arg_boxes`	参数输入控件
实验参数管理器	`entries/dashboard`	默认参数系统
实验任务折叠管理	`widgets/theexpandables`	可折叠分区
实验任务预备队列管理器	`widgets/models`	队列/预备表格模型
多线程任务管理器	`widgets/browser_workers`	Worker 线程
多线程处理框架	`widgets/helper_workers`	Worker 线程
自动保存编辑器	`editors/auto_save_editor`	周期保存时刻
实验窗口控件类	`widgets/quatmQt`	GUI 基础控件

8.1 - 数据类控件

实验参数编辑控件：FloatBox/BoolBox/ComboBox，改动即写回参数属性。

概述

quatm/GUI/widgets/arg_boxes.py 提供数据类控件：一套把实验参数显示为可编辑控件的输入框体系。FloatBox / BoolBox / ComboBox 等控件继承对应管理器（FloatManager / BoolManager / ComboManager），带单位、范围与步长，值改动时立即写回属性（含 last_set），供实验窗口参数网格与参数系统使用。

组件

组件	说明
`FloatBox`	浮点参数输入框
`BoolBox`	布尔参数复选框
`ComboBox`	下拉列表参数
`IntManager` / `FloatManager` / `BoolManager` / `ComboManager` / `FrequencyManager`	各类型参数的控件管理器

用法

from quatm.GUI.widgets.arg_boxes import FloatBox, BoolBox, ComboBox

# 通常由参数系统按参数声明自动生成对应控件

更完整说明见参数框与参数系统。

8.2 - 实验窗口控件类

GUI 基础控件：BWidget/BFrame/BMainWindow 与可搜索组合框等。

概述

quatm/GUI/widgets/quatmQt.py 提供 GUI 基础控件类：BWidget / BFrame / BMainWindow 是各窗口/面板/主窗口的基类（带属性命名空间 _props，关闭时把几何保存到 QSettings、启动时恢复）；SearchComboBox 等提供带自动补全与过滤的可搜索组合框。

组件

组件	说明
`BWidget`	基础 QWidget（属性 + 几何持久化）
`BFrame`	基础 QFrame
`BMainWindow`	基础主窗口（QMainWindow + 标题/几何持久化）
`CustomCompleter`	支持 contains / begins 匹配的自动完成器
`SearchComboBox`	可搜索组合框（内置 SearchLineEdit）
`SearchLineEdit`	SearchComboBox 的自定义行编辑（焦点全选、Esc 还原）

用法

from quatm.GUI.widgets.quatmQt import BMainWindow, BWidget, BFrame

win = BMainWindow(name="我的窗口")   # 几何自动持久化

更完整说明见 GUI基础类。

8.3 - 实验序列编辑器

实验代码编辑与序列模拟：语法高亮、解析与输出通道时序可视化。

概述

quatm/GUI/editors/editor_sequencer.py 提供实验序列编辑器（编辑并模拟）： CodeEditorParser 组合主窗口把左侧 CodeEditor 代码编辑器与右侧序列可视化组合起来，编辑实验脚本后可一键模拟运行，把各输出通道的时序画成阶梯图。

组件

组件	说明
`CodeEditor`	代码编辑器：行号、Python 高亮、自动缩进与补全
`PythonHighlighter` / `LineNumberArea`	语法高亮 / 行号边距
`ExperimentParser`	解析实验：`buildExperiment` / `simulateExperiment` 返回命令栈
`ExperimentSequencer`	把序列按各输出通道随时间画成阶梯图
`CodeEditorParser`	组合主窗口：Save / Simulate / Clear 工具栏 + Dock 布局

用法

from quatm.GUI.editors.editor_sequencer import CodeEditorParser

win = CodeEditorParser(parent=parent, filename="experiments/my_experiment.py")

更完整说明见序列编辑器。

8.4 - 实验任务运行管理器

核心实验执行引擎：从队列取任务，按测量/序列/运行层级调度执行。

概述

quatm/GUI/experiment/experiment_manager.py 提供实验任务运行管理器（ExperimentManager）：从实验队列取出任务并执行的引擎。队列轮询运行在 worker 线程，任务按测量（measurement）→ 重复（repetition）→ 序列/扫描（sequence）→ 单次运行（run）的层级结构调度。

关键方法

方法	说明
`queue_fn`	持续轮询队列任务字典：按优先级、任务号与预约时间挑选任务
`run`	任务运行包装：任何结束方式都保证收尾
`pause`	暂停 / 恢复当前实验
`terminate_experiment`	优雅终止：让当前一次 run 自然跑完再停止
`start_measurement` / `start_sequence` / `end_sequence` / `end_measurement`	各阶段实验钩子
`set_dict`	把单个参数写入实验对象实例属性
`set_run_nr` / `set_rep_nr`	同步运行 / 重复序号
`start_queue` / `shutdown`	启动 / 停止常驻队列 worker

用法

from quatm.GUI.experiment.experiment_manager import ExperimentManager

manager = ExperimentManager(browser)   # browser 提供队列与界面
manager.start_queue()

更完整说明见实验管理器。

8.5 - 实验控制浏览器

主程序浏览器：文件树、队列/准备台/循环器与 MDI 实验窗口。

概述

quatm/GUI/browser/ 提供实验控制浏览器（Browser）：Quatm 的主应用窗口，基于 QMainWindow + QMdiArea。左侧 FileSelector 浏览实验脚本，顶部停靠实验队列、准备台与循环器，中央 MDI 区内每个实验一个 ExperimentWindow 子窗口。

核心组件

组件	模块	说明
`Browser`	`browser/main_window.py`	主窗口：MDI + 停靠部件 + 生命周期
`FileSelector`	`browser/file_selector.py`	实验文件树（双击打开/模拟）
`ExperimentWindow`	`browser/experiment_window.py`	单实验控制面板（参数/提交/扫描）
`ExperimentQueue` / `PrepStation`	`experiment/`	队列与准备台（顶部停靠）
`Looper`	`looper/`	条件循环器（顶部停靠）

生命周期

open_experiment：打开实验窗口；已打开则恢复并置前。
closeEvent：保存主窗口几何与子窗口状态后停止 worker 线程。
moveEvent / resizeEvent：防抖保存几何供下次启动恢复。

用法

from quatm.GUI.browser.main_window import Browser

browser = Browser()
browser.show()

更完整说明见实验浏览器。

8.6 - 实验队列管理器

表格化实验任务队列：任务字典、优先级排序、暂停/终止与预约执行。

概述

quatm/GUI/experiment/experiment_queue.py 提供实验队列管理器（ExperimentQueue ）：以表格展示任务队列（任务字典 expDict，任务号为主键），支持优先级排序、状态跟踪与暂停/终止/删除等控制。submit() 是 GUI 线程的唯一入队入口（集中分配任务号，Looper 经 submitItem 信号也走它）。

关键方法

方法	说明
`submit`	入队唯一入口：集中分配任务号
`pause`	暂停/恢复当前运行的实验
`set_sleeping`	把任务设为 Sleeping / Queued（预约执行）
`terminate_clicked` / `terminate_all`	优雅终止选中 / 全部任务（Termination Pending）
`delete_item` / `delete_clicked`	删除任务（运行中则优雅终止）
`update_item`	刷新某任务行
`set_model`	更换表格模型（`ScheduleModel`）

任务状态枚举：Queued / Waiting / Sleeping / Running / Paused / Scanning / Terminating / Termination Pending / Done / Failed。

用法

from quatm.GUI.experiment.experiment_queue import ExperimentQueue

q = ExperimentQueue(browser=parent)   # 嵌入实验浏览器
q.submit(task_dict)   # 入队（GUI 线程调用）

更完整说明见实验队列。

8.7 - 多线程任务管理器

QRunnable 多线程任务：Worker 回调执行 + WorkerSignals 信号回主线程。

概述

quatm/GUI/widgets/browser_workers.py 提供多线程任务管理器：Worker 继承 QRunnable，把回调函数放进 QThreadPool 线程池执行，并经 WorkerSignals 把 finished / error / result / progress 等信号发回主线程。供实验浏览器（实验队列、循环器等）使用；同构的 helper_workers 供对准/辅助工具使用。

组件

组件	说明
`Worker`	QRunnable 工作线程：设置、执行与收尾（含异常处理）
`WorkerSignals`	工作线程信号：finished / error / result / progress 等

用法

from quatm.GUI.widgets.browser_workers import Worker

worker = Worker(fn=long_running, args=(...), kwargs={...})
worker.signals.result.connect(on_result)
QThreadPool.globalInstance().start(worker)

更完整说明见后台工作线程。

8.8 - 自动保存编辑器

周期 h5 自动保存时间点列表编辑器：勾选 + 日期时间的保存时刻配置。

概述

quatm/GUI/editors/auto_save_editor.py 提供自动保存编辑器（AutoSaveEditor） ：以弹窗编辑周期 h5 自动保存的“时间点列表”，每一行 = 一个（勾选标记 + 日期时间），勾选的行在对应时刻触发一次自动保存。配置保存在属性（如 regular_auto_save_times）中。

组件

组件	说明
`AutoSaveEditor`	自动保存时间点编辑器（`BWidget` 弹窗）
`DateTimeWidget`	单行日期时间 + 勾选控件

关键方法

方法	说明
`load_AutoSaveEditor_props`	从属性读取日期时间与勾选状态（静态）
`update_props`	把日期时间与勾选状态写回属性（静态）
`update_datetime` / `update_ticked`	某一行日期时间 / 勾选变化时更新
`accept`	保存更改并关闭窗口

用法

from quatm.GUI.editors.auto_save_editor import AutoSaveEditor

editor = AutoSaveEditor(props=props, max_items=20, parent=parent)
editor.show()

更完整说明见自动保存。

8.9 - 实验时间线查看器

FPGA 实验时序可视化：DAC/TTL 输出通道随时间变化的阶梯图查看器。

概述

quatm/GUI/entries/experiment_timeline.py 提供实验时间线查看器（Timeline）：加载实验时序 JSON 文件（experiment.json），把各 DAC/TTL 输出通道随时间的变化绘制成阶梯子图，并输出通道勾选面板决定可见曲线，用于调试与验证实验时序。

组件

组件	说明
`Timeline`	时序查看主窗口：加载文件、绘图与通道控制
`TimelinePlotter`	时序可视化控件：随时间绘制每个在用输出的状态
`SelectorWidget`	输出通道勾选面板：全选 / 全不选

关键方法（Timeline）

方法	说明
`load_file`	加载并解析时序 JSON，构造时间序列并刷新通道选择器
`plot_experimental_sequence`	按通道勾选状态为每个输出建独立子图并绘阶梯图
`decode_ttl_bitmask`	把 32 位 TTL 位掩码拆成各通道的 set/clear 命令
`construct_time_sequences`	把步骤式时序转成按通道组织的 times/vals 序列
`reverse_device_db_transformation`	设备库反变换：内部名映射回可读名

用法

from quatm.GUI.entries.experiment_timeline import Timeline

tl = Timeline()
tl.load_file("experiment.json")   # 加载时序文件并绘图
tl.show()

更完整说明见时序浏览器。

8.10 - 多线程处理框架

QRunnable 多线程处理框架：Worker 回调执行 + WorkerSignals 信号回主线程。

概述

quatm/GUI/widgets/helper_workers.py（及同构的 browser_workers.py）提供多线程处理框架：Worker 继承 QRunnable，把任意回调函数放进 QThreadPool 线程池执行，并通过 WorkerSignals 以 finished / error / result / progress 等信号把结果送回 GUI 主线程。

browser_workers：供实验浏览器（实验队列、循环器等）使用；
helper_workers：供对准/辅助等工具使用。

组件

组件	说明
`Worker`	QRunnable 工作线程：设置、执行与收尾（含异常处理）
`WorkerSignals`	工作线程可发出的信号：finished / error / result / progress 等

用法

from quatm.GUI.widgets.helper_workers import Worker

worker = Worker(fn=long_running, args=(...), kwargs={...})
worker.signals.result.connect(on_result)   # 主线程槽函数
worker.signals.error.connect(on_error)
QThreadPool.globalInstance().start(worker)

更完整说明见后台工作线程。

8.11 - 实验任务循环管理器

条件循环执行器：按测量结果自动重复/跳转/终止任务组循环。

概述

quatm/GUI/looper/ 提供实验任务循环管理器（Looper）：以“循环组（标签页）” 组织任务条目，按顺序执行组内条目，并根据测量结果决定跳转或终止。LoopManager 在后台线程运行循环；循环定义持久化在 loopfile.json，与 Web 远程控制平台共用。

核心逻辑

LoopManager.run_loop()：从起始组开始，无限循环直到 terminate
  └─→ 按顺序执行组内条目
       ├─ Task：提交到实验队列，等待完成后推进（可设最大次数）
       └─ Conditional：读数据流字段比较 → 满足跳转 / 不满足走 else

组件

组件	说明
`LoopGroup`	循环组（一个标签页）
`TaskItem` / `ListItem`	任务条目 / 任务列表条目
`ConditionalItem` 等	数据条件、到达序号、时间等条件条目
`Baustelle`	组内条目的添加/删除/编辑面板
`DataManager`	订阅数据流、累积最新测量值
`LoopManager`	循环执行器（`run_loop()` / `terminate()`，后台线程）

用法

from quatm.GUI.looper import Looper

looper = Looper(parent=browser)   # 浏览器顶部 dock 的循环器标签页

更完整说明见循环器。

8.12 - 实验任务预备队列管理器

预备任务（准备台）的表格模型：PrepModel 列表模型与队列 ScheduleModel。

概述

quatm/GUI/widgets/models.py 提供把 Python 字典 / 列表映射为 Qt 表格模型的基类（源自 ARTIQ models）。预备队列（准备台）用列表型 PrepModel：预备任务不需要唯一 ID、顺序可自由调整；实验队列用字典型 ScheduleModel（按优先级再按任务号排序）。

核心类

类	说明
`_SyncSubstruct`	包装底层容器的字典操作辅助（append/insert/pop 回调刷新）
`DictSyncModel`	字典→表格模型基类
`ListSyncModel`	列表→表格模型基类
`ScheduleModel`	实验队列（ExperimentQueue）模型：任务按优先级/任务号排序
`PrepModel`	预备队列（PrepStation）模型：列表型，顺序可调

具体业务模型通过子类实现 convert（键/值/列转单元格内容）、sort_key（排序键）与 flags（编辑标志）三个钩子。

用法

from quatm.GUI.widgets.models import PrepModel

model = PrepModel(init=prep_list)   # 预备任务列表

模型说明见数据模型；预备队列操作见准备台。

8.13 - 实验运行调度管理器

运行调度机制：队列集中入队，worker 按优先级/预约时间取任务执行。

概述

实验运行调度由实验队列 + 执行引擎协作完成：ExperimentQueue 的 submit() 是 GUI 线程的唯一入队入口（集中分配任务号，准备台与循环器也经它入队）；常驻 worker 在 ExperimentManager.queue_fn 中轮询任务字典，按优先级 → 任务号 → 预约时间（due_check）挑选任务并执行（measurement → sequence → run）。

调度流程

PrepStation / Looper / 实验窗口 --submit()--> 队列任务字典
        ↓
ExperimentManager.queue_fn（worker 线程，按优先级/任务号/预约时间）
        ↓
start_measurement → start_sequence → 多次 run → end_sequence → end_measurement

运行时支持暂停 / 恢复（pause）与优雅终止（terminate_experiment，Termination Pending）。

8.14 - 实验预处理

准备台：任务发往队列前的暂存、编辑、排序与推送（prepfile 持久化）。

概述

quatm/GUI/experiment/prepstation.py 提供实验预处理（PrepStation）：实验浏览器顶部 dock 中的准备台，用于在任务发往实验队列前暂存与编辑。任务列表以 PrepModel 表格展示（顺序可自由调整），持久化到 prepfile.json。

关键方法

方法	说明
`push` / `push_row` / `push_first`	把选中/指定/第一个任务推送到实验队列
`push_to_looper`	把选中任务推送到循环器
`move_up` / `move_down`	调整任务顺序
`delete_clicked` / `set_sleeping`	删除 / 休眠任务
`open_editor` / `open_viewer` / `save_params`	编辑参数、查看参数、保存为 JSON
`update_prep_file`	把任务列表保存到 prepfile.json
`load_previous`	从 prepfile.json 恢复上次任务

用法

from quatm.GUI.experiment.prepstation import PrepStation

ps = PrepStation(browser=parent)
ps.push_first()   # 把第一个预备任务推入队列

更完整说明见准备台。

8.15 - 实验集合管理器

分布式进程面板：按 Servers/Driver/GUI/Viewer/Monitor 分类启停后台进程。

概述

quatm/GUI/entries/processmanager.py 提供实验集合管理器（进程管理器）：按 Servers / Driver / GUI / Viewer / Monitor 分类读取配置，为每个脚本条目生成一个 SingleProcess 启停按钮面板，统一管理整套实验软件进程。进程以当前解释器按脚本或模块（python -m）方式启动，并携带项目根与父进程看门狗环境。

组件

组件	说明
`ProcessManager`	分类面板：读取配置为每个条目生成启停按钮
`SingleProcess`	单条目面板：启动 / 异步终止 / 状态轮询着色

关键方法（SingleProcess）

方法	说明
`startProcess`	停掉旧实例后以当前解释器启动子进程
`stopProcess`	异步终止子进程，不阻塞 GUI 线程
`updateStatus`	周期轮询退出状态并着色（运行中 / 退出 / 崩溃）

用法

from quatm.GUI.entries.processmanager import ProcessManager

pm = ProcessManager(parent=parent)
pm.show()

更完整说明见进程管理器。

8.16 - 实验参数管理器

默认实验参数系统：DefaultExp 聚合设备参数，Dashboard 按设备分组编辑。

概述

quatm/GUI/entries/dashboard.py 提供实验参数管理器：DefaultExp 是聚合所有设备属性的实验基类（build() 遍历设备数据库并按类型分组），各类型参数管理器（BasicManager / IntManager / FloatManager / BoolManager / ComboManager / FrequencyManager）按参数声明生成带单位/范围的输入控件； Dashboard 面板把设备分组展示为可编辑的默认参数区。

组件

组件	说明
`DefaultExp`	默认实验：聚合全部设备属性并按设备分组
`Dashboard`	默认参数面板：按设备分组生成参数控件
`BasicManager` 等	各类型参数控件管理器（Int/Float/Bool/Combo/Frequency）

用法

from quatm.GUI.entries.dashboard import Dashboard

panel = Dashboard(parent=parent)   # 按设备分组显示默认参数

更完整说明见参数系统。

8.17 - 实验运行监视器

数据流监控 GUI：数据/图像/命令/消息多标签监视与单流面板。

概述

quatm/GUI/streammonitor/ 提供实验运行监视器：MainWindow 以标签页容纳数据流（Data）、图像流（Image）、命令（Command）、消息日志（Message）与历史（History ）等监控；每个监控标签由 StreamMonitor 订阅单一数据流并实时展示。

组件

组件	说明
`MainWindow`	监控主窗口：多标签页容器 + 菜单
`StreamMonitor`	单流监控面板：订阅某一数据流并实时展示
`MessageTableModel`	消息日志表格模型（时间戳/来源/级别/内容，按级别着色）
`ImageTableModel`	图像流元数据表格（固定时间/来源列 + 动态键列）

用法

from quatm.GUI.streammonitor import MainWindow, StreamMonitor

win = MainWindow(parent=parent)   # 多标签监控主窗口
panel = StreamMonitor(name="PMT", stream_type="Data", parent=parent)

更完整说明见数据流监视器。

8.18 - 实验任务折叠管理

可折叠分区对话框：SectionExpandButton 切换 + CollapsibleDialog 定义分区。

概述

quatm/GUI/widgets/theexpandables.py 提供可折叠分区组件：CollapsibleDialog （QDialog 子类）用一棵隐藏标题的 QTreeWidget 组织若干可折叠分区，每个分区标题为 SectionExpandButton 按钮，点击即展开/折叠对应内容。

组件

组件	说明
`SectionExpandButton`	展开/折叠某分区的按钮（`QPushButton`）
`CollapsibleDialog`	可添加可折叠分区的对话框基类

关键方法（CollapsibleDialog）

方法	说明
`define_sections`	覆写此方法，以 (title, widget) 元组定义全部分区
`add_section`	添加一个可折叠分区
`add_button` / `add_widget`	创建含按钮的顶层条目 / 挂入内容控件

用法

from quatm.GUI.widgets.theexpandables import CollapsibleDialog

class MyDialog(CollapsibleDialog):
    def define_sections(self):
        self.add_section("参数", some_widget)
        self.add_section("高级", advanced_widget)

dlg = MyDialog()
dlg.define_sections()
dlg.show()

更完整说明见可折叠组件。

9 - 应用案例

通过真实实验案例了解 Quatm 框架在量子物理研究中的应用。

本目录收录来自实验室的 真实实验脚本 与配套辅助工具，展示用 Experiment.build/run、设备属性与参数面板组织实验的方式。

超冷原子实验

案例	说明
MOT 装载优化	调节锂 MOT/CMOT 磁场电流与失谐，优化磁光阱装载
吸收成像	原子荧光/吸收成像：膨胀时间、成像频率与三帧处理
光偶极阱	MOT/CMOT 装载 → ODT 俘获 → TOF → 成像的完整序列
偶极阱优化辅助工具	实验辅助：xODT 对准 + 杂散场补偿

离子阱实验

案例	说明
离子装载与冷却	烧蚀 → 激光冷却 → 荧光计数的装载序列
量子态操控与检测	光学泵浦与状态相关荧光检测
光学囚禁离子	光偶极阱纯光学囚禁离子与态检测
电场偏移补偿辅助工具	杂散场补偿：GUI 工具 + 电压扫描脚本

原子/离子相互作用

案例	说明
原子—离子碰撞	原子 + 离子：装载、态制备与碰撞序列
光偶极阱相互作用实验	光偶极阱中原子-离子相互作用完整时序

系统校准

案例	说明
系统校准	快门、相机触发与触发延迟标定等校准脚本

9.1 - MOT 装载优化

利用 Quatm 的参数扫描和多维时序控制，自动优化磁光阱装载效率。

概述

本实验脚本提供类mot_settings：在 build() 中声明锂 MOT/CMOT 全套设备，并把轴向 / 径向磁场电流与 MOT/CMOT 失谐暴露为 GUI 参数，便于手动或扫描式地优化磁光阱装载。run() 为空时序，可在此基础上扩展成像/计数判断装载效果。

设备（build 节选）

设备	用途
`li_cooling_aom` / `li_repump_aom` / `li_zeeman_aom`	冷却 / 再泵浦 / 塞曼光开关
`li_cooling_power` / `li_repump_power` / `li_zeeman_power`	各路功率
`li_lock_mot` / `li_lock_cmot`	锁频参考

参数（build 节选）

MOT_Axial / _Radial、CMOT_Axial / _Radial（梯度/均匀场电流）、MOT_Current / CMOT_Current（阱电流）、 MOT_detuning / CMOT_detuning（失谐）。

关键代码（节选）

from quatm.experiment import Experiment, NumberValue

class mot_settings(Experiment):
    def build(self):
        self.setattr_device("li_cooling_power")
        self.setattr_argument("MOT_detuning", NumberValue(...))
        # ... 其余设备/参数省略

装载优化

改变磁场电流与失谐后，可结合荧光计数或吸收成像（见同目录吸收成像）测量原子数来判断装载效率。

9.2 - 电场偏移补偿辅助工具

补偿离子阱杂散电场：GUI 工具 + 阱轴电压扫描脚本。

概述

离子阱实验常受杂散电场影响（离子位置偏移/微运动）。电场偏移补偿辅助工具把电压扫描、数据绘图与补偿电压求取整合起来：GUI 侧由 quatm/GUI/alignment/comp_helper.py 的 CompensationHelper 提供；实验侧用 Usage Example/experiments/compensation.py（类 compensation）对离子加 shim 电压并触发多帧图像，扫描 trap_x / trap_y 等轴。

GUI 组件（comp_helper）

组件	说明
`Compensation`	补偿主面板（每阱轴绘图 + 控制）
`PlotWidget` / `TabWidget`	每阱轴一个标签页的绘图
`ControlWidget` / `SingleAxisWidget`	各轴扫描控制与“找补偿电压”（两拟合线交点）
`CompVoltageScan`	在 rf 约束上执行电压扫描

用法

from quatm.GUI.alignment.comp_helper import CompensationHelper

comp = CompensationHelper(parent=parent)

更完整说明见实验辅助。

9.3 - 离子装载与冷却

利用 Quatm 的多阶段时序控制，实现从激光烧蚀到荧光探测的完整离子装载流程。

概述

本脚本提供类loading_ion：编排从开射频阱、烧蚀产生离子、激光冷却到荧光检测的完整离子装载流程。烧蚀脉冲的个数、脉宽与冷却/检测时长等均为 GUI 参数。

参数（build 节选）

Nr_Ablation_Pulses、tune_pulse_number、pulse_duration、det_time、shutter_time、V_rf（阱电压）、ion_cool_power。

时序

开射频阱（V_rf）→ 烧蚀脉冲（多次）→ 激光冷却
  → 荧光检测（计数判断离子是否装载成功）

关键代码（节选）

from quatm.experiment import Experiment

class loading_ion(Experiment):
    def build(self):
        self.setattr_argument("Nr_Ablation_Pulses", NumberValue(...))
        self.setattr_argument("V_rf", NumberValue(...))
        # ... 其余省略

配套

离子装载完成后的冷却与荧光计数可配合量子态检测做态相关测量；射频阱默认参数见 rf_trap.py。

9.4 - 偶极阱优化辅助工具

用实验辅助工具做 ODT 对准：xODT 对准 + 杂散场补偿。

概述

做光偶极阱（xODT/cODT）实验前，需要用偶极阱优化辅助工具把光束对准到原子/离子上。GUI 侧的实验辅助主窗口 odt_utils（quatm/GUI/entries/odt_utils.py ）以标签页聚合两类对准工具：

标签页	真实组件	用途
xODT 对准	`alignment/odt_utils.odt`	压电镜轴扫描 → 高斯拟合 → 发布，把 xODT/cODT 对准到原子云
杂散场补偿	`alignment/odt_utils.compensation`	沿各阱轴找补偿电压，最小化杂散场

用法

from quatm.GUI.entries.odt_utils import odt_utils

helper = odt_utils()   # 独立进程启动，含 xODT 对准与杂散场补偿标签页

完整说明见 GUI 组件目录的实验辅助；对准后的 ODT 实验见光偶极阱。

9.5 - 系统校准

Quatm 在日常实验系统校准与维护中的自动化应用。

功能介绍

除物理实验外，Quatm 将日常校准任务也编为标准实验脚本，实现一键运行和自动记录。覆盖相机暗噪声、快门响应、频率合成器验证和触发延迟标定等常见校准需求。

代码结构

所有校准实验均遵循相同的结构模式：

继承 Experiment 类
在 build() 中声明被测设备和校准参数
在 run() 中执行校准流程并自动记录结果

典型校准任务

相机暗噪声表征

功能：在无光条件下连续采集图像帧，统计暗电流噪声分布。

主要步骤：

关闭所有光源，设置相机曝光时间
循环采集 N 帧暗图像
计算每像素的均值和标准差
保存噪声图谱至 HDF5

涉及设备：相机

快门响应时间测量

功能：测量机械快门从 TTL 触发到完全开启/关闭的延迟时间。

主要步骤：

光电探测器对准快门后的光束
TTL 触发快门开启，同步启动高速采集
记录探测器信号上升/下降沿时间
重复测量取平均

涉及设备：快门（TTL）、光电探测器

频率合成器验证

功能：验证 Valon 5009 或 DDS 频率合成器的实际输出频率和功率。

主要步骤：

设置频率合成器到目标频率
频谱仪测量实际输出
扫描频率范围，记录偏差
生成校准曲线

涉及设备：Valon 5009/DDS（串口）、频谱仪

相机触发延迟标定

功能：测量 TTL 触发到相机实际曝光窗口之间的延迟。

主要步骤：

脉冲光源与相机触发共享同一 TTL 信号
扫描触发延迟参数
检测每帧中光脉冲出现位置
标定最佳延迟值

涉及设备：相机、脉冲光源（TTL）

9.6 - 原子—离子碰撞实验

利用 Quatm 的多系统协同控制，研究冷原子与单离子之间的碰撞动力学。

概述

该实验提供类 secondinteraction：把锂原子 MOT 与离子装载、态制备、移位整合成一次原子-离子碰撞/相互作用实验。各阶段封装成独立方法，便于复用与扩展。

阶段方法

方法	说明
`load_ions`	烧蚀装载 + 激光冷却离子
`count_ions`	荧光计数判断离子是否在阱
`Ion_to_D_state` / `Ion_to_S_state`	态制备
`load_MOT` / `MOT_off`	装载 / 关闭锂 MOT
`ion_state_preparation`	相互作用前的离子态准备
`run`	编排装载—态制备—碰撞—检测序列

参数（build 节选）

Loading_Time、Nr_Ablation_Pulses、Det_Time、Nr_Pictures、 loadingtime_MOT、detection_time、RF_Voltage_Final 等。

关键代码（节选）

from quatm.experiment import Experiment, delay, realtime

class secondinteraction(Experiment):
    def run(self):
        self.load_ions()        # 烧蚀装载 + 激光冷却
        self.Ion_to_S_state()   # 制备到 S1/2
        self.load_MOT()         # 装载锂 MOT
        # 相互作用…然后成像/计数

9.7 - 量子态操控与检测

利用 Quatm 的精确时序和统计分析，实现离子量子态的光学泵浦与状态相关荧光检测。

概述

该实验脚本提供类 state_prep：把离子光学泵浦到 S1/2 或 D3/2 态，并可选在结束时恢复一个冷却循环。态相关检测则用荧光计数区分亮/暗态。

参数

on_s_off_d（泵浦到 S1/2（关 650）还是 D3/2（关 493））、 cooling_end（结束前是否加一次冷却）。

态制备逻辑

S1/2：先关 650 光 → 离子落入 S1/2；
D3/2：先关 493 光 → 离子被泵浦到 D3/2。

此逻辑同样出现在 secondinteraction 的 Ion_to_S_state / Ion_to_D_state 中，并用 count_ions 荧光计数做状态相关检测（亮 = S1/2，暗 = D3/2 等）。

关键代码（节选）

from quatm.experiment import Experiment, BoolValue

class state_prep(Experiment):
    def build(self):
        self.setattr_argument("on_s_off_d", BoolValue(value=False))
        self.setattr_argument("cooling_end", BoolValue(value=True))
        # ... 其余省略

9.8 - 吸收成像

利用 Quatm 的相机控制和图像分析，实现原子云吸收成像的自动化采集与分析。

概述

本实验脚本提供类absorption_imaging：在 build() 中声明冷却/成像光与相机触发，把 MOT 装载、探测闪光与自由飞行膨胀时间暴露为参数；run() 编排成像序列，并提供 fluorescence_imaging 与 absorption_imaging 两种探测方式。

参数（build 节选）

Mot_loading、Flash_us（探测闪光时长）、expansiontime_ms（自由飞行膨胀）、 image_detuning（成像失谐）、MOT_detuning。

设备（build 节选）

li_cooling_aom / li_repump_aom / li_zeeman_aom（冷却/再泵浦/塞曼）、 li_absorption_h（水平吸收探测光）、li_imaging_valon + dds_0（成像频率源）、 trigger_radba（触发）。

关键代码（节选）

from quatm.experiment import Experiment, NumberValue, delay

class absorption_imaging(Experiment):
    def build(self):
        self.setattr_device("li_absorption_h")
        self.setattr_device("li_imaging_valon")
        self.setattr_argument("expansiontime_ms", NumberValue(...))
        # ... 其余省略

    def absorption_imaging(self):
        # 含原子/无原子/背景三帧，计算光学深度
        ...

数据分析

光学深度（柱密度）的计算与发布由分析进程 ImageDivider 完成，见数据与分析/吸收成像。

9.9 - 光偶极阱中的原子-离子相互作用

中性原子与单个离子在光偶极阱中的相互作用实验示例。

概述

在该示例中，我们把锂原子的 MOT / 光偶极阱（ODT）与钡离子的冷却、移位和态检测组合成一次完整的原子-离子相互作用实验。实验类 interaction_optical_trapping 继承 Experiment，主流程由 init_CMOT、absorption_imaging、expose_camera 与 run 等方法分阶段搭建。

一次典型序列大致为：先装载 MOT 并把离子预冷、移位“让开”，再装载原子云进入 CMOT 与光偶极阱，经蒸发、自旋极化后让离子移回并与原子相互作用（可做损失谱或 Feshbach 共振测量），最后做光学测温、吸收成像与离子产物态检测。

主要设备

类别	设备（节选）	用途
锂 MOT/CMOT	`li_cooling_aom` / `li_repump_aom` / `li_zeeman_aom`、`dds_0/1`、`li_mot_det_switch`	冷却/再泵浦/塞曼光与频率、失谐切换
磁场	`b_quadrupole`、`b_homogen`、`quadrupole_fet_off`、`homogen_fet_off`、Feshbach 线圈继电器	MOT 梯度、均匀场、Feshbach/蒸发场
Ba 激光与态	`aom_1(_ttl)`、`aom_2(_ttl)`、各快门、`trigger_cam`	离子冷却、泵浦、离子态检测
光偶极阱	`li_odt_*`（xODT/cODT）、laser 功率	原子/离子的光阱
成像	`li_absorption_h`、`li_imaging_freq`、`trigger_abs`	吸收成像与垂直触发

时序阶段（run 内注释归纳）

MOT 装载 → 离子预冷并移位（让出原子装载空间）
  → CMOT（可选高梯度/功率/失谐阶段）→ 转移进 ODT / 双色阱
  → 蒸发冷却（可选 rf 关联）→ 自旋极化
  → 离子移回原子云 → 相互作用 / 损失 / Feshbach 测量
  → 阱频测量 / 飞行时间(TOF) → 离子光学测温 → 吸收成像 + 离子态检测

关键代码（节选）

from quatm.experiment import NumberValue, BoolValue, Experiment, delay, realtime

class interaction_optical_trapping(Experiment):
    def build(self):
        # 锂 MOT/CMOT 相关设备
        self.setattr_device("li_cooling_power")
        self.setattr_device("li_cooling_aom")
        self.setattr_device("b_quadrupole")
        self.setattr_device("b_homogen")
        # ... 其余设备省略

    def run(self):
        # 相互作用期间让离子保持在原子云中
        with realtime():
            self.li_cooling_aom = False
            delay(0.5)
            # ... 时序省略

运行

把脚本放入 experiments/ 对应目录后，在实验浏览器（Browser）中打开即可看到 build 生成的参数面板；点击运行会按 run 的时序执行整段序列。该脚本也可作为编写自定义原子-离子相互作用实验的模板（关注其中的离子移位 ramps、CMOT 装载与 ODT 转移分段）。

9.10 - 光偶极阱实验

利用 Quatm 的双参数扫描和寿命测量功能，研究 ODT 中冷原子的俘获与损耗特性。

概述

本实验脚本提供类 optical_trapping：在 build() 声明锂 MOT/CMOT 与成像设备，把装载 / 俘获 / 成像的关键时序参数暴露为 GUI 参数；run() 通过 init_CMOT、fluorescence_imaging 与 absorption_imaging 等方法编排完整的光偶极阱（ODT）实验序列。

时序阶段

MOT 装载（Mot_loading）→ CMOT（init_CMOT：梯度/失谐/功率切换）
  → ODT 俘获（trapping_time_ms）→ 释放 → 飞行时间（time_of_flight）
  → 吸收成像 / 荧光成像

参数（build 节选）

Mot_loading、Flash_us、trapping_time_ms、resonance_shift、 image_detuning、detuning_ramp_slope_MHz_ms、time_of_flight、 MOT_detuning / CMOT_detuning、MOT_Current_Loading / CMOT_Current 与 Homogenous_Current_* 系列等。

关键代码（节选）

from quatm.experiment import Experiment, NumberValue, delay

class optical_trapping(Experiment):
    def build(self):
        self.setattr_device("li_cooling_aom")
        self.setattr_device("li_absorption_h")
        self.setattr_argument("trapping_time_ms", NumberValue(...))
        # ... 其余省略

    def init_CMOT(self):
        # CMOT 阶段：梯度、失谐与功率切换
        ...

配套

对准 xODT/cODT 光路可用偶极阱优化辅助工具；成像数据分析见吸收成像与数据与分析目录的吸收成像。

9.11 - 光学囚禁离子

用光偶极阱纯光学囚禁离子并做态检测。

概述

该示例以实验类 OpticalTrappingIon 演示用光偶极阱 纯光学囚禁单个离子。射频势阱（rf）可选择关闭以测量纯光阱性能，也可在可调磁场下进行光学囚禁；配合离子激光冷却、自旋准备与产物态检测，离子还可经轴向电极在阱内外移动。

主要设备

类别	设备（节选）	用途
Ba 激光	`ba_493_aom(_ttl)`、`ba_493_vert_aom`、`ba_650_aom(_ttl)`、`ba_493_res_shut`、`ba_493_det_shut`、`ba_615_shut`	冷却、泵浦（S1/2↔P1/2、D3/2 等）、快门
光偶极阱	`odt_power` / `odt_aom` / `odt_shut`	光囚禁光束的功率与开关
射频阱	`rf`、`rf_off`	射频 Paul 阱约束（可关以实现纯光阱）
轴向移动	`trap_ax`、`trap_ax_pc`、`trap_ax_wall`、`trap_ax_offs`	离子轴向移位（shuttling）
磁场	`b_homogen`、`shim`	预冷/囚禁时的量化磁场
检测	`trigger_cam`	径向离子荧光/态检测触发

参数（build 中 `setattr_argument` 节选）

trapping_time、odtpower、rf_init 与 rf_ramp_duration、opt_ramp_duration、repumpers_on、pump_d32、 ba_spin_prep、b_field_precooling(_applied) / b_field_opt_trap(_applied)、 shuttle_ion / shift_voltage、shutter_time、detect_ba_product_state 等。

时序阶段

初始化
  → 离子自旋准备
  → 磁场切换（可选高场探测）
  → （可选）轴向移出再移回离子
  → 线性爬升光囚禁束功率 → 关闭射频约束（纯光学囚禁）
  → 关闭光阱（释放）与磁场
  → 产物态/荧光检测

关键代码（节选）

from quatm.experiment import *   # Experiment, NumberValue, BoolValue, delay, realtime ...

class OpticalTrappingIon(Experiment):
    def build(self):
        self.setattr_device("ba_493_aom")
        self.setattr_device("odt_power")
        self.setattr_device("rf")
        self.setattr_argument("trapping_time", NumberValue(ndecimals=0, step=10,
                             value=100, unit="µs"))
        # ... 其余参数省略

    def run(self):
        with realtime():
            # 爬升光囚禁束、关闭射频约束实现纯光学囚禁
            self.odt_power = self.odtpower
            self.rf_trap_off = True
            # ... 时序省略

运行

将该脚本放入 experiments 后，在实验浏览器（Browser）中打开即会生成参数面板；调节 odtpower 与 trapping_time 可扫描光学囚禁的功率与时长，配合 detect_ba_product_state 读取离子产物态。

10 - 实验最佳实践

编写可靠、高效的 Quatm 实验脚本的建议与技巧。

实验结构设计

单一职责原则

每个实验脚本聚焦一个明确的物理目标，避免混合多个不相关的逻辑：

experiments/
├── absorption_imaging.py    # 吸收成像
├── fluorescence_detect.py   # 荧光探测
├── rabi_scan.py             # Rabi 振荡
└── sideband_cooling.py      # 边带冷却

复用公共逻辑

将重复步骤提取为 Mixin 类：

class CoolingMixin:
    def doppler_cooling(self, duration=5):
        self.cooling_laser = True
        self.repump_laser = True
        from quatm.experiment.experiment import delay
        delay(duration)
        self.cooling_laser = False

class SidebandExperiment(CoolingMixin, Experiment):
    def run(self):
        self.doppler_cooling()
        # ... 后续步骤

设备管理

在 build 中声明，在 run 中使用

def build(self):
    self.setattr_device("camera")    # 声明
    self.setattr_device("fpga")

def run(self):
    self.camera.expose(0.1)         # 使用

设备状态检查

在实验开始前检查设备连接和状态：

def run(self):
    if not self.controller.is_ready():
        raise RuntimeError("控制器未就绪")
    self.camera.set_temperature(-70)

错误处理与恢复

异常安全关闭

务必在 finally 或上下文管理器中确保关键设备安全关闭：

def run(self):
    try:
        self.mot_coils = True
        with realtime():
            self.cooling_laser = True
            delay(5000)
    finally:
        self.cooling_laser = False
        self.mot_coils = False

使用模拟模式测试

在连接真实硬件前，先通过模拟模式验证实验逻辑：

# 在 device_db.py 中设置模拟模式
"/Devices/simulating": True

性能优化

合理使用 realtime 上下文

realtime() 上下文内的代码直接转换为 FPGA 时序指令，避免在其中放入复杂计算：

# ❌ 不推荐
with realtime():
    result = complex_computation()  # 计算耗时不明确
    self.dac_output = result

# ✅ 推荐
result = complex_computation()  # 在 realtime 外完成计算
with realtime():
    self.dac_output = result

大数据流优化

对于图像等大数据，使用 ImageClient 而非 DataClient，确保数据通道不被阻塞。

测试策略

单元测试

每个自定义驱动和 Mixin 应编写对应的单元测试：

# tests/test_cooling_mixin.py
def test_doppler_cooling():
    exp = MockExperiment()
    exp.doppler_cooling(duration=1)
    assert exp.cooling_laser == False  # 冷却结束后应关闭

集成测试

在模拟模式下运行完整实验流程，验证各组件协作正常。

常见问题

问题	说明	解决方案
`delay()` 单位混淆	`delay(100)` 是 100ms，不是 100s	使用 `delay(5*1000)` 明确表示秒
忘记关闭激光/磁场	实验异常退出时设备保持开启	使用 `try/finally` 确保关闭
属性缓存未刷新	`PropertyAttribute` 值未及时同步	始终使用 `.value` 读写属性
相机未冷却就采集	暗电流噪声过大	采集前检查温度：`assert camera.temperature <= -60`


## 数据管理

通过 `DataClient` 发送结构化的实验数据：

```python
def run(self):
    self._dataq.send({
        "atom_count": N,
        "temperature": T,
        "b_field": self.b_field,
    })

数据以 HDF5 格式保存，自动包含时间戳和扫描参数。

性能优化

减少 GUI 更新频率：仅在关键步骤更新显示
使用 simulation_class_decorator 在模拟模式下快速迭代
高频循环中避免 print()，使用 send_debug() 代替

错误处理

def run(self):
    try:
        self.controller.start_process(1)
        delay(10)
    finally:
        self.controller.reset()
        self.shutter = False

11 - 物理模型库

量子物理实验的物理建模与计算工具

概述

Quatm 物理模型库（physics）提供冷原子/离子混合实验所需的物理建模和计算工具。它包含原子属性数据库、光与物质相互作用计算、光偶极阱（ODT）势建模、Feshbach 共振分析等功能。

原子数据库 — `quatm.physics.odt.atomlib`

提供常用实验原子/离子的物理属性数据，包含基态到激发态的跃迁频率、线宽、Clebsch-Gordan 耦合系数等。

预定义原子

原子/离子	字典名	典型用途
Ba⁺	`BariumDict`	离子阱量子计算
⁶Li	`LithiumDict`	超冷费米气体
Mg⁺	`MagnesiumDict`	离子阱量子计算
⁸⁷Rb	`RubidiumDict`	玻色-爱因斯坦凝聚
Ca⁺	`CalciumDict`	离子阱精密测量

属性字段

每个原子字典包含以下物理常数：

字段	说明
`name`	元素/同位素名称
`charge`	电荷量 (C)
`mass`	原子质量 (kg)
`SP_frequencies`	强跃迁 (S→P) 角频率
`SP_decays`	强跃迁线宽 (角频率)
`SP_linpolcoupling`	Clebsch-Gordan 平方耦合系数
`DP_frequencies`	弱跃迁 (D 态) 频率
`DP_decays`	弱跃迁线宽
`DP_linpolcoupling`	弱跃迁耦合系数

使用示例

from quatm.physics.odt.atomlib import Atom, BariumDict

# 创建钡离子实例
ba_ion = Atom(BariumDict)
print(f"质量: {ba_ion.mass:.2e} kg")
print(f"电荷: {ba_ion.charge:.2e} C")

预实例化的原子可直接导入：Ba, Li, Mg, Rb, Ca。

光与物质相互作用 — `quatm.physics.odt.lightmatterint`

计算给定原子和激光配置下的光-物质相互作用量，基于 Metcalf 和 van der Straten 的形式理论。

`LMinteraction` 类

from quatm.physics.odt.lightmatterint import LMinteraction
from quatm.physics.odt.atomlib import Ba
from quatm.physics.odt.lasers import Laser

# 创建激光对象和相互作用计算器
laser = Laser(wavelength=532e-9, power=10.0, waist=50e-6)
lm = LMinteraction(ion=Ba, laser=laser)

关键方法

方法	功能	公式
`SPStarkShift(transition)`	单跃迁 AC Stark 位移	$\delta_n = -\frac{3\pi c^2}{2\omega_0^3} \left(\frac{\Gamma}{\omega_0-\omega_L} + \frac{\Gamma}{\omega_0+\omega_L}\right) I$
`S12shift()`	S→P 总 Stark 位移	各跃迁加权求和
`ScattRate(transition)`	单跃迁散射率	非共振光子散射速率
`TotalScattRate()`	总散射率	所有强跃迁散射率之和

光偶极阱建模 — `quatm.physics.odt.opticaltraputils`

`Trap` 类

建模完整的光偶极阱势，综合计算以下贡献：

一个或多个高斯激光束的光学势
直流电场（杂散场和四极曲率）
与附加囚禁离子的库仑相互作用

from quatm.physics.odt.opticaltraputils import Trap

trap = Trap(
    laser=laser,
    ion=ba_ion,
    efields=efield_config,
    laseroffset=(0.0, 0.0)  # 激光束偏离阱中心的位置
)

关键方法

方法	说明
`AnalTrapDepth()`	无线性杂散场时的解析阱深 (mK)
`FullPotential2D(x, y)`	计算 (x, y) 处的 2D 完整势
`FullPotential3D(x, y, z)`	计算 (x, y, z) 处的 3D 完整势
`FullPotential(point, ion_pos)`	计算空间某点的完整势 (K)，可含其他离子位置

物理学公式参考

AC Stark 位移

光偶极阱中原子经历的 AC Stark 位移：

$$U_{\text{dip}} = -\frac{3\pi c^2}{2\omega_0^3} \left(\frac{\Gamma}{\omega_0 - \omega_L} + \frac{\Gamma}{\omega_0 + \omega_L}\right) I$$

其中 $\omega_0$ 为原子共振频率，$\omega_L$ 为激光频率，$\Gamma$ 为跃迁线宽，$I$ 为激光强度。

光子散射率

非共振光子散射导致的加热速率为：

$$\Gamma_{\text{sc}} = \frac{3\pi c^2}{2\hbar\omega_0^3} \left(\frac{\omega_L}{\omega_0}\right)^3 \left(\frac{\Gamma}{\omega_0 - \omega_L} + \frac{\Gamma}{\omega_0 + \omega_L}\right)^2 I$$

11.1 - 原子数据库

Ba、Rb、Li、Mg、Ca 原子属性：质量、跃迁频率、Clebsch-Gordan 系数。

概述

atomlib 提供常用冷原子和离子实验原子种类的预计算物理数据。

预定义原子

字典	种类	典型用途
`BariumDict`	Ba⁺	离子阱量子计算
`RubidiumDict`	⁸⁷Rb	玻色-爱因斯坦凝聚
`LithiumDict`	⁶Li	超冷费米气体
`MagnesiumDict`	Mg⁺	离子阱精密测量
`CalciumDict`	Ca⁺	离子阱光钟

属性字段

属性	说明
`mass`	原子质量 (kg)
`ground_state`	基态能级标识
`excited_state`	激发态能级标识
`transition_frequency`	跃迁频率 (Hz)
`decay_rate`	自发辐射衰减率 (s⁻¹)
`clebsch_gordan`	Clebsch-Gordan 耦合系数

11.2 - 电场计算

离子阱电场势能：杂散场、曲率和一维离子位置计算。

概述

efields 计算 Paul 阱中离子的电场势能分布，支持杂散场和曲率参数，基于 James 方法求解一维离子平衡位置。

类

类	说明
`efields`	电场势能计算，含杂散场和曲率
`DCTrap`	管理平均/随机杂散场配置

from quatm.physics.odt.efields import efields

field = efields(stray_field=(1e-3, 0, 0), curvature=0.01)
potential = field.compute_potential(x_grid)

11.3 - 激光模型

高斯光束激光：光束尺寸、强度、波前曲率和缩放电场。

概述

Laser 类建模高斯光束激光器，管理波长/频率/波数的自动同步转换，计算沿传播方向的光束尺寸、R 曲率半径和缩放电场。

from quatm.physics.odt.lasers import Laser

laser = Laser(wavelength=1064e-9, power=10.0, waist=50e-6)
intensity = laser.intensity(z=0.0)
w = laser.beam_radius(z=0.01)

11.4 - 光物质作用

AC Stark 频移和散射率：S→P 和 D→P 跃迁的 Clebsch-Gordan 加权计算。

概述

LMinteraction 计算激光场与原子的相互作用：包括基态到激发态（S→P）和亚稳态到激发态（D→P）的 AC Stark 频移及离共振光子散射率。

from quatm.physics.odt.lightmatterint import LMinteraction

lm = LMinteraction(atom=Ba, laser=laser)
shift = lm.stark_shift(intensity=1e6)  # Hz
rate = lm.scattering_rate(intensity=1e6)  # s⁻¹

11.5 - 光阱模型

复合阱：偶极光束+电场的全 1D/2D/3D 势阱计算。

概述

Trap 将高斯光束光偶极阱与静电场组合为复合势阱模型，计算阱深（势能转折点）和三维势能分布。

from quatm.physics.odt.opticaltraputils import Trap

trap = Trap(laser=odt_laser, efield=dc_field)
depth = trap.trap_depth()  # µK
potential_2d = trap.potential_2d(x, y, z=0)

11.6 - 统计工具

二项式 Wilson 评分区间：离子态判别置信区间。

概述

statistics 提供基于 Wilson 评分区间的二项式比例置信区间工具，用于离子态判别的统计误差估计。

函数	说明
`wilson_score(p, n)`	计算比例 p 的 Wilson 评分
`wilson_err(p, n)`	Wilson 置信区间半宽
`getrandbincont(p, n, N)`	从二项式结果采样 N 次实验概率

Wigner 符号 (utils)

utils 模块提供 Wigner3j 和 Wigner6j 符号的完整 Racah 公式实现，用于角动量耦合计算。

12 - 代码贡献指南

如何对Quatm项目贡献您的智慧

Quatm是一个开源项目，我们热爱并欢迎大家提交补丁和贡献，以使Quatm及其文档变得更好。

贡献Quatm

Quatm主要托管在 https://github.com/quatm/quatm，并在项目私有Git服务器进行镜像备份。

贡献者许可协议

在您参与对本项目的贡献时，除非在有书面协议的例外情况下，您（或您的雇主）保留对您的贡献的版权，并自动给予我们使用和重新分发您的贡献作为项目一部分的权限。具体细节请参考本项目的贡献者许可协议。

代码审核

所有提交都需要经过审核。我们使用 GitHub 的Pull Request（Merge Request）进行代码审核。

社区准则

在交流讨论中，请遵循 Quatm社区准则。

创建问题

如果您想在Quatm中看到某些功能（或者发现某些功能没有按预期工作），但您不确定如何自己修复，请创建一个 issue。您也可以通过社交媒体直接与我们联系。

报告 Bug

使用 GitHub Issue 的 Bug 报告模板创建新 Issue
详细描述问题：你期望看到什么？实际看到了什么？
附上截图和 GIF 动画，展示操作步骤和问题现象
提供复现步骤，使维护者能快速定位问题

功能建议

使用 GitHub Issue 的功能建议模板
清晰简洁地描述建议的功能
尽可能包含使用场景和预期效果

Pull Request 流程

Fork 项目仓库
创建功能分支：git checkout -b feature/my-feature
编写代码并添加测试
确保所有状态检查通过
提交 PR 并填写 PR 模板

代码风格

Python 代码风格

所有 Python 代码必须遵循 PEP 8 规范：

使用 4 空格缩进
类名使用 CamelCase，函数和变量使用 snake_case
导入顺序：标准库 → 第三方库 → 本地模块
为公开 API 编写 docstring

Git 提交信息规范

使用现在时态（“Add feature”，不是 “Added feature”）
使用祈使语气（“Move cursor to…"，不是 “Moves cursor to…"）
第一行限制在 72 字符以内
在第一行之后引用相关 Issue 编号

示例：

Add temperature monitor driver for LFI3751

Implement RS-232 communication and PID auto-tuning
for the Wavelength Electronics LFI3751 controller.

Closes #42

社区联系方式

GitHub Issues：github.com/quatm/quatm/issues
邮件：contact@quatm.com
QQ 交流群：参见技术交流页面
微信公众号：关注获取最新订阅消息

13 - 监控设备

实验室环境监测设备驱动 — 温度控制器、高斯计、示波器、激光控制器、真空规

概述

quatm.monitor 包提供实验室硬件和环境条件的监控驱动。每个监控器作为独立进程运行，通过 RPC 框架暴露功能，持续轮询硬件设备并将读数发布到分布式属性系统，供 GUI、日志和实验反馈使用。

注意：每个监控模块都是可独立运行的脚本。RPC 绑定地址通过命令行参数配置。

温度控制器 — `LFI3751`

Wavelength Electronics LFI-3751 温度控制器驱动，通过 RS-232 串口通信。

主要功能

NTC 热敏电阻校准（Steinhart-Hart 系数）
温度和电流限制配置
PID 自动优化 (auto_PID)
传感器类型选择（热敏电阻、RTD、AD590、LM335）

使用示例

from quatm.monitor.LFI3751 import LFI3751

tc = LFI3751("/dev/ttyUSB0")
# 配置 NTC 热敏电阻参数
tc.set_sensor_properties(a=1.125e-3, b=2.347e-4, c=8.563e-8)
# 设置温度限制
tc.set_temperature_limits(lo=15.0, hi=35.0)
# 设定目标温度并启动
tc.set_temperature(25.0)
tc.turn_on()
# 读取当前温度
current_temp = tc.get_temperature()

参数	说明
`port`	串口设备路径，如 `/dev/ttyUSB0`

高斯计 — `PCE-MFM_3000`

PCE-MFM 3000 高斯计驱动，通过串口返回磁场读数（Gauss）。

使用示例

from quatm.monitor.PCE_MFM_3000 import PCE_MFM_3000

gm = PCE_MFM_3000("/dev/ttyUSB1")
b_field = gm.get_b()  # 返回磁场值 (Gauss)

⚠️ 注意：霍尔探头的磁场校准会随时间漂移，Feshbach 共振实验建议定期对照已知原子跃迁（如 RF 谱）重新校准。

示波器 — `ds1054z`

Rigol DS1054Z 数字示波器驱动，通过 PyVISA SCPI 命令进行波形捕获、电压测量和频率分析。

参数	说明
`resource`	VISA 资源字符串

激光控制器 — `dlc_pro`

Toptica DLC pro 激光控制器接口，监控激光二极管电流、温度设定值、压电扫描参数和锁频状态。

使用示例

from quatm.monitor.dlc_pro import toptica

laser = toptica("192.168.1.50", 1998)
locked = laser.get_lock_status()    # 检查锁频状态
error = laser.get_error_signal()     # 读取锁频误差信号

真空规 — `mvc3`

真空规驱动，用于监测实验腔体的真空度。在冷原子实验中，超高真空（UHV）环境对原子寿命至关重要。

13.1 - LFI3751 温控器

Wavelength Electronics LFI3751 温控器驱动：PyVISA 通信。

概述

LFI3751 驱动 Wavelength Electronics 的高精度半导体激光器温控器，通过 PyVISA 通信。

from quatm.monitor.LFI3751 import LFI3751

tc = LFI3751(addr="USB0::...")
temp = tc.get_temperature()
tc.set_setpoint(25.0)

13.2 - 高斯计

PCE-MFM 3000 高斯计驱动：串口通信，实时磁场测量。

概述

PCE_MFM_3000 驱动 PCE Instruments 的磁场强度测量仪，通过串口实时读取磁感应强度。

from quatm.monitor.PCE_MFM_3000 import PCE_MFM_3000

gauss = PCE_MFM_3000(port="/dev/ttyUSB0")
field = gauss.get_field()  # 返回 mT 值

13.3 - 腔体环境传感器

Arduino 温湿度气压传感器：腔体环境实时监测。

概述

arduino 驱动通过 Arduino Nano 读取腔体内的温度、湿度和气压传感器数据。

from quatm.monitor.cavity_arduino import arduino

env = arduino(port="/dev/ttyACM0")
temp, hum, press = env.read_all()

13.4 - PC 健康监控

CPU/内存/磁盘/网络实时监控：基于 psutil。

概述

PC_health 通过 psutil 监控实验控制计算机的 CPU 使用率、内存占用、磁盘空间和网络流量，防止因资源耗尽导致实验中断。

from quatm.monitor.pc_health import PC_health

health = PC_health()
cpu = health.get_cpu_percent()
mem = health.get_memory_usage()
disk = health.get_disk_free()

13.5 - 示波器

Rigol DS1054Z 示波器驱动：PyVISA 波形采集与电压测量。

概述

ds1054z 驱动 Rigol DS1054Z 四通道数字示波器，通过 PyVISA 进行波形采集和自动测量。

from quatm.monitor.ds1054z import ds1054z

scope = ds1054z(addr="USB0::...")
waveform = scope.get_waveform(channel=1)
vpp = scope.measure_vpp(channel=1)

14 - 工具函数

Quatm 通用工具函数：变密度采样等辅助功能

概述

quatm.utils 包提供 Quatm 框架中跨模块使用的通用工具函数。

变密度采样 — `quatm.utils.vds`

变密度采样（Variable Density Sampling, VDS）允许在参数空间中高效探索，将采样点集中在感兴趣的区域（如量子系统中的共振或相变附近）。

核心思想

在物理实验中，某些参数区域比其他区域更有意义。例如：

Feshbach 共振附近的磁场扫描
光谱线中心附近的频率扫描
相变临界点附近的参数探索

VDS 通过在感兴趣区域自动加密采样点，在平坦区域稀疏采样，实现以最少的数据点获取最多信息。

`gauss_prime_norm` — 归一化高斯导数

高斯函数的导数，归一化到最大值为 1：

$$f(x) = \sqrt{e} \cdot \frac{x - \mu}{\sigma} \exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right)$$

from quatm.utils.vds import gauss_prime_norm

# 计算 x=5.0 处的高斯导数值
val = gauss_prime_norm(5.0, mu=5.0, sigma=1.0)

参数	说明
`x`	输入值，可以是标量或 `numpy.ndarray`
`mu`	高斯中心
`sigma`	高斯标准差

`gauss_prime_norm_abs` — 绝对值归一化高斯导数

高斯导数绝对值的归一化形式，适合用作对称峰检测的兴趣函数。

`create_support_points_stochastic` — 随机支持点生成

从精细等距网格开始，随机移除低兴趣区域的点，保留高兴趣区域的点。

from quatm.utils.vds import (
    create_support_points_stochastic,
    gauss_prime_norm_abs
)

# 定义兴趣函数：在 x=5.0 附近集中采样
def interest(x, center, width):
    return gauss_prime_norm_abs(x, center, width)

points = create_support_points_stochastic(
    start=0.0,      # 扫描起点
    stop=10.0,      # 扫描终点
    steps=50,       # 最终支持点数量
    interest_fn=interest,
    max_stepsize=0.5,   # 最大允许步长
    enhancement=0.8,    # 0-1，1 表示强增强
    center=5.0,         # 传递给 interest_fn
    width=1.0           # 传递给 interest_fn
)

参数	说明
`start`	扫描起点，始终包含在最终支持点中
`stop`	扫描终点，始终包含在最终支持点中
`steps`	最终支持点数量
`interest_fn`	兴趣函数 `f(x, **kwargs)`，返回 0（低兴趣）到 1（高兴趣）
`max_stepsize`	相邻支持点最大间距
`enhancement`	0-1，1 表示强增强感兴趣区域，0 表示均匀随机采样
`**kwargs`	传递给 `interest_fn` 的额外参数

应用场景

变密度采样特别适用于：

Feshbach 共振谱扫描：在共振峰附近加密采样
光谱线扫描：在线心附近提高分辨率
相变参数扫描：在临界区域精细探索
阱频率测量：在预期共振频率附近集中采样

14.1 - 变密度采样

变密度采样：按兴趣函数在参数空间加密采样的支撑点生成器。

概述

quatm/utils/vds.py 提供**变密度采样（VDS）**工具：生成支撑点（采样点），随机分布并在感兴趣区域按给定兴趣函数加密，用于优化有限的实验时间。

函数

函数	说明
`create_support_points_stochastic(start, stop, steps, interest_fn, ...)`	生成随机分布且 ROI 加密的支撑点
`gauss_prime_norm(x, mu, sigma)`	高斯函数导数的归一化形式（峰值归一为 1）
`gauss_prime_norm_abs(x, mu, sigma)`	高斯导数绝对值的归一化形式

用法

from quatm.utils.vds import create_support_points_stochastic

# interest_fn 返回权重（0-1），决定各处的采样密度
points = create_support_points_stochastic(
    start=0, stop=100, steps=200,
    interest_fn=lambda x: gauss_prime_norm_abs(x, mu=50, sigma=10),
)

15 - Web 远程控制平台

quatm.web：与桌面 GUI 同源的浏览器端实验控制平台，支持手机移动端，随时随地掌握实验全局。

quatm.web 是 Quatm 核心包的内置子包（quatm/web/），随 pip install quatm 一起安装，无需额外组件。它把桌面 GUI 的全部核心能力搬进浏览器，并在桌面端与手机移动端分别做了适配。

平台定位

Quatm 桌面 GUI 功能强大，但实验室外、路途中或手机上无法使用。quatm.web 把实验控制延伸到任何有浏览器的设备：

桌面电脑：完整的实验操作台，布局与桌面 GUI 对齐；
手机/平板：专为触屏优化的紧凑界面，随时查看实验状态、调整参数、启停任务；
零安装：客户端只需浏览器，无需安装任何软件或依赖。

Web 服务由实验 PC 上的 webhub 提供，经 TCP/IPC 直连实验的 Hub 网络，与桌面 GUI 共享同一套状态：实验队列、扫描定义、任务暂存、逻辑循环、属性树全部同源。

一键启动

Web 服务已封装为进程管理器的一个 Servers 条目，开箱即用：

"Servers": {
    "Web Hub": {
        "active": false,
        "script": "../quatm/servers/webhub.py",
        "host": "0.0.0.0",
        "port": 8000
    }
}

把 active 改为 true（或在进程管理器中点击 Web Hub），浏览器打开 http://<实验PC>:8000 即可。也可命令行启动：

python -m quatm.web --project <用户项目> --port 8000

功能总览

Web 平台共九个功能页，逐一复刻桌面 GUI 的核心窗口：

页面	对应桌面 GUI	能力
监控	Datastream Monitor / Image Monitor	实时曲线（通道/序列/数组）、消息日志、相机图像
实验	Browser + Experiment Window + ExperimentQ	实验文件列表、参数表单、运行/停止；与桌面实验队列双向同步（桌面 Browser 在线时任务交由其队列执行器运行，状态实时回传）
仪表盘	Dashboard	按设备分组渲染参数控件，带单位/范围/步进元数据，直接写回属性库
数据	h5storage	实时运行追踪（每个 run 完成即累积、X/Y 任选字段绘制实时扫描图）+ HDF5 归档浏览、8 种拟合模型、CSV 导出
属性	Property Editor	完整属性树浏览与编辑（与桌面 GUI 共享同一属性系统）
分析	Analysis Manager	启动/停止分析脚本，与桌面 GUI 的勾选状态互通
时间线	Experiment Timeline	解析 FPGA 序列：TTL 位掩码拆解、device_db 反向映射、多通道阶梯图
通知	Notification Editor	推送通知配置（Webhook），实验完成/异常自动推送
进程	Process Manager	远程查看与启停实验 PC 上的服务/驱动/GUI 进程

实验页进一步对齐桌面 Browser 的顶部 dock，提供 队列管理 / 任务暂存 / 逻辑循环 三个标签页：

实验队列：与桌面 Browser 的队列执行器双向同步（Web 提交 → 桌面队列执行，状态实时回传；桌面排队任务在 Web 同样可见）；
实验暂存：与桌面 GUI 共用同一份 prepfile.json，任务暂存、推送、排序；
实验逻辑：与桌面 GUI 共用同一份 loopfile.json，任务循环 + 数据条件分支，支持最大次数/最大连续次数终止。

与桌面 GUI 同源的实验操作

Web 实验窗口完整复刻桌面实验窗口的操作逻辑：

参数保存/加载：与桌面 GUI 同目录、同格式（experiment_params/<实验>/<日期>/ ），桌面保存的参数集 Web 可直接加载；
参数扫描：Scan 下拉与桌面 scanCombo 同源（属性树），SequenceEditor 式编辑器在浏览器中直接创建/编辑扫描（参数、起止、步数、随机化、Snake/nD 模式）；
实验窗口按钮行：提交 / Run Next / Prep / Save / Load，与桌面布局一致。

移动端特调

在手机/平板上打开同一地址，界面自动切换为触屏优化布局：

导航横向滚动，所有页面一屏可达；
布局自动堆叠为单列，图表高度适配小屏；
按钮与输入控件放大到触控友好尺寸（≥38px）；
参数网格、进程列表、表格等自动重排。

远程访问

实验 PC 与远程客户端共用同一套 configuration/configfile/configfile.json 约定。生成服务器侧（Hub 绑定 tcp://*:56xx）与客户端侧（端点指向实验 PC）配置：

# 实验 PC：Hub 开放到局域网
python -m quatm.web endpoints --project <项目> --server --out server_config.json

# 远程机器：端点指向实验 PC
python -m quatm.web endpoints --project <项目> --remote-host <IP地址> --out client_config.json

也可通过 SSH 隧道安全访问（Hub 本身无认证，建议仅在内网/VPN 使用）：

ssh -L 5601:localhost:5601 -L 8000:localhost:8000 user@experiment-pc

架构

浏览器（桌面/手机）──HTTP/WebSocket──► webhub（quatm.servers.webhub）
                                          │ TCP/IPC/RPC 直连实验 Hub 网络
                    ┌─────────────────────┼──────────────────────┐
                    ▼                     ▼                      ▼
              Data/Image Hub        Property Hub           Message Hub
                    │                     │                      │
              实验数据实时流          与桌面 GUI 共享          实验日志与
               （含实时追踪）          的属性系统               异常通知

Web 服务与桌面 GUI 使用完全相同的 Hub 端点与消息协议，因此两者可以 同时在线、协同操作：桌面提交的任务在手机端可见，手机端修改的参数在桌面 GUI 实时同步。

通信	Pylon SDK (GenICam)
接口	USB3 / GigE
传感器	CMOS
像素格式	Mono8/16, Bayer
功能	ROI, Binning, 硬件触发

主题	模块
队列/准备台表格模型	`widgets/models.py`（ScheduleModel / PrepModel）
订阅编辑	`editors/subscription_editor.py`
自动保存时间表	`editors/auto_save_editor.py`
属性树编辑	`entries/property_editor.py`
实时更新绘图	`entries/updating_plot.py`
滚动波形 / 实时滚动图	`entries/scrollwindow.py`、`entries/live_plot.py`
数据流监控	`streammonitor/`
图像监控 / 图像查看	`entries/image_monitor.py`、`entries/image_group.py`
对准辅助	`alignment/`（odt / comp / verdi helper）
压电镜控制	`entries/piezo_mirror_controler.py`
H5 数据管理	`h5storage/`

组件	模块	说明
`ExperimentQueue`	`experiment/experiment_queue.py`	任务队列：入队、状态跟踪、暂停/终止
`ExperimentManager`	`experiment/experiment_manager.py`	执行引擎：取任务、跑测量/序列/运行
`PrepStation`	`experiment/prepstation.py`	预备任务，推送入队
`Looper`	`looper/`	条件循环，经 submit 入队

方法	功能	公式
`SPStarkShift(transition)`	单跃迁 AC Stark 位移	\(\delta_n = -\frac{3\pi c^2}{2\omega_0^3} \left(\frac{\Gamma}{\omega_0-\omega_L} + \frac{\Gamma}{\omega_0+\omega_L}\right) I\)
`S12shift()`	S→P 总 Stark 位移	各跃迁加权求和
`ScattRate(transition)`	单跃迁散射率	非共振光子散射速率
`TotalScattRate()`	总散射率	所有强跃迁散射率之和

欢迎使用Quatm

什么是 Quatm？

Quatm 适合我吗？

系统架构

各层职责

文档导航

1 - 快速开始

环境要求

安装

验证

下一步

1.1 - 编写第一个实验

实验的基本结构

build() — 声明阶段

设备声明模式

参数类型

run() — 执行阶段

设备控制

数据采集

运行实验

1.2 - 常见问题

Windows 系统

FPGA 控制器驱动

Linux 系统

Qt 图形库依赖

相机权限

Windows Subsystem for Linux (WSL)

Web 远程控制平台（quatm.web）

旧版本安装缺少 quatm.web 子包

与桌面 GUI 同时操作同一进程

1.3 - 配置仪器设备

设备类型

配置示例

属性设备参数

TTLOut — 数字输出

DAC — 模拟输出

通用属性配置

校准文件

自定义驱动接入

2 - 实验编辑指南

Experiment 基类

核心方法

声明设备

声明参数

设备属性类型

实验生命周期

时序控制

delay() 函数

实验控制设备

数据管理

发送实验数据

前馈控制

模拟模式

3 - 设备与驱动

设备接入模式

驱动分类

属性设备详解

TTLOut — 数字输出

DAC — 模拟输出

校准文件

自定义驱动

通信协议

3.1 - 科学相机

概述

Andor 系列：iXon EMCCD / Zyla sCMOS / Shamrock 光谱仪

概述

Andor SDK2 (EMCCD) AndorSDK2Camera

⚙️ iXon EMCCD Andor SDK2 系列

初始化

关键参数

Andor SDK3 (sCMOS) AndorSDK3Camera

⚙️ Zyla / Neo sCMOS Andor SDK3 系列

初始化

Andor Shamrock 光谱仪 ShamrockSpectrograph

设备配置

校准提示

FLIR / Teledyne / Blackfly S / Grasshopper3

概述

⚙️ Blackfly S / Grasshopper3 FLIR Spinnaker 系列

初始化

Andor SDK2 (EMCCD) `AndorSDK2Camera`

Andor SDK3 (sCMOS) `AndorSDK3Camera`

Andor Shamrock 光谱仪 `ShamrockSpectrograph`

TLCamera `ThorlabsTLCamera`

Andor SDK2 (EMCCD) `AndorSDK2Camera`

Andor SDK3 (sCMOS) `AndorSDK3Camera`

Andor Shamrock 光谱仪 `ShamrockSpectrograph`

TLCamera 科学相机 `ThorlabsTLCamera`