1. include the correct *ELPA* module and define a name for the ELPA instance
```Fortran
```fortran
useelpa! 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
calle%set("na",na,success)! size of matrix
calle%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
callelpa_deallocate()
```
8. when *ELPA* is not needed anymore, unitialize the *ELPA* library
```Fortran
```fortran
callelpa_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)
@@ -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
useelpa
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
calle%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
| 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
calle%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
useelpa
...
...
@@ -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
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
