Experiment framework

1 - Data Widgets

Overview

quatm/GUI/widgets/arg_boxes.py provides data widgets: a family of input boxes that present experiment parameters as editable controls. FloatBox / BoolBox / ComboBox and the other widgets subclass the corresponding manager (FloatManager / BoolManager / ComboManager), carry a unit, range and step, and write a changed value straight back to the attribute (including last_set); they are used by the parameter grid of the experiment window and by the parameter system.

Components

Usage

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

# usually the parameter system generates the matching widget from the parameter declaration

For a fuller description see Parameter boxes and Parameter system.

2 - Base Window Widgets

Overview

quatm/GUI/widgets/quatmQt.py provides the GUI base widget classes: BWidget / BFrame / BMainWindow are the base classes of the various windows/panels/main windows (with a property namespace _props, saving the geometry to QSettings on close and restoring it on start-up); SearchComboBox and others provide searchable combo boxes with autocompletion and filtering.

Components

Usage

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

win = BMainWindow(name="My window")   # geometry persisted automatically

For a fuller description see GUI base classes.

3 - Sequence Editor

Overview

quatm/GUI/editors/editor_sequencer.py provides the sequence editor (edit and simulate): the CodeEditorParser composite window combines the CodeEditor code editor on the left with the sequence visualisation on the right; after editing an experiment script you can simulate a run with one click and the timing of the individual output channels is drawn as step plots.

Components

Usage

from quatm.GUI.editors.editor_sequencer import CodeEditorParser

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

For a fuller description see Sequence editor.

4 - Experiment Run Manager

Overview

quatm/GUI/experiment/experiment_manager.py provides the experiment run manager (ExperimentManager): the engine that takes tasks out of the experiment queue and executes them. The queue polling runs in a worker thread, and tasks are scheduled in the hierarchy measurement (measurement) → repetition (repetition) → sequence/scan (sequence) → single run (run).

Key methods

Usage

from quatm.GUI.experiment.experiment_manager import ExperimentManager

manager = ExperimentManager(browser)   # browser supplies the queue and the interface
manager.start_queue()

For a fuller description see Experiment manager.

5 - Experiment Browser

Overview

quatm/GUI/browser/ provides the experiment browser (Browser): the main application window of Quatm, built on QMainWindow + QMdiArea. The FileSelector on the left browses the experiment scripts, the experiment queue, preparation station and looper are docked at the top, and each experiment has its own ExperimentWindow sub-window in the central MDI area.

Core components

Lifecycle

• open_experiment: opens an experiment window; if it is already open, it is restored and brought to the front.
• closeEvent: saves the main-window geometry and the sub-window state, then stops the worker threads.
• moveEvent / resizeEvent: debounced saving of the geometry for restoration on the next start.

Usage

from quatm.GUI.browser.main_window import Browser

browser = Browser()
browser.show()

For a fuller description see Experiment browser.

6 - Experiment Queue Manager

Overview

quatm/GUI/experiment/experiment_queue.py provides the experiment queue manager (ExperimentQueue ): it shows the task queue as a table (the task dictionary expDict, keyed by task number) and supports priority sorting, state tracking and controls such as pause/terminate/delete. submit() is the only enqueueing entry point on the GUI thread (task numbers are allocated centrally, and the Looper also goes through it via the submitItem signal).

Key methods

Task-state enumeration: Queued / Waiting / Sleeping / Running / Paused / Scanning / Terminating / Termination Pending / Done / Failed.

Usage

from quatm.GUI.experiment.experiment_queue import ExperimentQueue

q = ExperimentQueue(browser=parent)   # embedded in the experiment browser
q.submit(task_dict)   # enqueue (called on the GUI thread)

For a fuller description see Experiment queue.

7 - Worker Task Manager

Overview

quatm/GUI/widgets/browser_workers.py provides the worker task manager: Worker subclasses QRunnable and executes a callback in the QThreadPool thread pool, then sends finished / error / result / progress signals back to the main thread via WorkerSignals. It is used by the experiment browser (experiment queue, looper, etc.); the isomorphic helper_workers is used by alignment/auxiliary tools.

Components

Usage

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)

For a fuller description see Background worker threads.

8 - Auto-save Editor

Overview

quatm/GUI/editors/auto_save_editor.py provides the auto-save editor (AutoSaveEditor): a popup dialog for editing the “list of points in time” of the periodic HDF5 auto-save, where every row is one (tick mark + date/time) pair and a ticked row triggers one auto-save at the corresponding instant. The configuration is stored in a property (such as regular_auto_save_times).

Components

Key methods

Usage

from quatm.GUI.editors.auto_save_editor import AutoSaveEditor

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

For a fuller description see Auto-save.

9 - Timeline Viewer

Overview

quatm/GUI/entries/experiment_timeline.py provides the timeline viewer (Timeline): it loads an experiment-timing JSON file (experiment.json), plots the variation over time of each DAC/TTL output channel as a step subplot, and the output-channel check panel determines which curves are visible; it is used to debug and verify the experiment timing.

Components

Key methods (Timeline)

Usage

from quatm.GUI.entries.experiment_timeline import Timeline

tl = Timeline()
tl.load_file("experiment.json")   # load the timing file and plot it
tl.show()

For a fuller description see Timing browser.

10 - Multithreaded Worker Framework

Overview

quatm/GUI/widgets/helper_workers.py (and the isomorphic browser_workers.py) provides the multithreaded worker framework: Worker subclasses QRunnable and puts an arbitrary callback function into the QThreadPool thread pool for execution, and returns the result to the GUI main thread through WorkerSignals using finished / error / result / progress signals.

• browser_workers: used by the experiment browser (experiment queue, looper, etc.);
• helper_workers: used by alignment/auxiliary and similar tools.

Components

Usage

from quatm.GUI.widgets.helper_workers import Worker

worker = Worker(fn=long_running, args=(...), kwargs={...})
worker.signals.result.connect(on_result)   # main-thread slot
worker.signals.error.connect(on_error)
QThreadPool.globalInstance().start(worker)

For a fuller description see Background worker threads.

11 - Loop Manager

Overview

quatm/GUI/looper/ provides the loop manager (Looper): task entries are organised as “loop groups (tabs)”, the entries of a group are executed in order, and the jumps or termination are decided from measurement results. LoopManager runs the loop in a background thread; the loop definition is persisted in loopfile.json and shared with the web remote-control platform.

Core logic

LoopManager.run_loop(): start from the first group, loop indefinitely until terminate
  └─→ execute the entries of the group in order
       ├─ Task: submit to the experiment queue, advance once complete (maximum count configurable)
       └─ Conditional: read data-stream fields and compare → jump if satisfied / else branch otherwise

Components

Usage

from quatm.GUI.looper import Looper

looper = Looper(parent=browser)   # looper tab of the dock at the top of the browser

For a fuller description see Looper.

12 - Preparation Queue Manager

Overview

quatm/GUI/widgets/models.py provides base classes that map Python dictionaries / lists onto Qt table models (derived from the ARTIQ models). The preparation queue (preparation station) uses the list-type PrepModel: prepared tasks need no unique ID and their order can be changed freely; the experiment queue uses the dictionary-type ScheduleModel (sorted by priority, then by task number).

Core classes

Concrete business models implement three hooks in a subclass: convert (key/value/column to cell content), sort_key (sorting key) and flags (edit flags).

Usage

from quatm.GUI.widgets.models import PrepModel

model = PrepModel(init=prep_list)   # list of prepared tasks

The models are described in Data models; preparation-queue operations are described in Preparation station.

13 - Experiment Run Scheduler

Overview

Experiment run scheduling is accomplished by the experiment queue and the execution engine working together: submit() of the ExperimentQueue is the only enqueueing entry point on the GUI thread (task numbers are allocated centrally, and the preparation station and looper also enqueue through it); the resident worker polls the task dictionary in ExperimentManager.queue_fn and selects and executes tasks by priority → task number → reservation time (due_check) (measurement → sequence → run).

Related components

Scheduling flow

PrepStation / Looper / experiment window --submit()--> queue task dictionary
        ↓
ExperimentManager.queue_fn (worker thread, by priority/task number/reservation time)
        ↓
start_measurement → start_sequence → several runs → end_sequence → end_measurement

At run time pause / resume is supported (pause) as well as graceful termination (terminate_experiment, Termination Pending).

Related pages

• Experiment Queue Manager, Experiment Run Manager, Experiment Preparation, Loop Manager

14 - Experiment Preparation

Overview

quatm/GUI/experiment/prepstation.py provides experiment preparation (PrepStation): the preparation station in the dock at the top of the experiment browser, used for staging and editing tasks before they are sent to the experiment queue. The task list is displayed with a PrepModel table (its order can be changed freely) and persisted to prepfile.json.

Key methods

Usage

from quatm.GUI.experiment.prepstation import PrepStation

ps = PrepStation(browser=parent)
ps.push_first()   # push the first prepared task into the queue

For a fuller description see Preparation station.

15 - Process Manager

Overview

quatm/GUI/entries/processmanager.py provides the process manager: it reads the configuration grouped as Servers / Driver / GUI / Viewer / Monitor and generates a SingleProcess start/stop button panel for every script entry, managing the whole set of experiment-software processes in one place. A process is started with the current interpreter, either as a script or as a module (python -m), and carries the project root and the parent-process watchdog environment.

Components

Key methods (SingleProcess)

Usage

from quatm.GUI.entries.processmanager import ProcessManager

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

For a fuller description see Process manager.

16 - Experiment Parameter Manager

Overview

quatm/GUI/entries/dashboard.py provides the experiment parameter manager: DefaultExp is the experiment base class that aggregates the attributes of all devices (build() walks the device database and groups them by type), and the per-type parameter managers (BasicManager / IntManager / FloatManager / BoolManager / ComboManager / FrequencyManager) generate input widgets with unit/range from the parameter declarations; the Dashboard panel presents the device groups as editable default-parameter sections.

Components

Usage

from quatm.GUI.entries.dashboard import Dashboard

panel = Dashboard(parent=parent)   # show the default parameters grouped by device

For a fuller description see Parameter system.

17 - Run Monitor

Overview

quatm/GUI/streammonitor/ provides the run monitor: MainWindow hosts monitoring tabs for data streams (Data), image streams (Image), commands (Command), the message log (Message) and history (History); each monitoring tab consists of a StreamMonitor that subscribes to a single data stream and displays it in real time.

Components

Usage

from quatm.GUI.streammonitor import MainWindow, StreamMonitor

win = MainWindow(parent=parent)   # multi-tab monitoring main window
panel = StreamMonitor(name="PMT", stream_type="Data", parent=parent)

For a fuller description see Data stream monitor.

18 - Collapsible Sections

Overview

quatm/GUI/widgets/theexpandables.py provides collapsible section components: CollapsibleDialog (a QDialog subclass) organises several collapsible sections with a QTreeWidget whose header is hidden; each section header is a SectionExpandButton button, and clicking it expands/collapses the corresponding content.

Components

Key methods (CollapsibleDialog)

Usage

from quatm.GUI.widgets.theexpandables import CollapsibleDialog

class MyDialog(CollapsibleDialog):
    def define_sections(self):
        self.add_section("Parameters", some_widget)
        self.add_section("Advanced", advanced_widget)

dlg = MyDialog()
dlg.define_sections()
dlg.show()

For a fuller description see Collapsible components.