Quick Start#

Obtaining the Code#

ICON is simultaneously developed in several repositories. There is the primary repository icon and several secondary ones: icon-nwp, icon-mpim, etc. If unsure, use the primary repository. If you don’t have access to any of those, choose the public icon-model repository.

Clone the ICON repository of choice and its submodules using the following command:

git clone --recursive https://gitlab.dkrz.de/icon/icon-model.git

Users with a DKRZ GitLab account are recommended to clone the repository via the SSH protocol:

git clone --recursive git@gitlab.dkrz.de:icon/icon-model.git

Configuring and Building#

The configuration step is typically executed by running the configure script with command-line arguments. These arguments specify the locations of libraries and tools needed for building. Note that the list of arguments required for successful configuration can be lengthy and complex, so it’s recommended to use a platform- or machine-specific configure wrapper, which automatically sets the necessary compiler and linker flags along with the recommended configuration options. You can find the configure wrappers in the respective subdirectories of the config directory.

For example, to build ICON on Levante@DKRZ with OpenMP enabled using the Intel compiler, run the following command:

./config/dkrz/levante.intel --enable-openmp

Alternatively, you can create a directory and perform an out-of-source build:

mkdir build && cd build
/path/to/icon/config/dkrz/levante.intel --enable-openmp

Using an out-of-source build, you can build ICON in multiple configurations using the same copy of the source code.

The building step is done by running make command with an optional argument specifying the number of jobs to run simultaneously. Usually, 8 is a good choice. For example:

make -j8

The result of the building — the executable file of ICON — is saved to the bin subdirectory of the build directory.

ICON on your system

If you want to build and run ICON on your personal computer, consider using the generic configure wrapper. For detailed information on Configuration and Building please refer to the respective section.

Running ICON#

To run ICON, you need to create a runscript that sets the required environment variables and calls the executable. One way to get started with running ICON is to use the mkexp utility to generate a runscript and experimental configuration for the “bubble” test.

../utils/mkexp/mkexp bubble.config

The command above generates a runscript called ../experiments/bubble/scripts/bubble.run_start. To execute the experiment, navigate to the directory containing the script and submit it for the execution:

cd ../experiments/bubble/scripts
sbatch bubble.run_start

The output will be directed to the Work directory identified after the execution of mkexp.

Running ICON

For detailed information please refer to section Running ICON.

FAQ#

  1. I run the configure script without any arguments and it fails. What should I do?

    First, we recommend checking whether there is a suitable Configure wrappers in the config directory that you could use instead of running the configure script directly. If that is not the case, you need at least to specify the LIBS variable telling the configure script which libraries to link the executables to. The content of the list depends on the configure options you specify (see Table 1), for example:

    ./configure --disable-mpi --disable-coupling LIBS='-lnetcdff -lnetcdf -llapack -lblas'

    If the libraries reside in nonstandard directories, you might also need to specify the FCFLAGS, CPPFLAGS, and LDFLAGS variables to tell the script which directories need to be searched for header and library files (see section Configuration) for more details).

  2. How can I reproduce the configuration of the model used in a Buildbot test?

    Scripts run by Buildbot for configuration and building of the model reside in the config/buildbot directory. You can run them manually on the corresponding machine.

  3. I get an error message from the configure script starting with “configure: error: unable to find sources of…”. What does this mean?

    Most probably, you forgot to initialize and/or update git submodules. You can do that by switching to the source root directory of ICON and running the following command:

    git submodule update --init

  4. I have problems configuring/building ICON. What is the most efficient way to ask for help?

    Whoever you ask for help will appreciate receiving the log files. You can generate a tarball with the log files by running the following commands from the root build directory of ICON:

    make V=1 2>&1 | tee make.log
tar --transform 's:^:build-report/:' -czf build-report.tar.gz $(find . -name 'config.log' -o -name 'CMakeCache.txt') make.log

    The result of the commands above will be file build-report.tar.gz, which should be attached to the very first email describing your problem. Please, do not forget to specify the repository and the branch that you experience the issue with, preferably in the form of a URL (e.g. https://gitlab.dkrz.de/icon/icon-model/-/tree/release-2025.04-public).

On this page