Getting Started

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 open-source icon-model repository.

Note for the beginners

This guide assumes some knowledge on git and the linux operating system. If that is not the case, check this tutorial for beginners, that will guide you to run your first ICON simulation in a matter of minutes. Alternatively, for a more detailed tutorial with a focus on NWP physics, check the resources of the DWD Academic ICON Course – July 2025 (Talks and Notebooks).

FAQ

Check our Frequently Answered Questions section in case you have troubles while handling ICON, or you are simply curious.

Discuss with the ICON Community on exchange.icon-model.org

Obtaining the Code

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 platform- or machine-specific configure wrappers for the configure script. These wrappers provide all necessary compiler and linker flags along with the recommended configuration options for a particular build (note that the config script can also be called directly by specifying the flags as command-line arguments, but the list of arguments required for successful configuration can be lengthy and complex). 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, Building, and Supported Environments please refer to the respective section.

Setting Input Data

Here info on all necessary input data.

Running ICON

To run ICON, you need to create a runscript that sets the required environment variables, sets the experiment configuration, and calls the executable. The preferred way to do that is to use the mkexp utility (please install six and jinja2 in your python environment). For in-source builds, copy the desired example configuration from the <src-dir>/run/examples to the run folder:

cd <src-dir>/run
cp examples/bubble.config .

If running in HPC resources, add the slurm account number in the bubble.config file by introducing the ACCOUNT = <slurm-account> line. Make sure this line is above any [...] section. Then, call mkexp:

../utils/mkexp/mkexp bubble.config

To execute the experiment, navigate to the Script directory generated by the command above and submit bubble.run_start:

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

The run log will be directed to bubble.run.log and the output to Work directory (generated by the mkexp command above).

Running ICON

For detailed information please refer to section Running ICON.

Supported configurations

ICON partners provide a number of supported scientific configurations that already provide everything necessary for running ICON experiments.