Smaller changes for ELPA 2014.06 release

- the library version number is changed due to change in ABI
- the INSTALL ascii file is updated
- a RELEASE_NOTES file is introduced

ELPA_2014.06/INSTALL

@@ -7,7 +7,9 @@ install ELPA as library, but to include it in your source code, please refer
 to point (B). 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.
+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)!
 
 
 
@@ -20,20 +22,32 @@ The configure installation is best done in four steps
    
    Check the available options with "configure --help". 
    ELPA is shipped with several different versions of the
-   elpa2-kernel, each optimized and tuned for a different
-   architecture. Since, at the moment we do not want to
-   define a default, which works but maybe with less then
-   the optimal performance, it is MANDATORY that you choose
-   (real and complex kernels) for your system, via the
-   "--with-..." option. For hints which kernels might be best
-   for you, please refer to the file 
-   "./src/elpa2_kernels/README_elpa2_kernels.txt".
-   If no kernel is specified at the configure step an exception
-   prompting this error is thrown.
+   elpa2-kernel, each is optimized and tuned for a different
+   architecture.
+
+1.1) Choice of ELPA2 kernels
+
+   With this release of ELPA (2014.06 or newer) it is _not_
+   mandatory anymore 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.2 Setting up blacs/scalapack
 
    Please point to your blacs/scalapack installation and the
    linkline with the variables "BLACS_LDFLAGS" and "BLACS_FCFLAGS".
-   "BLACS_LDFLAGS" should then contain the correct linkline for your
+   "BLACS_LDFLAGS" should  contain the correct linkline for your
    blacs/scalapack installation and "BLACS_FCFLAGS" the include path
    and any other flags you need at compile time.
 
@@ -43,21 +57,36 @@ The configure installation is best done in four steps
 
    You can either specify your own builds of lapack/blacs/scalapack
    or use specialized Vendor packages, e.g. if available you can use 
-   Intel's MKL. If you do not set the variables "BLACS_LDFLAGS" and 
-   "BLACS_FCFLAGS" ELPA will not be build! 
+   Intel's MKL. 
+
+   The configure procedure will check whether blacs/scalapack is available
+   at build-time. If you do not set the variables "BLACS_LDFLAGS" and 
+   "BLACS_FCFLAGS" the chances are high that ELPA will not build.
+
+1.3 Setting optimizations
 
    Please set the optimisation that you would like with the
    variable "FCFLAGS", "CFLAGS", and "CXXFLAGS", e.g. FCFLAGS="-O3 -xAVX",
    please see "./src/elpa2_kernels/README_elpa2_kernels.txt".
 
+   Setting the optimization flags for the AVX kernels can be a hazel. 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.
+
+1.4 Installation location
+
    Set the "prefix" - flag, if you wish another installation location than
    the default "/usr/local/".
 
+1.5 Hybrid OpenMP support
+
    If you want to use the hybrid MPI/OpenMP version of ELPA please specify
-   "--enable-openmp" or "--with-openmp". Note that the Bluegene P/Q kernels
-   are not yet tested in the combination with OpenMP and thus at the moment
-   this combination is switched of. Please see ./src/elpa2_kernels/README_elpa2_kernels.txt for more details and a hint how to use it anyway.
+   "--enable-openmp" or "--with-openmp".
 
+1.6 Other
 
    Note, that at the moment we do not officially support "cross compilation"
    allthough it should work.
@@ -67,11 +96,16 @@ The configure installation is best done in four steps
 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 "test_real", "test_real2", "test_complex", and "test_complex2"
+   binaries "test_real", "test_real2", "test_complex", "test_complex2",
+   "test_complex2_default_kernel", "test_complex2_choose_kernel_with_api",
+   "test_real2_default_kernel", and "test_real2_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.
+   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 "print_available_elpa2_kernels"
+   is provided, which is rather self-explanatory.
 
 
 4) run "make install"
@@ -86,7 +120,7 @@ B) Installing ELPA without the autotools procedure
     If you do so, please distibute then all files of ELPA with your code.
 
     However, this is not the recommended way for several reasons:
-     - from the last release, ELPA has grown substantially in performance
+     - 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

ELPA_2014.06/Makefile.am

@@ -176,11 +176,6 @@ pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = elpa.pc
 
 # test programs
-if WITH_OPENMP
-build_lib = libelpa_mt.la 
-else
-build_lib = libelpa.la 
-endif
 
 #bindir = $(abs_top_builddir)
 bin_PROGRAMS = test_real test_real2 test_real2_default_kernel test_complex test_complex2 test_complex2_default_kernel test_real2_choose_kernel_with_api test_complex2_choose_kernel_with_api print_available_elpa2_kernels

ELPA_2014.06/RELEASE_NOTES

+This file contains the release notes for the ELPA 2014.06.000 version
+
+
+
+What is new?
+-------------
+
+With this release (and newer) it is not mandatory anymore to specify the real
+and complex kernels at build-time! Instead the choice of kernel is now a
+run-time option
+
+The kernels can either be choosen by environment variables "REAL_ELPA_KERNEL" 
+and "COMPLEX_ELPA_KERNEL", or in the code with an additional argument in
+the call to the library (see the examples in ./test for more details)
+
+It is still possible to build ELPA with a specific real and complex kernel, if 
+one wants to obtain the old behaviour (see configure --help for the exact 
+options)
+
+
+Any incompatibles to previous version?
+---------------------------------------
+
+The ABI of ELPA has changed! It will be necessary to rebuild the programs using
+ELPA if this new version should be used. Beware, that not rebuilding the user 
+programs most likely leads to undefined behaviour!
+
+
+

ELPA_2014.06/configure

@@ -3057,7 +3057,8 @@ ELPA_LIB_VERSION=2014.06.000
 
 # this is the version of the API, should be changed in the major revision
 # if and only if the actual API changes
-ELPA_SO_VERSION=0:0:0
+# see http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
+ELPA_SO_VERSION=1:0:0
 
 
  { $as_echo "$as_me:${as_lineno-$LINENO}: checking for GNU make" >&5

ELPA_2014.06/configure.ac

@@ -10,7 +10,8 @@ AM_SILENT_RULES([yes])
 AC_SUBST([ELPA_LIB_VERSION], [2014.06.000])
 # this is the version of the API, should be changed in the major revision
 # if and only if the actual API changes
-AC_SUBST([ELPA_SO_VERSION], [0:0:0])
+# see http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
+AC_SUBST([ELPA_SO_VERSION], [1:0:0])
 
 AX_CHECK_GNU_MAKE()
 if test x$_cv_gnu_make_command = x ; then