实验框架

1 - 数据类控件

概述

quatm/GUI/widgets/arg_boxes.py 提供数据类控件：一套把实验参数显示为可编辑控 件的输入框体系。FloatBox / BoolBox / ComboBox 等控件继承对应管理器 （FloatManager / BoolManager / ComboManager），带单位、范围与步长，值改动时 立即写回属性（含 last_set），供实验窗口参数网格与参数系统使用。

组件

用法

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

# 通常由参数系统按参数声明自动生成对应控件

更完整说明见 参数框 与 参数系统。

2 - 实验窗口控件类

概述

quatm/GUI/widgets/quatmQt.py 提供 GUI 基础控件类：BWidget / BFrame / BMainWindow 是各窗口/面板/主窗口的基类（带属性命名空间 _props，关闭时把几何保存到 QSettings、启动时恢复）；SearchComboBox 等提供带自动补全与过滤的可搜索组合框。

组件

用法

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

win = BMainWindow(name="我的窗口")   # 几何自动持久化

更完整说明见 GUI基础类。

3 - 实验序列编辑器

概述

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

组件

用法

from quatm.GUI.editors.editor_sequencer import CodeEditorParser

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

更完整说明见 序列编辑器。

4 - 实验任务运行管理器

概述

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

关键方法

用法

from quatm.GUI.experiment.experiment_manager import ExperimentManager

manager = ExperimentManager(browser)   # browser 提供队列与界面
manager.start_queue()

更完整说明见 实验管理器。

5 - 实验控制浏览器

概述

quatm/GUI/browser/ 提供实验控制浏览器（Browser）：Quatm 的主应用窗口，基于 QMainWindow + QMdiArea。左侧 FileSelector 浏览实验脚本，顶部停靠实验队列、 准备台与循环器，中央 MDI 区内每个实验一个 ExperimentWindow 子窗口。

核心组件

生命周期

• open_experiment：打开实验窗口；已打开则恢复并置前。
• closeEvent：保存主窗口几何与子窗口状态后停止 worker 线程。
• moveEvent / resizeEvent：防抖保存几何供下次启动恢复。

用法

from quatm.GUI.browser.main_window import Browser

browser = Browser()
browser.show()

更完整说明见 实验浏览器。

6 - 实验队列管理器

概述

quatm/GUI/experiment/experiment_queue.py 提供实验队列管理器（ExperimentQueue ）：以表格展示任务队列（任务字典 expDict，任务号为主键），支持优先级排序、状 态跟踪与暂停/终止/删除等控制。submit() 是 GUI 线程的唯一入队入口（集中分配任务 号，Looper 经 submitItem 信号也走它）。

关键方法

任务状态枚举：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 线程调用）

更完整说明见 实验队列。

7 - 多线程任务管理器

概述

quatm/GUI/widgets/browser_workers.py 提供多线程任务管理器：Worker 继承 QRunnable，把回调函数放进 QThreadPool 线程池执行，并经 WorkerSignals 把 finished / error / result / progress 等信号发回主线程。供实验浏览器（实验队列、 循环器等）使用；同构的 helper_workers 供对准/辅助工具使用。

组件

用法

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 - 自动保存编辑器

概述

quatm/GUI/editors/auto_save_editor.py 提供自动保存编辑器（AutoSaveEditor） ：以弹窗编辑周期 h5 自动保存的“时间点列表”，每一行 = 一个（勾选标记 + 日期时间） ，勾选的行在对应时刻触发一次自动保存。配置保存在属性（如 regular_auto_save_times）中。

组件

关键方法

用法

from quatm.GUI.editors.auto_save_editor import AutoSaveEditor

editor = AutoSaveEditor(props=props, max_items=20, parent=parent)
editor.show()

更完整说明见 自动保存。

9 - 实验时间线查看器

概述

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

组件

关键方法（Timeline）

用法

from quatm.GUI.entries.experiment_timeline import Timeline

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

更完整说明见 时序浏览器。

10 - 多线程处理框架

概述

quatm/GUI/widgets/helper_workers.py（及同构的 browser_workers.py）提供多线 程处理框架：Worker 继承 QRunnable，把任意回调函数放进 QThreadPool 线程池 执行，并通过 WorkerSignals 以 finished / error / result / progress 等信号把结果 送回 GUI 主线程。

• browser_workers：供实验浏览器（实验队列、循环器等）使用；
• helper_workers：供对准/辅助等工具使用。

组件

用法

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)

更完整说明见 后台工作线程。

11 - 实验任务循环管理器

概述

quatm/GUI/looper/ 提供实验任务循环管理器（Looper）：以“循环组（标签页）” 组织任务条目，按顺序执行组内条目，并根据测量结果决定跳转或终止。LoopManager 在 后台线程运行循环；循环定义持久化在 loopfile.json，与 Web 远程控制平台共用。

核心逻辑

LoopManager.run_loop()：从起始组开始，无限循环直到 terminate
  └─→ 按顺序执行组内条目
       ├─ Task：提交到实验队列，等待完成后推进（可设最大次数）
       └─ Conditional：读数据流字段比较 → 满足跳转 / 不满足走 else

组件

用法

from quatm.GUI.looper import Looper

looper = Looper(parent=browser)   # 浏览器顶部 dock 的循环器标签页

更完整说明见 循环器。

12 - 实验任务预备队列管理器

概述

quatm/GUI/widgets/models.py 提供把 Python 字典 / 列表映射为 Qt 表格模型的基类 （源自 ARTIQ models）。预备队列（准备台）用列表型 PrepModel：预备任务不需要 唯一 ID、顺序可自由调整；实验队列用字典型 ScheduleModel（按优先级再按任务号 排序）。

核心类

具体业务模型通过子类实现 convert（键/值/列转单元格内容）、sort_key（排序键） 与 flags（编辑标志）三个钩子。

用法

from quatm.GUI.widgets.models import PrepModel

model = PrepModel(init=prep_list)   # 预备任务列表

模型说明见 数据模型；预备队列操作见 准备台。

13 - 实验运行调度管理器

概述

实验运行调度由 实验队列 + 执行引擎 协作完成：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）。

相关页面

• 实验队列管理器、实验任务运行管理器、 实验预处理、实验任务循环管理器

14 - 实验预处理

概述

quatm/GUI/experiment/prepstation.py 提供实验预处理（PrepStation）：实验浏 览器顶部 dock 中的准备台，用于在任务发往实验队列前暂存与编辑。任务列表以 PrepModel 表格展示（顺序可自由调整），持久化到 prepfile.json。

关键方法

用法

from quatm.GUI.experiment.prepstation import PrepStation

ps = PrepStation(browser=parent)
ps.push_first()   # 把第一个预备任务推入队列

更完整说明见 准备台。

15 - 实验集合管理器

概述

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

组件

关键方法（SingleProcess）

用法

from quatm.GUI.entries.processmanager import ProcessManager

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

更完整说明见 进程管理器。

16 - 实验参数管理器

概述

quatm/GUI/entries/dashboard.py 提供实验参数管理器：DefaultExp 是聚 合所有设备属性的实验基类（build() 遍历设备数据库并按类型分组），各类型参数管理 器（BasicManager / IntManager / FloatManager / BoolManager / ComboManager / FrequencyManager）按参数声明生成带单位/范围的输入控件； Dashboard 面板把设备分组展示为可编辑的默认参数区。

组件

用法

from quatm.GUI.entries.dashboard import Dashboard

panel = Dashboard(parent=parent)   # 按设备分组显示默认参数

更完整说明见 参数系统。

17 - 实验运行监视器

概述

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

组件

用法

from quatm.GUI.streammonitor import MainWindow, StreamMonitor

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

更完整说明见 数据流监视器。

18 - 实验任务折叠管理

概述

quatm/GUI/widgets/theexpandables.py 提供可折叠分区组件：CollapsibleDialog （QDialog 子类）用一棵隐藏标题的 QTreeWidget 组织若干可折叠分区，每个分区标题 为 SectionExpandButton 按钮，点击即展开/折叠对应内容。

组件

关键方法（CollapsibleDialog）

用法

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()

更完整说明见 可折叠组件。