Installation & Usage

Installation (via nix)

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

Usage

1. Make atomiq available to the python interpreter in your nix environment (see Installation (via nix)).

2. Include your components database as a dictionary into the ARTIQ devicedb under the components key. You can either directly write your components into your device_db.py or you load it from a different file by adding the following code to your device_db.py:

   from components import components
   device_db["components"] = components
   

   Now the file components.py should reside in the same directory as your device_db.py and define a dict components that contains the definition of the components.

3. Inherit your Experiments from AtomiqExperiment like in the following example

   from artiq.experiment import kernel
   from atomiq import AtomiqExperiment
   
   class ATQExperiment(AtomiqExperiment):
   
     components = ["aom_cooler"]
   
     @kernel
     def step(self, point):
         self.log.info("Testmessage from the core")
   
         self.aom_cooler.detune(3e6)
         self.aom_cooler.set_amplitude(0.3)
   
         for _ in range(10):
             self.aom_cooler.pulse(3*ms)
             delay(4*ms)
   

This example in more elaborate form can be found here

Note

Atomiq does not handle the initialization procedure required by some of the Sinara hardware after power cycling to ensure a fast cycle time. Please refer to our init example for more information.