Getting started

git clone https://github.com/quatm-team/quatm-core.git
cd quatm-core
python -m venv python_venv
source python_venv/bin/activate        # Windows: python_venv\Scripts\activate
pip install -e .
pip install -e ".[hardware]"           # optional hardware dependencies

from quatm.experiment import Experiment

class HelloQuatm(Experiment):
    def build(self):
        print("Quatm ready")

    def run(self):
        print("Hello, Quatm!")

HelloQuatm().run()

python -m quatm.GUI.entries.start_quatm --root <project>

1 - Basic configuration

Project root

Quatm resolves the project root in this order:

1. QUATM_PROJECT_ROOT (set by the project launcher);
2. the nearest parent directory containing configuration/configfile/configfile.json or a .quatm_project marker;
3. the legacy repository layout.

A project keeps its own configuration and data; the framework package is installed separately. This lets several laboratories share one installation while keeping their files independent.

Directory layout

<project>/
├── configuration/
│   ├── configfile/configfile.json   # services and GUI entries to launch
│   ├── device_db.py                 # instruments used by experiments
│   └── properties/                  # persisted property tree
├── experiments/                     # experiment scripts
├── Data/                            # HDF5 acquisition files
├── drivers/                         # optional project-local drivers
├── monitor/                         # optional monitors
└── analysis/                        # optional analysis scripts

Device database

configuration/device_db.py maps logical names to drivers. An experiment refers to these names, never to vendor APIs directly.

DEVICE_DB = {
    'mot_coils': {
        'type': 'attr',
        'module': 'quatm.drivers.xxx',
        'class': 'XxxDriver',
        'address': 'tcp://192.168.1.50:5025',
        'arguments': {'channel': 1},
    },
    'probe_laser': {
        'type': 'local',
        'module': 'drivers.probe_laser',
        'class': 'ProbeLaser',
        'arguments': {'port': 'COM4'},
    },
}

The three modes are:

A project-local module (for example drivers.probe_laser) takes precedence over a bundled driver with the same suffix. local_only / analysis_local_only can enforce that no bundled fallback is used.

Services

configuration/configfile/configfile.json declares the services and GUI programs for the project. The Operations Console reads this file, starts selected entries and tracks their state. Service processes are ordinary operating-system processes, so a crash is isolated and can be restarted independently.

Verify the setup

from quatm.servers.configreader import PROJECT_ROOT
print(PROJECT_ROOT)

Then open the Device Manager, select a device and use Test connection with simulation enabled. No hardware is required for this step.

2 - Your first experiment

A minimal experiment

Put this file under the project’s experiments/ directory. Quatm discovers experiment classes from that tree.

from quatm.experiment import Experiment


class FirstExperiment(Experiment):
    def build(self):
        self.duration = self.NumberValue(100.0, unit='ms')
        self.enabled = self.BoolValue(True)
        self.phase = self.StringCombo('A', options=['A', 'B'])

    def run(self):
        if not self.enabled:
            return
        self.delay(self.duration)

build() is called once per experiment instance and declares the parameter panel. run() is called once per repetition.

Parameter types

Run it

1. Open the Experiment Browser.
2. Select FirstExperiment.py.
3. Set duration and enabled in the parameter panel.
4. Press Run.
5. Watch the task in the Task Monitor; the Browser shows progress and results.

In simulation mode the run completes without hardware. Data, parameters and task metadata are archived to HDF5 under Data/.

Scans and repetitions

Use the browser’s scan controls to vary a parameter, set the number of repetitions, or submit a multi-dimensional scan. The framework expands the scan into individual runs and records the scan definition alongside the data.

Where to go next

• Experiment editing for the full lifecycle and timing API.
• Data and analysis for HDF5 layout and fitting.
• Examples for realistic MOT and ion-trap sequences.

3 - Known issues

Windows

FPGA controller driver

The vendor-provided SDK must be installed, and the FPGA requires the timetable to be defined and flashed according to the actual requirements. No real hardware is needed in simulation mode.

Linux

Qt GUI library dependencies

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

Camera permissions

Andor / BlackFly cameras require udev rules.

Windows Subsystem for Linux (WSL)

WSL users should make sure to run from a Linux filesystem mount; operating on the Windows filesystem causes unexpected errors.

Web remote control platform (quatm.web)

Upgrading from an older version leaves the quatm.web subpackage missing

When upgrading from an older version, the Web Hub reports an error at startup saying the subpackage is missing: simply re-run pip install -e . (quatm.web is installed together with the quatm core).

Operating the same process from the desktop GUI at the same time

The desktop process manager and the web process page manage the same set of services/GUIs. Before starting an entry, either entry point first terminates the instance managed by the other entry point, so that nothing is launched twice; if a process is restarted unexpectedly, check whether a start action was performed on the other side.

4 - Frequently asked questions

The questions below are the ones we hear most often — from a first installation to the quiet details that matter once an experiment is running.

Installation and platforms

Which operating systems are supported? Quatm uses Qt 6/PySide6; supported platforms follow the Qt 6.11 matrix: Windows 10 (1809+) and Windows 11 on x86-64, macOS 13 or newer, and Linux x86-64 (Ubuntu 22.04/24.04, Debian 12, or equivalent). ARM64 desktop support is limited; see the Qt 6.11 supported-platform matrix. Python 3.9 or newer is required.

What are the minimum requirements? A machine with at least 8 GB of memory and 4 CPU cores is recommended for the full GUI and data services. Real-time control requires an FPGA-class controller.

Devices and drivers

Do I need specific hardware? No single vendor is required, but a real-time controller with TTL/DAC outputs is needed for timed sequences. Instruments using standard protocols can be integrated by selecting or writing a driver; the effort depends on the protocol and vendor SDK.

How do I integrate a custom device? Write a driver class and register it in device_db.py as type: local (or map channels with attr / generic_attr). See Device drivers.

Which cameras are supported? Andor, FLIR/BlackFly and other scientific cameras are covered by the driver catalogue; custom cameras can be added through project-local drivers.

Data

What format is used? Experiment data is archived as HDF5, with optional streaming/export services.

How large are the files? A typical absorption-imaging run is on the order of 10–50 MB, depending on image count and resolution. Plan disk capacity and retention for long campaigns.

Updating

How do I upgrade? Update the Python environment and reinstall the package, or pull the repository and rerun the bootstrap. Check the changelog for incompatible changes.

Will my experiment scripts break? Quatm follows semantic versioning for public interfaces; major changes are documented with migration notes. Verify in simulation before a campaign.

Related

• Documentation home
• Contact and support