Update documentation about checking the blacs distribution

documentation/USERS_GUIDE.md

@@ -376,6 +376,8 @@ to be done in the application using MPI which wants to call ELPA, namely
 
 - Initializing the MPI
 - creating a blacs distributed matrix
+- IMPORTANT: it is very, very important that you check the return value of "descinit" of your blacs distribution!
+  ELPA relies that the distribution it should work on is _valid_. If this is not the case the behavior is undefined!
 - 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 
@@ -438,6 +440,12 @@ call BLACS_Gridinfo( my_blacs_ctxt, nprow, npcol, my_prow, my_pcol )
 
 call descinit( sc_desc, na, na, nblk, nblk, 0, 0, my_blacs_ctxt, na_rows, info )
 
+! check the return code
+if (info .ne. 0) then
+  print *,"Invalid blacs-distribution. Abort!"
+  stop
+endif
+
 ! Allocate matrices 
 
 allocate(a (na_rows,na_cols))

src/elpa.F90

@@ -100,6 +100,13 @@
 !> \brief Abstract definition of the elpa_t type
 !>
 !>
+!> Since ELPA needs (in case of MPI builds) that the matix is block-cyclic distributed
+!> the user has to ensure this distribution _before_ calling ELPA.
+!> Experience shows, that it is very important that the user checks the return code of
+!> 'descinit' to check whether the block-cyclic distribution is valid.
+!> Note that ELPA relies on a valid block-cyclic distribution and might show unexpected
+!> behavior if this has not been ensured before calling ELPA.
+!>
 !> A typical usage of ELPA might look like this:
 !>
 !> Fortran synopsis