ICONMATH library

This repository is an external library of ICON collecting modules of ICON supporting and enabling math operations. The library is divided into three components:

• libiconmath-support: contains general modules that are used in ICON to support math operations but are independent of the data types in ICON.
• libiconmath-horizontal: contains modules which compute several mathematical operators such as divergence, gradient, Laplacian etc.
• libiconmath-interpolation: contains modules that interpolates and reconstructs scalar and vector fields used in ICON.

Requirements

The following packages/libraries are required for libiconmath libraries

• Fortran compiler
• CMake 3.18+
• libfortran-support to access some utility functions for Fortran

The following requirements are optional

• fprettify for Fortran code formatting
• OpenACC to run the code on GPU nodes
• REUSE v3.0.0+ for licensing

For Users

How to install libiconmath?

1. Clone the repository

git clone https://gitlab.dkrz.de/icon-libraries/libiconmath.git
cd libiconmath

2. Create a build directory

mkdir build
cd build

3. Configure the library

cmake ..

For GPU support with OpenACC, use the following command

cmake -DIM_ENABLE_OPENACC=ON ..

4. Compile the library

make

5. Install the library

make install

make install needs to be run with sudo if the installation directory is not writable by the user. To install the library in a specific directory, use the following command

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX ..
make install

where $PREFIX is the installation directory.

6. Check the installation

ls $PREFIX/lib

where $PREFIX is the installation directory. The library files should be in the lib directory.

7. Check the module files

ls $PREFIX/include

where $PREFIX is the installation directory. The module files should be in the mod directory.

How to use libiconmath in your project?

What modules are in the libiconmath-support library?

The libiconmath-support library includes some general modules that are used in ICON to support math operations but are independent of the data types in ICON. Here is a list of the supported modules.

• mo_gridman_constants: constants relevant for implementational issues
• mo_lib_grid_geometry_info: grid-related basic structures and geometry parameters
• mo_lib_loopindices: determines start and end indices of do loops
• mo_math_constants: main mathematical constants
• mo_math_types: basis math types
• mo_math_utilities: various mathematical algorithms
• mo_random_number_generators: generators for pseudo random numbers

What modules are in the libiconmath-interpolation library?

The libiconmath-interpolation library includes modules that interpolates and reconstructs scalar and vector fields used in ICON. Here is a list of the supported modules.

• mo_lib_interpolation_scalar: contains the implementation of interpolation and reconstruction for scalar fields
• mo_lib_interpolation_vector: contains the implementation of interpolation and reconstruction for vector fields
• mo_lib_intp_rbf: perform vector RBF reconstruction

What modules are in the libiconmath-horizontal library?

The libiconmath-horizontal library includes modules which compute several mathematical operators such as divergence, gradient, Laplacian etc.

• mo_lib_divrot: contains the implementation of divergence, rotation and linear reconstruction
• mo_lib_gradient: contains the implementation of mathematical gradient operators
• mo_lib_laplace: contains the implementation of computing Laplacian of scalar and vector fields

How to link modules from math libraries (same for libiconmath-support, libiconmath-interpolation, and libiconmath-horizontal)

• The individual libraries will be built into libiconmath/build/src/support/<library_name>.dylib (or .so depending on the platform)
• The module files (Fortran) for a <component> of the library (i.e. support, interpolation or horizontal) will be built under libiconmath/build/src/<component>/mod/

Include the library in your CMakeLists.txt

find_package(iconmath REQUIRED)
target_link_libraries(your_target PRIVATE iconmath::support iconmath::interpolation iconmath::horizontal)

Include the module files in your Fortran code, as an example,

use mo_math_types, only: t_tangent_vectors
use mo_lib_interpolation_scalar, only: verts2edges_scalar_lib
use mo_lib_divrot, only: div_lib

For developers

Some notes for developers

• The libiconmath library is only configured by CMake.
  • Tips and standards on CMake ICON developer wiki/CMake recommendations and requirements
• The libiconmath library uses fprettify for formatting Fortran codes. Run make format before you commit.
• The libiconmath library is unit tested. (work in progress) All merge request changes are preferable to have a unit test. See icon-c/Wiki/Testing and building of ICON C/Unit test frameworks for more information on unit testing.
  • Fortran unit tests are written in FortUTF. Assertions Documentation
• Fortran preprocessing is automatically applied for files with .F90 extensions. See #4 for more details.
• Make sure your code is tested.
• Check license by reuse lint. Check requirements.

How to add modules in libiconmath-support, libiconmath-interpolation or libiconmath-horizontal?

• For each <component>, the steps are the same. The only difference is the directory where the module file should be placed.

1. Put your module file under src/support/, src/interpolation/ or src/horizontal/ depending on the component.
2. Add your file to the library configuration list at src/<component>/CMakeLists.txt.

add_library(
  iconmath-<component>
  ...
# Add your module to the list. The list is in alphabetical order.
  ...
)

Check linting and formatting

Check the code format

make format

Check the license

• Use the following command to check whether the license header is added correctly

reuse lint

• More details can be found in the reuse tool GitHub page.
• The following license should be used for the library
  • Code snippets should have license BSD-3-Clause
  • Documentations should have license CC-BY-4.0
  • Files unrelated to the library itself should have license CC0-1.0

Check the CMake style

• Use the following command to check the CMake style

cmake-lint cmake/*.cmake **/CMakeLists.txt

• Use the following command to fix the CMake style issues

cmake-format -i cmake/*.cmake **/CMakeLists.txt

• More details can be found in the cmake-format GitHub page.

Check typos

• Use the following command to check typos in the code

typos

• More details can be found in the typos GitHub page.

Check OpenACC style

• Clone the repository ICON OpenAcc Beautifier

git clone https://gitlab.dkrz.de/dwd-sw/icon-openacc-beautifier.git

• Use the following command to check the OpenACC style

python3 icon-openacc-beautifier/main.py src/

How to contribute

Please open a merge request and select one of our templates: [feature/bugfix]. Detailed instructions on how to proceed are provided there.

Contact

This repository is mainly maintained by the following maintainers:

• Pradipta Samanta (samanta@dkrz.de)
• Yen-Chen Chen (yen-chen.chen@kit.edu)
• Sergey Kosukhin (sergey.kosukhin@mpimet.mpg.de)

This repository is owned by the icon-libraries group, contacts about general ICON library questions:

• Will Sawyer (william.sawyer@cscs.ch)
• Florian Prill (florian.prill@dwd.de)
• Luis Kornblueh (luis.kornblueh@mpimet.mpg.de)