Building Reproducible Experiments

Atomiq and in general the atomiq one ecosystem focuses on building reproducible experiments by gathering and saving as much data and configuration as possible together with the measured data.

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

  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

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

chown -R root repository/

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

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.

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 experiment HERO 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)