Building ICON#

Hint

auto-icon takes care of building the ICON model for you - but it is configurable.

This page is on how to configure this if the default does not suit you. By default, the model is built once (per Autosubmit experiment, but can also be shared between experiments on the same machine) and the latest version of the model code is used for this.

Building ICON with the configure scripts#

Building ICON with the configure scripts is the recommended way for all machines for which these scripts exist.

Main build options#

There are a few options determining how the model is build, collected in the ICON section of the configuration. This section is contained in conf/common/build.yml (linked as <EXPNAME>/build.yml). Additionally, the configure file (ICON.CONFIG_FILE:) to be used is specified in the platform-specific config file conf/common/platforms/<platform>.yml. The most important configure options are

Option

Description

OPTIONS

extra configure options passed on to the configure script

ENSURE_BUILD

always trigger an (incremental) build, i.e. run make
This is most useful for model development.

BRANCH

branch to be build

COMMIT

commit to check out
HEAD: (default): latest commit of the specified branch
CURRENT: uses the current status of the repo; useful for editing the repo in-place

SHA of commit or tag

SUBMODULES

use specific submodule branches or commits. The syntax is <submodule>:<branch>:<commit>, where submodule is the submodules name, e.g. art, and branch and commit are analogous to above

Some notes on further options are explained in more detail in the following.

Model version#

By default, the icon-nwp repository in the latest version (current HEAD) of the default branch master is pulled and built. This can be changed with the options GROUP, SLUG, BRANCH and COMMIT. The repository <GROUP>/<SLUG> will be pulled and the respective branch will be used. If COMMIT: HEAD is set, the latest version of the branch is used, if it points to a specific commit hash, this one will be used. If COMMIT: CURRENT is set, no pull will be performed but instead the current version in the (existing) repository will be used. If there is none, the behavior is the same as with HEAD.

Note

In the auto-icon branch public, the default repository is the public ICON repository icon/icon-model in the latest release.

Installation directory#

The %HPCROOTDIR% is the root directory for the Autosubmit experiment on the cluster and can differ from cluster to cluster. On both HoreKa and Levante this is ~/<EXPID>.

A directory referred to as %AISHAREDIR% is used by auto-icon for ICON and the Python venv. By default, it is set to %HPCROOTDIR%, but can also be set to a different directory to share the ICON installation and/or Python venv. %AISHAREDIR% can be set at the top of the build.yml configuration file or directly with the --share option of the init script.

ICON is cloned in this directory, creating a subdirectory called like the ICON model project (specifically like the option ICON.SLUG). All configure and build files are stored in a subdirectory icon-build and finally it is installed in a directory icon. This directory is also used when searching for input files. These directories can be modified with the options INSTALLDIR, BUILDDIR and REPODIR.

Model development with auto-icon#

auto-icon is designed to be a useful tool for both production simulations and for model development. To use it for model development, the recommended workflow is as follows:

  1. Create an experiment with auto-icon that reflects your experiment for testing. (Obviously this can be repeated for several different experiments.)

  2. When running the init script, use the option -b to link the file containing the build configuration.

  3. Configure the experiment to suit your purposes. Using several members might be interesting to test several similar use cases, e.g. using a new flag and also a reference case.

  4. Set the appropriate parameters for building the model, specifically the branch and the policy to build the model.

Re-building and incremental builds#

If the BUILD_ICON job is started again, when the model has already been built before, auto-icon will check if a binary exists and skip the build if so. This behavior can be changed with the option ENSURE_BUILD (rebuild even if a binary exists; no configure will be done in this case, making an incremental build). The option REBUILD_FROM_SCRATCH does what it says: all the named icon directories will be cleared in a first step, then a new build is started with git clone -> configure -> build.

Building ICON with spack#

Configure scripts do not exist for all machines. For these machines, ICON can be built with spack. To do so, in the file conf/common/build.yml set the option BUILD_TYPE: spack. The corresponding section in this file allows detailed configuration on how to build ICON. This has to be adjusted to the respective machine, some details and examples can be found in the Quick start guide.