Installation & Usage
====================

Installation (via nix)
----------------------
#. Acquire a working `nix` installation and enable `nix flakes``. You can follow the official
   `ARTIQ docs <https://m-labs.hk/artiq/manual/installing.html#installing-via-nix-linux>`_.

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

 .. code-block:: bash

    $ 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

 .. list-table::
    :header-rows: 1

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

    .. code-block:: bash

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

  .. code-block:: nix


      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:

  .. list-table::
    :header-rows: 1

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

2. And add it to the outputs:

  .. code-block:: nix

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

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

  .. code-block:: nix

    (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 :ref:`this example <Nix example>`





Usage
-----

#. Make atomiq available to the python interpreter in your `nix` environment (see `Installation (via nix)`_).
#. 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`:

    .. code-block:: python

       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.
#. Inherit your Experiments from :class:`~atomiq.atomiq.AtomiqExperiment` like in the following example

   .. code-block:: python

    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 :ref:`here <Aom example>`

.. 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 :ref:`init example <examples-init>` for more information.