# Shortest Guide to Success This guide provides a short list of all the required commands to [set up Autosubmit and auto-icon](/Setup/Setting-up-auto-icon.md), create an experiment and [run your first experiment](/Introductory-guides/Step-by-step-guide.md). See the linked guides for more detailed information.\ The guide is specifically designed for the art case. For other cases, check out the project Readme. ## Relevant placeholders and key terms - 'local': your laptop/workstation you are currently working on; Autosubmit will run on this computer - 'remote': the HPC system, you connect to - ``: the HPC system to use. Fully tested are `LEVANTE` and `HOREKA`. - ``: experiment identifier of the form `a123`, provided by auto-icon ## Prerequisites :::{hint} These have to be run only once for all experiments. ::: ### 1. Set up Gitlab access from HPC system :::{note} If you use the public version of ICON, you can skip this step. ::: :::{Important} To be executed on the **remote** system. ::: Create a personal access token (PAT) for the DKRZ Gitlab: In the DKRZ Gitlab, select on the left sidebar -\> avatar -\> **Edit profile**. On the left sidebar, go to **Access Tokens** and click **Add new token**. Enter a name, expiry date and `read_repository` for the scope. Copy and save the created PAT. Leave the window open, you will need it again. Now, set up the netrc credentials manager on the remote HPC machine, by running the commands and substituting the placeholders `<...>`: ```bash cat > ~/.netrc << EOF machine gitlab.dkrz.de login password EOF git config --global credential.helper "netrc" ``` ### 2. Set up HPC system :::{Important} To be executed on the **remote** system. ::: :::{admonition} Levante :class: note :collapsible: closed ```bash if [ ! -f ~/.bashrc ]; then cp /etc/skel/.bashrc ~/ fi cat >> ~/.bashrc << EOF source /sw/etc/profile.levante mkdir -p /work/$(id -gn)/$USER export WORK=/work/$(id -gn) export SCRATCH=/scratch/${USER:0:1}/$USER EOF ``` ::: :::{admonition} HoreKa :class: note :collapsible: closed ```bash ws_allocate auto-icon 60 ``` ::: :::{admonition} Different HPC system :class: note :collapsible: closed After step 2 of the Experiment setup, you have to add your platform to *auto-icon*, following [these instructions](/Developers/Platforms.md#adding-a-new-platform). ::: ### 3. Set up Autosubmit :::{Important} To be executed on the **local** system. ::: :::{admonition} KIT users :class: note :collapsible: closed KIT users should connect to the [Autosubmit server](/Setup/Autosubmit-server.md) with their KIT username (e.g. `ab1234`) and password (only within KIT network or VPN): ``` ssh -X @auto-icon.scc.kit.edu ``` ::: :::{admonition} Non-KIT users :class: note :collapsible: closed Autosubmit needs to be installed: [Official Autosubmit installation instructions](https://autosubmit.readthedocs.io/en/master/installation/index.html) Install the prerequisites `bash`, `python3 >= 3.9`, `pip >= 24.0`, `sqlite3`, `git-scm > 1.8.2`, `subversion`, `dialog`, `curl`, `python-tk` (`tkinter` in centOS), `graphviz >= 2.41` and `rsync` on the 'local' system with your package manager. Install Autosubmit: ```bash pip install autosubmit autosubmit configure autosubmit install ``` ::: ### 4. Create an SSH key :::{Important} To be executed on the **local** system. ::: ```bash ssh-keygen -t ed25519 -f ~/.ssh/key_as2hpc -C "Autosubmit access to HPC" ``` Add the public key `~/.ssh/key_as2hpc.pub` to the HPC system. This depends on the HPC system (instructions for [Levante](https://docs.dkrz.de/doc/levante/access-and-environment.html#public-key-authentication) and [HoreKa](https://www.nhr.kit.edu/userdocs/horeka/sshkeys/#adding-a-new-ssh-key)). Then unlock the key (this will prompt for the key passphrase): ```bash eval $(ssh-agent -s) ssh-add ~/.ssh/key_as2hpc ``` ## Experiment setup :::{Important} To be executed on the **local** system. ::: ### 1. Add an experiment and initialize it Remember to substitute `` with your HPC system (case sensitive, usually ALL CAPS!). The option `-b` sets the _auto-icon_ branch, `public` defaults to the public ICON version, `main` to the internal ICON version. ```bash autosubmit expid -min -repo https://gitlab.dkrz.de/auto-icon/auto-icon.git -conf "conf/art.yml" \ -b public -d "Test run of LAM_OEM with auto-icon." -H Autosubmit is running with 4.0.84 The new experiment "a00j" has been registered. Generating folder structure... Experiment folder: /pool/experiments/a00j Generating config files... Experiment a00j created ``` This prints an experiment id (in the line "Experiment created" and of the form `a123`, short expid) and experiment folder. The next step is to initialize the experiment with _auto-icon_: ```bash cd autosubmit create -np ./proj/git_project/auto-icon-init -e LAM_OEM [--share [/`). ### 3. Create the workflow and run the experiment Remember to substitute `` with your experiment id! ```bash autosubmit create -np nohup autosubmit run & ``` If you get connection issues, check your connection again. Also the ssh-agent has to be set up again, each time you log off and on. You can follow the current status of your experiment with: ```bash autosubmit monitor [--txt] ``` The option `--txt` prints text output only, while leaving out the option provides you with a graphical representation. :::{hint} You can also monitor your progress via the [Autosubmit GUI](/Setup/Autosubmit-server.md#connecting-to-the-autosubmit-gui). ::: ## Success! How to go on? The recommended steps depend on whether you know the model already or not.\ **If you do so**: 1. Check out the Setup/Setting up auto-icon first (optional, but it sets up everything to also use the non-public versions of the model code). 2. Go through the [Step-by-Step guide](/Introductory-guides/Step-by-step-guide.md#4-initialize-the-auto-icon-project), especially the sections about configuring the model. You can rerun the model with an updated config to get used to it. 3. Follow the [transformation guide](/Introductory-guides/Transform-a-runscript-into-an-auto-icon-configuration.md) to create a configuration that resembles one of your runscripts. It is recommended to create a new experiment for this. **If you don't know the model**: 1. Go through the [Step-by-Step guide](/Introductory-guides/Step-by-step-guide.md). You can rerun the model with an updated config to get used to the various options you have and you can also check out different [templates](/Userguide/Templates.md). 2. Check out the Setup/Setting up auto-icon first (optional, but it sets up everything to also use the non-public versions of the model code). 3. Learn more on how the ICON model works with the [ICON guide](https://www.dwd.de/EN/ourservices/nwp_icon_tutorial/nwp_icon_tutorial_en.html).