Skip to content

Latest commit

 

History

History

generic

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 
gcc
gcc
 
 

README.md

Introduction

This directory contains generic configure wrappers for ICON. You can use them either inside the docker containers or natively on your system.

Docker containers

The easiest way to build and run ICON on your personal machine is to use Docker images from the iconmodel repository on Docker Hub.

The recommended workflow is to build and run ICON inside the container and manage and edit the source code in a separate terminal, using the tools available on your machine. This scenario implies that the directory with ICON source code is located on the host machine and mounted to the container. You will also need to mount a so-called pool directory containing ICON input files, e.g. grid files. The contents and the layout of the directory depends on the experiment you want to run and are not covered in this document.

Run the container in the interactive mode as follows:

docker run -it -v /path/to/icon-src:/home/icon/icon -v /path/to/pool:/home/icon/pool iconmodel/icon-dev

where /path/to/icon-src and /path/to/pool are paths to ICON source and pool directories on your machine, and /home/icon/icon and /home/icon/pool are respective mount points of the directories inside the container.

As a result of the previous command you will get an interactive command prompt of the container. You can now configure, build and run ICON using the following commands as a reference:

icon@dev-gcc$ cd ./icon
icon@dev-gcc$ ./config/generic/gcc
icon@dev-gcc$ make -j4
icon@dev-gcc$ ./make_runscripts atm_tracer_Hadley
icon@dev-gcc$ cd ./run
icon@dev-gcc$ ./exp.atm_tracer_Hadley.run

NOTE: To be able to run ICON inside the container, you might need to increase the amount of RAM available to Docker (Preferences->Resources->Memory).

Native building

The generic wrappers in this directory are written with the assumption that the required software libraries are installed to the same prefix. The prefix defaults to /opt/local on macOS and to /usr on other platforms. The default values can be overridden by setting the environment variable ICON_SW_PREFIX:

export ICON_SW_PREFIX='/path/to/icon/prerequisites'

Prerequisites

This section provides a list of software required for building and running ICON. The users can build and install (to the same prefix) the listed packages manually or use a package managers available for their platform. The basic instructions on how to do it on several popular platforms are provided in section Tested platforms.

Building tools

Software libraries

  • MPICH, OpenMPI or any other MPI implementation that provides compiler wrappers mpicc and mpif90 for C and Fortran, respectively, as well as the job launcher mpiexec.

    NOTE: The job launcher of OpenMPI fails to run more MPI processes than the number of real processor cores available on the machine by default. That might lead to failures when configuring or running ICON. The solution to the problem is to run the configure wrapper with an additional argument MPI_LAUNCH='mpiexec --oversubscribe' (alternatively, you can set the OMPI_MCA_rmaps_base_oversubscribe environment variable to 1).

    NOTE: It is not rare that the latest versions (or the default versions available via the package managers) of OpenMPI and MPICH are affected with bugs that make the libraries unusable for ICON. A good way to make sure that the MPI library does not have significant defects is to switch to the root source directory of ICON and run the following commands (do not forget the aforementioned extra arguments for the configure wrapper if you are using OpenMPI):

    ./config/generic/gcc --enable-yaxt --enable-cdi-pio --enable-coupling
make -j4 check-bundled TESTS= XFAIL_TESTS=  # this step speeds up the next one but can be skipped
make check-bundled  # avoid running this step in parallel on a weak machine, i.e. omit the -j argument
test $? -eq 0 && echo "Everything is fine" || echo "Something went wrong"

    After that, you can clean up the source directory and reconfigure ICON the way you need.

  • HDF5 with high-level interface (for NetCDF-С), thread-safety (for CDO), and szlib filtering support (only C interface required, not a direct dependency of ICON)

  • NetCDF-C with NetCDF-4 support

  • NetCDF-Fortran

  • BLAS

  • LAPACK

  • ecCodes with JPEG2000 and AEC support (only C interface required)

  • libfyaml

  • Libxml2

See section ICON dependencies for more details.

Optional tools

Tested platforms and tools

This section provides basic instructions on how to install most commonly required subset of ICON dependencies on different operating systems using relevant package managers.

macOS with MacPorts

Tested on macOS Ventura 13.5.1.

Most of the required software packages are either already available on the system or installed together with Xcode and Command Line Tools for Xcode, which are prerequisites for MacPorts. The rest of the required software can be installed by running the following commands:

# Install building tools and ICON dependencies:
sudo port -N install       \
  cmake                    \
  gcc12                    \
  mpich-gcc12              \
  hdf5 +hl+threadsafe+szip \
  netcdf                   \
  netcdf-fortran +gcc12    \
  eccodes                  \
  libxml2

# Install libfyaml, which is currently not available via MacPorts:
curl -OL https://github.com/pantoniou/libfyaml/releases/download/v0.8/libfyaml-0.8.tar.gz
tar xvf libfyaml-0.8.tar.gz
cd libfyaml-0.8
./configure --prefix=/opt/local
make -j
sudo make install

# The command above can be reverted as follows:
# curl -OL https://github.com/pantoniou/libfyaml/releases/download/v0.8/libfyaml-0.8.tar.gz
# tar xvf libfyaml-0.8.tar.gz
# cd libfyaml-0.8
# ./configure --prefix=/opt/local
# sudo make uninstall

# Select the compiler and MPI compiler wrappers:
sudo port select --set gcc mp-gcc12
sudo port select --set mpi mpich-gcc12-fortran
hash -r

# Install optional tools:
sudo port -N install cdo +netcdf

NOTE: You can try replacing mpich with openmpi in the commands above if the version of MPICH that is currently available via MacPorts fails the tests described in the Software libraries section. Note, however, that OpenMPI is known to have problems with running on macOS. Although the list of known issues is very dated, some of them are still relevant. In particular, this one (also see here). The solution here is to run the configure wrapper with one more argument BUILD_ENV="export TMPDIR='/tmp';" and make sure that the TMPDIR environment variable is set to /tmp before running ICON.

Ubuntu with Apt

Tested on Ubuntu Jammy Jellyfish 22.04.3 LTS.

# Install building tools and ICON dependencies:
sudo apt install -y \
  build-essential   \
  cmake             \
  python3           \
  gcc               \
  gfortran          \
  libopenmpi-dev    \
  libhdf5-dev       \
  libnetcdf-dev     \
  libnetcdff-dev    \
  libeccodes-dev    \
  libblas-dev       \
  liblapack-dev     \
  libfyaml-dev      \
  libxml2-dev

# Select MPI libraries and compiler wrappers
sudo update-alternatives --set mpi /usr/bin/mpicc.openmpi
sudo update-alternatives --set mpirun /usr/bin/mpirun.openmpi

# If the two non-interactive commands above do not work,
# try the interactive analogues:
# sudo update-alternatives --config mpi
# sudo update-alternatives --config mpirun

# Install optional tools:
sudo apt install -y cdo

Arch Linux with Pacman

Tested on Arch Linux 2023.07.23.

# Install building tools and ICON dependencies:
sudo pacman -S --noconfirm \
  base-devel               \
  git                      \
  cmake                    \
  python                   \
  gcc-fortran              \
  openmpi                  \
  hdf5                     \
  netcdf                   \
  netcdf-fortran           \
  blas                     \
  lapack                   \
  libxml2

# Install libfyaml from the Arch User Repository:
( git clone https://aur.archlinux.org/libfyaml.git && cd libfyaml && makepkg -csi --noconfirm )
# Install ecCodes from the Arch User Repository:
( git clone https://aur.archlinux.org/eccodes.git && cd eccodes && makepkg -csi --noconfirm )

# Install optional tools:
sudo pacman -S --noconfirm rsync
# Install CDO and its extra dependencies from the Arch User Repository:
( git clone https://aur.archlinux.org/udunits.git && cd udunits && makepkg -csi --noconfirm )
( git clone https://aur.archlinux.org/magics++.git && cd magics++ && makepkg -csi --noconfirm )
( git clone https://aur.archlinux.org/cdo.git && cd cdo && makepkg -csi --noconfirm )

macOS/Linux with Spack

Tested on Ubuntu Desktop Jammy Jellyfish 22.04.3 LTS.

NOTE: Spack has its own list of prerequisites. The default Ubuntu Desktop installation seems to be missing only few of them:

sudo apt install -y build-essential git gfortran
# Install Spack:
git clone https://github.com/spack/spack.git
. ./spack/share/spack/setup-env.sh

# Find compilers and building tools that are already installed on the system:
spack compiler find
spack external find

# Install ICON dependencies:
spack install                             \
  cmake                                   \
  openmpi                                 \
  netcdf-fortran ^hdf5+hl+szip+threadsafe \
  eccodes                                 \
  netlib-lapack                           \
  libfyaml                                \
  libxml2

# Symlink the dependencies to a single prefix (e.g. to $HOME/icon-sw):
export ICON_SW_PREFIX="$HOME/icon-sw"
spack view symlink -i "$ICON_SW_PREFIX" \
  cmake                                 \
  openmpi                               \
  netcdf-fortran                        \
  eccodes                               \
  netlib-lapack                         \
  libfyaml                              \
  libxml2

# Install optional tools:
spack install cdo