SWITCHING_TO_NEW_INTERFACE.md 7.31 KB
Newer Older
1
## Documentation how to switch from the legacy API to the new API of the *ELPA* library ##
2

3
This document gives some hints how one can switch from the **deprecated** legacy API to new, long-term supported API of the *ELPA* library.
Andreas Marek's avatar
Andreas Marek committed
4
**At latest with the release ELPA 2019.11.001 you have to use the new API, since the old API has been removed**
5
6
7
8
9
10
11
12
13

### Using *ELPA* from a Fortran code ###

Up to now, if you have been using the (legacy API of the) *ELPA* library you had to do the following
steps: (we assume that MPI and a distributed matrix in block-cyclic scalapack layout is already created in
the user application)

1. including the *ELPA* modules

14
```Fortran
15
16
   use elpa1
   use elpa2   ! this step was only needed if you wanted to use the ELPA 2stage solver
17
```
18

19
2. invoke the "elpa_get_communicators" routine, in order to obtain the row/column MPI communicators needed by *ELPA*
20

21
```Fortran
22
23
   mpierr = elpa_get_communicators(mpi_comm_world, my_prow, my_pcol, &
                                   mpi_comm_rows, mpi_comm_cols)
24
```
25
26

3. do the desired task with the *ELPA* library, which could be
27
28
29
30
31
32
33
  - a) elpa_solve_[real|complex]_1stage_[double|single]     ! solve EV problem with ELPA 1stage solver
  - b) elpa_solve_[real|complex]_2stage_[double|single]     ! solve EV problem with ELPA 2stage solver
  - c) elpa_solve_tridi_[double|single]                     ! solve a the problem for a tri-diagonal matrix
  - d) elpa_cholesky_[real|complex]_[double|single]         ! Cholesky decomposition
  - e) elpa_invert_trm_[real|complex]_[double|single]       ! invert triangular matrix
  - f) elpa_mult_at_b_real_[double|single]                  ! multiply a**T * b
  - g) elpa_mult_ah_b_complex_[double|single]               ! multiply a**H * b
34
35
36
37
38
39

For each of the function calls you had to set some parameters (see man pages) to control the execution like
useGPU=[.false.|.true.], choice of ELPA 2stage kernel .... New parameters were likely added with a new release of
the *ELPA* library to reflect the growing functionality.


40
41
**The new interface of *ELPA* is more generic, which, however, requires ONCE the adaption of the user code if the new
interface should be used.**
42
43
44
45
46
47

This are the new steps to do (again it is assumed that MPI and a distributed matrix in block-cyclic scalapack layout is already created in
the user application):

1. include the correct *ELPA* module and define a name for the ELPA instance

48
```Fortran
49
   use elpa   ! this is the only module needed for ELPA
50

51
   class(elpa_t), pointer :: e   ! name the ELPA instance "e"
52
```
53
54
55

2. initialize ELPA and create the instance

56
57
58
```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
59
60
   endif

61
   e => elpa_allocate()
62
```
63
64
65

3. set the parameters which describe the matrix setup and the MPI

66
```Fortran
67
68
69
   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
70

71
72
   call e%set("local_ncols", na_cols,success)            ! MPI process local cols of the distributed matrix
   call e%set("nblk", nblk, success)                     ! size of block-cylic distribution
73

74
75
76
77
   call e%set("mpi_comm_parent", MPI_COMM_WORLD,succes)  ! global communicator for all processes which have parts of
                                                         ! the distributed matrix
   call e%set("process_row", my_prow, success)           ! row coordinate of MPI task
   call e%set("process_col", my_pcol, success)           ! column coordinate of MPI task
78
```
79
80
81

4. setup the ELPA instance

82
```Fortran
83
   success = e%setup()
84
```
85

86
5. set/get any possible option (see man pages, or the document USERS_GUIDE.md)
87

88
```Fortran
89
   call e%get("qr", qr, success)                        ! query whether QR-decomposition is set
90
   print *, "qr =", qr
91
   if (success .ne. ELPA_OK) stop
92
93

   call e%set("solver", ELPA_SOLVER_2STAGE, success)    ! set solver to 2stage
94
   if (success .ne. ELPA_OK) stop
95

96
97
   call e%set("real_kernel", ELPA_2STAGE_REAL_GENERIC, success) ! set kernel of ELPA 2stage solver for
                                                                !real case to the generic kernel
98

99
100
101
```

   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)):
102

103

104
105
106
107
108
109
110
111
112
113
| Parameter name | Short description     | default value               | possible values         | since API version | 
| :------------- |:--------------------- | :-------------------------- | :---------------------- | :---------------- | 
| solver         | use ELPA 1 stage <br>  or 2 stage solver | ELPA_SOLVER_1STAGE          | ELPA_SOLVER_1STAGE <br> ELPA_SOLVER_2STAGE      | 20170403          |
| gpu            | use GPU (if build <br> with GPU support)| 0                           | 0 or 1             | 20170403          | 
| real_kernel    | real kernel to be <br> used in ELPA 2 | ELPA_2STAGE_REAL_DEFAULT    | see output of <br> elpa2_print_kernels    | 20170403          |
| complex kernel | complex kernel to <br>  be used in ELPA 2 | ELPA_2STAGE_COMPLEX_DEFAULT | see output of <br>  elpa2_print_kernels     | 20170403          |
| omp_threads    | OpenMP threads used <br> (if build with OpenMP <br> support) | 1 | >1 | 20180525 |
| qr | Use QR decomposition in <br> ELPA 2 real | 0 | 0 or 1 |  20170403  |
| timings | Enable time <br> measurement | 1 | 0 or 1 |  20170403  |
| debug | give debug information | 0 | 0 or 1 | 20170403  |
114
115


116
6. do the desired task with the *ELPA* library, which could be
117
118


119
120
121
122
123
124
125
126
127
| Name         | Purpose                                                                 | since API version |
| :----------- | :---------------------------------------------------------------------- | :---------------- |
| eigenvectors | solve std. eigenvalue problem <br> compute eigenvalues and eigenvectors | 20170403  |
| eigenvalues  | solve std. eigenvalue problem <br> compute eigenvalues only             | 20170403  |
| generalized_eigenvectors | solve generalized eigenvalule problem <br> compute eigenvalues and eigenvectors | 20180525 |
| generalized_eigenvalues  | solve generalized eigenvalule problem <br> compute eigenvalues only             | 20180525 |
| hermitian_multiply       | do (real) a^T x b <br> (complex) a^H x b                                        | 20170403 |
| cholesky                 | do cholesky factorisation                                                       | 20170403 |
| invert_triangular        | invert a upper triangular matrix                                                | 20170403 |
128

129
130

7. when not needed anymore, destroy the instance
131
132

```Fortran
133
   call elpa_deallocate()
134
```
135
136
137

8. when *ELPA* is not needed anymore, unitialize the *ELPA* library

138
139
140
```Fortran
   call elpa_uninit()
```
141
142
143
144
145
146
147
148

### Online and local documentation ###

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
the available kernels.

Andreas Marek's avatar
Andreas Marek committed
149
Also a [online doxygen documentation] (http://elpa.mpcdf.mpg.de/html/Documentation/ELPA-2019.11.001/html/index.html)
150
151
152
for each *ELPA* release is available.