Compile Instructions

The section ‘Dependencies’ lists the general requirements for the compilation. The section ‘System-dependent dependency installation’ gives some instructions on how to install these dependencies on Windows, some Linux-distributions and MacOS. Conda based dependency installation is described in the section ‘Conda dependent installation’.

Dependencies

To clone and compile mHM you need at least the following:

• Fortran compiler: We support gfortran, nagfor and ifort
• Build system: We support make and ninja
• cmake: Software for build automation
• NetCDF-Fortran: NetCDF I/O for Fortran
• git: version control system
• (optional) fypp: Fortran pre-processor written in Python

System-dependent dependency installation

After you installed all dependencies on your system you can proceed with cloning and compiling.

Unix (Linux / MacOS)

1. MacOS with homebrew available:

    brew install git gcc netcdf cmake
   

2. Ubuntu, Mint and other apt-get based systems with matching repositories:

    sudo apt-get install git gfortran netcdf-bin libnetcdf-dev libnetcdff-dev cmake
   

3. Archlinux:

    sudo pacman -S git gcc-libs netcdf-fortran cmake
   

4. yum based systems (CentOS, OpenSuse):

    sudo yum -y install git gcc-gfortran netcdf-fortran cmake
   

Windows

On Windows 10 and later we recommend to use Windows Subsystem for Linux (WSL) to be able to use Linux by e.g. installing Ubuntu there.

Easiest way to do so is:

1. install the Windows Terminal
2. open the Windows Terminal and type:

    wsl --install -d ubuntu
   

3. Open Ubuntu from the new entry in the start menu

Then you can follow the install instructions for Ubuntu from above.

If you rather want to use Cygwin (tool providing Linux functionality on Windows), step-by-step guidelines on how to install all Cygwin libraries can be viewed in this youtube video created by Mehmet Cüneyd Demirel (Istanbul Technical University).

Module systems

If you are on a module system, load the modules gcc or intel depending on your favorite compiler. Then, load the modules netcdf-fortran and cmake.

These modules will have system specific names, environments, etc. You may use module spider to find the right packages and the right dependencies, potentially use corresponding wiki pages.

On EVE (the cluster at the UFZ)

A set of load-scripts is provided in hpc-module-loads (see the repository for more details), to load all needed modules for specific compilers:

• Example: GNU 7.3 compiler (foss/2018b Toolchain):

  source hpc-module-loads/eve.gcc73
  

  or (MPI support)

  source hpc-module-loads/eve.gcc73MPI
  

Conda dependent installation

The simplest way to compile this project on your local computer is to use a conda environment (on Linux (including WSL) or MacOS) provided by Miniforge to install NetCDF, a Fortran compiler, make, cmake.

On Windows we recommend to use Windows Subsystem for Linux (WSL) to be able to use Linux (see above) and set up conda there.

You can get the latest version of Miniforge with (for Linux/MacOS/WSL):

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh
bash Miniforge3-$(uname)-$(uname -m).sh

To create a (local) conda environment with all dependencies type the following:

conda create -y --prefix ./fortran_env
conda activate ./fortran_env
conda install -y git cmake make fortran-compiler netcdf-fortran

Then you can proceed with cloning and compiling.

Cloning the repository

First you need to clone the repository (if you already have git, otherwise see below):

git clone https://git.ufz.de/mhm/mhm.git

This will give you a new folder mhm/ containing the whole repository. You can go into it by:

cd mhm/

If you then want to compile a specific version (different from the latest development version), you can check that out with e.g.:

git checkout v5.11.2

Afterwards you can continue with the compilation.

Compilation commands

It could be necessary to set your desired fortran compiler with an environment variable, e.g.:

export FC=gfortran

We prepared a set of scripts to automatize the build and compilation process to generate an executable in the root directory with the following naming scheme:

• Release version mhm:

  source CI-scripts/compile
  

• Debug version mhm_debug:

  source CI-scripts/compile_debug
  

• Release version with MPI support mhm_mpi:

  source CI-scripts/compile_MPI
  

• Debug version with MPI support mhm_mpi_debug:

  source CI-scripts/compile_MPI_debug
  

• Release version with OpenMP support mhm_openmp:

  source CI-scripts/compile_OpenMP
  

• Debug version with OpenMP support mhm_openmp_debug:

  source CI-scripts/compile_OpenMP_debug
  

Then you can find an executable mhm (or mhm[_mpi|_openmp][_debug]) in the current folder. You can execute it with:

./mhm

Installation

To install mhm after compilation, i.e. make it available as a command mhm, you can do the following (assuming you used the release compile script, otherwise replace release with the respective build folder):

cmake --install release

If you need to provide a prefix, where to install it, you can just pass one. For example, if you used a conda environment for compilation, you can also install mhm there with:

cmake --install release --prefix $CONDA_PREFIX

Compilation without Internet

Starting with version 5.12, mHM is depending on FORCES, our Fortran library for Computational Environmental Systems. This library is downloaded on the fly by CPM, the cmake package manager.

If you don’t want to download it indirectly, know you wont have internet during your development or you want to work on routines provided by FORCES, you can place a copy of the FORCES repository in the root of your cloned mHM repository by e.g.:

git clone https://git.ufz.de/chs/forces.git

The new folder forces/ will be automatically recognized during compilation as described above and nothing will be downloaded.

If you just want a specific version (see src/CMakeLists.txt for the currently used one), do this:

git clone --branch v0.3.2 --depth 1 https://git.ufz.de/chs/forces.git

If you have already cloned FORCES somewhere else, you can also provide a path to this repository. You can do this with all mentioned compile scripts, e.g.:

source CI-scripts/compile -DCPM_forces_SOURCE=<path/to/your/forces/repo>

For example, if you have cloned FORCES next to mhm, this could look like this:

source CI-scripts/compile -DCPM_forces_SOURCE=../forces

Additional CMake infos

The presented compile scripts all just execute two cmake commands with a specific set of configuration flags. The basic cmake workflow, to configure and compile in a build/ folder, is:

cmake -B build
cmake --build build

You can control all cmake options by passing them as directives staring with -D to the cmake configuration. For example for debug configuration, you can do the following:

cmake -B build -DCMAKE_BUILD_TYPE=Debug

To configure the build interactively, you can also use ccmake (command line tool) or the CMake GUI (graphical user interface). Check their respective documentation for further information. To use ccmake you can do the following:

cmake -B build
ccmake build

Then set your desired options and re-configure your build (by pressing c). Afterwards build you project as always by executing:

cmake --build build --parallel