Structure of the repository

This document is intended as a guideline through the auto-icon repository.

The repository contains a set of directories and a few additional important files.

Gitlab CI/CD

The directory .gitlab-ci contains several configuration files relevant for the CI/CD pipelines. It contains

• Configurations for the pipelines running at KIT and LMU

• Overview of available testcases for KIT pipeline

• Config for the documentation pipeline jobs

• Config (job-templates.yml) and script (generate-ci-config.sh) to create the child pipeline running auto-icon experiments

Configuration

The directory conf contains all (yaml) configuration files. It directly contains a file and corresponding directory for each ICON case and additionally a directory with config files common to all cases. Further info is already available in the User guide.

Documentation

The directory docs contains all raw files for the documentation, that is created with sphinx in a pipeline and hosted as Gitlab pages. It further contains a makefile and a source subdirectory. The latter then contains several subdirectoires for the chapters and an index.

To add something to the documentation, either modify one of the existing files or add a new one. In the latter case, also add the file to the corresponding toctree (in the respective index.rst file). Further, you should test if the documentation looks correct by building it locally. You can do so by running sphinx-build -b html docs/source/ public/ and then opening public/index.html in your browser.

See also

Detailed commands to build the documentation are outlined in the CI/CD job (.gitlab-ci/documentation.yml)

Examples

The examples directory contains a few scripts for running tests of the build_only, real-from-ideal and real-from-dwd-ana test cases and an example for the platforms_user.yml configuration. Other examples could be placed here, if necessary.

Licenses

Files with the license texts relevant for auto-icon are all placed in the LICESNSES directory.

Namelists

All namelist templates are contained here, separated by the ICON case, along with a common directory for the master namelist and other miscellaneous namelists. Some cases further have a modified master namelist in their respective directory (e.g. art and seamless).

Spack related files

Spack related files are contained in the two directories platforms and spack_repo. Those should not contain other stuff than required for the spack installation.

Templates

The templates directory contains all script templates that Autosubmit will execute. If a job shall be modified or a new job added, this is the correct place. There is a common subdirectory for jobs shared among the ICON cases and further subdirectories for the individual cases. Additionally, there is a utils subdirectory containing multiple python modules with utility functions, used accross many jobs.

Hint

When developing a new python job, always check out the utilities, if there are some existing functions, classes, etc. that can be of use for your purpose.

Tests

The tests directory contains a few files for testing beyond the CI pipelines.

Other files

Besides standard (config) files like .gitignore, README.md, REUSE.toml, ruff.toml, .pre-commit-config.yaml and .gitlab-ci.yml, there is also the init script auto-icon-init.py and a symlink to it auto-icon-init. The init script shall be modified for many changes as it is the main entrypoint for users for new experiments.