How to install ELPA =================== First of all, if you do not want to build ELPA yourself, and you run Linux, it is worth having a look at the ELPA webpage http://elpa.rzg.mpg.de and/or the repositories of your Linux distribution: there exist pre-build packages for a number of Linux distributions like Fedora, Debian, and OpenSuse. More, will hopefully follow in the future. If you want to build (or have to since no packages are available) ELPA yourself, please note that ELPA is shipped with a typical "configure" and "make" autotools procedure. This is the only supported way how to build and install ELPA. If you obtained ELPA from the official git repository, you will not find the needed configure script! Please look at the "INSTALL_FROM_GIT_VERSION" file for the documentation how to proceed. If --- against our recommendations --- you do not want to install ELPA as library, or you do not want to use the autotools you will have to find a solution by yourself. This approach is NOT supported by us in any way and we strongly discourage this approach. If you do this, because you want to include ELPA within your code project (i.e. use ELPA not as an external library but "assimilate" it in your projects ), please distribute then _ALL_ files (as obtained from an official release tar-ball) of ELPA with your code. Note, however, that including the ELPA source files in your code projects (and not using ELPA as external library) is only allowed under the terms of the LGPL license if your code is ALSO under LGPL. (A): Installing ELPA as library with configure =================================================== The configure installation is best done in four steps 1) run configure: Check the available options with "configure --help". ELPA is shipped with several different versions of the elpa2-kernel, each is optimized and tuned for a different architecture. 1.1) Choice of MPI compiler (wrappers) It is mandatory that the C and C++ parts are compiled with the GNU C, C++ compilers. Thus, all ELPA test programs which are written in C must be compiled and linked with the MPI compiler (wrapper) which uses the GNU C compilers. The Fortran parts of ELPA can be compiled with any Fortran compiler of your choice. It is for example quite common to compile the Fortran part with the Intel Fortran compiler but the C,C++ parts must be compiled with the GNU compilers. Thus special care has to be taken that the correct MPI compiler (wrappers) are found by the autotools! The configure script tries to find the correct wrappers automatically, but sometimes it will fail. In these cases it is necessary to set these compilers by hand: ../configure FC=fortran_compiler_wrapper_of_your_choice CC=gnu_compiler_wrapper will tell autotools which wrappers to take. 1.2) Choice of ELPA2 kernels With the release of ELPA (2014.06 or newer) it is _not_ mandatory any more to define the (real and complex) kernels at build time. The configure procedure will build all the kernels which can be used on the build system. The choice of the kernels is now a run-time option. This is the most convenient and also recommended way. It is intended to augment this with an auto-tuning feature. Nevertheless, one can still define at build-time _one_ specific kernel (for the real and the complex case each). Then, ELPA is configured only with this real (and complex) kernel, and all run-time checking is disabled. Have a look at the "configure --help" messages and please refer to the file "./src/elpa2_kernels/README_elpa2_kernels.txt". 1.3) Setting up Blacs/Scalapack The configure script tries to auto-detect an installed Blacs/Scalapack library. If this is successful, you do not have to specify anything in this regard. However, this will fail, if you do not use Netlib Blacs/Scalapack but vendor specific implementations (e.g. Intel's MKL library or the implementation of Cray and so forth...). In this case, please point to your Blacs/Scalapack installation and the link-line with the variables "SCALAPACK_LDFLAGS" and "SCALAPACK_FCFLAGS". "SCALAPACK_LDFLAGS" should contain the correct link-line for your Blacs/Scalapack installation and "SCALAPACK_FCFLAGS" the include path and any other flags you need at compile time. For example with Intel's MKL 11.2 library one might have to set SCALAPACK_LDFLAGS="-L$MKLROOT/lib/intel64 -lmkl_scalapack_lp64 -lmkl_intel_lp64 \ -lmkl_sequential -lmkl_core -lmkl_blacs_intelmpi_lp64 \ -lpthread -lm -Wl,-rpath,$MKL_HOME/lib/intel64" and SCALAPACK_FCFLAGS="-I$MKLROOT/include/intel64/lp64" Note, that the actual MKL linkline depends on the installed MKL version. If your libraries are in non-standard locations, you can think about specifying a runtime library search path ("rpath") in the link-line, otherwise it will be necessary to update the LD_LIBRARY_PATH environment variable. In any case, auto-detection or manual specification of Blacs/Scalapack, the configure procedure will check whether Blacs/Scalapack is available at build-time and try to link with it. 1.4) Setting optimizations Please set the optimisation that you prefer with the variable "FCFLAGS", "CFLAGS", and "CXXFLAGS", please see "./src/elpa2_kernels/README_elpa2_kernels.txt". Note that _NO_ compiler optimization flags are set automatically. It is always adviced to set them by e.g.: ./configure CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2" Note that it is mandatory to set optimization flags for C, C++, and Fortran since ELPA uses source files and compile steps from all these languages. Also note that building of the SSE and AVX kernels, requires compilation with the GNU C Compiler (gcc). It is advised to set also CFLAGS="-march=native" CXXFLAGS="-march=native", since otherwise the GNU compiler does not support AVX, even if the hardware does. If you already included "-mAVX" in the flags, you can skip "-march=native". If you want to use the newer AVX2 instructions, assuming they are supported on your hardware, please set CFLAGS="-march=avx2 -mfma" and CXXFLAGS="-march=avx2 -mfma". Setting the optimization flags for the AVX kernels can be a hassle. If AVX kernels are build for your system, you can set the configure option "--with-avx-optimizations=yes". This will automatically set a few compiler optimization flags which turned out to be beneficial for AVX support. However, it might be that on your system/compiler version etc. other flags are the better choice. AND this does _not_ set the above mentioned flags, which you should still set by hand: ./configure CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2" An istallation with AVX2 and best-optimizations could thus look like this: ./configure CFLAGS="-O2 -mavx2 -mfma" CXXFLAGS="-O2 -mavx2 -mfma" FCFLAGS="-O2" --with-avx-optimization 1.5) Installation location Set the "--prefix" flag if you wish another installation location than the default "/usr/local/". 1.6) Hybrid OpenMP support If you want to use the hybrid MPI/OpenMP version of ELPA please specify "--enable-openmp". Note that the ELPA library will then contain a "_mt" in it's name to indicate multi threading support. 1.7) Other Note, that at the moment we do not officially support "cross compilation" although it should work. 2) run "make" 3) run "make check" A simple test of ELPA is done. At the moment the usage of "mpiexec" is required. If this is not possible at your system, you can run the binaries elpa1_test_real elpa2_test_real elpa1_test_complex elpa2_test_complex elpa2_test_complex_default_kernel elpa2_test_complex_choose_kernel_with_api elpa2_test_real_default_kernel elpa2_test_real_choose_kernel_with_api yourself. At the moment the tests check whether the residual and the orthogonality of the found eigenvectors are lower than a threshold of 5e-12. If this test fails, or if you believe the threshold should be even lower, please talk to us. Furthermore, your run-time choice of ELPA kernels is tested. This is intended as a help to get used to this new feature. With the same thought in mind, a binary "elpa2_print_kernels" is provided, which is rather self-explanatory. Also some of the above mentioned tests are provided as C source files. These should demonstrate, how to call ELPA from a C program (i.e. which headers to include and call the ELPA functions). They are NOT intended as a copy and paste solution! 4) run "make install" Note that a pkg-config file for ELPA is produced. You should then be able to link the ELPA library to your own applications. B) Installing ELPA without the autotools procedure =================================================== We do not support installation without the autotools anymore! If you think you need this, sorry, but then you are on your own. How to use ELPA =============== Using ELPA should be quite simple. It is similar to ScalaPack but the API is different. See the examples in the directory "./test". There it is shown how to evoke ELPA from a Fortran code. If you installed ELPA, a pkg-config file is produced which will tell you how to link your own program with ELPA.