INSTALL 7.68 KB
Newer Older
1
2
3
How to install ELPA:
----------------------

4
First of all, if you do not want to build ELPA yourself, and you run Linux,
5
6
it is worth haveing a look at the ELPA webpage and/or the repositories of
your Linux distibution: there exist pre-build packages for a few
7
8
9
10
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,
11
12
13
14
15
16
17
18
please note that ELPA is shipped with a typical "configure" and "make"
procedure. It is recommended to use this way to install ELPA, see (A).
If you do not want to  install ELPA as library, but to include it in your
source code, please refer to point (B). Note, that this is not recommended
and no support whatsoever can be given for this approach !
However, an example makefile "Makefile.example" can be found in ./test,
to give some hints how this is done. Please distibute then all files of ELPA
with your code. Please note, that usage of ELPA as described in Section (B)
19
20
21
requires advanced knowledge about compilers, preprocessor flags, and
optimizations. Please also not, that we cannot give any official support if
ELPA is used as described in Section (B)!
22
23
24
25
26
27
28
29



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

The configure installation is best done in four steps

30
31
32
1) run configure:

   Check the available options with "configure --help".
33
   ELPA is shipped with several different versions of the
34
35
36
37
38
   elpa2-kernel, each is optimized and tuned for a different
   architecture.

1.1) Choice of ELPA2 kernels

39
   With the release of ELPA (2014.06 or newer) it is _not_
40
41
   mandatory anymore to define the (real and complex) kernels
   at build time. The configure procedure will build all the
42
43
   kernels which can be used on the build system. The choice of
   the kernels is now a run-time option. This is the most
44
45
46
47
   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_
48
49
   specific kernel (for the real and the complex case each).
   Then, ELPA is configured only with this real (and complex)
50
51
52
53
54
   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".


55
1.2 Setting up Blacs/Scalapack
56

57
58
   The configure script tries to auto-detect an installed Blacs/Scalapack
   library. If this is successfull, you do not have to specify anything
59
60
   in this regard. However, this will fail, if you do not use Netlib
   Blacs/Scalapack but vendor specific implementations (e.g. Intel's MKL
61
62
63
64
65
66
   library or the implementation of Cray).

   Please then point to your Blacs/Scalapack installation and the
   linkline with the variables "SCALAPACK_LDFLAGS" and "SCALAPACK_FCFLAGS".
   "SCALAPACK_LDFLAGS" should  contain the correct linkline for your
   Blacs/Scalapack installation and "SCALAPACK_FCFLAGS" the include path
67
68
69
70
71
72
   and any other flags you need at compile time.

   It is recommended that you use the "rpath functionality" in the linkline,
   otherwise it will be necessary to update the LD_LIBRARY_PATH environment
   variable.

73
74
75
   In any case, auto-detection of manual specifing of Blacs/Scalapack,
   the configure procedure will check whether Blacs/Scalapack is available
   at build-time and try to link with it.
76
77

1.3 Setting optimizations
78

79
   Please set the optimisation that you prefer with the
80
81
82
   variable "FCFLAGS", "CFLAGS", and "CXXFLAGS", e.g. FCFLAGS="-O3 -xAVX",
   please see "./src/elpa2_kernels/README_elpa2_kernels.txt".

83
84
85
86
87
   Note that _NO_ compiler omptimization flags are set automatically. It
   is always adviced to set the by e.g.:

   CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2" ./configure

88
   Setting the optimization flags for the AVX kernels can be a hazel. If AVX
89
90
91
92
   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
93
94
95
96
97
98
   are the better choice. AND this thus _not_ set the above mentioned flags,

   which you should still set by hand:

   CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2" ./configure

99
100
101

1.4 Installation location

102
103
104
   Set the "prefix" - flag, if you wish another installation location than
   the default "/usr/local/".

105
106
1.5 Hybrid OpenMP support

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

111
1.6 Other
112
113
114
115
116
117
118
119
120

   Note, that at the moment we do not officially support "cross compilation"
   allthough 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
121
   binaries "elpa1_test_real", "elpa2_test_real",
122
123
124
   "elpa1_test_complex", "elpa2_test_complex",
   "elpa2_test_complex_default_kernel", "elpa2_test_complex_choose_kernel_with_api",
   "elpa2_test_real_default_kernel", and "elpa2_test_real_choose_kernel_with_api"
125
126
127
   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
128
129
   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
130
   new feature. With the same thought in mind, a binary "elpa2_print_kernels"
131
   is provided, which is rather self-explanatory.
132
133
134
135
136
137
138
139
140
141


4) run "make install"
   Note that a pckconfig 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
===================================================
    You can find an example makefile "Makefile.example" in "./test",
142
    to see how you can use ELPA directly in your code, and not as library.
143
144
145
    If you do so, please distibute then all files of ELPA with your code.

    However, this is not the recommended way for several reasons:
146
     - for several releases, ELPA has grown substantially in performance
147
148
149
150
151
       optimizations but also complexity. The simple "just use elpa source
       files in your code" approach is becoming more and more difficult.
    - you still have to choose an elpa2-kernel (see at (A)). Getting them
      build from hand might be tedious.
    - the file elpa2.F90 uses preprocessor defines for the different kernels.
152
      you will have to do this by hand, if you do not use the autotools
153
154
155
156
      infrastructure.
    - also the test programs now use preprocessor defines, discriminating
      between version with and without OpenMP
    - it is entirely possible that due to ever growing complexity of ELPA
157
      in future releases the build procedure without autotools will not be
158
      supported anymore
159

160
161
162
163
164
165

    Thus, if you really want to use ELPA this way and not with the autotools
    please ensure the following
    - make yourself familiar with the preprocessor flags you will need
      for your configuration of ELPA and define them in a file "config-f90.h"
    - adapte the Makefile.example accordingly to your needs
166

167
168
169
170
171
172
173
174
175
176
    Again, it is strongly encouraged to use the autotools build procedure!

How to use ELPA:
-----------------
Using ELPA should be quite simple. It is similiar to ScalaPack but the API
is different. See the examples in the directory "./test". There is shown how
to evoke ELPA from a Fortran code.

If you installed ELPA with the build procedure a pk-config file is produced,
which will tell you how to link against ELPA.