Code and compilation

Requirements

Before starting the tutorial, make sure that you meet the requirements of MicroHH. In order to compile MicroHH you need:

  • C++ compiler (C++17)

  • Fortran compiler (Fortran 2003)

  • FFTW3

  • Boost

  • NetCDF4-C

  • CMake

  • MPI2/3 implementation (optional for MPI support)

  • CUDA (optional for GPU support)

  • Python + Numpy (optional for running example cases)

  • Ipython + NetCDF4 + Matplotlib (optional for plotting results example cases)

Note

The legacy netCDF C++ and NetCDF-CXX4 libraries are no longer supported (or required), as MicroHH has its own C++ wrapper for the NetCDF4-C library.

If you are running on OSX, please install also the GNU sed (gnu-sed in Homebrew, or gsed in MacPorts)

Obtaining the MicroHH code

Note

If you want to contribute code to MicroHH, it is best not to clone the code from the main repository, but instead make a fork using the fork option at https://github.com/microhh/microhh. This will create a copy of MicroHH in https://github.com/your_username/microhh, which you can download using git clone https://github.com/your_username/microhh.git. If you do not want to contribute, it is fine to clone the code from the main repository.

The MicroHH code is hosted at Github (https://github.com/microhh/microhh). The code can either be downloaded as a ZIP file (https://github.com/microhh/microhh/archive/main.zip), but if Git (version control system) is installed, the code can also be downloaded using:

Check out the code from GitHub using

git clone --recurse-submodules https://github.com/microhh/microhh.git

In case you had already checked out the repository without checking out the submodules, use:

git submodule update --init --recursive

The advantage of using Git is that the model can easily be updated at a later time by calling git pull from anywhere in the MicroHH directory.

Compilation of the code

At the starting point of this tutorial, we assume that you are in the main directory of MicroHH. First, we will take care of the configuration file. Enter the config directory:

cd config

Here, you find a potential series of settings with the extension .cmake for different systems. Check whether your system is there. If not, you can try the generic configuration (generic.cmake), or create a file with the correct compiler settings and the proper location for all libraries on your system. Then, copy your system file to default.cmake, for example:

cp generic.cmake default.cmake

Then, go back to the main directory and create a subdirectory with an arbitrary name in which you will compile the code. Let us assume this directory is called build:

cd ..
mkdir build
cd build

From this directory, run cmake with the suffix .. to point to the parent directory where the CMakeLists.txt is found. This builds the model without Message Passing Interface (MPI) and CUDA support.

cmake ..

Running cmake without arguments gives you a serial build without GPU support in double precision. Parallel builds with MPI can be enabled by adding the -DUSEMPI=TRUE flag. GPU support using NVIDIA CUDA can be enabled with the flag -DUSECUDA=TRUE. Note that they cannot be combined at the moment in absence of multi-GPU support. The precision of the code can be reduced from double (64-bits) to single (32-bits) precision using the flag -DUSESP=TRUE. Some examples are found below here:

cmake .. -DUSEMPI=TRUE
cmake .. -DUSECUDA=TRUE -DUSESP=TRUE
cmake .. -DUSESP=TRUE

Note

If you get an error add_subdirectory given source "rte-rrtmgp-cpp/src_kernels" which is not an existing directory, you probably forgot to specify --recurse-submodules in the git clone command. You can fix this by running git submodule update --init --recursive once.

Warning

Once the build has been configured and you wish to change the USECUDA, USEMPI, or USESP setting, you must delete the build directory or create an additional empty directory from which cmake is run again.

With the previous command you have triggered the build system and created the Makefile, if the default.cmake file contains the correct settings. Now, you can start the compilation of the code and create the MicroHH executable with:

make -j 4

Your directory should contain a file named microhh now. This is the main executable.