Building Reproducible Experiments
---------------------------------

Atomiq and in general the `atomiq one ecosystem <https://doc.atomiq.one>`_ focuses on building reproducible
experiments by gathering and saving as much data and configuration as possible together with the measured data.

.. _atomiq_git_integration:

Experiment Git Integration
##########################

The ``--git-autocommit`` flag enables automatic version control for experiments. When enabled, any changes to experiment files are automatically committed to the Git repository before execution. This ensures that:

- Experiments always run from a specific, reproducible commit hash
- Changes to experiment code are automatically tracked without manual intervention
- The experiment database automatically picks up the latest committed version


Note, that new experiment files must be added manually to the repository for the experiment db to pick them up.
The feature builds on the `ARTIQ git integration <https://m-labs.hk/artiq/manual/getting_started_mgmt.html#setting-up-git-integration>`_ and works mostly the same but adds the possibility to auto commit experiments
before they run.

To use this feature:

1. Enable Git integration with the ``--git`` flag. To get this running, follow the documentation in `the ARTIQ manual <https://m-labs.hk/artiq/manual/getting_started_mgmt.html#setting-up-git-integration>`_
2. Add the ``--git-autocommit`` flag to automatically commit changes
3. The system will create commits with messages like "Updated experiment <class_name>" using the master instance name as author

.. code-block:: bash

   atomiq_master --git --git-autocommit [other options]

.. note::

   The ``--git-autocommit`` flag requires ``--git`` to be set. If you enable autocommit without Git integration, the master will exit with an error.

.. warning::

   The repository needs to belong to the user the atomiq master is running as. If you are using docker, this is typically root.
   If you are using rootless podman, using the same user as the user you use to write experiments, you don't need to do anything.

   To change ownership, run

   .. code-block:: bash

      chown -R root repository/

   To be still able to write to the files, give your user group write access.

   .. code-block:: bash

      chmod -R g+w repository/

   With the new ownership, git will complain about it when run from the host machine. Run the command it shows you in the error message to mark your repository as a safe directory.

.. note::

   If you see the error ``reference 'refs/heads/master' not found`` when starting the ``atomiq_master``, you need to commit at least one experiment to the repository manually.

   .. code-block:: bash

      cd repository && git add test.py && git commit


You can access the current revission hash

- in an experiment by ``self.scheduler.expid["repo_rev"]``
- from the :ref:`experiment HERO <heros in atomiq>` via the ``git_rev`` attribute

The autocommit process is controlled by the ``repo_rev`` key in the ``expid`` dict that is submitted. Only if ``expid[repo_rev] == None`` a new commit is created and used to run the experiment. This implies two things:

- You can pass a specific commit hash via the ``repo_rev`` key (can be done via the appropriate field in the dashboard) to use the experiment from
- If the ``repo_rev`` key is not in the dict at all, atomiq does not commit changes and ARTIQ uses its currently known hash (typically the git hash that was checked out when the experiment db was loaded)