Changes

Page history
Update to release 2020.05.001 authored by Andreas Marek's avatar Andreas Marek
Show whitespace changes
Inline Side-by-side
USERS_GUIDE.md
View page @ c9f9bb47
## Users guide for the *ELPA* library ##
This document provides the guide for using the *ELPA* library with the new API (API version 20170403 or higher).
Please do understand that this release deprecated the old, legacy interface API!
If you want to use the deprecated legacy API (we strongly recommend against this), please use the ELPA release
2019.05.002 or older.
......@@ -11,10 +10,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.rc1/html/index.html)
Also a [online doxygen documentation](http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2020.05.001/html/index.html)
for each *ELPA* release is available.
......@@ -23,12 +22,6 @@ for each *ELPA* release is available.
With release 2017.05.001 of the *ELPA* library the interface has been rewritten substantially, in order to have a more generic
interface and to avoid future interface changes.
The release ELPA 2018.11.001 was the last release, where the legacy API has been
enabled by default (and can be disabled at build time).
With release ELPA 2019.05.001 the legacy API is disabled by default, however,
can be still switched on at build time.
With the release ELPA 2019.11.001 the legacy API will has been deprecated and has been removed.
### Table of Contents: ###
......@@ -44,7 +37,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 +63,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 +112,7 @@ Fortran synopsis
```
C Synopsis:
```C
```x
#include <elpa/elpa.h>
elpa_t handle;
......@@ -187,7 +180,7 @@ The following table gives a list of all supported parameters which can be used t
## III) List of computational routines ##
The following compute routines are available in *ELPA*: Please have a look at the man pages or [online doxygen documentation] (http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2019.11.001.rc1/html/index.html) for details.
The following compute routines are available in *ELPA*: Please have a look at the man pages or [online doxygen documentation] (http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2020.05.001/html/index.html) for details.
| Name | Purpose | since API version |
......@@ -208,13 +201,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 +218,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 +238,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 +261,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 +276,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 +322,7 @@ Fortran synopsis
```
C Synopsis
```C
```c
/* prepare ELPA the usual way; only steps for autotuning are commented */
#include <elpa/elpa.h>
......@@ -381,7 +375,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 +384,7 @@ call ELPA.
For simplicity only a Fortran example is shown
```Fortran
```fortran
use mpi
......
......