Installation - bertdupe/Matjes GitHub Wiki

Installation

So far the installation is only tested on few Linux systems and one mac system, this page aims to help during the installation process.

Basic installation

Current prerequisites for compiling Matjes:

  • Fortran and C++ compiler (eg. gfortran/g++)
  • Cmake

Additional libraries which can speed up evaluations or enable further functionalities:

  • Eigen 3.3
  • FFTW3
  • CUDA
  • MPI
  • MKL (Intel math kernel library) (For Inspector-executor Sparse BLAS and FEAST diagonalization)
  • LAPACK
  • BLAS

After obtaining the source code, the config.cmake file has to be chosen as described in the following section.

Afterwards, the installation process is initiated by calling the ./compile.sh script from the Matjes main directory. The shell asks to enter an additional keyword (debug, check, release) and confirm with enter, which chooses from an internal set of compiler flags (e.g. optimization level, options are set in ./cmake/compilerflags.cmake). No input chooses the release options.

Then, Matjes is compiled in the build_cmake directory and a link to the executable is set in the main directory.

config.cmake-File

The config.cmake file located in the main directory is used to specify installation options, such as linking directories, compiler flags, and Preprocessor flags. It is called within cmake before initialization of the project so that direct references to the different program parts are impossible, but one can preprocessor flags, compilers, compiler flags, and later used cmake variables. The basic idea is that all machine dependent information for compilation and well as the inclusion of features is specified locally in that file, while more general installation necessities are included in the git repository.

Example config.cmake-files can be obtained from ./cmake/configlist/ (removing the respective suffix from the file name) and should be placed in the main directory.

Additional linking and include commands for the compiler can be added using the add_lib cmake-variables, respectively. For example:

set(add_lib ${add_lib} "-L$ENV{MKLROOT}/lib/intel64 -Wl,--no-as-needed -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core -lgomp -lpthread -lm -ldl") 
include_directories( $ENV{MKLROOT}}/include )

Example config.cmake

This example config.cmake-file gives an overview of possible choices:

set(CMAKE_CXX_COMPILER "mpicxx")
set(CMAKE_Fortran_COMPILER "mpif90")

#set faster release flags
#set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -fno-protect-parens -ffast-math")
#set(CMAKE_CXX_FLAGS_RELEASE "-Ofast -march=native -mtune=intel")

#include_directories( /usr/include ) #FFTW directory include

#some parameters that can be modified on the cmake stage
#set(MKL_linker  "-Wl,--no-as-needed -lmkl_gf_lp64 -lmkl_sequential -lmkl_core -lpthread -lm -ldl")
#set(MKL_library_path $ENV{MKLROOT}/lib/intel64)
#set(MKL_include_path $ENV{MKLROOT}/include)
#set(netCDF_fortran_library "netcdff")
#set(FFTW_linker "-lfftw3") 
#set(CMAKE_CUDA_ARCHITECTURES 75)
#set(manual_linker_language "CXX")  #set linker language to CXX linking fails with many unknown symbols

#options to enable/disable features (leaving out enables if library is found)
#set(USE_BLAS    FALSE)
#set(USE_CUDA    FALSE)
#set(USE_EIGEN   FALSE)
#set(USE_FFTW    FALSE)
#set(USE_LAPACK  FALSE)
#set(USE_MKL     FALSE)
#set(USE_netCDF  FALSE)
set(USE_OPENMP  TRUE)   #without entry default off

#MANUALLY SET PREPROCESSOR FLAGS
add_compile_definitions(CPP_SCRIPT)     #disables some check of nonsensical input for less interactive sessions
add_compile_definitions(CPP_MPI)        #enables MPI-parallelization
add_compile_definitions(CPP_MRG)        #enables alternative seeded random number generator (problem at very large number of evaluations (boundaries implemented incorrectly))
add_compile_definitions(CPP_USE_WORK)   #enables use of work array for single site energy evaluation which can speed up Monte-Carlo evaluations
#add_compile_definitions(Eigen3_DIR=/home/pbuhl/programs/eigen/cmake)   #Eigen environment variables to choose directory of installation
#add_compile_definitions(CPP_DEBUG)     #enables further checks

Feature selection

The preprocessor flags should be added here using the add_compile_definitions(CPP_EXAMPLE) cmake-command.

CPP_CUDA, CPP_EIGEN, CPP_LAPACK, CPP_BLAS, CPP_FFTW, and CPP_MKL are set automatically, depending whether the required executable or library is found. It is possible to enforce the usage of the respective option though

#set(USE_BLAS    FALSE) #ENFORCE/DISABLE usage of BLAS
#set(USE_CUDA    FALSE) #ENFORCE/DISABLE usage of Cuda
#set(USE_EIGEN   FALSE) #ENFORCE/DISABLE usage of Eigen
#set(USE_FFTW    FALSE) #ENFORCE/DISABLE usage of FFTW
#set(USE_LAPACK  FALSE) #ENFORCE/DISABLE usage of Lapack
#set(USE_MKL     FALSE) #ENFORCE/DISABLE usage of MKL
#set(USE_netCDF  FALSE) #ENFORCE/DISABLE usage of netcdf

or respectively disable it with FALSE. If these parameters are not set the respective library is automatically searched and enabled if found (see cmake/external_lib_check.cmake).

The Eigen-library is located using the cmake find_package function.

The CUDA choice requires the environment $CUDA_PATH to be set, otherwise the cmake enable_language feature is used. Additionally the CUDA architecture might have to be set with eg. set(CMAKE_CUDA_ARCHITECTURES 75) depending on the graphic card generation.

OpenMP can furthermore be enabled using set(USE_OPENMP TRUE), by default it is disables.

MKL

The Intel math kernel library (MKL) can be used for its implementation of lapack as well as more specifically for its implementation implementation of sparse matrices (SPBLAS,Inspector-executor Sparse BLAS Routines) and their diagonalization procedure for sparse matrices using the FEAST algorithm.

MKL linking instructions can be conveniently obtained from the Intel® Math Kernel Library Link Line Advisor. They should be used by setting the MKLROOT environment variable which most often gets set by default (the referred directory contains the "lib" and "include" directory). specifics can be set through the following variables:

set(MKL_library_path $ENV{MKLROOT}/lib/intel64)
set(MKL_include_path $ENV{MKLROOT}/include)
set(MKL_linker "-Wl,--no-as-needed -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core -lgomp -lpthread -lm -ldl")

Preprocessor flags

Hamiltonian description

The following preprocessor flag are automatically set and allow different Hamiltonian implementations in normal space:

  • CPP_MKL : Using the sparse matrix implementation of the Intel Inspector-executor Sparse BLAS Routines.
  • CPP_EIGEN : Describes the Hamiltonian using the Eigen library.
  • CPP_CUDA : Enables the evaluation the Hamiltonian (and also the FFT Hamiltonian) on the graphic-card.
  • CPP_FFTW3 : Signifies the FFTW3 library is installed which is necessary for the discrete fourier implementation of the magnetic-dipolar Hamiltonian.

Other flags

  • CPP_BLAS : Uses BLAS routines to speed up a few operations and dense matrix vector product.
  • CPP_LAPACK : Necessary for most dense diagonalization routines.
  • CPP_DEBUG : Provides some additional output.
  • CPP_MRG : Uses the Mersenne Twister algorithm for generating pseudo-random sequences (Same Random number every time, problem with integer boundary appears after many interations).
  • CPP_MPI : Enables some MPI-parallelization (should be expanded and described elsewhere in more detail).
  • CPP_SCRIPT : Changes some stops to warnings when inserting zero Hamiltonian entries
  • CPP_USE_WORK : Enables use of work array for single site energy evaluation which can speed up Monte-Carlo evaluations

Known Problems

During compilation

Error: Cannot find Eigen3Config.cmake or eigen3-config.cmake.

Solution: Set Eigen3-DIR as described on the Eigen website in case of multiple installations (using the Matjes config.cmake) and make sure you have an installation including the cmake files there. In case of Ubuntu those files were included in the eigen-dev package.

Error: At linking stage of the compilation (the end) a gigantic number of errors with complaining about invalid characters appears (This happened on archer 2 with the gnu environment).

Solution: Set the linker language to C++ using the manual variable set(manual_linker_language "CXX") in the config.cmake file.

After compilation

Error message: error while loading shared libraries: libmkl_gf_lp64.so: cannot open shared object file: No such file or directory

Solution: The Matjes executable doesn't find the mkl-libraries, manually set the LD_LIBRARY_PATH to the directory including the mkl libraries (eg.export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/intel/mkl/lib/intel64), or try to resolve this with the mklvars.sh script provided with mkl.