Update of Doxygen documentation

src/elpa.F90

@@ -48,6 +48,39 @@
 
 ! The ELPA public API
 
+
+!> \mainpage
+!> Eigenvalue SoLvers for Petaflop-Applications (ELPA)
+!> \par
+!> http://elpa.mpcdf.mpg.de
+!>
+!> \par
+!>    The ELPA library was originally created by the ELPA consortium,
+!>    consisting of the following organizations:
+!>
+!>    - Max Planck Computing and Data Facility (MPCDF) formerly known as
+!>      Rechenzentrum Garching der Max-Planck-Gesellschaft (RZG),
+!>    - Bergische Universität Wuppertal, Lehrstuhl für angewandte
+!>      Informatik,
+!>    - Technische Universität München, Lehrstuhl für Informatik mit
+!>      Schwerpunkt Wissenschaftliches Rechnen ,
+!>    - Fritz-Haber-Institut, Berlin, Abt. Theorie,
+!>    - Max-Plack-Institut für Mathematik in den Naturwissenschaften,
+!>      Leipzig, Abt. Komplexe Strukutren in Biologie und Kognition,
+!>      and
+!>    - IBM Deutschland GmbH
+!>
+!>   Some parts and enhancements of ELPA have been contributed and authored
+!>   by the Intel Corporation and Nvidia Corporation which are not part of
+!>   the ELPA consortium.
+!>
+!>   Contributions to the ELPA source have been authored by (in alphabetical order):
+!>
+!> \author T. Auckenthaler, Volker Blum, A. Heinecke, L. Huedepohl, R. Johanni, Werner Jürgens, Pavel Kus, and A. Marek
+!>
+!> All the important information is in the \ref elpa_api::elpa_t derived type
+
+
 !> \brief Fortran module to use the ELPA library. No other module shoule be used
 module elpa
   use elpa_constants

src/elpa2/elpa2.F90

@@ -53,7 +53,7 @@
 ! Author: Andreas Marek, MPCDF
 
 #include "config-f90.h"
-!> \brief Fortran module which provides the routines to use the 2-stage ELPA solver
+!> \brief Fortran module which provides the routines to use the 2-stage ELPA solver. Implementation only. Should not be used directly
 module elpa2_impl
   use elpa_utilities, only : error_unit
 

src/elpa2/legacy_interface/elpa2_utilities.F90

@@ -50,7 +50,7 @@
 ! Author: Andreas Marek, MPCDF
 
 #include "config-f90.h"
-
+!> \brief Fortran module tp provide some variables for the LEGACY interface. This is obsolete, please use the new interface
 module elpa2_utilities
   use elpa
   use precision

src/elpa_abstract_impl.F90

@@ -46,7 +46,7 @@
 !    the original distribution, the GNU Lesser General Public License.
 !
 #include "config-f90.h"
-
+!> \brief Fortran module to provide an abstract definition of the implementation. Do not use directly. Use the module "elpa"
 module elpa_abstract_impl
   use elpa_api
 #ifdef HAVE_DETAILED_TIMINGS

src/elpa_api.F90

@@ -46,7 +46,9 @@
 !    the original distribution, the GNU Lesser General Public License.
 !
 #include "config-f90.h"
-!> \brief Fortran module which provides the definition of the ELPA API
+!> \brief Fortran module which provides the definition of the ELPA API. Do not use directly! Use the module "elpa"
+
+
 module elpa_api
   use elpa_constants
   use, intrinsic :: iso_c_binding
@@ -64,6 +66,53 @@ module elpa_api
       c_float, c_float_complex
 
   !> \brief Abstract definition of the elpa_t type
+
+  !>
+  !> A typical usage of ELPA might look like this:
+  !>
+  !> Fortran synopsis
+  !>
+  !> \code{.f90}
+  !>  use elpa
+  !>  class(elpa_t), pointer :: elpa
+  !>
+  !>  if (elpa_init(20170403) /= ELPA_OK) then
+  !>     print *, "ELPA API version not supported"
+  !>     stop
+  !>   endif
+  !>   elpa => elpa_allocate()
+  !>
+  !>   call elpa%set("na", na, success)
+  !>   assert_elpa_ok(success)
+  !>   call elpa%set("nev", nev, success)
+  !>   assert_elpa_ok(success)
+  !>   call elpa%set("local_nrows", na_rows, success)
+  !>   assert_elpa_ok(success)
+  !>   call elpa%set("local_ncols", na_cols, success)
+  !>   assert_elpa_ok(success)
+  !>   call elpa%set("nblk", nblk, success)
+  !>   assert_elpa_ok(success)
+  !>   call elpa%set("mpi_comm_parent", MPI_COMM_WORLD, success)
+  !>   assert_elpa_ok(success)
+  !>   call elpa%set("process_row", my_prow, success)
+  !>   assert_elpa_ok(success)
+  !>   call elpa%set("process_col", my_pcol, success)
+  !>   assert_elpa_ok(success)
+  !>
+  !>   assert(elpa%setup() .eq. ELPA_OK)
+  !>
+  !>   call e%set("solver", ELPA_SOLVER_2STAGE, success)
+  !>   assert_elpa_ok(success)
+  !> \endcode
+  !>   ... set and get all other options that are desired
+  !> \code{.f90}
+  !>   call e%solve(a, ev, z, success)
+  !>   assert_elpa_ok(success)
+  !>
+  !>   call elpa_deallocate(e)
+  !>
+  !>   call elpa_uninit()
+  !> \endcode
   type, abstract :: elpa_t
     private
 
@@ -80,7 +129,7 @@ module elpa_api
       procedure(elpa_setup_i),   deferred, public :: setup          !< export a setup method
       procedure(elpa_destroy_i), deferred, public :: destroy        !< export a destroy method
 
-      !< key/value store
+      ! key/value store
       generic, public :: set => &                                   !< export a method to set integer/double key/values
           elpa_set_integer, &
           elpa_set_double
@@ -90,20 +139,20 @@ module elpa_api
       procedure(elpa_is_set_i),  deferred, public :: is_set         !< method to check whether key/value is set
       procedure(elpa_can_set_i), deferred, public :: can_set        !< method to check whether key/value can be set
 
-      !< Timer
+      ! Timer
       procedure(elpa_get_time_i), deferred, public :: get_time
       procedure(elpa_print_times_i), deferred, public :: print_times
 
-      !< Actual math routines
+      ! 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_d, &                                           !< for symmetric real valued / hermitian complex valued
+          elpa_solve_f, &                                           !< matrices
           elpa_solve_dc, &
           elpa_solve_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
-          elpa_hermitian_multiply_dc, &                              !< for complex valued matrices a**H * b
+          elpa_hermitian_multiply_dc, &                             !< for complex valued matrices a**H * b
           elpa_hermitian_multiply_f, &
           elpa_hermitian_multiply_fc
 
@@ -120,7 +169,7 @@ module elpa_api
           elpa_invert_trm_fc
 
       generic, public :: solve_tridi => &                           !< method to solve the eigenvalue problem for a tridiagonal
-          elpa_solve_tridi_d, &                           !< matrix
+          elpa_solve_tridi_d, &                                     !< matrix
           elpa_solve_tridi_f
 
 
@@ -344,7 +393,7 @@ module elpa_api
   end interface
 
 
-  !< Actual math routines
+  ! Actual math routines
 
   !> \brief abstract definition of interface to solve double real eigenvalue problem
   !> Parameters

src/elpa_driver/legacy_interface/elpa.F90

@@ -52,7 +52,7 @@
 ! writen by A. Marek (MPCDF), andreas.marek@mpcdf.mpg.de
 
 #include "config-f90.h"
-!> \brief Fortran module which provides the routines to the ELPA solver (1 and 2 stage)
+!> \brief Fortran module which provides the routines to the ELPA solver (1 and 2 stage). This is the LEGACY interface. Do not use anymore!
 module elpa_driver
   use, intrinsic :: iso_c_binding, only : c_double, c_int, c_float, c_float_complex, c_double_complex
   use elpa1

src/elpa_impl.F90

@@ -47,7 +47,7 @@
 !
 #include "config-f90.h"
 
-!> \brief Fortran module which provides the implementation of the API
+!> \brief Fortran module which provides the actual implementation of the API. Do not use directly! Use the module "elpa"
 module elpa_impl
   use elpa_abstract_impl
   use, intrinsic :: iso_c_binding

src/helpers/mod_mpi.F90

@@ -43,6 +43,7 @@
 
 #include "config-f90.h"
 
+!> \brief Fortran module which exports the MPI functions to ELPA
 module elpa_mpi
 #ifndef WITH_MPI
   use elpa_mpi_stubs

src/helpers/mod_mpi_stubs.F90

@@ -42,7 +42,7 @@
 ! Author Andreas Marek, MPCDF
 
 #include "config-f90.h"
-
+!> \brief Fortran module which exports the MPI stubs function, if ELPA as been built without MPI support
 module elpa_mpi_stubs
   use precision
   implicit none

src/helpers/mod_precision.F90

@@ -41,6 +41,7 @@
 ! This file was written by A. Marek, MPCDF
 
 #include "config-f90.h"
+!> \brief Fortran module which defines the datatypes used in ELPA
 module precision
   use iso_c_binding, only : C_FLOAT, C_DOUBLE, C_FLOAT_COMPLEX, C_DOUBLE_COMPLEX, C_INT32_T, C_INT64_T, C_INT