Short reference#

Set up and run an experiment#

Note

Here, we assume Autosubmit is set up, i.e. autosubmit --version successfully returns a version number >= 4.0. Otherwise see this guide to set it up.

A detailed step-by-step guide can be found here. The Autosubmit tutorial is also a good starting point for running a first (dummy) experiment with autosubmit.

  1. Create your autosubmit experiment (Autosubmit doc):

autosubmit expid -min -repo "https://gitlab.dkrz.de/auto-icon/auto-icon.git" \
    -conf "conf/art.yml" -b main -H <HPCARC> -d <description>

  1. Initiate your experiment to clone the auto-icon repo in your project folder:
    autosubmit create <expid> -np

  2. Run the init file with appropriate parameters. For details check the help with the option -h.
    ./proj/git_project/auto-icon-init

  3. Configure your experiment by adjusting all parameters in the configuration and modifying the namelist template (symlinks in <expname>/):

    • Experiment configuration file: experiment.yml

    • Namelist file: namelist.yml or namelist.nml

    • Additional files, e.g. build.yml, wrappers.yml
      See this guide if you want to transform your runscript into an auto-icon configuration.

  4. Run your experiment in the background (Autosubmit doc):
    nohup autosubmit run <expid> &

For a short description of the most used Autosubmit commands, see the documentation page for Autosubmit commands and the official documentation.

Re-use a configuration#

If you have a configuration established for some experiment and now want to copy it for a similar experiment, there is an easy way to do so:
The project with the configuration is itself a git repository. You can enter the directory

cd /path/to/<expid>/proj/git_project

create a new branch and push it to the gitlab:

git checkout -b <new_branch_name>
git push

For keeping everything nice and clean, please enter a reasonable branch name. The recommendation is to start with your (last) name and add an experiment description or some identifier. The expid could also serve for this or be included additionally. Examples could be

baer_long-term-dust-projection
baer_a80d_long-term-dust-projection
baer_a80d

Doing so furthermore creates a persistent branch with your configuration, enhancing reproducibility an data security.
When creating a new experiment, you can just add the created branch name to the autosubmit expid command with the -b option.

Don’t forget to update your minimal configuration file in the source experiment, i.e. in /pool/experiments/<expid>/conf/minimal.yml modify

GIT:
  PROJECT_BRANCH: "<new_branch_name>"

Update to latest auto-icon version#

If you need to re-run an experiment that has a configuration stored in a separate branch and you would like to update auto-icon for the project (e.g. because there is some new feature in auto-icon that you want to use), you can merge the updated main branch into your experiment branch to pull all the changes. This will also indicate, if there are conflicting settings.

Set the status of jobs#

There are some examples and the official documentation on how to set the status of a single or multiple jobs manually.