MiMiC Framework

The following installation guide provides quick and concise instructions to get MiMiC running as quickly as possible. The MiMiC framework consists of two components, namely the MiMiC library and the MiMiC communication library (MCL). In the following, we provide the requirements for both components and the instructions for building and installing each component.

Along with the MiMiC framework, we also provide the utility tool MiMiCPy, which is a Python-based collection of tools that automates the setup of MiMiC-based simulations. See MiMiCPy for installation instructions.

Throughout this guide, we primarily use Git to obtain the MiMiC framework sources, but we also provide optional download links. In case you opt for the latter option, just note that the directory names extracted from downloaded files might differ.

Requirements

A list of minimum requirements to build the MiMiC framework is given below. Optional dependencies and supported external programs are also listed.

Minimum Requirements

  • CMake 3.12

  • Fortran compiler (Fortran 2008 standard)

  • C++ compiler (C++17 standard)

  • MPI library (MPI 2.1 standard)

Optional Dependencies

Supported External Programs

See External Programs for installation instructions.

Build and Installation

The two components of the MiMiC framework are configured, built, tested, and installed using the CMake build system. The following instructions will guide you through the process from download to installation.

Before we start, it is important to decide where MiMiC should be installed. In this guide, we will use .local in user’s home directory, but feel free to choose whichever location you prefer:

INSTALL_DIR=${HOME}/.local

In the following, we will refer to this variable to set CMAKE_INSTALL_PREFIX which determines the root of install directory. This means that after invoking make install, everything will be installed in this directory using standard GNU locations, i.e., lib (or lib64), include, share, etc.

Moreover, to be consistent with the compilers used for the different programs you are going to build, you can set the environment variables FC, CC, and CXX to your chosen Fortran, C, and C++ compilers, respectively. These are then detected by CMake during the build configuration process.

Finally, we recommend that you download the sources in a separate directory. Here we will create and use a directory in the user’s home directory, but again feel free to use whichever location you prefer:

SOURCE_DIR=${HOME}/mimic_sources
mkdir -p ${SOURCE_DIR}

Building with tests

We strongly recommend to build with tests if you are planning to use the builds for production simulations. Note that some tests require either mpirun or mpiexec which may not be available on all HPC clusters. If neither is available, then those tests will fail, but that does not necessarily mean that the MCL build will not work.

Warning

Instructions in this guide are written for releases of MiMiC and MCL. Note that the development branch may be unstable or contain breaking changes that are not compatible with released versions of supported programs. Therefore we do not recommend that you use it unless you really know what you are doing.

MiMiC Communication Library

It is necessary to build and install MCL first, as the MiMiC library depends on it. Start by changing directory to the common source directory:

cd ${SOURCE_DIR}

Then start either by downloading and unpacking the release version of MCL from here or clone it directly from the MiMiC repository:

git clone -b 2.0.1 https://gitlab.com/MiMiC-projects/CommLib.git

Next, enter the MCL root directory, create a build directory and enter it:

cd CommLib
mkdir build
cd build

From here, you configure the build using CMake, and then build and install:

cmake -DBUILD_SHARED_LIBS=YES -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR} ..
make
make install

Additionally, you might also want to build and run tests. To do so, you need to add -DBUILD_TESTS=YES in the configure step shown above and run make test before make install. The prerequisite for this is the GoogleTest testing and mocking framework. If you do not have it, you can build it in a few steps. However, this has to be done before you configure MCL.

Installing GoogleTest

If you already have a functioning build of GoogleTest just set these environment variables:

export GTEST_ROOT=<path to your GTest build>
export GMOCK_ROOT=<path to your GMock build>

Otherwise, you can clone the GoogleTest repository, build, and install by following these steps:

cd ${SOURCE_DIR}
git clone -b release-1.12.1 https://github.com/google/googletest.git
cd googletest
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR} ..
make
make install

Failing tests

Note that tests mpitransport and mpmdtransport require either mpirun or mpiexec which may not be available on all HPC clusters. If neither is available, then those tests will fail, but that does not necessarily mean that the MCL build will not work.

MiMiC Library

Once we have installed the communication library, we can proceed to the compilation of MiMiC. Move to the source directory:

cd ${SOURCE_DIR}

And then you either download and unpack the release version of MiMiC from here or clone it directly from the MiMiC repository:

git clone -b 0.2.0 https://gitlab.com/MiMiC-projects/MiMiC.git

Enter the MiMiC root directory and from there create a build directory and enter it:

cd MiMiC
mkdir build
cd build

Then you configure the build by running CMake and then build and finally install:

cmake -DENABLE_OPENMP=YES -DBUILD_SHARED_LIBS=YES -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR} ..
make
make install

As with MCL, we recommend that you also build and run the tests suite. This is done in the same manner by adding a CMake flag -DBUILD_TESTS=YES when configuring and calling make test before the installing. The only difference is that MiMiC uses pFUnit testing framework, which you can install following the instructions below.

Installing pFUnit

First clone pFUnit repository to the source directory:

cd ${SOURCE_DIR}
git clone -b v4.6.1 https://github.com/Goddard-Fortran-Ecosystem/pFUnit.git

Enter the directory, create and enter build directory, configure, build, and install:

cd pFUnit
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR} ..
make tests
make install

If you encounter an error related to git submodules, try using a more recent version of git.

Failing tests

Note that tests test_main and test_data_collect require either mpirun or mpiexec which may not be available on all HPC clusters. If neither is available, then those tests will fail, but that does not necessarily mean that the MiMiC build will not work.