Commit f4f59b5d authored by Andreas Marek's avatar Andreas Marek Committed by Lorenz Huedepohl

ELPA 2015.02.002 release

- provide C interface for ELPA Library

- correct an error in the test case for QR-decomposition
parent 16f52e50
......@@ -10,9 +10,9 @@ set forth below.
****
The code is distributed under the terms of the GNU Lesser General Public
License version 3 (LGPL). The full text can be found in the file "lgpl.txt"
in this repository. "lgpl.txt" makes reference to the GPL v3, which can also
The code is distributed under the terms of the GNU Lesser General Public
License version 3 (LGPL). The full text can be found in the file "lgpl.txt"
in this repository. "lgpl.txt" makes reference to the GPL v3, which can also
be found in this repository ("gpl.txt").
****
......
How to install ELPA:
----------------------
How to install ELPA
===================
First of all, if you do not want to build ELPA yourself, and you run Linux,
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
distributions like Fedora, Debian, and Opensuse. More, will hopefully follow
in the future.
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"
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)
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)!
procedure. This is the only supported way how to build and install ELPA.
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.
(A): Installing ELPA as library with configure
......@@ -37,7 +32,7 @@ The configure installation is best done in four steps
1.1) Choice of ELPA2 kernels
With the release of ELPA (2014.06 or newer) it is _not_
mandatory anymore to define the (real and complex) kernels
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
......@@ -55,22 +50,23 @@ The configure installation is best done in four steps
1.2 Setting up Blacs/Scalapack
The configure script tries to auto-detect an installed Blacs/Scalapack
library. If this is successfull, you do not have to specify anything
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).
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
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.
It is recommended that you use the "rpath functionality" in the linkline,
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 of manual specifing of Blacs/Scalapack,
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.
......@@ -80,26 +76,28 @@ The configure installation is best done in four steps
variable "FCFLAGS", "CFLAGS", and "CXXFLAGS", e.g. FCFLAGS="-O3 -xAVX",
please see "./src/elpa2_kernels/README_elpa2_kernels.txt".
Note that _NO_ compiler omptimization flags are set automatically. It
is always adviced to set the by e.g.:
Note that _NO_ compiler optimization flags are set automatically. It
is always adviced to set them by e.g.:
CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2" ./configure
./configure CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2"
Setting the optimization flags for the AVX kernels can be a hazel. If AVX
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
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 thus _not_ set the above mentioned flags,
which you should still set by hand:
CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2" ./configure
./configure CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2"
1.4 Installation location
Set the "prefix" - flag, if you wish another installation location than
Set the "--prefix" flag if you wish another installation location than
the default "/usr/local/".
1.5 Hybrid OpenMP support
......@@ -111,17 +109,25 @@ The configure installation is best done in four steps
1.6 Other
Note, that at the moment we do not officially support "cross compilation"
allthough it should work.
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"
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", and "elpa2_test_real_choose_kernel_with_api"
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
......@@ -132,45 +138,24 @@ The configure installation is best done in four steps
4) run "make install"
Note that a pckconfig file for ELPA is produced. You should then be
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
===================================================
You can find an example makefile "Makefile.example" in "./test",
to see how you can use ELPA directly in your code, and not as library.
If you do so, please distibute then all files of ELPA with your code.
However, this is not the recommended way for several reasons:
- for several releases, ELPA has grown substantially in performance
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.
you will have to do this by hand, if you do not use the autotools
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
in future releases the build procedure without autotools will not be
supported anymore
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
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
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 with the build procedure a pk-config file is produced,
which will tell you how to link against ELPA.
If you installed ELPA, a pkg-config file is produced which will tell you how to
link your own program with ELPA.
......@@ -10,3 +10,17 @@ https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
conditions.
The state of release 2014.06.001 defines this interface
- 2
Incompatible API change. The routine for ELPA 2 real case takes an
optional argument, defining whether QR decomposition is used or not
The state of release 2015.02.001 defines this interface
- 3
Incompatible API change. C Functions are added to provide an C interface.
The subroutine "get_elpa_row_col_comms" has been converted to a function
which returns an error code.
The state of release 2015.02.002 defines this interface
......@@ -10,49 +10,15 @@ a) ABI change
Most importantly, the ABI of the ELPA libray changed!
A rebuild/relink of the user code using the ELPA library is mandatory!
Hopefully, this will be the last ABI change for some time.
b) QR-decomposition
---------------------
The only major change (which results in point a) is in the ELPA-2
part of the library for real matrices:
the fully blocked QR decomposition has been moved from the development part
to the release!
It is now possible to use this QR decomposition by either setting an
environment variable "ELPA_QR_DECOMPOSITION" to "yes", or to call the
"solve_evp_real_2stage" solver with the additional (optional) argument
"useQR=.true."
Note, that the environment variable always takes precedence over the setting in
the API call.
Furthernote, that if neither the environment variable or the API keyword are not
set, or set to "no" or ".false.", respectively, then no QR-decomposition is used
(i.e. the previous behaviour is maintained).
The QR-decomposition fails, if the chosen matrix size is not a multiple of the
blocksize. The library will give a warning message if this happens and it will
abort.
c) Debug messages
----------------------
By setting the environment variable "ELPA_DEBUG_MESSAGES" to "yes", ELPA will now
print more information if an error occurs.
d) Optimization flags
-----------------------
The configure procedure was adapted to be more consistent. No compiler omptimization
flags are set automatically anymore, this is up to the user at build time
e) OpenMP check
b) C interface
----------------------
The checks for OpenMP in the configure have been improved
ELPA now is shipped with a C interface to directly call the ELPA library (written in Fortran)
from C code. Header files are provided to declare the c functions.
Since ELPA is still a Fortran library it might be necessary to link it together with the needed
Fortran runtime libraries in your C code.
......
AC_PREREQ([2.69])
AC_INIT([elpa],[2015.02.001], [elpa-library@rzg.mpg.de])
AC_INIT([elpa],[2015.02.002], [elpa-library@rzg.mpg.de])
AC_SUBST([PACKAGE_VERSION])
AC_CONFIG_SRCDIR([src/elpa1.F90])
......@@ -34,7 +34,7 @@ rm -rf config.h config-f90.h
# by the current interface, as they are ABI compatible (e.g. only new symbols
# were added by the new interface)
#
AC_SUBST([ELPA_SO_VERSION], [2:0:0])
AC_SUBST([ELPA_SO_VERSION], [3:0:0])
#
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment