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

3 4
This document gives some hints how one can switch from the **deprecated** legacy API to new, long-term supported API of the *ELPA* library.
**We strongly recommend users to switch as soon as possible, since the deprecated API will be removed at some point!**
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-2018.11.001/html/index.html)
150 151 152
for each *ELPA* release is available.