Requirements

MiMiC Framework

Minimum requirements

  • CMake 3.12+

  • Fortran compiler that supports the Fortran 2008 standard

  • MiMiC Communication Library 2.0+

Optional dependencies

  • Git (to clone the source repository)

  • Fortran compiler that supports the OpenMP 3.0 standard (to enable threading)

The following optional dependencies are only needed to build the test suite:

  • C++ compiler that supports the C++14 standard

  • MPI library that supports the MPI 2.1 standard

  • pFUnit 4.0+

MiMiC Communication Library

Minimum requirements

  • CMake 3.12+

  • C++ compiler that supports the C++14 standard

  • MPI library that supports the MPI 2.1 standard

Optional dependencies

  • Git (to clone the source repository)

  • Fortran compiler that supports the Fortran 2008 standard (to build the Fortran API)

The following optional dependencies are only needed to build the test suite:

  • GoogleTest (can optionally be downloaded at build time)

Supported external programs

  • GROMACS 2022 series or newer (not released)

  • CPMD 4.5 or higher (not released)

It is also possible to patch CPMD 4.3 and GROMACS 2021. See Getting the Sources for information on how to obtain the patches and Build and Install for instructions on how to apply the patches.

Getting the Sources

MiMiC Framework

The MiMiC framework is hosted on GitLab (https://gitlab.com/MiMiC-projects/MiMiC). The released versions can be downloaded at https://gitlab.com/MiMiC-projects/MiMiC/-/releases. From the command line, a specific version can be downloaded using wget:

$ wget https://gitlab.com/MiMiC-projects/MiMiC/-/archive/0.1.0/MiMiC-0.1.0.tar.gz

Alternatively, the entire source (incl. development versions) can be obtained by cloning the git repository (developers may want to create a fork on GitLab and clone that instead):

$ git clone https://gitlab.com/MiMiC-projects/MiMiC.git

This will create a directory named MiMiC. Entering that directory will put you directly in the main development branch. From here, released version can be checked out by:

$ git checkout 0.1.0

where you can replace the tag with the version that you want. A released version can also be checked out directly by supplying the release tag when cloning:

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

Warning

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

The MiMiC communication library is also hosted on GitLab (https://gitlab.com/MiMiC-projects/CommLib). The same procedure as for MiMiC can be followed by just replacing the URLs. In short, the released versions can be downloaded at https://gitlab.com/MiMiC-projects/CommLib/-/releases:

$ wget https://gitlab.com/MiMiC-projects/CommLib/-/archive/2.0.0/CommLib-2.0.0.tar.gz

while the repository can be cloned and a released version checked out as follows:

$ git clone https://gitlab.com/MiMiC-projects/CommLib.git
$ git checkout 2.0.0

Warning

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.

External programs

CPMD

The CPMD program itself can be obtained from https://www.cpmd.org/ and we refer to their documentation for further instructions. Official support for MiMiC is only available from CPMD 4.5 and higher. However, patches for CPMD 4.1 and 4.3 can be downloaded at https://mimic-project.org/cpmd-patches. Instructions on how to apply the patches are given below in Build and Install.

Todo

Add CPMD patches

GROMACS

GROMACS can be obtained from https://www.gromacs.org/ and we refer to their documentation for further instructions. Official support for MiMiC is only available from GROMACS 2022 series and newer. However, patches for the GROMACS 2021 series can be downloaded at https://mimic-project.org/gromacs-patches. Instructions on how to apply the patches are given below in Build and Install.

Todo

Add GROMACS patches

Build and Install

The MiMiC framework and communication library are configured, built, tested, and installed using the CMake build system. The following instructions will guide you through the process from download to installation. The Quickstart guide will get you through the process without providing details and may not work for everyone. On the other hand, the Walkthrough installation will go into more detail and describe each step more carefully.

Quickstart guide

The complete process from download to install using typical settings of both the MiMiC framework and communication library is as follows:

Note

Take care to check that each step completes successfully before moving on to the next step. In particular, ensure that all tests pass.

$ wget https://gitlab.com/MiMiC-projects/CommLib/-/archive/2.0.0/CommLib-2.0.0.tar.gz
$ tar -zxvf CommLib-2.0.0.tar.gz
$ cd CommLib-2.0.0
$ mkdir build
$ cd build
$ cmake -DBUILD_FORTRAN_API=YES -DBUILD_TESTS=YES -DDOWNLOAD_GTEST=YES -DCMAKE_INSTALL_PREFIX=${HOME}/.local ..
$ make
$ make test
$ make install
$ cd ../../
$ wget https://gitlab.com/MiMiC-projects/MiMiC/-/archive/0.1.0/MiMiC-0.1.0.tar.gz
$ tar -zxvf MiMiC-0.1.0.tar.gz
$ cd MiMiC-0.1.0
$ mkdir build
$ cd build
$ cmake -DENABLE_OPENMP=YES -DBUILD_TESTS=YES -DCMAKE_INSTALL_PREFIX=${HOME}/.local ..
$ make
$ make test
$ make install
$ cd ../../

This will install everything in your user’s home directory under .local using standard GNU locations (i.e., lib or lib64, include, etc.). If everything completed successfully then it is safe to delete the CommLib-2.0.0 and MiMiC-0.1.0 directories (as well as the downloaded source packages). The next step is to enable MiMiC in the external programs that you want to use (see Building external programs with MiMiC support).

Walkthrough installation

It is necessary to build and install the communication library first as the MiMiC framework depends on it. Therefore we start by downloading and unpacking the communication library.

Then we change directory to the root of the communication library and from there create a build directory, enter it, configure, build, and install.

The MiMiC communication library is configured, built, and installed using CMake which in most cases can be used without alot of manual configuration. Apart from the standard CMake options, there are also the following list of options that are specific to CommLib:

  • BUILD_FORTRAN_API - Build the Fortran API (required by MiMiC)

  • INCLUDE_TESTS - Build the test suite

  • DOWNLOAD_GTEST - Download GoogleTest (needed to run the test suite)

The quick and simple procedure is as follows (more detailed instructions are provided below):

$ mkdir <build-directory>
$ cd <build-directory>
$ cmake -DBUILD_FORTRAN_API=YES -DCMAKE_INSTALL_PREFIX=<install-path-prefix> <path-to-commlib>
$ make
$ make install

where <build-directory> is the directory in which the code will be built (which is safe to delete after successful completion), <install-path-prefix> is the path prefix in which the compiled files will be installed in standard directories (i.e., bin, include, lib (or lib64), etc.), and <path-to-commlib> is the path to the root of the CommLib source code.

A typical procedure Start the process by creating a build directory and entering it:

$ mkdir build
$ cd build

From there you first configure the build using CMake:

$ cmake -DBUILD_FORTRAN_API=YES -DCMAKE_INSTALL_PREFIX=${HOME}/.local ..

Here we have chosen to build the Fortran API because it is needed by MiMiC and also specified an install path using CMake’s standard CMAKE_INSTALL_PREFIX option. The supplied install path is a prefix and the files will be installed in standard locations below the given prefix, i.e., bin, include, lib/lib64, etc. Note that the default install path (usually /usr/local) will often require superuser privileges. By default only static libraries are built and to instead build shared libraries you need to add -DBUILD_SHARED_LIBS=YES. It is also possible to build the code completely outside of the source directory in which case you replace .. with the path to the root of the source directory. In case CMake did not detect the compiler that you want to use then you can manually select it by adding -DCMAKE_CXX_COMPILER=<c++-compiler> (and -DCMAKE_Fortran_COMPILER=<fortran-compiler> if you chose to build the Fortran API) or by setting the environment variable CXX (and FC for the Fortran compiler).

Note

Examine the output from CMake to ensure that it completes without errors before moving on.

Once the build is configured it can be compiled and installed as follows:

$ make
$ make install

This will also install CMake package files allowing you to easily include CommLib in a CMake configuration.

These instructions assume that you are in the root folder of the MiMiC source. From here you should first create a build drectory and enter it:

Todo

This is how you build and install MiMiC

Building external programs with MiMiC support

The following instructions will focus on how to enable MiMiC in supported programs and as such will not be thorough guides on the build and install process of each program. For that we refer to the instructions given by the distributors of the programs.

Building CPMD with MiMiC support

Todo

Expand with patch and simple build instructions

Building GROMACS with MiMiC support

Todo

Expand with patch and simple build instructions