INSTALL.md

@@ -2,10 +2,22 @@
 
 ## Preamble ##
 
-This file provides documentation on how to build the *ELPA* library in **version ELPA-2018.05.001**.
+This file provides documentation on how to build the *ELPA* library in **version ELPA-2018.11.001.rc1**.
 With release of **version ELPA-2017.05.001** the build process has been significantly simplified,
 which makes it easier to install the *ELPA* library.
 
+The old, obsolete legacy API will be deprecated in the future !
+Allready now, all new features of ELPA are only available with the new API. Thus, there
+is no reason to keep the legacy API arround for too long.
+
+The release ELPA 2018.11.001 will be the last release, where the legacy API is
+enabled by default (and can be disabled at build time).
+With release ELPA 2019.05.001 the legacy API will be disabled by default, however,
+can be still switched on at build time.
+Most likely with the release ELPA 2019.11.001 the legacy API will be deprecated and not supported anymore.
+
+The release of ELPA 2018.11.001 changes the ABI and API, since more functions have an error argument. In C this error argument is required, in Fortran it is optional.
+
 ## How to install *ELPA* ##
 
 First of all, if you do not want to build *ELPA* yourself, and you run Linux,
@@ -64,6 +76,11 @@ An excerpt of the most important (*ELPA* specific) options reads as follows:
 |  --enable-autotuning                 | enables autotuning functionality, default yes         |
 |  --enable-c-tests                    | enables the C tests for elpa, default yes             |
 | --disable-assumed-size               | do NOT use assumed-size Fortran arrays. default use   |
+| --enable-scalapack-tests             | build also ScalaPack tests for performance comparison; needs MPI |
+| --disable-Fortran2008-features       | disable Fortran 2008 if compiler does not support it  |
+| --enable-pyhton                      | build and install python wrapper, default no          |
+| --enable-python-tests                | enable python tests, default no.                      |
+
 
 We recommend that you do not build ELPA in its main directory but that you use it
 in a sub-directory:
@@ -105,7 +122,7 @@ explicitely enabled.
 Please note, that it is absolutely supported that both versions of the *ELPA* library are build
 and installed in the same directory.
 
-### A) Setting of MPI compiler and libraries ###
+#### A) Setting of MPI compiler and libraries ####
 
 In the standard case *ELPA* needs a MPI compiler and MPI libraries. The configure script
 will try to set this by itself. If, however, on the build system the compiler wrapper
@@ -125,7 +142,7 @@ to the configure call.
 Please continue reading at "C) Enabling GPU support"
 
 
-### B) Building *ELPA* without MPI support ###
+#### B) Building *ELPA* without MPI support ####
 
 If you want to build *ELPA* without MPI support, add
 
@@ -145,7 +162,7 @@ Note, that the installed *ELPA* library files will be suffixed with
 
 Please continue reading at "C) Enabling GPU support"
 
-### C) Enabling GPU support ###
+### Enabling GPU support ###
 
 The *ELPA* library can be build with GPU support. If *ELPA* is build with GPU
 support, users can choose at RUNTIME, whether to use the GPU version or not.
@@ -165,7 +182,7 @@ It might be necessary to also set the options (please see configure --help)
 Please continue reading at "D) Enabling OpenMP support".
 
 
-### D) Enabling OpenMP support ###
+### Enabling OpenMP support ###
 
 The *ELPA* library can be build with OpenMP support. This can be support of hybrid
 MPI/OpenMP parallelization, since *ELPA* is build with MPI support (see A ) or only
@@ -185,7 +202,7 @@ However, the GPU choice at runtime is not compatible with OpenMP support.
 Please continue reading at "E) Standard libraries in default installation paths".
 
 
-### E) Standard libraries in default installation paths###
+### Standard libraries in default installation paths ###
 
 In order to build the *ELPA* library, some (depending on the settings during the
 configure step) libraries are needed.
@@ -207,7 +224,7 @@ If your configure steps finish succcessfully, please continue at "G) Choice of E
 If your configure step aborts, or you want to use libraries in non standard paths please continue at
 "F) Non standard paths or non standard libraries".
 
-### F) Non standard paths or non standard libraries ###
+### Non standard paths or non standard libraries ###
 
 If standard libraries are on the build system either installed in non standard paths, or
 special non standard libraries (e.g. *Intel's MKL*) should be used, it might be necessary
@@ -236,18 +253,26 @@ Please, for the correct link-line refer to the documentation of the correspondig
 suggest the [Intel Math Kernel Library Link Line Advisor] (https://software.intel.com/en-us/articles/intel-mkl-link-line-advisor).
 
 
-### G) Choice of ELPA2 compute kernels ###
+### Choice of ELPA2 compute kernels ###
 
 ELPA 2stage can be used with different implementations of compute intensive kernels, which are architecture dependent.
 Some kernels (all for x86_64 architectures) are enabled by default (and must be disabled if you do not want them),
 others are disabled by default and must be enabled if they are wanted.
 
-One can enable or disable "kernel classes" by setting e.g.
+One can enable "kernel classes" by setting e.g.
 
 --enable-avx2 
 
+
 This will try to build all the AVX2 kernels. Please see configure --help for all options
 
+With
+
+--disable-avx2
+
+one chan choose not to build the AVX2 kernels.
+
+
 During the configure step all possible kernels will be printed, and whether they will be enabled or not.
 
 It is possible to build *ELPA* with as many kernels as desired, the user can then choose at runtime which
@@ -257,6 +282,44 @@ It this is not desired, it is possible to build *ELPA* with only one (not necess
 real and complex valued case, respectively. This can be done with the "--with-fixed-real-kernel=NAME" or
 "--with-fixed-complex-kernel=NAME" configure options. For details please do a "configure --help"
 
+#### Cross compilation ####
+
+The ELPA library does _not_ supports cross-compilation by itself, i.e. compilation of the ELPA library on an architecture wich is not
+identical than the architecture ELPA should be used on.
+
+Whenever a cross-compilation situation might occur, great care has to be taken during the build process by the user.
+
+At the moment we see two potential pitfalls:
+
+1.) The "build architecure" is inferior to the "target" architecture (w.r.t. the instructions sets)
+
+In this case, at the moment, the ELPA library can only be build with instructions sets supported on the build
+system. All later instruction sets will _not_ be used in the compilation. This case might lead to less optimal
+performance compared to the case that ELPA is build directly on the target system.
+
+For example, if the "build architecture" consists of an HASWELL node (supporting up to Intel's AVX2 instruction set) and the 
+"target architecture" is a Skylake node (supporting Intel's AVX-512 instruction set) than the AVX-512 kernels can not be build
+This will lead to a performance degradation on the Skylake nodes, but is otherwise harmless (no chrashes).
+
+
+2.) The "build architecure" is superior to the "target" architecture (w.r.t. the instructions sets)
+
+This case is a critical one, since ELPA will by default build with instructions sets which are not supported on the target
+system. This will lead to crashes, if during build the user does not take care to solve this issue.
+
+For example, if the "build architecture" supports Intels' AVX-2 instruction set and the 
+"target architecture" does only support Intel's AVX instruction set, then by default ELPA will be build with AVX-2 instruction set
+and this will also be used at runtime (since it improves the performance). However, at the moment, since the target system does not support
+AVX-2 instructions this will lead to a crash.
+
+One can avoid this unfortunate situation by disabling instructions set which are _not_ supported on the target system.
+In the case above, setting
+
+--disable-avx2
+
+during build, will remdy this problem.
+
+
 ### Doxygen documentation ###
 A doxygen documentation can be created with the "--enable-doxygen-doc" configure option