INSTALL 6.87 KB
Newer Older
Andreas Marek's avatar
Andreas Marek committed
1
2
How to install ELPA
===================
3

4
First of all, if you do not want to build ELPA yourself, and you run Linux,
Andreas Marek's avatar
Andreas Marek committed
5
6
7
8
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.
9
10

If you want to build (or have to since no packages are available) ELPA yourself,
11
please note that ELPA is shipped with a typical "configure" and "make"
Andreas Marek's avatar
Andreas Marek committed
12
procedure. This is the only supported way how to build and install ELPA.
13

Andreas Marek's avatar
Andreas Marek committed
14
15
16
17
If --- against our recommendations --- you do not want to install ELPA as
library, but to include it in your source code you will have to find a solution
by yourself. If you do this anyway, please distribute then all files of ELPA
with your code.
18
19
20
21
22
23
24


(A): Installing ELPA as library with configure
===================================================

The configure installation is best done in four steps

25
26
27
1) run configure:

   Check the available options with "configure --help".
28
   ELPA is shipped with several different versions of the
29
30
31
32
33
   elpa2-kernel, each is optimized and tuned for a different
   architecture.

1.1) Choice of ELPA2 kernels

34
   With the release of ELPA (2014.06 or newer) it is _not_
Andreas Marek's avatar
Andreas Marek committed
35
   mandatory any more to define the (real and complex) kernels
36
   at build time. The configure procedure will build all the
37
38
   kernels which can be used on the build system. The choice of
   the kernels is now a run-time option. This is the most
39
40
41
42
   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_
43
44
   specific kernel (for the real and the complex case each).
   Then, ELPA is configured only with this real (and complex)
45
46
47
48
49
   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".


50
1.2 Setting up Blacs/Scalapack
51

52
   The configure script tries to auto-detect an installed Blacs/Scalapack
Andreas Marek's avatar
Andreas Marek committed
53
   library. If this is successful, you do not have to specify anything
54
55
   in this regard. However, this will fail, if you do not use Netlib
   Blacs/Scalapack but vendor specific implementations (e.g. Intel's MKL
56
   library or the implementation of Cray and so forth...).
57

58
   In this case, please  point to your Blacs/Scalapack installation and the
Andreas Marek's avatar
Andreas Marek committed
59
60
   link-line with the variables "SCALAPACK_LDFLAGS" and "SCALAPACK_FCFLAGS".
   "SCALAPACK_LDFLAGS" should  contain the correct link-line for your
61
   Blacs/Scalapack installation and "SCALAPACK_FCFLAGS" the include path
62
63
   and any other flags you need at compile time.

64
65
66
67
68
69
70
71
72
73
74
75
76
   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="-L$MKLROOT/mkl/lib/intel64 -lmkl_scalapack_lp64 -lmkl_intel_lp64 \
                      -lmkl_sequential -lmkl_core -lmkl_blacs_intelmpi_lp64 -lpthread  \
		      -lm -I$MKLROOT/include/intel64/lp64"

   Note, that the actual MKL linkline depends on the installed MKL version.

Andreas Marek's avatar
Andreas Marek committed
77
78
   If your libraries are in non-standard locations, you can think about
   specifying a runtime library search path ("rpath") in the link-line,
79
80
81
   otherwise it will be necessary to update the LD_LIBRARY_PATH environment
   variable.

Andreas Marek's avatar
Andreas Marek committed
82
   In any case, auto-detection or manual specification of Blacs/Scalapack,
83
84
   the configure procedure will check whether Blacs/Scalapack is available
   at build-time and try to link with it.
85
86

1.3 Setting optimizations
87

88
   Please set the optimisation that you prefer with the
89
90
91
   variable "FCFLAGS", "CFLAGS", and "CXXFLAGS", e.g. FCFLAGS="-O3 -xAVX",
   please see "./src/elpa2_kernels/README_elpa2_kernels.txt".

Andreas Marek's avatar
Andreas Marek committed
92
93
   Note that _NO_ compiler optimization flags are set automatically. It
   is always adviced to set them by e.g.:
94

Andreas Marek's avatar
Andreas Marek committed
95
   ./configure CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2"
96

Andreas Marek's avatar
Andreas Marek committed
97
98
99
100
   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.

   Setting the optimization flags for the AVX kernels can be a hassle. If AVX
101
102
103
104
   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
105
106
107
   are the better choice. AND this thus _not_ set the above mentioned flags,
   which you should still set by hand:

Andreas Marek's avatar
Andreas Marek committed
108
   ./configure CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2"
109

110
111
112

1.4 Installation location

Andreas Marek's avatar
Andreas Marek committed
113
   Set the "--prefix" flag if you wish another installation location than
114
115
   the default "/usr/local/".

116
117
1.5 Hybrid OpenMP support

118
   If you want to use the hybrid MPI/OpenMP version of ELPA please specify
119
120
   "--with-openmp". Note that the ELPA library will then contain a "_mt" in
   it's name to indicate multi threading support.
121

122
1.6 Other
123
124

   Note, that at the moment we do not officially support "cross compilation"
Andreas Marek's avatar
Andreas Marek committed
125
   although it should work.
126
127
128
129

2) run "make"

3) run "make check"
Andreas Marek's avatar
Andreas Marek committed
130
131

   A simple test of ELPA is done. At the moment the usage of "mpiexec"
132
   is required. If this is not possible at your system, you can run the
Andreas Marek's avatar
Andreas Marek committed
133
134
135
136
137
138
139
140
141
142
143
   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

144
145
146
   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
147
148
   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
149
   new feature. With the same thought in mind, a binary "elpa2_print_kernels"
150
   is provided, which is rather self-explanatory.
151
152
153


4) run "make install"
Andreas Marek's avatar
Andreas Marek committed
154
155

   Note that a pkg-config file for ELPA is produced. You should then be
156
157
158
159
160
   able to link the ELPA library to your own applications.


B) Installing ELPA without the autotools procedure
===================================================
Andreas Marek's avatar
Andreas Marek committed
161
162
163
164
165
166
167
168
169
170

   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
171
172
to evoke ELPA from a Fortran code.

Andreas Marek's avatar
Andreas Marek committed
173
174
If you installed ELPA, a pkg-config file is produced which will tell you how to
link your own program with ELPA.