# ulm-iqo/qudi architecture

> Architecture diagram of the GitHub repository ulm-iqo/qudi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ulm-iqo/qudi
- Repository: https://github.com/ulm-iqo/qudi

## Overview

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`](https://github.com/ulm-iqo/qudi/tree/master/logic) (Logic layer), [`core/manager.py`](https://github.com/ulm-iqo/qudi/blob/master/core/manager.py) (Manager), [`gui`](https://github.com/ulm-iqo/qudi/tree/master/gui) (GUI layer), [`start.py`](https://github.com/ulm-iqo/qudi/blob/master/start.py) (start.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_bootstrap["Bootstrap & config"]
  node_node_start["start.py<br/>entry point<br/>[start.py]"]
  node_node_config["config"]
  node_node_config_gui["Config GUI<br/>config editor"]
end

subgraph group_group_core["Core framework"]
  node_node_kernel{{"Kernel<br/>runtime core<br/>[qudikernel.py]"}}
  node_node_manager["Manager<br/>[manager.py]"]
  node_node_config_core["Config core<br/>config system<br/>[config.py]"]
  node_node_module["Module base<br/>module model<br/>[module.py]"]
  node_node_connector["Connectors<br/>dependency wiring<br/>[connector.py]"]
  node_node_thread["Threading<br/>concurrency<br/>[threadmanager.py]"]
  node_node_remote["Remote<br/>distributed runtime<br/>[remote.py]"]
  node_node_logger["Logging<br/>[logger.py]"]
end

subgraph group_group_layers["Runtime layers"]
  node_node_gui["GUI layer<br/>qt front ends"]
  node_node_manager_gui["Manager GUI<br/>control plane ui"]
  node_node_experiment_guis["Experiment GUIs<br/>domain ui"]
  node_node_logic["Logic layer<br/>experiment logic"]
  node_node_interfuse["Interfuse<br/>adapter layer"]
  node_node_pulsed["Pulsed stack<br/>measurement pipeline"]
  node_node_hardware["Hardware layer<br/>device drivers"]
  node_node_interfaces["Interfaces<br/>contracts"]
end

subgraph group_group_support["Support & tooling"]
  node_node_tasks["Task runner<br/>automation<br/>[taskrunner.py]"]
  node_node_jupyter["Jupyter kernel<br/>interactive scripting"]
  node_node_analysis["Analysis & save<br/>data services<br/>[fit_logic.py]"]
  node_node_qtwidgets["Qt widgets<br/>ui widgets"]
end

node_node_start -->|"loads"| node_node_config
node_node_start -->|"starts"| node_node_kernel
node_node_config_gui -->|"edits"| node_node_config
node_node_kernel -->|"hosts"| node_node_manager
node_node_manager -->|"instantiates"| node_node_module
node_node_manager -->|"schedules"| node_node_thread
node_node_manager -->|"proxies"| node_node_remote
node_node_config_core -->|"configures"| node_node_manager
node_node_module -->|"declares"| node_node_connector
node_node_gui -->|"includes"| node_node_manager_gui
node_node_gui -->|"includes"| node_node_experiment_guis
node_node_gui -->|"reuses"| node_node_qtwidgets
node_node_manager_gui -->|"controls"| node_node_manager
node_node_experiment_guis -->|"drives"| node_node_logic
node_node_logic -->|"depends on"| node_node_interfaces
node_node_logic -->|"passes through"| node_node_interfuse
node_node_interfuse -->|"adapts"| node_node_hardware
node_node_interfaces -->|"implemented by"| node_node_hardware
node_node_pulsed -->|"specializes"| node_node_logic
node_node_tasks -->|"automates"| node_node_logic
node_node_jupyter -->|"scripts"| node_node_logic
node_node_analysis -->|"supports"| node_node_logic

click node_node_start "https://github.com/ulm-iqo/qudi/blob/master/start.py"
click node_node_config "https://github.com/ulm-iqo/qudi/tree/master/config"
click node_node_config_gui "https://github.com/ulm-iqo/qudi/tree/master/tools/config_gui"
click node_node_kernel "https://github.com/ulm-iqo/qudi/blob/master/core/qudikernel.py"
click node_node_manager "https://github.com/ulm-iqo/qudi/blob/master/core/manager.py"
click node_node_config_core "https://github.com/ulm-iqo/qudi/blob/master/core/config.py"
click node_node_module "https://github.com/ulm-iqo/qudi/blob/master/core/module.py"
click node_node_connector "https://github.com/ulm-iqo/qudi/blob/master/core/connector.py"
click node_node_thread "https://github.com/ulm-iqo/qudi/blob/master/core/threadmanager.py"
click node_node_remote "https://github.com/ulm-iqo/qudi/blob/master/core/remote.py"
click node_node_logger "https://github.com/ulm-iqo/qudi/blob/master/core/logger.py"
click node_node_gui "https://github.com/ulm-iqo/qudi/tree/master/gui"
click node_node_manager_gui "https://github.com/ulm-iqo/qudi/tree/master/gui/manager"
click node_node_experiment_guis "https://github.com/ulm-iqo/qudi/tree/master/gui/confocal"
click node_node_logic "https://github.com/ulm-iqo/qudi/tree/master/logic"
click node_node_interfuse "https://github.com/ulm-iqo/qudi/tree/master/logic/interfuse"
click node_node_pulsed "https://github.com/ulm-iqo/qudi/tree/master/logic/pulsed"
click node_node_hardware "https://github.com/ulm-iqo/qudi/tree/master/hardware"
click node_node_interfaces "https://github.com/ulm-iqo/qudi/tree/master/interface"
click node_node_tasks "https://github.com/ulm-iqo/qudi/blob/master/logic/taskrunner.py"
click node_node_jupyter "https://github.com/ulm-iqo/qudi/tree/master/logic/jupyterkernel"
click node_node_analysis "https://github.com/ulm-iqo/qudi/blob/master/logic/fit_logic.py"
click node_node_qtwidgets "https://github.com/ulm-iqo/qudi/tree/master/qtwidgets"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_start,node_node_config,node_node_config_gui toneBlue
class node_node_kernel,node_node_manager,node_node_config_core,node_node_module,node_node_connector,node_node_thread,node_node_remote,node_node_logger toneAmber
class node_node_gui,node_node_manager_gui,node_node_experiment_guis,node_node_logic,node_node_interfuse,node_node_pulsed,node_node_hardware,node_node_interfaces toneMint
class node_node_tasks,node_node_jupyter,node_node_analysis,node_node_qtwidgets toneRose
```

## Components

### Bootstrap & config

Entry points and configuration assembly for launching a Qudi session.

- [start.py](https://github.com/ulm-iqo/qudi/blob/master/start.py): entry point · Top-level launcher that starts the application runtime. · `start.py`
- [config](https://github.com/ulm-iqo/qudi/tree/master/config): configs · Session and module composition files used to build a runtime. · `config`
- [Config GUI](https://github.com/ulm-iqo/qudi/tree/master/tools/config_gui): config editor · Tooling for editing and managing configuration files. · `tools/config_gui`

### Core framework

Kernel, module management, configuration, threads, logging, and remote execution.

- [Kernel](https://github.com/ulm-iqo/qudi/blob/master/core/qudikernel.py): runtime core · Core runtime orchestration and module lifecycle boundary. · `core/qudikernel.py`
- [Manager](https://github.com/ulm-iqo/qudi/blob/master/core/manager.py): module manager · Coordinates module startup, shutdown, and runtime composition. · `core/manager.py`
- [Config core](https://github.com/ulm-iqo/qudi/blob/master/core/config.py): config system · Configuration parsing, options, and state variables for modules. · `core/config.py`
- [Module base](https://github.com/ulm-iqo/qudi/blob/master/core/module.py): module model · Common module lifecycle and metadata model for plugins. · `core/module.py`
- [Connectors](https://github.com/ulm-iqo/qudi/blob/master/core/connector.py): dependency wiring · Explicit interfaces used to bind modules together. · `core/connector.py`
- [Threading](https://github.com/ulm-iqo/qudi/blob/master/core/threadmanager.py): concurrency · Thread and process management for isolated execution. · `core/threadmanager.py`
- [Remote](https://github.com/ulm-iqo/qudi/blob/master/core/remote.py): distributed runtime · Remote module transport and polling support for multi-host setups. · `core/remote.py`
- [Logging](https://github.com/ulm-iqo/qudi/blob/master/core/logger.py): logging · Framework logging and log routing infrastructure. · `core/logger.py`

### Runtime layers

Primary application layers for GUI, logic, hardware, and interfaces.

- [GUI layer](https://github.com/ulm-iqo/qudi/tree/master/gui): qt front ends · Qt desktop applications and reusable widgets for operators and experiments. · `gui`
- [Manager GUI](https://github.com/ulm-iqo/qudi/tree/master/gui/manager): control plane ui · Administrative console for modules, threads, logs, and remote endpoints. · `gui/manager`
- [Experiment GUIs](https://github.com/ulm-iqo/qudi/tree/master/gui/confocal): domain ui · Experiment-specific Qt front ends such as confocal, ODMR, pulsed, camera, and spectrum. · `gui/confocal`
- [Logic layer](https://github.com/ulm-iqo/qudi/tree/master/logic): experiment logic · Experiment orchestration, workflows, analysis, and stateful measurement control. · `logic`
- [Interfuse](https://github.com/ulm-iqo/qudi/tree/master/logic/interfuse): adapter layer · Middleware that adapts or combines device behavior between logic and hardware. · `logic/interfuse`
- [Pulsed stack](https://github.com/ulm-iqo/qudi/tree/master/logic/pulsed): measurement pipeline · Sequence generation, extraction, and analysis for pulsed experiments. · `logic/pulsed`
- [Hardware layer](https://github.com/ulm-iqo/qudi/tree/master/hardware): device drivers · Concrete instrument drivers and dummy implementations for laboratory devices. · `hardware`
- [Interfaces](https://github.com/ulm-iqo/qudi/tree/master/interface): contracts · Abstract hardware and service contracts implemented by drivers. · `interface`

### Support & tooling

Automation, scripting, analysis, and utilities that cut across the runtime.

- [Task runner](https://github.com/ulm-iqo/qudi/blob/master/logic/taskrunner.py): automation · Automated workflow execution and reusable task definitions. · `logic/taskrunner.py`
- [Jupyter kernel](https://github.com/ulm-iqo/qudi/tree/master/logic/jupyterkernel): interactive scripting · Embedded interactive scripting and notebook-style control integration. · `logic/jupyterkernel`
- [Analysis & save](https://github.com/ulm-iqo/qudi/blob/master/logic/fit_logic.py): data services · Plotting, fitting, saving, and trace or spectrum analysis services. · `logic/fit_logic.py`
- [Qt widgets](https://github.com/ulm-iqo/qudi/tree/master/qtwidgets): ui widgets · Reusable custom widgets shared across multiple GUIs. · `qtwidgets`

## Connections

- 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.
