INSTALL 9.22 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
autotools procedure. This is the only supported way how to build and install ELPA.
13

14
15
16
17
18
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.


Andreas Marek's avatar
Andreas Marek committed
19
If --- against our recommendations --- you do not want to install ELPA as
20
21
22
23
24
25
26
27
28
29
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.
30
31
32
33
34
35
36


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

The configure installation is best done in four steps

37
38
39
1) run configure:

   Check the available options with "configure --help".
40
   ELPA is shipped with several different versions of the
41
42
43
   elpa2-kernel, each is optimized and tuned for a different
   architecture.

44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
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
69

70
   With the release of ELPA (2014.06 or newer) it is _not_
Andreas Marek's avatar
Andreas Marek committed
71
   mandatory any more to define the (real and complex) kernels
72
   at build time. The configure procedure will build all the
73
74
   kernels which can be used on the build system. The choice of
   the kernels is now a run-time option. This is the most
75
76
77
78
   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_
79
80
   specific kernel (for the real and the complex case each).
   Then, ELPA is configured only with this real (and complex)
81
82
83
84
85
   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".


86
1.3) Setting up Blacs/Scalapack
87

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

94
   In this case, please  point to your Blacs/Scalapack installation and the
Andreas Marek's avatar
Andreas Marek committed
95
96
   link-line with the variables "SCALAPACK_LDFLAGS" and "SCALAPACK_FCFLAGS".
   "SCALAPACK_LDFLAGS" should  contain the correct link-line for your
97
   Blacs/Scalapack installation and "SCALAPACK_FCFLAGS" the include path
98
99
   and any other flags you need at compile time.

100
101
102
103
104
105
106
   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

Andreas Marek's avatar
Andreas Marek committed
107
   SCALAPACK_FCFLAGS="-I$MKLROOT/include/intel64/lp64"
108
109
110

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

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

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

120
1.4) Setting optimizations
121

Andreas Marek's avatar
Andreas Marek committed
122

123
   Please set the optimisation that you prefer with the
Andreas Marek's avatar
Andreas Marek committed
124
   variable "FCFLAGS", "CFLAGS", and "CXXFLAGS",
125
126
   please see "./src/elpa2_kernels/README_elpa2_kernels.txt".

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

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

Andreas Marek's avatar
Andreas Marek committed
132
133
134
   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.

Andreas Marek's avatar
Andreas Marek committed
135
136
137
138
139
140
141
   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".

142
143
144
   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".

Andreas Marek's avatar
Andreas Marek committed
145

Andreas Marek's avatar
Andreas Marek committed
146
   Setting the optimization flags for the AVX kernels can be a hassle. If AVX
147
148
149
150
   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
Andreas Marek's avatar
Andreas Marek committed
151
   are the better choice. AND this does _not_ set the above mentioned flags,
152
153
   which you should still set by hand:

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

156
157
158
   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
159

160
1.5) Installation location
161

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

165
1.6) Hybrid OpenMP support
166

167
   If you want to use the hybrid MPI/OpenMP version of ELPA please specify
Andreas Marek's avatar
Andreas Marek committed
168
   "--enable-openmp". Note that the ELPA library will then contain a "_mt" in
169
   it's name to indicate multi threading support.
170

171
1.7) Other
172
173

   Note, that at the moment we do not officially support "cross compilation"
Andreas Marek's avatar
Andreas Marek committed
174
   although it should work.
175
176
177
178

2) run "make"

3) run "make check"
Andreas Marek's avatar
Andreas Marek committed
179
180

   A simple test of ELPA is done. At the moment the usage of "mpiexec"
181
   is required. If this is not possible at your system, you can run the
Andreas Marek's avatar
Andreas Marek committed
182
183
184
185
186
187
188
189
190
191
192
   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

193
194
195
   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
196
197
   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
198
   new feature. With the same thought in mind, a binary "elpa2_print_kernels"
199
   is provided, which is rather self-explanatory.
200

201
202
203
204
   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!

205
206

4) run "make install"
Andreas Marek's avatar
Andreas Marek committed
207
208

   Note that a pkg-config file for ELPA is produced. You should then be
209
210
211
212
213
   able to link the ELPA library to your own applications.


B) Installing ELPA without the autotools procedure
===================================================
Andreas Marek's avatar
Andreas Marek committed
214
215
216
217
218
219
220
221
222
223

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

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