# Installation¶

## Build prerequisites¶

• Python-3.6 (or later)

• CMake-3.11 (or later)

• GNU-5.4 or Intel-17 (or later) compilers (C++14 standard)

Hint

We have collected the recommended modules for the different Norwegian HPC systems under tools/<machine>.env. These files can be sourced in order to get a working environment on the respective machines, and may also serve as a guide for other HPC systems.

### C++ dependencies¶

The MRChem program depends on the following C++ libraries:

All these dependencies will be downloaded automatically at configure time by CMake, but can also be linked manually by setting the variables:

MRCPP_DIR=<path_to_mrcpp>/share/cmake/MRCPP
XCFun_DIR=<path_to_xcfun>/share/cmake/XCFun
Eigen3_DIR=<path_to_eigen3>/share/eigen3/cmake
nlohmann_json_DIR=<path_to_nlohmann_json>


### Python dependencies¶

A Python3 interpreter is also required for configuration (setup script) as well as launching the program (mrchem script). Developers will additionally need Python to update the input parser and build the documentation locally with Sphinx.

We strongly suggest not to install these Python dependencies globally, but rather to use a local virtual environment. We provide a Pipfile for specifying the Python dependencies. We recommend using Pipenv, since it manages virtual environment and package installation seamlessly. After installing it with your package manager, run:

$pipenv install  to create a virtual environment with all packages installed. Note Developers might want to run: $ pipenv install --dev


to install development packages, such as those needed to generate documentation with Sphinx.

The environment can be activated with:

$pipenv shell  Alternatively, any Python command can be run within the virtual environment by doing: $ pipenv run python -c "print('Hello, world')"


## Obtaining and building the code¶

The latest development version of MRChem can be found on the master branch on GitHub:

$git clone git@github.com:MRChemSoft/mrchem.git  The released versions can be found from Git tags vX.Y.Z under the release/X.Y branches in the same repository, or a zip file can be downloaded from Zenodo. By default, all dependencies will be fetched at configure time if they are not already available. In the following we will assume that the Python environment has been installed and activated as described above. ### Configure¶ The setup script will create a directory called <build-dir> and run CMake. There are several options available for the setup, the most important being: --cxx=<CXX> C++ compiler [default: g++] --omp Enable OpenMP parallelization [default: False] --mpi Enable MPI parallelization [default: False] --type=<TYPE> Set the CMake build type (debug, release, relwithdebinfo, minsizerel) [default: release] --prefix=<PATH> Set the install path for make install [default: ‘/usr/local’] --cmake-options=<STRING> Define options to CMake [default: ‘’] -h --help List all options The code can be built with four levels of parallelization: • no parallelization • only shared memory (OpenMP) • only distributed memory (MPI) • hybrid OpenMP + MPI Note In practice we recommend the shared memory version for running on your personal laptop/workstation, and the hybrid version for running on a HPC cluster. The serial and pure MPI versions are only useful for debugging. The default build is without parallelization and using GNU compilers: $ ./setup --prefix=<install-dir> <build-dir>


To use Intel compilers you need to specify the --cxx option:

$./setup --prefix=<install-dir> --cxx=icpc <build-dir>  To build the code with shared memory (OpenMP) parallelization, add the --omp option: $ ./setup --prefix=<install-dir> --omp <build-dir>


To build the code with distributed memory (MPI) parallelization, add the --mpi option and change to the respective MPI compilers (--cxx=mpicxx for GNU and --cxx=mpiicpc for Intel):

$make  ### Test¶ A test suite is provided to make sure that everything compiled properly. To run a collection of small unit tests: $ cd <build-dir>
$ctest -L unit  To run a couple of more involved integration tests: $ cd <build-dir>
$ctest -L integration  ### Install¶ After the build has been verified with the test suite, it can be installed with the following command: $ cd <build-dir>
$make install  This will install two executables under the <install-path>: <install-path>/bin/mrchem # Python input parser and launcher <install-path>/bin/mrchem.x # MRChem executable  Please refer to the User’s Manual for instructions for how to run the program. Hint We have collected scripts for configure and build of the hybrid OpenMP + MPI version on the different Norwegian HPC systems under tools/<machine>.sh. These scripts will build the current version under build-${version}, run the unit tests and install under install-${version}, e.g. to build version v1.0.0 on Fram: $ cd mrchem
$git checkout v1.0.0$ tools/fram.sh


The configure step requires internet access, so the scripts must be run on the login nodes, and it will run on a single core, so it might take some minutes to complete. The scripts will not install the Python dependencies, so this must be done manually in order to run the code.