Rename of "solve" method to "eigenvectors"

The public "solve" method has been renamed "eigenvectors" since it
computes the eigenvalues and (at least parts of) the eigenvectors

Another routine "eigenvalues" will just compute the eigenvalues

SWITCHING_TO_NEW_INTERFACE.md

@@ -58,7 +58,7 @@ the user application):
 !>
 !>   ! use method solve to solve the eigenvalue problem
 !>   ! other possible methods are desribed in \ref elpa_api::elpa_t derived type
-!>   call e%solve(a, ev, z, success)
+!>   call e%eigenvectors(a, ev, z, success)
 !>
 !>   ! cleanup
 !>   call elpa_deallocate(e)
@@ -128,7 +128,7 @@ the user application):
 
 
 6. do the desired task with the *ELPA* library, which could be
-   a) e%solve                         ! solve EV problem with solver as set by "set" method;
+   a) e%eigenvectors                  ! solve EV problem with solver as set by "set" method; returns eigenvalues AND eigenvectors
                                       ! (replaces a) and b) from legacy API)
    b) e%solve_tridi                   ! solve problem with tridiagonal matrix  (replacement for c) from legacy API)
    c) e%choleksy                      ! do a cholesky decomposition (replaces  d) from legacy API)

USERS_GUIDE.md

@@ -65,7 +65,8 @@ Using *ELPA* with the latest API is done in the following steps
 
   At the moment the following ELPA compute functions are available:
 
-    - "solve" solves the eigenvalue problem for single/double real/complex valued matrices
+    - "eigenvectors" solves the eigenvalue problem for single/double real/complex valued matrices and
+                     returns the eigenvalues AND eigenvectors
     - "hermetian_multipy" computes C = A^T * B (real) or C = A^H * B (complex) for single/double
       real/complex matrices
     - "cholesky" does a cholesky factorization for a single/double real/complex matrix

elpa/elpa_generic.h

@@ -36,7 +36,7 @@
         )(e, name, value, error)
 
 
-/*! \brief generic C method for elpa_solve
+/*! \brief generic C method for elpa_eigenvectors
  *
  *  \details
  *  \param  handle  handle of the ELPA object, which defines the problem
@@ -46,18 +46,18 @@
  *  \param  error   on return the error code, which can be queried with elpa_strerr()
  *  \result void
  */
-#define elpa_solve(handle, a, ev, q, error) _Generic((a), \
+#define elpa_eigenvectors(handle, a, ev, q, error) _Generic((a), \
                 double*: \
-                  elpa_solve_d, \
+                  elpa_eigenvectors_d, \
                 \
                 float*: \
-                  elpa_solve_f, \
+                  elpa_eigenvectors_f, \
                 \
                 double complex*: \
-                  elpa_solve_dc, \
+                  elpa_eigenvectors_dc, \
                 \
                 float complex*: \
-                  elpa_solve_fc \
+                  elpa_eigenvectors_fc \
         )(handle, a, ev, q, error)
 
 /*  \brief generic C method for elpa_cholesky

src/elpa.F90

@@ -132,9 +132,10 @@
 !>   ... set and get all other options that are desired
 !> \code{.f90}
 !>
-!>   ! use method solve to solve the eigenvalue problem
+!>   ! use method solve to solve the eigenvalue problem to obtain eigenvalues
+!>   ! and eigenvectors
 !>   ! other possible methods are desribed in \ref elpa_api::elpa_t derived type
-!>   call e%solve(a, ev, z, success)
+!>   call e%eigenvectors(a, ev, z, success)
 !>
 !>   ! cleanup
 !>   call elpa_deallocate(e)
@@ -178,7 +179,7 @@
 !>
 !>   /* use method solve to solve the eigenvalue problem */
 !>   /* other possible methods are desribed in \ref elpa_api::elpa_t derived type */
-!>   elpa_solve(handle, a, ev, z, &error);
+!>   elpa_eigenvectors(handle, a, ev, z, &error);
 !>
 !>   /* cleanup */
 !>   elpa_deallocate(handle);

src/elpa1/legacy_interface/elpa1_template.X90

@@ -162,7 +162,7 @@ function elpa_solve_evp_&
 
    call e%set("timings", 1)
 
-   call e%solve(a(1:lda,1:matrixCols), ev, q(1:ldq,1:matrixCols), successInternal)
+   call e%eigenvectors(a(1:lda,1:matrixCols), ev, q(1:ldq,1:matrixCols), successInternal)
 
    time_evp_fwd = e%get_time("elpa_solve_evp_&
    &MATH_DATATYPE&

src/elpa2/legacy_interface/elpa2_template.X90

@@ -195,7 +195,7 @@
     endif
     call e%set("timings", 1)
 
-    call e%solve(a(1:lda,1:matrixCols), ev, q(1:ldq,1:matrixCols), successInternal)
+    call e%eigenvectors(a(1:lda,1:matrixCols), ev, q(1:ldq,1:matrixCols), successInternal)
     if (successInternal .ne. ELPA_OK) then
       print *, "Cannot solve with ELPA 2stage"
       success = .false.

src/elpa_api.F90

@@ -98,11 +98,11 @@ module elpa_api
       procedure(elpa_print_times_i), deferred, public :: print_times
 
       ! Actual math routines
-      generic, public :: solve => &                                 !< method solve for solving the eigenvalue problem
-          elpa_solve_d, &                                           !< for symmetric real valued / hermitian complex valued
-          elpa_solve_f, &                                           !< matrices
-          elpa_solve_dc, &
-          elpa_solve_fc
+      generic, public :: eigenvectors => &                          !< method solve for solving the full eigenvalue problem
+          elpa_eigenvectors_d, &                                           !< for symmetric real valued / hermitian complex valued
+          elpa_eigenvectors_f, &                                           !< matrices
+          elpa_eigenvectors_dc, &
+          elpa_eigenvectors_fc
 
       generic, public :: hermitian_multiply => &                    !< method for a "hermitian" multiplication of matrices a and b
           elpa_hermitian_multiply_d, &                              !< for real valued matrices:   a**T * b
@@ -135,10 +135,10 @@ module elpa_api
       procedure(elpa_get_integer_i), deferred, private :: elpa_get_integer
       procedure(elpa_get_double_i),  deferred, private :: elpa_get_double
 
-      procedure(elpa_solve_d_i),    deferred, private :: elpa_solve_d
-      procedure(elpa_solve_f_i),    deferred, private :: elpa_solve_f
-      procedure(elpa_solve_dc_i), deferred, private :: elpa_solve_dc
-      procedure(elpa_solve_fc_i), deferred, private :: elpa_solve_fc
+      procedure(elpa_eigenvectors_d_i),    deferred, private :: elpa_eigenvectors_d
+      procedure(elpa_eigenvectors_f_i),    deferred, private :: elpa_eigenvectors_f
+      procedure(elpa_eigenvectors_dc_i), deferred, private :: elpa_eigenvectors_dc
+      procedure(elpa_eigenvectors_fc_i), deferred, private :: elpa_eigenvectors_fc
 
       procedure(elpa_hermitian_multiply_d_i),  deferred, private :: elpa_hermitian_multiply_d
       procedure(elpa_hermitian_multiply_f_i),  deferred, private :: elpa_hermitian_multiply_f
@@ -369,7 +369,7 @@ module elpa_api
   !> \param   q           double real matrix q: on output stores the eigenvalues
   !> \result  error       integer, optional : error code, which can be queried with elpa_strerr
   abstract interface
-    subroutine elpa_solve_d_i(self, a, ev, q, error)
+    subroutine elpa_eigenvectors_d_i(self, a, ev, q, error)
       use iso_c_binding
       import elpa_t
       implicit none
@@ -402,7 +402,7 @@ module elpa_api
   !> \param   q           single real matrix q: on output stores the eigenvalues
   !> \result  error       integer, optional : error code, which can be queried with elpa_strerr
   abstract interface
-    subroutine elpa_solve_f_i(self, a, ev, q, error)
+    subroutine elpa_eigenvectors_f_i(self, a, ev, q, error)
       use iso_c_binding
       import elpa_t
       implicit none
@@ -435,7 +435,7 @@ module elpa_api
   !> \param   q           double complex matrix q: on output stores the eigenvalues
   !> \result  error       integer, optional : error code, which can be queried with elpa_strerr
   abstract interface
-    subroutine elpa_solve_dc_i(self, a, ev, q, error)
+    subroutine elpa_eigenvectors_dc_i(self, a, ev, q, error)
       use iso_c_binding
       import elpa_t
       implicit none
@@ -469,7 +469,7 @@ module elpa_api
   !> \param   q           single complex matrix q: on output stores the eigenvalues
   !> \result  error       integer, optional : error code, which can be queried with elpa_strerr
   abstract interface
-    subroutine elpa_solve_fc_i(self, a, ev, q, error)
+    subroutine elpa_eigenvectors_fc_i(self, a, ev, q, error)
       use iso_c_binding
       import elpa_t
       implicit none

src/elpa_impl.F90

@@ -88,11 +88,11 @@ module elpa_impl
      procedure, private :: elpa_get_integer                     !< private methods to implement the querry of an integer/double key/value pair
      procedure, private :: elpa_get_double
 
-     procedure, private :: elpa_solve_d                         !< private methods to implement the solve step for real/complex
+     procedure, private :: elpa_eigenvectors_d                         !< private methods to implement the solve step for real/complex
                                                                 !< double/single matrices
-     procedure, private :: elpa_solve_f
-     procedure, private :: elpa_solve_dc
-     procedure, private :: elpa_solve_fc
+     procedure, private :: elpa_eigenvectors_f
+     procedure, private :: elpa_eigenvectors_dc
+     procedure, private :: elpa_eigenvectors_fc
 
      procedure, private :: elpa_hermitian_multiply_d            !< private methods to implement a "hermitian" multiplication of matrices a and b
      procedure, private :: elpa_hermitian_multiply_f            !< for real valued matrices:   a**T * b
@@ -554,7 +554,7 @@ module elpa_impl
 #endif
     end subroutine
 
-    !>  \brief elpa_solve_d: class method to solve the eigenvalue problem for double real matrices
+    !>  \brief elpa_eigenvectors_d: class method to solve the eigenvalue problem for double real matrices
     !>
     !>  The dimensions of the matrix a (locally ditributed and global), the block-cyclic distribution
     !>  blocksize, the number of eigenvectors
@@ -579,7 +579,7 @@ module elpa_impl
     !>                                              even if only a part of the eigenvalues is needed.
     !>
     !>  \param error                                integer, optional: returns an error code, which can be queried with elpa_strerr
-    subroutine elpa_solve_d(self, a, ev, q, error)
+    subroutine elpa_eigenvectors_d(self, a, ev, q, error)
       use elpa2_impl
       use elpa1_impl
       use elpa_utilities, only : error_unit
@@ -620,8 +620,8 @@ module elpa_impl
       endif
     end subroutine
 
-    !c> void elpa_solve_d(elpa_t handle, double *a, double *ev, double *q, int *error);
-    subroutine elpa_solve_d_c(handle, a_p, ev_p, q_p, error) bind(C, name="elpa_solve_d")
+    !c> void elpa_eigenvectors_d(elpa_t handle, double *a, double *ev, double *q, int *error);
+    subroutine elpa_eigenvectors_d_c(handle, a_p, ev_p, q_p, error) bind(C, name="elpa_eigenvectors_d")
       type(c_ptr), intent(in), value :: handle, a_p, ev_p, q_p
       integer(kind=c_int), optional, intent(in) :: error
 
@@ -633,11 +633,11 @@ module elpa_impl
       call c_f_pointer(ev_p, ev, [self%na])
       call c_f_pointer(q_p, q, [self%local_nrows, self%local_ncols])
 
-      call elpa_solve_d(self, a, ev, q, error)
+      call elpa_eigenvectors_d(self, a, ev, q, error)
     end subroutine
 
 
-    !>  \brief elpa_solve_f: class method to solve the eigenvalue problem for float real matrices
+    !>  \brief elpa_eigenvectors_f: class method to solve the eigenvalue problem for float real matrices
     !>
     !>  The dimensions of the matrix a (locally ditributed and global), the block-cyclic distribution
     !>  blocksize, the number of eigenvectors
@@ -662,7 +662,7 @@ module elpa_impl
     !>                                              even if only a part of the eigenvalues is needed.
     !>
     !>  \param error                                integer, optional: returns an error code, which can be queried with elpa_strerr
-    subroutine elpa_solve_f(self, a, ev, q, error)
+    subroutine elpa_eigenvectors_f(self, a, ev, q, error)
       use elpa2_impl
       use elpa1_impl
       use elpa_utilities, only : error_unit
@@ -708,8 +708,8 @@ module elpa_impl
     end subroutine
 
 
-    !c> void elpa_solve_f(elpa_t handle, float *a, float *ev, float *q, int *error);
-    subroutine elpa_solve_f_c(handle, a_p, ev_p, q_p, error) bind(C, name="elpa_solve_f")
+    !c> void elpa_eigenvectors_f(elpa_t handle, float *a, float *ev, float *q, int *error);
+    subroutine elpa_eigenvectors_f_c(handle, a_p, ev_p, q_p, error) bind(C, name="elpa_eigenvectors_f")
       type(c_ptr), intent(in), value :: handle, a_p, ev_p, q_p
       integer(kind=c_int), optional, intent(in) :: error
 
@@ -721,11 +721,11 @@ module elpa_impl
       call c_f_pointer(ev_p, ev, [self%na])
       call c_f_pointer(q_p, q, [self%local_nrows, self%local_ncols])
 
-      call elpa_solve_f(self, a, ev, q, error)
+      call elpa_eigenvectors_f(self, a, ev, q, error)
     end subroutine
 
 
-    !>  \brief elpa_solve_dc: class method to solve the eigenvalue problem for double complex matrices
+    !>  \brief elpa_eigenvectors_dc: class method to solve the eigenvalue problem for double complex matrices
     !>
     !>  The dimensions of the matrix a (locally ditributed and global), the block-cyclic distribution
     !>  blocksize, the number of eigenvectors
@@ -750,7 +750,7 @@ module elpa_impl
     !>                                              even if only a part of the eigenvalues is needed.
     !>
     !>  \param error                                integer, optional: returns an error code, which can be queried with elpa_strerr
-    subroutine elpa_solve_dc(self, a, ev, q, error)
+    subroutine elpa_eigenvectors_dc(self, a, ev, q, error)
       use elpa2_impl
       use elpa1_impl
       use elpa_utilities, only : error_unit
@@ -791,8 +791,8 @@ module elpa_impl
     end subroutine
 
 
-    !c> void elpa_solve_dc(elpa_t handle, double complex *a, double *ev, double complex *q, int *error);
-    subroutine elpa_solve_dc_c(handle, a_p, ev_p, q_p, error) bind(C, name="elpa_solve_dc")
+    !c> void elpa_eigenvectors_dc(elpa_t handle, double complex *a, double *ev, double complex *q, int *error);
+    subroutine elpa_eigenvectors_dc_c(handle, a_p, ev_p, q_p, error) bind(C, name="elpa_eigenvectors_dc")
       type(c_ptr), intent(in), value :: handle, a_p, ev_p, q_p
       integer(kind=c_int), optional, intent(in) :: error
 
@@ -805,11 +805,11 @@ module elpa_impl
       call c_f_pointer(ev_p, ev, [self%na])
       call c_f_pointer(q_p, q, [self%local_nrows, self%local_ncols])
 
-      call elpa_solve_dc(self, a, ev, q, error)
+      call elpa_eigenvectors_dc(self, a, ev, q, error)
     end subroutine
 
 
-    !>  \brief elpa_solve_fc: class method to solve the eigenvalue problem for float complex matrices
+    !>  \brief elpa_eigenvectors_fc: class method to solve the eigenvalue problem for float complex matrices
     !>
     !>  The dimensions of the matrix a (locally ditributed and global), the block-cyclic distribution
     !>  blocksize, the number of eigenvectors
@@ -834,7 +834,7 @@ module elpa_impl
     !>                                              even if only a part of the eigenvalues is needed.
     !>
     !>  \param error                                integer, optional: returns an error code, which can be queried with elpa_strerr
-    subroutine elpa_solve_fc(self, a, ev, q, error)
+    subroutine elpa_eigenvectors_fc(self, a, ev, q, error)
       use elpa2_impl
       use elpa1_impl
       use elpa_utilities, only : error_unit
@@ -881,8 +881,8 @@ module elpa_impl
     end subroutine
 
 
-    !c> void elpa_solve_fc(elpa_t handle, float complex *a, float *ev, float complex *q, int *error);
-    subroutine elpa_solve_fc_c(handle, a_p, ev_p, q_p, error) bind(C, name="elpa_solve_fc")
+    !c> void elpa_eigenvectors_fc(elpa_t handle, float complex *a, float *ev, float complex *q, int *error);
+    subroutine elpa_eigenvectors_fc_c(handle, a_p, ev_p, q_p, error) bind(C, name="elpa_eigenvectors_fc")
       type(c_ptr), intent(in), value :: handle, a_p, ev_p, q_p
       integer(kind=c_int), optional, intent(in) :: error
 
@@ -895,7 +895,7 @@ module elpa_impl
       call c_f_pointer(ev_p, ev, [self%na])
       call c_f_pointer(q_p, q, [self%local_nrows, self%local_ncols])
 
-      call elpa_solve_fc(self, a, ev, q, error)
+      call elpa_eigenvectors_fc(self, a, ev, q, error)
     end subroutine
 
     !> \brief  elpa_hermitian_multiply_d: class method to perform C : = A**T * B for double real matrices

test/C/test.c

@@ -221,7 +221,7 @@ int main(int argc, char** argv) {
    printf("Solver is set to %d \n", value);
 
    /* Solve EV problem */
-   elpa_solve(handle, a, ev, z, &error);
+   elpa_eigenvectors(handle, a, ev, z, &error);
    assert_elpa_ok(error);
 
    elpa_deallocate(handle);

test/Fortran/elpa1/complex_1stage.F90

@@ -143,7 +143,7 @@ program test_interface
    call e%set("solver", ELPA_SOLVER_1STAGE, success)
    assert_elpa_ok(success)
 
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
 
    call elpa_deallocate(e)

test/Fortran/elpa1/real_1stage.F90

@@ -142,7 +142,7 @@ program test_interface
 
    call e%set("solver", ELPA_SOLVER_1STAGE, success)
    assert_elpa_ok(success)
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
 
    if (myid .eq. 0) then

test/Fortran/elpa1/single_complex_1stage.F90

@@ -144,7 +144,7 @@ program test_interface
    call e%set("solver", ELPA_SOLVER_1STAGE, success)
    assert_elpa_ok(success)
 
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
 
    call elpa_deallocate(e)

test/Fortran/elpa1/single_real_1stage.F90

@@ -146,7 +146,7 @@ program test_interface
 
    call e%set("complex_kernel", ELPA_2STAGE_COMPLEX_DEFAULT, success)
    assert_elpa_ok(success)
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
    call elpa_deallocate(e)
 

test/Fortran/elpa2/complex_2stage.F90

@@ -146,7 +146,7 @@ program test_interface
    call e%set("complex_kernel", ELPA_2STAGE_COMPLEX_DEFAULT, success)
    assert_elpa_ok(success)
 
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
 
    call elpa_deallocate(e)

test/Fortran/elpa2/complex_2stage_banded.F90

@@ -257,7 +257,7 @@ program test_complex2_double_banded
 
    call e%set("solver", ELPA_SOLVER_2STAGE, success)
    assert_elpa_ok(success)
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
    call elpa_deallocate(e)
 

test/Fortran/elpa2/double_instance.F90

@@ -185,11 +185,11 @@ program test_interface
    call e2%set("solver", ELPA_SOLVER_1STAGE, success)
    assert_elpa_ok(success)
 
-   call e1%solve(a1, ev1, z1, success)
+   call e1%eigenvectors(a1, ev1, z1, success)
    assert_elpa_ok(success)
    call elpa_deallocate(e1)
 
-   call e2%solve(a2, ev2, z2, success)
+   call e2%eigenvectors(a2, ev2, z2, success)
    assert_elpa_ok(success)
    call elpa_deallocate(e2)
    call elpa_uninit()

test/Fortran/elpa2/real_2stage.F90

@@ -142,7 +142,7 @@ program test_interface
 
    call e%set("real_kernel", ELPA_2STAGE_REAL_DEFAULT, success)
    assert_elpa_ok(success)
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
 
    call elpa_deallocate(e)

test/Fortran/elpa2/real_2stage_banded.F90

@@ -244,7 +244,7 @@ program test_real2_double_banded
    call e%set("solver", ELPA_SOLVER_2STAGE, success)
    assert_elpa_ok(success)
 
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
    call elpa_deallocate(e)
 

test/Fortran/elpa2/single_complex_2stage.F90

@@ -145,7 +145,7 @@ program test_interface
    call e%set("complex_kernel", ELPA_2STAGE_COMPLEX_DEFAULT, success)
    assert_elpa_ok(success)
 
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
    call elpa_deallocate(e)
 

test/Fortran/elpa2/single_complex_2stage_banded.F90

@@ -256,7 +256,7 @@ program test_complex2_single_banded
 
    call e%set("solver", ELPA_SOLVER_2STAGE, success)
    assert_elpa_ok(success)
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
    call elpa_deallocate(e)
 

test/Fortran/elpa2/single_real_2stage.F90

@@ -150,7 +150,7 @@ program test_interface
 
    call e%set("complex_kernel", ELPA_2STAGE_COMPLEX_DEFAULT, success)
    assert_elpa_ok(success)
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
 
 

test/Fortran/elpa2/single_real_2stage_banded.F90

@@ -249,7 +249,7 @@ program test_real2_single_banded
    call e%set("solver", ELPA_SOLVER_2STAGE, success)
    assert_elpa_ok(success)
 
-   call e%solve(a, ev, z, success)
+   call e%eigenvectors(a, ev, z, success)
    assert_elpa_ok(success)
    call elpa_deallocate(e)
 

test/Fortran/test.F90

@@ -189,7 +189,7 @@ program test
 #endif
 
    ! The actual solve step
-   call e%solve(a, ev, z, error)
+   call e%eigenvectors(a, ev, z, error)
    assert_elpa_ok(error)
 
    call elpa_deallocate(e)