ScaLAPACK  2.0.2
ScaLAPACK: Scalable Linear Algebra PACKage
descinit.f
Go to the documentation of this file.
00001       SUBROUTINE DESCINIT( DESC, M, N, MB, NB, IRSRC, ICSRC, ICTXT,
00002      $                     LLD, INFO )
00003 *
00004 *  -- ScaLAPACK tools routine (version 1.7) --
00005 *     University of Tennessee, Knoxville, Oak Ridge National Laboratory,
00006 *     and University of California, Berkeley.
00007 *     May 1, 1997
00008 *
00009 *     .. Scalar Arguments ..
00010       INTEGER            ICSRC, ICTXT, INFO, IRSRC, LLD, M, MB, N, NB
00011 *     ..
00012 *     .. Array Arguments ..
00013       INTEGER            DESC( * )
00014 *     ..
00015 *
00016 *  Purpose
00017 *  =======
00018 *
00019 *  DESCINIT initializes the descriptor vector with the 8 input arguments
00020 *  M, N, MB, NB, IRSRC, ICSRC, ICTXT, LLD.
00021 *
00022 *  Notes
00023 *  =====
00024 *
00025 *  Each global data object is described by an associated description
00026 *  vector.  This vector stores the information required to establish
00027 *  the mapping between an object element and its corresponding process
00028 *  and memory location.
00029 *
00030 *  Let A be a generic term for any 2D block cyclicly distributed array.
00031 *  Such a global array has an associated description vector DESCA.
00032 *  In the following comments, the character _ should be read as
00033 *  "of the global array".
00034 *
00035 *  NOTATION        STORED IN      EXPLANATION
00036 *  --------------- -------------- --------------------------------------
00037 *  DTYPE_A(global) DESCA( DTYPE_ )The descriptor type.  In this case,
00038 *                                 DTYPE_A = 1.
00039 *  CTXT_A (global) DESCA( CTXT_ ) The BLACS context handle, indicating
00040 *                                 the BLACS process grid A is distribu-
00041 *                                 ted over. The context itself is glo-
00042 *                                 bal, but the handle (the integer
00043 *                                 value) may vary.
00044 *  M_A    (global) DESCA( M_ )    The number of rows in the global
00045 *                                 array A.
00046 *  N_A    (global) DESCA( N_ )    The number of columns in the global
00047 *                                 array A.
00048 *  MB_A   (global) DESCA( MB_ )   The blocking factor used to distribute
00049 *                                 the rows of the array.
00050 *  NB_A   (global) DESCA( NB_ )   The blocking factor used to distribute
00051 *                                 the columns of the array.
00052 *  RSRC_A (global) DESCA( RSRC_ ) The process row over which the first
00053 *                                 row of the array A is distributed.
00054 *  CSRC_A (global) DESCA( CSRC_ ) The process column over which the
00055 *                                 first column of the array A is
00056 *                                 distributed.
00057 *  LLD_A  (local)  DESCA( LLD_ )  The leading dimension of the local
00058 *                                 array.  LLD_A >= MAX(1,LOCr(M_A)).
00059 *
00060 *  Let K be the number of rows or columns of a distributed matrix,
00061 *  and assume that its process grid has dimension p x q.
00062 *  LOCr( K ) denotes the number of elements of K that a process
00063 *  would receive if K were distributed over the p processes of its
00064 *  process column.
00065 *  Similarly, LOCc( K ) denotes the number of elements of K that a
00066 *  process would receive if K were distributed over the q processes of
00067 *  its process row.
00068 *  The values of LOCr() and LOCc() may be determined via a call to the
00069 *  ScaLAPACK tool function, NUMROC:
00070 *          LOCr( M ) = NUMROC( M, MB_A, MYROW, RSRC_A, NPROW ),
00071 *          LOCc( N ) = NUMROC( N, NB_A, MYCOL, CSRC_A, NPCOL ).
00072 *  An upper bound for these quantities may be computed by:
00073 *          LOCr( M ) <= ceil( ceil(M/MB_A)/NPROW )*MB_A
00074 *          LOCc( N ) <= ceil( ceil(N/NB_A)/NPCOL )*NB_A
00075 *
00076 *  Arguments
00077 *  =========
00078 *
00079 *  DESC    (output) INTEGER array of dimension DLEN_.
00080 *          The array descriptor of a distributed matrix to be set.
00081 *
00082 *  M       (global input) INTEGER
00083 *          The number of rows in the distributed matrix. M >= 0.
00084 *
00085 *  N       (global input) INTEGER
00086 *          The number of columns in the distributed matrix. N >= 0.
00087 *
00088 *  MB      (global input) INTEGER
00089 *          The blocking factor used to distribute the rows of the
00090 *          matrix. MB >= 1.
00091 *
00092 *  NB      (global input) INTEGER
00093 *          The blocking factor used to distribute the columns of the
00094 *          matrix. NB >= 1.
00095 *
00096 *  IRSRC   (global input) INTEGER
00097 *          The process row over which the first row of the matrix is
00098 *          distributed. 0 <= IRSRC < NPROW.
00099 *
00100 *  ICSRC   (global input) INTEGER
00101 *          The process column over which the first column of the
00102 *          matrix is distributed. 0 <= ICSRC < NPCOL.
00103 *
00104 *  ICTXT   (global input) INTEGER
00105 *          The BLACS context handle, indicating the global context of
00106 *          the operation on the matrix. The context itself is global.
00107 *
00108 *  LLD     (local input)  INTEGER
00109 *          The leading dimension of the local array storing the local
00110 *          blocks of the distributed matrix. LLD >= MAX(1,LOCr(M)).
00111 *
00112 *  INFO    (output) INTEGER
00113 *          = 0: successful exit
00114 *          < 0: if INFO = -i, the i-th argument had an illegal value
00115 *
00116 *  Note
00117 *  ====
00118 *
00119 *  If the routine can recover from an erroneous input argument, it will
00120 *  return an acceptable descriptor vector.  For example, if LLD = 0 on
00121 *  input, DESC(LLD_) will contain the smallest leading dimension
00122 *  required to store the specified M-by-N distributed matrix, INFO
00123 *  will be set  -9 in that case.
00124 *
00125 *  =====================================================================
00126 *
00127 *     .. Parameters ..
00128       INTEGER            BLOCK_CYCLIC_2D, CSRC_, CTXT_, DLEN_, DTYPE_,
00129      $                   LLD_, MB_, M_, NB_, N_, RSRC_
00130       PARAMETER          ( BLOCK_CYCLIC_2D = 1, DLEN_ = 9, DTYPE_ = 1,
00131      $                     CTXT_ = 2, M_ = 3, N_ = 4, MB_ = 5, NB_ = 6,
00132      $                     RSRC_ = 7, CSRC_ = 8, LLD_ = 9 )
00133 *     ..
00134 *     .. Local Scalars ..
00135       INTEGER            MYCOL, MYROW, NPCOL, NPROW
00136 *     ..
00137 *     .. External Subroutines ..
00138       EXTERNAL           BLACS_GRIDINFO, PXERBLA
00139 *     ..
00140 *     .. External Functions ..
00141       INTEGER            NUMROC
00142       EXTERNAL           NUMROC
00143 *     ..
00144 *     .. Intrinsic Functions ..
00145       INTRINSIC          MAX, MIN
00146 *     ..
00147 *     .. Executable Statements ..
00148 *
00149 *     Get grid parameters
00150 *
00151       CALL BLACS_GRIDINFO( ICTXT, NPROW, NPCOL, MYROW, MYCOL )
00152 *
00153       INFO = 0
00154       IF( M.LT.0 ) THEN
00155          INFO = -2
00156       ELSE IF( N.LT.0 ) THEN
00157          INFO = -3
00158       ELSE IF( MB.LT.1 ) THEN
00159          INFO = -4
00160       ELSE IF( NB.LT.1 ) THEN
00161          INFO = -5
00162       ELSE IF( IRSRC.LT.0 .OR. IRSRC.GE.NPROW ) THEN
00163          INFO = -6
00164       ELSE IF( ICSRC.LT.0 .OR. ICSRC.GE.NPCOL ) THEN
00165          INFO = -7
00166       ELSE IF( NPROW.EQ.-1 ) THEN
00167          INFO = -8
00168       ELSE IF( LLD.LT.MAX( 1, NUMROC( M, MB, MYROW, IRSRC,
00169      $                                NPROW ) ) ) THEN
00170          INFO = -9
00171       END IF
00172 *
00173       IF( INFO.NE.0 )
00174      $   CALL PXERBLA( ICTXT, 'DESCINIT', -INFO )
00175 *
00176       DESC( DTYPE_ ) = BLOCK_CYCLIC_2D
00177       DESC( M_ )  = MAX( 0, M )
00178       DESC( N_ )  = MAX( 0, N )
00179       DESC( MB_ ) = MAX( 1, MB )
00180       DESC( NB_ ) = MAX( 1, NB )
00181       DESC( RSRC_ ) = MAX( 0, MIN( IRSRC, NPROW-1 ) )
00182       DESC( CSRC_ ) = MAX( 0, MIN( ICSRC, NPCOL-1 ) )
00183       DESC( CTXT_ ) = ICTXT
00184       DESC( LLD_ )  = MAX( LLD, MAX( 1, NUMROC( DESC( M_ ), DESC( MB_ ),
00185      $                              MYROW, DESC( RSRC_ ), NPROW ) ) )
00186 *
00187       RETURN
00188 *
00189 *     End DESCINIT
00190 *
00191       END