# 1. Installation

## 1.1. Dependencies

CheMPS2 can be built with CMake and depends on

- BLAS

- LAPACK

- HDF5 (Hierarchical Data Format Release 5)

It is parallelized for shared memory architectures with the Open Multi-Processing (OpenMP) API and for distributed memory architectures with the Message Passing Interface (MPI). A hybrid combination of both parallelization strategies is supported.

## 1.2. Download

It is advised to clone the CheMPS2 git repository from github. In your terminal, run:

    $ cd /sourcefolder
    $ git clone 'https://github.com/sebwouters/chemps2'
    $ cd chemps2

That way, future updates and bug fixes can be easily pulled in:

    $ cd /sourcefolder/chemps2
    $ git pull

## 1.3. Build the chemps2 library and binary

The files

    /sourcefolder/chemps2/CMakeLists.txt
    /sourcefolder/chemps2/CheMPS2/CMakeLists.txt
    /sourcefolder/chemps2/tests/CMakeLists.txt
    /sourcefolder/chemps2/sphinx/CMakeLists.txt

provide a minimal compilation. In your terminal, run:

    $ cd /sourcefolder/chemps2
    $ mkdir build
    $ cd build

CMake generates makefiles based on the user’s specifications:

    $ CXX=option1 cmake .. -DMKL=option2 -DCMAKE_INSTALL_PREFIX=/option3 -DWITH_MPI=option4

1. Option1 is the `c++` compiler; typically `g++`, `icpc`, or `clang++` on Linux. It is advised to use the intel compiler if available.

2. Option2 can be `ON` or `OFF` and is used to switch on the intel math kernel library.

3. /option3 is the prefix of the installation directory; typically `/usr` or `/usr/local` on Linux. On my computer, libchemps2 is then installed in `/option3/lib/x86_64-linux-gnu/`, the headers in `/option3/include/chemps2/`, and the binary in `/option3/bin/chemps2`.

4. Option4 can be `ON` or `OFF` and is used to switch on the possibility to compile with MPI. Please note that the compiler should then provide `mpi.h`. Option1 should hence be the `mpic++` compiler; typically `mpic++` or `mpiicpc` on Linux. It is advised to use the intel compiler if available.

If one or more of the required libraries are not found, use the command

    $ CMAKE_INCLUDE_PATH=option5 CMAKE_LIBRARY_PATH=option6 CXX=option1 cmake .. -DMKL=option2 -DCMAKE_INSTALL_PREFIX=/option3 -DWITH_MPI=option4

instead, where option5 and option6 are respectively the missing colon-separated include and library paths:

    CMAKE_INCLUDE_PATH=/my_libs/lib1/include:/my_libs/lib2/include
    CMAKE_LIBRARY_PATH=/my_libs/lib1/lib:/my_libs/lib2/lib

Remarks:

1. For operating systems based on debian, the HDF5 headers are located in the folder `/usr/include/hdf5/serial/`. If CMake complains about the HDF5 headers, try to pass it with the option `-DHDF5_INCLUDE_DIRS=/usr/include/hdf5/serial`.

2. Sometimes it might be necessary to specify the MKL libraries, e.g. for mixed-type GCC and single-threaded MKL compilation with the option `-DLAPACK_LIBRARIES="/opt/intel/mkl/lib/intel64/libmkl_intel_lp64.so;/opt/intel/mkl/lib/intel64/libmkl_sequential.so;/opt/intel/mkl/lib/intel64/libmkl_core.so"`.

3. For building with GCC, errors involving unresolved symbols or a message `plugin needed to handle lto object` may indicate a failure of the interprocedural optimization. This can be resolved by passing full locations to gcc toolchain utilites to the `setup` command above: `-DCMAKE_RANLIB=/path/to/gcc-ranlib -DCMAKE_AR=/path/to/gcc-ar` .

To compile, run:

    $ make

To install, run:

    $ make install

For non-standard installation directories, please remember to append the library path to `LD_LIBRARY_PATH` in your `.bashrc`.

## 1.4. Test libchemps2

To test libchemps2 for compilation without MPI, run:

    $ cd /sourcefolder/chemps2/build
    $ make test

To test libchemps2 for compilation with MPI, run:

    $ cd /sourcefolder/chemps2/build/tests
    $ OMP_NUM_THREADS=YYY mpirun -np ZZZ ./test1
    $ OMP_NUM_THREADS=YYY mpirun -np ZZZ ./test2
    ...

`YYY` specifies the number of threads per process and `ZZZ` the number of processes. Note that the tests are too small to see (near) linear scaling with the number of cores, although improvement should still be noticeable.

## 1.5. Test the chemps2 binary

To test the chemps2 binary for compilation without MPI, run:

    $ man /sourcefolder/chemps2/chemps2.1
    $ cd /sourcefolder/chemps2/build/CheMPS2
    $ ./chemps2 --help
    $ cp /sourcefolder/chemps2/tests/test14.input .
    $ sed -i "s/path\/to/sourcefolder\/chemps2\/tests\/matrixelements/" test14.input
    $ cat test14.input
    $ ./chemps2 --file=test14.input

Note that when you use the CASPT2 checkpoint, and want to restart a calculation at a later point, you should

> 1. switch the option `SCF_ACTIVE_SPACE` to `I`

> 2. remove the `CheMPS2_DIIS.h5` checkpoint

in order to ensure that exactly the same orbitals are used in the different runs.

To test the chemps2 binary for compilation with MPI, prepend the binary with:

    $ OMP_NUM_THREADS=YYY mpirun -np ZZZ ./chemps2 --file=test14.input

## 1.6. Build PyCheMPS2

PyCheMPS2 is a python interface to libchemps2, for compilation without MPI. It can be built with Cython. The installation is independent of CMake and assumes that you have installed the CheMPS2 library with `make install`. For non-standard installation directories of CheMPS2, please remember to append the library path to `LD_LIBRARY_PATH` in your `.bashrc`. In addition, the include path should be appended to `CPATH`:

    $ export CPATH=${CPATH}:/option3/include

where `/option3` is the option provided to CMake with `-DCMAKE_INSTALL_PREFIX=/option3` above. For operating systems based on debian, the HDF5 headers are located in the folder `/usr/include/hdf5/serial/`. If it was explicitly passed to CMake, it should also be appended to `CPATH`:

    $ export CPATH=${CPATH}:/option3/include:/usr/include/hdf5/serial

The python wrapper can be installed with:

    $ cd /sourcefolder/chemps2/PyCheMPS2
    $ python setup.py build_ext -L ${LD_LIBRARY_PATH}
    $ python setup.py install --prefix=/option3

On my machine, the python wrapper is installed to the folder `/option3/lib/python2.7/site-packages`, but the folder `lib` and the distribution of python can vary.

Compilation of PyCheMPS2 occurs by linking to the `c++` library in the installation directory. The installation of PyCheMPS2 will fail if that library is not properly installed. If you have pulled a newer version of CheMPS2, please remember to reinstall the `c++` library first, before reinstalling PyCheMPS2!

## 1.7. Test PyCheMPS2

When libchemps2 has been compiled without MPI, PyCheMPS2 can be tested by running (remember that the python site-packages folder can vary):

    $ cd /sourcefolder/chemps2/PyCheMPS2/tests
    $ export PYTHONPATH=${PYTHONPATH}:/option3/lib/python2.7/site-packages
    $ python test1.py
    $ python test2.py
    ...

If you compiled the `c++` library with `-DMKL=ON`, you might get the error

    Intel MKL FATAL ERROR: Cannot load libmkl_avx.so or libmkl_def.so.

This issue of using Intel’s MKL inside python is known and reported. To get the python tests to run, you can set the variable `LD_PRELOAD` in order to preload libmkl_rt.so. On my system, this is done with

    $ export LD_PRELOAD=/opt/intel/mkl/lib/intel64/libmkl_rt.so

The python tests do exactly the same thing as the `c++` tests above, and illustrate the usage of the python interface to libchemps2. The tests should end with a line stating whether or not they succeeded. Note that the tests are too small to see (near) linear scaling with the number of cores, although improvement should still be noticeable.