Commit 52b3ce2a authored by Andreas Marek's avatar Andreas Marek

Fix typos and markdown

parent 919e9ba0
### How to contribute to the *ELPA* library: ###
We are very happy and gratefull if you are willing to help us improve *ELPA*.
We are very happy and grateful if you are willing to help us improve *ELPA*.
Thus, we would like to make this process as simple as possible for you,
but at the same time still keep it manageable for us
......
......@@ -7,8 +7,8 @@ in the (near) future from the *ELPA* library.
### A) Deprecated interfaces:###
With the release of ELPA 2017.05.001 a new, more general API for the library has
been published. All new features of ELPA will only be accesible via this new interface.
For ease of transion, the old API as defined in release ELPA 2016.11.001 has been frozen in
been published. All new features of ELPA will only be accessible via this new interface.
For ease of transiiton, the old API as defined in release ELPA 2016.11.001 has been frozen in
and will be still supported for some time, albeit without any new features. This old API has been
deprecated in release ELPA 2019.11.001 and has been removed.
......
This diff is collapsed.
## A list of known (and hopefully soon solved) issues of *ELPA* ##
For more details and recent updates please visit the online [issue system] (https://gitlab.mpcdf.mpg.de/elpa/elpa/issues)
For more details and recent updates please visit the online [issue system](https://gitlab.mpcdf.mpg.de/elpa/elpa/issues)
Issues which are not mentioned in a newer release are (considered as) solved.
### ELPA 2019.11.001 release ###
......@@ -31,7 +31,7 @@ Issues which are not mentioned in a newer release are (considered as) solved.
- at the moment no issues are known
### ELPA 2017.05.001 release ###
- accidently a memory leak has been introduced
- accidentaly a memory leak has been introduced
### ELPA 2017.05.001.rc2 release ###
- compilation with Intel Compiler 2018 beta does not work
......@@ -55,6 +55,6 @@ Issues which are not mentioned in a newer release are (considered as) solved.
### ELPA 2016.05.001 release ###
- QR decomposition fails for certain combinations of matrix sizes, number of eigenvalues to compute and block size
- The generated check-scripts (in the step "make check") do not call the binary with "mpiexec" when *ELPA* is build with
- The generated check-scripts (in the step "make check") do not call the binary with `mpiexec` when *ELPA* is build with
MPI
......@@ -6,7 +6,7 @@ The current release is ELPA 2019.11.001 The current supported API version
is 20190501. This release supports the earliest API version 20170403.
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
Already 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 was the last release, where the legacy API has been
......@@ -81,7 +81,7 @@ Nonetheless, we are grateful if you cite the following publications:
If you use ELPA in general:
T. Auckenthaler, V. Blum, H.-J. Bungartz, T. Huckle, R. Johanni,
L. Kr\"amer, B. Lang, H. Lederer, and P. R. Willems,
L. Krämer, 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).
......
......@@ -11,14 +11,14 @@ the user application)
1. including the *ELPA* modules
```Fortran
```fortran
use elpa1
use elpa2 ! this step was only needed if you wanted to use the ELPA 2stage solver
```
2. invoke the "elpa_get_communicators" routine, in order to obtain the row/column MPI communicators needed by *ELPA*
2. invoke the `elpa_get_communicators` routine, in order to obtain the row/column MPI communicators needed by *ELPA*
```Fortran
```fortran
mpierr = elpa_get_communicators(mpi_comm_world, my_prow, my_pcol, &
mpi_comm_rows, mpi_comm_cols)
```
......@@ -45,7 +45,7 @@ the user application):
1. include the correct *ELPA* module and define a name for the ELPA instance
```Fortran
```fortran
use elpa ! this is the only module needed for ELPA
class(elpa_t), pointer :: e ! name the ELPA instance "e"
......@@ -53,7 +53,7 @@ the user application):
2. initialize ELPA and create the instance
```Fortran
```fortran
if (elpa_init(20170403) /= ELPA_OK) then ! put here the version number of the API
error stop "ELPA API version not supported" ! which you are using
endif
......@@ -63,7 +63,7 @@ the user application):
3. set the parameters which describe the matrix setup and the MPI
```Fortran
```fortran
call e%set("na", na,success) ! size of matrix
call e%set("local_nrows", na_rows,success) ! MPI process local rows of the distributed matrixdo the
! desired task with the *ELPA* library, which could be
......@@ -79,11 +79,11 @@ the user application):
4. setup the ELPA instance
```Fortran
```fortran
success = e%setup()
```
5. set/get any possible option (see man pages, or the document USERS_GUIDE.md)
5. set/get any possible option (see man pages, or the document [USERS_GUIDE.md](USERS_GUIDE.md))
```Fortran
call e%get("qr", qr, success) ! query whether QR-decomposition is set
......@@ -98,7 +98,7 @@ the user application):
```
At the moment, the following configurable runtime options are supported ([see here if you cannot read it in your editor] (https://gitlab.mpcdf.mpg.de/elpa/elpa/wikis/USERS_GUIDE)):
At the moment, the following configurable runtime options are supported ([see here if you cannot read it in your editor](https://gitlab.mpcdf.mpg.de/elpa/elpa/wikis/USERS_GUIDE)):
| Parameter name | Short description | default value | possible values | since API version |
......@@ -129,13 +129,13 @@ the user application):
7. when not needed anymore, destroy the instance
```Fortran
```fortran
call elpa_deallocate()
```
8. when *ELPA* is not needed anymore, unitialize the *ELPA* library
```Fortran
```fortran
call elpa_uninit()
```
......@@ -143,10 +143,10 @@ the user application):
Local documentation (via man pages) should be available (if *ELPA* has been installed with the documentation):
For example "man elpa2_print_kernels" should provide the documentation for the *ELPA* program which prints all
For example `man elpa2_print_kernels` should provide the documentation for the *ELPA* program which prints all
the available kernels.
Also a [online doxygen documentation] (http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2019.11.001/html/index.html)
Also a [online doxygen documentation](http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2019.11.001/html/index.html)
for each *ELPA* release is available.
......@@ -11,10 +11,10 @@ If you need instructions on how to build *ELPA*, please look at [INSTALL.md] (IN
Local documentation (via man pages) should be available (if *ELPA* has been installed with the documentation):
For example "man elpa2_print_kernels" should provide the documentation for the *ELPA* program, which prints all
For example `man elpa2_print_kernels` should provide the documentation for the *ELPA* program, which prints all
the available kernels.
Also a [online doxygen documentation] (http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2019.11.001/html/index.html)
Also a [online doxygen documentation](http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2019.11.001/html/index.html)
for each *ELPA* release is available.
......@@ -44,7 +44,7 @@ With the release ELPA 2019.11.001 the legacy API will has been deprecated and ha
Using *ELPA* just requires a few steps:
- include elpa headers "elpa/elpa.h" (C-Case) or use the Fortran module "use elpa"
- include elpa headers `elpa/elpa.h` (C-Case) or use the Fortran module `use elpa`
- define a instance of the elpa type
......@@ -70,7 +70,7 @@ To be more precise a basic call sequence for Fortran and C looks as follows:
Fortran synopsis
```Fortran
```fortran
use elpa
class(elpa_t), pointer :: elpa
integer :: success
......@@ -119,7 +119,7 @@ Fortran synopsis
```
C Synopsis:
```C
```x
#include <elpa/elpa.h>
elpa_t handle;
......@@ -171,7 +171,7 @@ C Synopsis:
## II) List of supported tunable parameters ##
The following table gives a list of all supported parameters which can be used to tune (influence) the runtime behaviour of *ELPA* ([see here if you cannot read it in your editor] (https://gitlab.mpcdf.mpg.de/elpa/elpa/wikis/USERS_GUIDE))
The following table gives a list of all supported parameters which can be used to tune (influence) the runtime behaviour of *ELPA* ([see here if you cannot read it in your editor](https://gitlab.mpcdf.mpg.de/elpa/elpa/wikis/USERS_GUIDE))
| Parameter name | Short description | default value | possible values | since API version |
| :------------- |:--------------------- | :-------------------------- | :---------------------- | :---------------- |
......@@ -208,13 +208,15 @@ If *ELPA* has been build with OpenMP threading support you can specify the numbe
Please note that it is **mandatory** to set the number of threads to be used with the OMP_NUM_THREADS environment variable **and**
with the **set method**
```Fortran
```fortran
call e%set("omp_threads", 4, error)
```
**or the *ELPA* environment variable**
```
export ELPA_DEFAULT_omp_threads=4 (see Section V for an explanation of this variable).
```
Just setting the environment variable OMP_NUM_THREADS is **not** sufficient.
......@@ -223,7 +225,7 @@ This is necessary to make the threading an autotunable option.
## V) Influencing default values with environment variables ##
For each tunable parameter mentioned in Section II, there exists a default value. This means, that if this parameter is **not explicitly** set by the user by the
*ELPA* set method, *ELPA* takes the default value for the parameter. E.g. if the user does not set a solver method, than *ELPA* will take the default "ELPA_SOLVER_1STAGE".
*ELPA* set method, *ELPA* takes the default value for the parameter. E.g. if the user does not set a solver method, than *ELPA* will take the default 1`ELPA_SOLVER_1STAGE`.
The user can change this default value by setting an enviroment variable to the desired value.
......@@ -243,7 +245,7 @@ in order to define the 2stage solver as the default.
**Important note**
The default valule is completly ignored, if the user has manually set a parameter-value pair with the *ELPA* set method!
Thus the above environemnt variable will **not** have an effect, if the user code contains a line
```Fortran
```fortran
call e%set("solver",ELPA_SOLVER_1STAGE,error)
```
.
......@@ -266,13 +268,12 @@ sets are supported:
| :---------------------- | :------------------------------------------------------ |
| ELPA_AUTOTUNE_FAST | { solver, real_kernel, complex_kernel, omp_threads } |
| ELPA_AUTOTUNE_MEDIUM | all of abvoe + { gpu, partly gpu } |
| ELPA_AUTOTUNE_EXTENSIVE | all of above + { various blocking factors, stripewidth, |
| | intermediate_bandwidth } |
| ELPA_AUTOTUNE_EXTENSIVE | all of above + { various blocking factors, stripewidth, intermediate_bandwidth } |
2.) the user can **remove** tunable parameters from the list of autotuning possibilites by explicetly setting this parameter,
e.g. if the user sets in his code
```Fortran
```fortran
call e%set("solver", ELPA_SOLVER_2STAGE, error)
```
**before** invoking the autotuning, then the solver is fixed and not considered anymore for autotuning. Thus the ELPA_SOLVER_1STAGE would be skipped and, consequently, all possible autotuning parameters, which depend on ELPA_SOLVER_1STAGE.
......@@ -282,7 +283,7 @@ The user can invoke autotuning in the following way:
Fortran synopsis
```Fortran
```fortran
! prepare elpa as you are used to (see Section I)
! only steps for autotuning are commentd
use elpa
......@@ -328,7 +329,7 @@ Fortran synopsis
```
C Synopsis
```C
```c
/* prepare ELPA the usual way; only steps for autotuning are commented */
#include <elpa/elpa.h>
......@@ -381,7 +382,7 @@ The following is a skeleton code of an basic example on how to use ELPA. The pur
to be done in the application using MPI which wants to call ELPA, namely
- Initializing the MPI
- creating a blacs distributed matrics
- creating a blacs distributed matrix
- using this matrix within ELPA
The skeleton is not ment to be copied and pasted, since the details will always be dependent on the application which should
......@@ -390,7 +391,7 @@ call ELPA.
For simplicity only a Fortran example is shown
```Fortran
```fortran
use mpi
......
......@@ -2,7 +2,7 @@
**DISCLAIMER**
This document provides some guidelines for using the legacy interface of the *ELPA* library with user applications.
The legacy interface is deprecated and will be disabled at some point without any special anouncement.
The legacy interface is deprecated and will be disabled at some point without any special announcement.
The following guidelines will not be updated or corrected anymore.
**We strongly recommend all users to use the long-term supported new API of ELPA, which has been published with the
release of 2017.05.001.**
......@@ -22,7 +22,7 @@ The *ELPA* library consists of two main parts:
Both variants of the *ELPA* solvers are available for real or complex singe and double precision valued matrices.
Thus *ELPA* provides the following user functions (see man pages or [online] (http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2019.11.001/html/index.html) for details):
Thus *ELPA* provides the following user functions (see man pages or [online](http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2019.11.001/html/index.html) for details):
- elpa_get_communicators : set the row / column communicators for *ELPA*
- elpa_solve_evp_complex_1stage_{single|double} : solve a {single|double} precision complex eigenvalue proplem with the *ELPA 1stage* solver
......@@ -57,6 +57,7 @@ please have a look at the man pages and/or the online documentation (see above).
of a simple example program can be found in ./test_project_1stage_legacy_api/src.
```fortran
! All ELPA routines need MPI communicators for communicating within
! rows or columns of processes, these are set in elpa_get_communicators
......@@ -88,11 +89,12 @@ of a simple example program can be found in ./test_project_1stage_legacy_api/src
print '(a)','| One-step ELPA solver complete.'
print *
end if
```fortran
#### Shared-memory version of *ELPA* ####
If the *ELPA* library has been compiled with the configure option "--with-mpi=0",
If the *ELPA* library has been compiled with the configure option `--with-mpi=0`,
no MPI will be used.
Still the **same** call sequence as in the MPI case can be used (see above).
......@@ -103,6 +105,7 @@ Still the **same** call sequence as in the MPI case can be used (see above).
SYNOPSIS
FORTRAN INTERFACE
```fortran
use elpa1
success = elpa_get_communicators (mpi_comm_global, my_prow, my_pcol, mpi_comm_rows, mpi_comm_cols)
......@@ -114,8 +117,10 @@ SYNOPSIS
integer, intent(out) mpi_comm_row: communicator for communication within columns of processes
integer success: return value indicating success or failure of the underlying MPI_COMM_SPLIT function
```
C INTERFACE
```c
#include "elpa_generated.h"
success = elpa_get_communicators (int mpi_comm_world, int my_prow, my_pcol, int *mpi_comm_rows, int *Pmpi_comm_cols);
......@@ -127,7 +132,7 @@ SYNOPSIS
int *mpi_comm_row: pointer to the communicator for communication within columns of processes
int success: return value indicating success or failure of the underlying MPI_COMM_SPLIT function
```
#### Using *ELPA 1stage* ####
......@@ -136,9 +141,11 @@ only the real or complex valued solver has to be called:
SYNOPSIS
FORTRAN INTERFACE
```fortran
use elpa1
success = elpa_solve_evp_real_1stage_{single|double} (na, nev, a(lda,matrixCols), ev(nev), q(ldq, matrixCols), ldq, nblk, matrixCols, mpi_comm_rows,
mpi_comm_cols)
```
With the definintions of the input and output variables:
......@@ -157,11 +164,12 @@ SYNOPSIS
logical success: return value indicating success or failure
C INTERFACE
```c
#include "elpa.h"
success = elpa_solve_evp_real_1stage_{single|double} (int na, int nev, double *a, int lda, double *ev, double *q, int ldq, int nblk, int matrixCols, int
mpi_comm_rows, int mpi_comm_cols);
```
With the definintions of the input and output variables:
int na: global dimension of quadratic matrix a to solve
......@@ -185,10 +193,11 @@ DESCRIPTION
will be stored in q. All memory of the arguments must be allocated outside the call to the solver.
FORTRAN INTERFACE
```fortran
use elpa1
success = elpa_solve_evp_complex_1stage_{single|double} (na, nev, a(lda,matrixCols), ev(nev), q(ldq, matrixCols), ldq, nblk, matrixCols, mpi_comm_rows,
mpi_comm_cols)
```
With the definintions of the input and output variables:
integer, intent(in) na: global dimension of quadratic matrix a to solve
......@@ -206,11 +215,13 @@ DESCRIPTION
logical success: return value indicating success or failure
C INTERFACE
```c
#include "elpa.h"
#include <complex.h>
success = elpa_solve_evp_complex_1stage_{single|double} (int na, int nev, double complex *a, int lda, double *ev, double complex*q, int ldq, int nblk, int
matrixCols, int mpi_comm_rows, int mpi_comm_cols);
```
With the definintions of the input and output variables:
......@@ -256,13 +267,13 @@ If no kernel is set via the *ELPA 2stage API* then the default kernels will be s
##### Setting the *ELPA 2stage* compute kernels #####
##### Setting the *ELPA 2stage* compute kernels with environment variables#####
##### Setting the *ELPA 2stage* compute kernels with environment variables #####
The utility program "elpa2_print_kernels" can list which kernels are available and which
would be chosen. This reflects the setting of the default kernel.
##### Setting the *ELPA 2stage* compute kernels with API calls#####
##### Setting the *ELPA 2stage* compute kernels with API calls #####
It is also possible to set the *ELPA 2stage* compute kernels via the API.
......@@ -270,10 +281,12 @@ As an example the API for ELPA real double-precision 2stage is shown:
SYNOPSIS
FORTRAN INTERFACE
```fortran
use elpa1
use elpa2
success = elpa_solve_evp_real_2stage_double (na, nev, a(lda,matrixCols), ev(nev), q(ldq, matrixCols), ldq, nblk, matrixCols, mpi_comm_rows,
mpi_comm_cols, mpi_comm_all, THIS_REAL_ELPA_KERNEL, useQR, useGPU)
```
With the definintions of the input and output variables:
......@@ -295,10 +308,12 @@ SYNOPSIS
logical success: return value indicating success or failure
C INTERFACE
```c
#include "elpa.h"
success = elpa_solve_evp_real_2stage_double (int na, int nev, double *a, int lda, double *ev, double *q, int ldq, int nblk, int matrixCols, int
mpi_comm_rows, int mpi_comm_cols, int mpi_comm_all, int THIS_ELPA_REAL_KERNEL, int useQR, int useGPU);
```
With the definintions of the input and output variables:
......@@ -335,10 +350,11 @@ As an exmple the real double-precision case is explained:
SYNOPSIS
FORTRAN INTERFACE
```fortran
use elpa_driver
success = elpa_solve_evp_real_double (na, nev, a(lda,matrixCols), ev(nev), q(ldq, matrixCols), ldq, nblk, matrixCols, mpi_comm_rows, mpi_comm_cols, mpi_comm_all, THIS_REAL_ELPA_KERNEL=THIS_REAL_ELPA_KERNEL, useQR, useGPU, method=method)
```
Generalized interface to the ELPA 1stage and 2stage solver for real-valued problems
......@@ -381,10 +397,11 @@ As an exmple the real double-precision case is explained:
C INTERFACE
```c
#include "elpa.h"
success = elpa_solve_evp_real_double (int na, int nev, double *a, int lda, double *ev, double *q, int ldq, int nblk, int matrixCols, int mpi_comm_rows, int mpi_comm_cols, int mpi_comm_all, int THIS_ELPA_REAL_KERNEL, int useQR, int useGPU, char *method);"
```
With the definintions of the input and output variables:"
......@@ -437,7 +454,7 @@ argument "useGPU = .true." or "useGPU = 1" for the Fortran and C case, respectiv
*ELPA* 2stage compute kernels, the enviroment variable takes precendence over the setting in the API call.
Further note that it is NOT allowed to define the usage of GPUs AND to EXPLICITLY set an ELPA 2stage compute kernel other than
"REAL_ELPA_KERNEL_GPU" or "COMPLEX_ELPA_KERNEL_GPU".
`REAL_ELPA_KERNEL_GPU` or `COMPLEX_ELPA_KERNEL_GPU`.
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