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:

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.

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 \
             artiq_master --bind \* -r /experiment --device-db /experiment/device_db.py -v

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.

Finally, if you want to use the artiq dashboard (with modifications from atomiq), you can also use the docker image. 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 \
             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 \
             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

services:
  artiq-master:
    container_name: "artiq-master"
    image: registry.gitlab.com/atomiq-project/atomiq:stable
    restart: unless-stopped
    volumes:
      - "./device_db.py:/device_db.py"
      - "./repository:/repository"
    ports:
      - "3250:3250" #notify
      - "3251:3251" #control
      - "1067:1067" #broadcast
    command: ["artiq_master", "--bind", "*", "-r", "/repository", "--device-db", "/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
    command: ["artiq_ctlmgr", "--bind", "*", "-s", "artiq-master", "-v"]

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.

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):

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

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¶

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.

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>

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

Embedd in Existing Flake¶

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

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

And add it to the outputs:

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

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.