How ulm-iqo/qudi works
1. What this repository is
Qudi is a modular laboratory experiment control framework written in Python, centered on Qt-based desktop GUI control, instrument drivers, logic modules, and a runtime module manager. It is not a monolith; it is a plugin-like system for assembling experiments from interchangeable components.
2. Startup and composition
The application is typically assembled from configuration files under config/. start.py is the top-level entry point, and the manager/core layer reads the config to decide which hardware, logic, and GUI modules to instantiate, how they are connected, and which threads or remote endpoints they run in. tools/config_gui is a companion utility for editing those configs.
3. Core framework boundary
The core/ package is the framework kernel: module lifecycle, configuration handling, dependency wiring, logging, thread management, remote communication, and metadata. Key concepts here are:
- modules with managed startup/shutdown
- connectors/interfaces for explicit dependencies
- status/config options for runtime parameters
- thread and process management for isolating work
- remote module support for distributed setups
4. The architectural layers
The repo is organized into four main runtime layers:
- hardware/: concrete device drivers and dummy implementations
- interface/: abstract contracts that hardware modules implement
- logic/: experiment orchestration, data processing, workflows
- gui/: Qt widgets and windows for user interaction
This separation is the main architectural boundary to capture in a diagram.
5. Control/data flow
The usual path is:
GUI event → logic module → hardware driver → measurement/data return → logic processing → GUI update.
GUIs do not talk directly to instruments; they control logic modules. Logic modules, in turn, depend on interface-defined hardware services. This keeps the GUI and device drivers decoupled.
6. Hardware subsystem
hardware/ contains many vendor- and instrument-specific drivers: AWGs, counters, cameras, lasers, microwave sources, motion stages, spectrometers, power supplies, wavemeters, temperature controllers, and more. Many modules have corresponding *_dummy.py versions, indicating the framework is designed to run without physical hardware for testing and development. Some drivers wrap external C APIs or instrument libraries.
7. Logic subsystem
logic/ is where experiment behavior lives: confocal scanning, ODMR, pulsed measurements, laser control, PID, magnet control, fit handling, task execution, time-series reading, and saving. Logic modules combine multiple hardware interfaces into experiment-level operations and often own the state machines or measurement loops. The logic/fitmethods/ and pulsed subpackages show that data analysis and sequence generation are first-class concerns, not afterthoughts.
8. Interfuse and adaptation layer
logic/interfuse/ is an important architectural boundary. These modules sit between logic and hardware to transform, combine, or correct device behavior without rewriting either side. Examples include scanner correction, magnet-motor coupling, microwave differential scanning, and switch combiners. In a diagram, this is a separate adapter/middleware layer.
9. GUI subsystem
gui/ contains many independent Qt front ends for specific experiments and tools: confocal, ODMR, pulsed, camera, magnet, spectrometer, task runner, plotter, manager, etc. The .ui files show that Qt Designer is used heavily. The GUI layer also includes reusable widgets in qtwidgets/ and app-wide styling in artwork/styles/.
10. Manager and operator tools
gui/manager/ is the administrative console for the system: module control, logs, thread views, remote module views, and application state. This suggests the framework has a central operator-facing control plane separate from experiment GUIs. The manager is the place where module health, startup/shutdown, and runtime diagnostics are surfaced.
11. Remote and distributed execution
The repo explicitly supports multi-computer operation. core/remote.py, core/parentpoller.py, and the remote widgets in the manager GUI indicate a client/server or controller/worker model for modules running on other hosts. This matters for architecture diagrams because some modules are local, while others can be proxied over the network.
12. Automation, tasks, and scripting
logic/taskrunner.py plus logic/tasks/ provide a workflow/task abstraction for automated procedures such as refocusing or mirror switching. logic/jupyterkernel/ embeds Jupyter/IPython-style scripting support, letting users drive the same module graph interactively. This is the framework’s scripting/automation side, separate from the operator GUI.
13. Data handling and analysis
The repository includes reusable logic for plotting, saving, trace analysis, spectrum handling, time-series reading, and fitting. logic/save_logic.py, logic/qdplot_logic.py, logic/fit_logic.py, and logic/trace_analysis_logic.py indicate that acquisition and analysis are integrated into the runtime rather than exported to external tools only.
14. Domain-specific measurement stacks
Several subtrees represent complete application stacks built on the same framework: confocal microscopy, ODMR, pulsed experiments, NV center tooling, camera control, wavemeter logging, and laser/magnet workflows. These are not separate applications; they are domain packages assembled from the same core abstractions.
15. Operational tooling and ecosystem
The repo includes docs, notebooks, CI scripts, conda environment files, and installation helpers. That points to a research-lab workflow where reproducibility, platform setup, and documentation are important. The README also notes the project is deprecated in favor of qudi-core, so this repository should be viewed as the older all-in-one framework version.
16. Diagram takeaway
The most accurate architecture diagram should show:
config/bootstrap → core manager/kernel → runtime module graph with four main branches: GUI, logic, hardware, and remote services. Around that, add task automation, Jupyter/scripting, and analysis/saving as cross-cutting capabilities, with interfaces and interfuse modules enforcing decoupling between control logic and device drivers.
Main entry points: logic Logic layer · manager.py Manager · gui GUI layer · start.py start.py
Components 23
Bootstrap & config
Entry points and configuration assembly for launching a Qudi session.
- start.py · Top-level launcher that starts the application runtime.
start.py - config · Session and module composition files used to build a runtime.
config - Config GUI · Tooling for editing and managing configuration files.
tools/config_gui
Core framework
Kernel, module management, configuration, threads, logging, and remote execution.
- Kernel · Core runtime orchestration and module lifecycle boundary.
core/qudikernel.py - Manager · Coordinates module startup, shutdown, and runtime composition.
core/manager.py - Config core · Configuration parsing, options, and state variables for modules.
core/config.py - Module base · Common module lifecycle and metadata model for plugins.
core/module.py - Connectors · Explicit interfaces used to bind modules together.
core/connector.py - Threading · Thread and process management for isolated execution.
core/threadmanager.py - Remote · Remote module transport and polling support for multi-host setups.
core/remote.py - Logging · Framework logging and log routing infrastructure.
core/logger.py
Runtime layers
Primary application layers for GUI, logic, hardware, and interfaces.
- GUI layer · Qt desktop applications and reusable widgets for operators and experiments.
gui - Manager GUI · Administrative console for modules, threads, logs, and remote endpoints.
gui/manager - Experiment GUIs · Experiment-specific Qt front ends such as confocal, ODMR, pulsed, camera, and spectrum.
gui/confocal - Logic layer · Experiment orchestration, workflows, analysis, and stateful measurement control.
logic - Interfuse · Middleware that adapts or combines device behavior between logic and hardware.
logic/interfuse - Pulsed stack · Sequence generation, extraction, and analysis for pulsed experiments.
logic/pulsed - Hardware layer · Concrete instrument drivers and dummy implementations for laboratory devices.
hardware - Interfaces · Abstract hardware and service contracts implemented by drivers.
interface
Support & tooling
Automation, scripting, analysis, and utilities that cut across the runtime.
- Task runner · Automated workflow execution and reusable task definitions.
logic/taskrunner.py - Jupyter kernel · Embedded interactive scripting and notebook-style control integration.
logic/jupyterkernel - Analysis & save · Plotting, fitting, saving, and trace or spectrum analysis services.
logic/fit_logic.py - Qt widgets · Reusable custom widgets shared across multiple GUIs.
qtwidgets
Connections 22
- start.py → config: loads · Startup reads configuration to determine the runtime composition.
- start.py → Kernel: starts · Launcher hands control to the kernel/runtime.
- Config GUI → config: edits · Config editor modifies session and module configuration files.
- Kernel → Manager: hosts · Kernel delegates module lifecycle and composition to the manager.
- Manager → Module base: instantiates · Manager creates managed modules from configuration.
- Manager → Threading: schedules · Manager uses thread/process management for execution isolation.
- Manager → Remote: proxies · Manager can connect to modules running on remote hosts.
- Config core → Manager: configures · Configuration system feeds module setup and runtime options.
- Module base → Connectors: declares · Modules expose explicit dependencies through connectors.
- GUI layer → Manager GUI: includes · Manager GUI is one major application within the GUI layer.
- GUI layer → Experiment GUIs: includes · Domain-specific experiment windows live in the GUI layer.
- GUI layer → Qt widgets: reuses · GUIs share custom widgets and common UI helpers.
- Manager GUI → Manager: controls · Operator console drives module lifecycle and diagnostics.
- Experiment GUIs → Logic layer: drives · Experiment GUIs control logic modules rather than hardware directly.
- Logic layer → Interfaces: depends on · Logic talks to abstract services instead of concrete drivers.
- Logic layer → Interfuse: passes through · Logic can use interfuse adapters for transformed device behavior.
- Interfuse → Hardware layer: adapts · Interfuse modules sit between logic and concrete hardware drivers.
- Interfaces → Hardware layer: implemented by · Hardware drivers implement the declared interfaces.
- Pulsed stack → Logic layer: specializes · Pulsed measurement modules are a major logic subsystem.
- Task runner → Logic layer: automates · Tasks execute repeated procedures against logic modules.
- Jupyter kernel → Logic layer: scripts · Interactive kernel provides direct programmatic control of logic.
- Analysis & save → Logic layer: supports · Fitting, saving, plotting, and trace analysis support experiment workflows.