Installation

Installation via Docker

Atomiq provides docker images that bundle everything needed to run atomiq inside the artiq ecosystem. This is probably the easiest way to get atomiq and artiq running in a few simple steps:

1. If not already done, install docker on your system and make sure that the docker daemon is running and your user has sufficient permissions to create and run docker containers.

   Tip

   Here you can find a Docker Compose file to get you started even faster. The Compose file assumes a standard ARTIQ folder structure. To understand its structure, continue reading here. This Compose file should also work on Docker Desktop for Windows. But note that we do not officially support atomiq on windows.

2. Assume you have your atomiq/ARTIQ experiment scripts and the device_db.py in the current folder, you can start the artiq_master by running:

   $ docker run --rm -it \
                -v `pwd`:/experiment \
                -p 1380:1380 -p 1381:1381 -p 1382:1382 -p 3250:3250 -p 3251:3251 -p 1067:1067 \
                registry.gitlab.com/atomiq-project/atomiq:stable \
                python -m atomiq.frontend.atomiq_master --bind \* -r /experiment --device-db /experiment/device_db.py -v --heros-connect tcp/<IP_OR_HOSTNAME>:7447
   

   The --heros-connect option allows you specify a zenoh peer that can be used to connect to the network of HEROs. If the container is run in the docker host network, UDP discovery is possible and this option is not necessary.

   Additionally, you might want to run the artiq_ctlmgr. This is easily done with the following command:

   $ docker run --rm -it \
                -p 1066:1066 -p 3249:3249 -p 1383:1383 -p 1384:1384 -p 1385:1385 -p 1386:1386 \
                registry.gitlab.com/atomiq-project/atomiq:stable \
                artiq_ctlmgr --bind \* -s 172.17.0.1 -v
   

   Make sure that you set the host correctly for the core_moninj, core_log, and core_analyzer in your device_db.py.

3. Finally, if you want to use the artiq dashboard (with modifications from atomiq), you can also use the docker image atomiq:stable-full. However, passing the GUI from the container to the host system needs a bit more complexity and depends on your precise setup.

   Tip

   You can also run the dashboard from a local python environment, without using docker, as described here

   Assuming you are running on linux with an X server, the following will start the dashboard

   $ xhost +
   $ docker run -it --rm \
                -e DISPLAY \
                -v $HOME/.Xauthority:/qao/.Xauthority:rw \
                -v /tmp/.X11-unix/:/tmp/.X11-unix \
                registry.gitlab.com/atomiq-project/atomiq:stable-full \
                python -m atomiq.frontend.atomiq_dashboard -s <ARTIQ_MASTER_IP_OR_HOSTNAME>
   

   Note that the xhost command comes with severe security implications as it essentially gives full access to your X server. Only do this in a trusted environment.

   If you are running wayland, the following command will launch the dashboard:

   $ docker run -it --rm \
                -e XDG_RUNTIME_DIR=/tmp \
                -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/tmp/$WAYLAND_DISPLAY \
                -e "WAYLAND_DISPLAY" \
                -e "QT_QPA_PLATFORM=wayland" \
                registry.gitlab.com/atomiq-project/atomiq:stable-full \
                python -m atomiq.frontend.atomiq_dashboard -s <ARTIQ_MASTER_IP_OR_HOSTNAME>
   

   Here, you will have to replace <ARTIQ_MASTER_IP_OR_HOSTNAME> with the IP or the hostname of the machine where your artiq_master is running.

In the above examples, the stable tag is used. This will run an ARTIQ-8 environment. If you need a different environment, replace the stable tag in the examples above with one of the following:

<TAG>	ARTIQ Version
old-stable	ARTIQ 7
stable	ARTIQ 8
latest	ARTIQ Beta

Note

Even if you are not interested in using atomiq, you can still use the atomiq docker image to get artiq running on your system without having to setup the nix packet manager

Using Docker Compose

A convenient way to pull up the artiq master and the artiq ctlmgr is to use docker compose. You can thus replace the above using the following compose file (you can also find this file in the repository)

services:
  artiq-master:
    container_name: "artiq-master"
    image: registry.gitlab.com/atomiq-project/atomiq:stable
    restart: unless-stopped
    volumes:
      - ".:/experiment" # this should point to the folder where the device_db and the repository is located
      # - ".:/git/atomiq" # use the local atomiq installation
      # - "/path/to/some_package:/git/custom/some_package" # include custom python code
    ports:
      - "1380:1380" #Core device (management)
      - "1381:1381" #Core device (main)
      - "1382:1382" #Core device (analyzer)
      - "3250:3250" #notify
      - "3251:3251" #control
      - "1067:1067" #broadcast

    # master command (see atomiq_master doc and manual docker section above for more options)
    command: ["python", "-m", "atomiq.frontend.atomiq_master", "--bind", "*", "-r", "/experiment/repository", "--device-db", "/experiment/device_db.py", "-v"]
  artiq-ctlmgr:
    container_name: "artiq-ctlmgr"
    image: registry.gitlab.com/atomiq-project/atomiq:stable
    restart: unless-stopped
    ports:
      - "1066:1066" # logging
      - "3249:3249" # control
      - "1383:1383" # moninj
      - "1384:1384" # moninj
      - "1385:1385" # core-analyzer
      - "1386:1386" # core-analyzer
    command: ["artiq_ctlmgr", "--bind", "*", "-s", "artiq-master", "-v"]

Important

For the communication between the artiq_master and the artiq_ctlmgr happens now within the automatically created docker network. However, this requires that you change the host for core_moninj, core_log, and core_analyzer in your device_db.py to the name of the artiq_ctlmgr docker service (in this case artiq-ctlmgr).

Additionally, also the dashboard needs to know who is meant by artiq-ctlmgr. This can be achieved by adding --add-host artiq-ctlmgr:<IP_OR_HOSTNAME_OF_ARTIQ_CTRLMGR> to the docker call starting the dashboard or if you installed the dashboard via pip, you need to add a local DNS entry. On most systems this can be for example done by adding <IP_OR_HOSTNAME_OF_ARTIQ_CTRLMGR> artiq-ctlmgr to /etc/hosts, but this can vary depending on your distribution.

Add Custom Code/Software to the ARTIQ Environment

Extending the available software in the docker container of the artiq_master is required if your experiment scripts need to make use of some custom tools. Depending one your requirements this can be solved in two ways (or both at the same time):

1. Add your own python code into the atomiq container To add your own python code (that does not depend on any external libraries) you can just create a bind mount from the local directory containing your custom code to the /git/custom directory in the container. This directory is in the python path and every python file in this folder can be imported in python.

2. Add third party packages or non-python tools to the artiq container To achieve this you can just create your own docker image that derives from the atomiq docker image. Then simply start your atomiq_master from your custom, extended image rather than from registry.gitlab.com/atomiq-project/atomiq:stable.

   The following simple example dockerfile extends the image by the scipy python library

   FROM registry.gitlab.com/atomiq-project/atomiq:stable
   RUN pip install --break-system-packages scipy
   

   Here you can learn more on how to extend docker images.

   Warning

   The docker image uses alpine linux as a base, which uses the musl c-library. If you need to use device libraries compiled for glibc, we recommend running them outside the docker container and connecting them with HEROS.

Changing the Atomiq Code in the Running system

For development purposes, it is useful to be able to modify the atomiq and the artiq code. To achieve this, clone a local copy of atomiq/artiq from gitlab/github and use docker bind mounts to overlay the paths /git/atomiq or /git/artiq with your locally cloned copy. Make sure that the versions you cloned fits your system.

Installation via Nix

Warning

We do not support this method anymore since it is virtually impossible to build the dependencies of heros in nix. Please use the docker method above whenever possible.

1. Acquire a working nix installation and enable nix flakes`. You can follow the official ARTIQ docs.

Atomiq provides a nix flake file that can either be run directly or called from an existing ARTIQ nix flake file.

Atomiq as the Main Flake

This method is recommended for new setups.

1. Install atomiq and ARTIQ by installing flake.nix from within this repository

$ cd atomiq
$ nix develop .#dev-<branch>
# some installation happening
$ which artiq_master
/nix/store/<__i_am_a_hash__>-python<version>-env/bin/artiq_master
$ python -c "import atomiq,artiq; print(dir())"
[(...), 'artiq', 'atomiq']

Here, branch is one of the following, depending on which version of ARTIQ you are using

<branch>	ARTIQ Version
old_stable	ARTIQ 7
stable	ARTIQ 8
beta	ARTIQ Beta

Note

Local development of atomiq needs the atomiq sources to be linked into the nix environment. A shell doing this can be entered by running

$ nix develop .#localdev-<branch>

Embedd in Existing Flake

1. If you have an existing flake you want to use, you can include atomiq as an input. Add the following line to the top of your flake file:

inputs.artiq = "git+https://github.com/m-labs/artiq.git?<ref>";
inputs.atomiq.url = "git+https://gitlab.com/atomiq-project/atomiq";
inputs.atomiq.inputs.artiqpkgs_<branch>.follows = "artiq";

Here, <branch> is the atomiq branch corresponding to the different artiq versions <ref> as below:

<branch>	<ref>
old_stable	?ref=release-7
stable	?ref=release-8
beta

2. And add it to the outputs:

outputs = { self, artiq, extrapkg, atomiq}:

3. Inside your derivation or shell, you can then load atomiq by adding it to the Python package list

(pkgs.python3.withPackages(ps: [
  atomiq.packages.x86_64-linux.atomiq_artiq_<branch>
]))

where <branch> is one of the branch names as in the table above.

Warning

Atomiq provides the ARTIQ package as a propagated dependency. To avoid a collision error, the base artiq package must be removed from the Python package list

A sample flake.nix file can be found in this example

Installing Client/Dashboard Only

If you want to only run the dashboard (including the atomiq modifications) or the artiq client for example on an auxiliary lab computer or your office pc, you can simply install ARTIQ and atomiq in a python virtual environment by running:

# Create a new virtual environment
python -m venv /path/to/your/venv

# Activate the virtual environment
source /path/to/your/venv/bin/activate

# Install required packages
pip install git+https://github.com/m-labs/artiq@release-8 git+https://gitlab.com/atomiq-project/atomiq git+https://github.com/m-labs/sipyco pyqt5

You can specify the ARTIQ version by adjusting the branch (here release-8). Currently, we support release-7 (old-stable), release-8 (stable), and master (beta). Note, that for the beta version, you need to install pyqt6 instead of pyqt5.

Now, the dashboard can be launched by running:

source /path/to/your/venv/bin/activate && python -m atomiq.frontend.atomiq_dashboard

The vanilla dashboard can be launched analogously:

source /path/to/your/venv/bin/activate && artiq_dashboard

In both cases, command line arguments can be specified as usual.