Skip to content

GitLab

elpa
elpa
Commit 31a03aa2 authored by Andreas Marek's avatar Andreas Marek
Browse files
Options

Add migration notice

parent 392d782a
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 14 additions and 48733 deletions
.gitignore deleted 100644 → 0
View file @ 392d782a
*.o
*.lo
*.deps
*.dirstamp
*.libs
*.fortran_dependencies
modules/
Makefile.in
aclocal.m4
ar-lib
autom4te.cache
compile
config.guess
config.h.in
config.sub
configure
depcomp
install-sh
ltmain.sh
missing
test-driver
.gitlab-ci.yml deleted 100644 → 0
View file @ 392d782a
jobs:
script: ./autogen.sh && ./configure && make && make check TEST_FLAGS='1500 50 16'
COPYING/COPYING deleted 100644 → 0
View file @ 392d782a
Licensing and copyright terms for the ELPA library:
ELPA Consortium (2011)
****
Copyright of the original code rests with the authors inside the ELPA
consortium. The copyright of any additional modifications shall rest
with their original authors, but shall adhere to the licensing terms
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
be found in this repository ("gpl.txt").
****
ELPA reflects a substantial effort on the part of the original
ELPA consortium, and we ask you to respect the spirit of the
license that we chose: i.e., please contribute any changes you
may have back to the original ELPA library distribution, and keep
any derivatives of ELPA under the same license that we chose for
the original distribution, the GNU Lesser General Public License.
When in doubt, talk to us. What we would like to ensure is that the ELPA
code can be used as needed, while providing a strong incentive for
others to contribute their modifications back to the original development.
****
COPYING/gpl.txt deleted 100644 → 0
View file @ 392d782a
This diff is collapsed.
COPYING/lgpl.txt deleted 100644 → 0
View file @ 392d782a
GNU LESSER GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
This version of the GNU Lesser General Public License incorporates
the terms and conditions of version 3 of the GNU General Public
License, supplemented by the additional permissions listed below.
0. Additional Definitions.
As used herein, "this License" refers to version 3 of the GNU Lesser
General Public License, and the "GNU GPL" refers to version 3 of the GNU
General Public License.
"The Library" refers to a covered work governed by this License,
other than an Application or a Combined Work as defined below.
An "Application" is any work that makes use of an interface provided
by the Library, but which is not otherwise based on the Library.
Defining a subclass of a class defined by the Library is deemed a mode
of using an interface provided by the Library.
A "Combined Work" is a work produced by combining or linking an
Application with the Library. The particular version of the Library
with which the Combined Work was made is also called the "Linked
Version".
The "Minimal Corresponding Source" for a Combined Work means the
Corresponding Source for the Combined Work, excluding any source code
for portions of the Combined Work that, considered in isolation, are
based on the Application, and not on the Linked Version.
The "Corresponding Application Code" for a Combined Work means the
object code and/or source code for the Application, including any data
and utility programs needed for reproducing the Combined Work from the
Application, but excluding the System Libraries of the Combined Work.
1. Exception to Section 3 of the GNU GPL.
You may convey a covered work under sections 3 and 4 of this License
without being bound by section 3 of the GNU GPL.
2. Conveying Modified Versions.
If you modify a copy of the Library, and, in your modifications, a
facility refers to a function or data to be supplied by an Application
that uses the facility (other than as an argument passed when the
facility is invoked), then you may convey a copy of the modified
version:
a) under this License, provided that you make a good faith effort to
ensure that, in the event an Application does not supply the
function or data, the facility still operates, and performs
whatever part of its purpose remains meaningful, or
b) under the GNU GPL, with none of the additional permissions of
this License applicable to that copy.
3. Object Code Incorporating Material from Library Header Files.
The object code form of an Application may incorporate material from
a header file that is part of the Library. You may convey such object
code under terms of your choice, provided that, if the incorporated
material is not limited to numerical parameters, data structure
layouts and accessors, or small macros, inline functions and templates
(ten or fewer lines in length), you do both of the following:
a) Give prominent notice with each copy of the object code that the
Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the object code with a copy of the GNU GPL and this license
document.
4. Combined Works.
You may convey a Combined Work under terms of your choice that,
taken together, effectively do not restrict modification of the
portions of the Library contained in the Combined Work and reverse
engineering for debugging such modifications, if you also do each of
the following:
a) Give prominent notice with each copy of the Combined Work that
the Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the Combined Work with a copy of the GNU GPL and this license
document.
c) For a Combined Work that displays copyright notices during
execution, include the copyright notice for the Library among
these notices, as well as a reference directing the user to the
copies of the GNU GPL and this license document.
d) Do one of the following:
0) Convey the Minimal Corresponding Source under the terms of this
License, and the Corresponding Application Code in a form
suitable for, and under terms that permit, the user to
recombine or relink the Application with a modified version of
the Linked Version to produce a modified Combined Work, in the
manner specified by section 6 of the GNU GPL for conveying
Corresponding Source.
1) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (a) uses at run time
a copy of the Library already present on the user's computer
system, and (b) will operate properly with a modified version
of the Library that is interface-compatible with the Linked
Version.
e) Provide Installation Information, but only if you would otherwise
be required to provide such information under section 6 of the
GNU GPL, and only to the extent that such information is
necessary to install and execute a modified version of the
Combined Work produced by recombining or relinking the
Application with a modified version of the Linked Version. (If
you use option 4d0, the Installation Information must accompany
the Minimal Corresponding Source and Corresponding Application
Code. If you use option 4d1, you must provide the Installation
Information in the manner specified by section 6 of the GNU GPL
for conveying Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the
Library side by side in a single library together with other library
facilities that are not Applications and are not covered by this
License, and convey such a combined library under terms of your
choice, if you do both of the following:
a) Accompany the combined library with a copy of the same work based
on the Library, uncombined with any other library facilities,
conveyed under the terms of this License.
b) Give prominent notice with the combined library that part of it
is a work based on the Library, and explaining where to find the
accompanying uncombined form of the same work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new versions
of the GNU Lesser General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the
Library as you received it specifies that a certain numbered version
of the GNU Lesser General Public License "or any later version"
applies to it, you have the option of following the terms and
conditions either of that published version or of any later version
published by the Free Software Foundation. If the Library as you
received it does not specify a version number of the GNU Lesser
General Public License, you may choose any version of the GNU Lesser
General Public License ever published by the Free Software Foundation.
If the Library as you received it specifies that a proxy can decide
whether future versions of the GNU Lesser General Public License shall
apply, that proxy's public statement of acceptance of any version is
permanent authorization for you to choose that version for the
Library.
Doxyfile.in deleted 100644 → 0
View file @ 392d782a
This source diff could not be displayed because it is too large. You can view the blob instead.
INSTALL deleted 100644 → 0
View file @ 392d782a
How to install ELPA
===================
First of all, if you do not want to build ELPA yourself, and you run Linux,
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"
autotools procedure. This is the only supported way how to build and install ELPA.
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.
If --- against our recommendations --- you do not want to install ELPA as
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.
(A): Installing ELPA as library with configure
===================================================
The configure installation is best done in four steps
1) run configure:
Check the available options with "configure --help".
ELPA is shipped with several different versions of the
elpa2-kernel, each is optimized and tuned for a different
architecture.
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
With the release of ELPA (2014.06 or newer) it is _not_
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
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.3) Setting up Blacs/Scalapack
The configure script tries to auto-detect an installed Blacs/Scalapack
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 and so forth...).
In this case, please point to your Blacs/Scalapack installation and the
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.
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
SCALAPACK_FCFLAGS="-I$MKLROOT/include/intel64/lp64"
Note, that the actual MKL linkline depends on the installed MKL version.
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 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.
1.4) Setting optimizations
Please set the optimisation that you prefer with the
variable "FCFLAGS", "CFLAGS", and "CXXFLAGS",
please see "./src/elpa2_kernels/README_elpa2_kernels.txt".
Note that _NO_ compiler optimization flags are set automatically. It
is always adviced to set them by e.g.:
./configure CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2"
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.
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".
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".
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 does _not_ set the above mentioned flags,
which you should still set by hand:
./configure CFLAGS="-O2" CXXFLAGS="-O2" FCFLAGS="-O2"
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
1.5) Installation location
Set the "--prefix" flag if you wish another installation location than
the default "/usr/local/".
1.6) Hybrid OpenMP support
If you want to use the hybrid MPI/OpenMP version of ELPA please specify
"--enable-openmp". Note that the ELPA library will then contain a "_mt" in
it's name to indicate multi threading support.
1.7) Other
Note, that at the moment we do not officially support "cross compilation"
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"
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
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
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 "elpa2_print_kernels"
is provided, which is rather self-explanatory.
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!
4) run "make install"
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
===================================================
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, a pkg-config file is produced which will tell you how to
link your own program with ELPA.
INSTALL_FROM_GIT_VERSION deleted 100644 → 0
View file @ 392d782a
Welcome to the git-based distribution of the ELPA eigensolver library.
If you are reading this file, you have obtained the ELPA library
through the git repository that hosts the source code and also allows
you to contribute improvements to the project if necessary.
The git version does not contain the necessary build script:
configure, Makefile ...
If you use the git version, you are most likely actively developing
features/improvements for ELPA, and a rebuild of the autotools scripts
will be necessary anyway.
Thus please run "autogen.sh" after your changes, in order to build the
autotoos scripts. Note that autoconf version >= 2.69 is needed for
ELPA.
After this step, please proceed as written in the "INSTALL" file.
LIBRARY_INTERFACE deleted 100644 → 0
View file @ 392d782a
Libtool interface number history (the "c" in [c:r:a] of
https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html).
- 0
Legacy interface number for all releases prior to 2014.06
- 1
Incompatible API change. Most subroutines were converted into functions
returning a success flag. Previously, the library called exit() on error
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
- 4
Incompatible API change. The Fortran versions of the library functions return
a logical indicating success or failure. The C versions of the library functions
return an integer {0,1} for success and failure.
Some interface need an extra argument, specifying the number of matrix columns
(see the documentation)
Makefile.am deleted 100644 → 0
View file @ 392d782a
This diff is collapsed.
README deleted 100644 → 0
View file @ 392d782a
If you obtained ELPA via the official git repository please have
a look at the "INSTALL_FROM_GIT_VERSION" for specific instructions
In your use of ELPA, please respect the copyright restrictions
found below and in the "COPYING" directory in this repository. In a
nutshell, if you make improvements to ELPA, copyright for such
improvements remains with you, but we request that you relicense any
such improvements under the same exact terms of the (modified) LGPL v3
that we are using here. Please do not simply absorb ELPA into your own
project and then redistribute binary-only without making your exact
version of the ELPA source code (unmodified or MODIFIED) available as
well.
*** Citing:
A description of some algorithms present in ELPA can be found in:
T. Auckenthaler, V. Blum, H.-J. Bungartz, T. Huckle, R. Johanni,
L. Kr\"amer, B. Lang, H. Lederer, and P. R. Willems,
"Parallel solution of partial symmetric eigenvalue problems from
electronic structure calculations",
Parallel Computing 37, 783-794 (2011).
doi:10.1016/j.parco.2011.05.002.
Marek, A.; Blum, V.; Johanni, R.; Havu, V.; Lang, B.; Auckenthaler,
T.; Heinecke, A.; Bungartz, H.-J.; Lederer, H.
"The ELPA library: scalable parallel eigenvalue solutions for electronic
structure theory and computational science",
Journal of Physics Condensed Matter, 26 (2014)
doi:10.1088/0953-8984/26/21/213201
Please cite this paper when using ELPA. We also intend to publish an
overview description of the ELPA library as such, and ask you to
make appropriate reference to that as well, once it appears.
*** Copyright:
Copyright of the original code rests with the authors inside the ELPA
consortium. The code is distributed under the terms of the GNU Lesser General
Public License version 3 (LGPL).
Please also note the express "NO WARRANTY" disclaimers in the GPL.
Please see the file "COPYING" for details, and the files "gpl.txt" and
"lgpl.txt" for further information.
*** Using ELPA:
ELPA is designed to be compiled (Fortran) on its own, to be later
linked to your own application. In order to use ELPA, you must still
have a set of separate libraries that provide
- Basic Linear Algebra Subroutines (BLAS)
- Lapack routines
- Basic Linear Algebra Communication Subroutines (BLACS)
- Scalapack routines
- a working MPI library
Appropriate libraries can be obtained and compiled separately on many
architectures as free software. Alternatively, pre-packaged libraries
are usually available from any HPC proprietary compiler vendors.
For example, Intel's ifort compiler contains the "math kernel library"
(MKL), providing BLAS/Lapack/BLACS/Scalapack functionality. (except on
Mac OS X, where the BLACS and Scalapack part must still be obtained
and compiled separately).
A very usable general-purpose MPI library is OpenMPI (ELPA was tested
with OpenMPI 1.4.3 for example). Intel MPI seems to be a very well
performing option on Intel platforms.
Examples of how to use ELPA are included in the accompanying
test_*.f90 subroutines in the "test" directory. An example makefile
"Makefile.example" is also included as a minimal example of how to
build and link ELPA to any other piece of code. In general, however,
we suggest to use the build environment in order to install ELPA
as library to your system.
*** Structure of this repository:
As in most git repositories, also this repository contains different branches.
The branch "master" is always identical to the one representing the latest release
of ELPA. All other branches, either represent development work, or previous releases of
ELPA.
.
RELEASE_NOTES deleted 100644 → 0
View file @ 392d782a
This file contains the release notes for the ELPA 2015.11.001 version
What is new?
-------------
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) C interface
----------------------
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.
Any incompatibles to previous version?
---------------------------------------
As mentioned before, the ABI of ELPA has changed! It will be necessary
to rebuild the programs using ELPA, if this new version should be used.
Beware, using the new library with code which was build with an older verion
should not even run. If it does, the results will be wrong !
THIS_REPO_HAS_MOVED 0 → 100644
View file @ 31a03aa2
Dear user,
this git repo has been moved to