LAPACK  3.4.1
LAPACK: Linear Algebra PACKage
clatm2.f
Go to the documentation of this file.
00001 *> \brief \b CLATM2
00002 *
00003 *  =========== DOCUMENTATION ===========
00004 *
00005 * Online html documentation available at 
00006 *            http://www.netlib.org/lapack/explore-html/ 
00007 *
00008 *  Definition:
00009 *  ===========
00010 *
00011 *       COMPLEX FUNCTION CLATM2( M, N, I, J, KL, KU, IDIST, ISEED, D,
00012 *                                IGRADE, DL, DR, IPVTNG, IWORK, SPARSE )
00013 * 
00014 *       .. Scalar Arguments ..
00015 *  
00016 *       INTEGER            I, IDIST, IGRADE, IPVTNG, J, KL, KU, M, N
00017 *       REAL               SPARSE
00018 *       ..
00019 *  
00020 *       .. Array Arguments ..
00021 *  
00022 *       INTEGER            ISEED( 4 ), IWORK( * )
00023 *       COMPLEX            D( * ), DL( * ), DR( * )
00024 *       ..
00025 *  
00026 *
00027 *> \par Purpose:
00028 *  =============
00029 *>
00030 *> \verbatim
00031 *>
00032 *>    CLATM2 returns the (I,J) entry of a random matrix of dimension
00033 *>    (M, N) described by the other paramters. It is called by the
00034 *>    CLATMR routine in order to build random test matrices. No error
00035 *>    checking on parameters is done, because this routine is called in
00036 *>    a tight loop by CLATMR which has already checked the parameters.
00037 *>
00038 *>    Use of CLATM2 differs from CLATM3 in the order in which the random
00039 *>    number generator is called to fill in random matrix entries.
00040 *>    With CLATM2, the generator is called to fill in the pivoted matrix
00041 *>    columnwise. With CLATM3, the generator is called to fill in the
00042 *>    matrix columnwise, after which it is pivoted. Thus, CLATM3 can
00043 *>    be used to construct random matrices which differ only in their
00044 *>    order of rows and/or columns. CLATM2 is used to construct band
00045 *>    matrices while avoiding calling the random number generator for
00046 *>    entries outside the band (and therefore generating random numbers
00047 *>
00048 *>    The matrix whose (I,J) entry is returned is constructed as
00049 *>    follows (this routine only computes one entry):
00050 *>
00051 *>      If I is outside (1..M) or J is outside (1..N), return zero
00052 *>         (this is convenient for generating matrices in band format).
00053 *>
00054 *>      Generate a matrix A with random entries of distribution IDIST.
00055 *>
00056 *>      Set the diagonal to D.
00057 *>
00058 *>      Grade the matrix, if desired, from the left (by DL) and/or
00059 *>         from the right (by DR or DL) as specified by IGRADE.
00060 *>
00061 *>      Permute, if desired, the rows and/or columns as specified by
00062 *>         IPVTNG and IWORK.
00063 *>
00064 *>      Band the matrix to have lower bandwidth KL and upper
00065 *>         bandwidth KU.
00066 *>
00067 *>      Set random entries to zero as specified by SPARSE.
00068 *> \endverbatim
00069 *
00070 *  Arguments:
00071 *  ==========
00072 *
00073 *> \param[in] M
00074 *> \verbatim
00075 *>          M is INTEGER
00076 *>           Number of rows of matrix. Not modified.
00077 *> \endverbatim
00078 *>
00079 *> \param[in] N
00080 *> \verbatim
00081 *>          N is INTEGER
00082 *>           Number of columns of matrix. Not modified.
00083 *> \endverbatim
00084 *>
00085 *> \param[in] I
00086 *> \verbatim
00087 *>          I is INTEGER
00088 *>           Row of entry to be returned. Not modified.
00089 *> \endverbatim
00090 *>
00091 *> \param[in] J
00092 *> \verbatim
00093 *>          J is INTEGER
00094 *>           Column of entry to be returned. Not modified.
00095 *> \endverbatim
00096 *>
00097 *> \param[in] KL
00098 *> \verbatim
00099 *>          KL is INTEGER
00100 *>           Lower bandwidth. Not modified.
00101 *> \endverbatim
00102 *>
00103 *> \param[in] KU
00104 *> \verbatim
00105 *>          KU is INTEGER
00106 *>           Upper bandwidth. Not modified.
00107 *> \endverbatim
00108 *>
00109 *> \param[in] IDIST
00110 *> \verbatim
00111 *>          IDIST is INTEGER
00112 *>           On entry, IDIST specifies the type of distribution to be
00113 *>           used to generate a random matrix .
00114 *>           1 => real and imaginary parts each UNIFORM( 0, 1 )
00115 *>           2 => real and imaginary parts each UNIFORM( -1, 1 )
00116 *>           3 => real and imaginary parts each NORMAL( 0, 1 )
00117 *>           4 => complex number uniform in DISK( 0 , 1 )
00118 *>           Not modified.
00119 *> \endverbatim
00120 *>
00121 *> \param[in,out] ISEED
00122 *> \verbatim
00123 *>          ISEED is INTEGER array of dimension ( 4 )
00124 *>           Seed for random number generator.
00125 *>           Changed on exit.
00126 *> \endverbatim
00127 *>
00128 *> \param[in] D
00129 *> \verbatim
00130 *>          D is COMPLEX array of dimension ( MIN( I , J ) )
00131 *>           Diagonal entries of matrix. Not modified.
00132 *> \endverbatim
00133 *>
00134 *> \param[in] IGRADE
00135 *> \verbatim
00136 *>          IGRADE is INTEGER
00137 *>           Specifies grading of matrix as follows:
00138 *>           0  => no grading
00139 *>           1  => matrix premultiplied by diag( DL )
00140 *>           2  => matrix postmultiplied by diag( DR )
00141 *>           3  => matrix premultiplied by diag( DL ) and
00142 *>                         postmultiplied by diag( DR )
00143 *>           4  => matrix premultiplied by diag( DL ) and
00144 *>                         postmultiplied by inv( diag( DL ) )
00145 *>           5  => matrix premultiplied by diag( DL ) and
00146 *>                         postmultiplied by diag( CONJG(DL) )
00147 *>           6  => matrix premultiplied by diag( DL ) and
00148 *>                         postmultiplied by diag( DL )
00149 *>           Not modified.
00150 *> \endverbatim
00151 *>
00152 *> \param[in] DL
00153 *> \verbatim
00154 *>          DL is COMPLEX array ( I or J, as appropriate )
00155 *>           Left scale factors for grading matrix.  Not modified.
00156 *> \endverbatim
00157 *>
00158 *> \param[in] DR
00159 *> \verbatim
00160 *>          DR is COMPLEX array ( I or J, as appropriate )
00161 *>           Right scale factors for grading matrix.  Not modified.
00162 *> \endverbatim
00163 *>
00164 *> \param[in] IPVTNG
00165 *> \verbatim
00166 *>          IPVTNG is INTEGER
00167 *>           On entry specifies pivoting permutations as follows:
00168 *>           0 => none.
00169 *>           1 => row pivoting.
00170 *>           2 => column pivoting.
00171 *>           3 => full pivoting, i.e., on both sides.
00172 *>           Not modified.
00173 *> \endverbatim
00174 *>
00175 *> \param[out] IWORK
00176 *> \verbatim
00177 *>          IWORK is INTEGER array ( I or J, as appropriate )
00178 *>           This array specifies the permutation used. The
00179 *>           row (or column) in position K was originally in
00180 *>           position IWORK( K ).
00181 *>           This differs from IWORK for CLATM3. Not modified.
00182 *> \endverbatim
00183 *>
00184 *> \param[in] SPARSE
00185 *> \verbatim
00186 *>          SPARSE is REAL
00187 *>           Value between 0. and 1.
00188 *>           On entry specifies the sparsity of the matrix
00189 *>           if sparse matix is to be generated.
00190 *>           SPARSE should lie between 0 and 1.
00191 *>           A uniform ( 0, 1 ) random number x is generated and
00192 *>           compared to SPARSE; if x is larger the matrix entry
00193 *>           is unchanged and if x is smaller the entry is set
00194 *>           to zero. Thus on the average a fraction SPARSE of the
00195 *>           entries will be set to zero.
00196 *>           Not modified.
00197 *> \endverbatim
00198 *
00199 *  Authors:
00200 *  ========
00201 *
00202 *> \author Univ. of Tennessee 
00203 *> \author Univ. of California Berkeley 
00204 *> \author Univ. of Colorado Denver 
00205 *> \author NAG Ltd. 
00206 *
00207 *> \date November 2011
00208 *
00209 *> \ingroup complex_matgen
00210 *
00211 *  =====================================================================
00212       COMPLEX FUNCTION CLATM2( M, N, I, J, KL, KU, IDIST, ISEED, D,
00213      $                         IGRADE, DL, DR, IPVTNG, IWORK, SPARSE )
00214 *
00215 *  -- LAPACK auxiliary routine (version 3.4.0) --
00216 *  -- LAPACK is a software package provided by Univ. of Tennessee,    --
00217 *  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
00218 *     November 2011
00219 *
00220 *     .. Scalar Arguments ..
00221 *
00222       INTEGER            I, IDIST, IGRADE, IPVTNG, J, KL, KU, M, N
00223       REAL               SPARSE
00224 *     ..
00225 *
00226 *     .. Array Arguments ..
00227 *
00228       INTEGER            ISEED( 4 ), IWORK( * )
00229       COMPLEX            D( * ), DL( * ), DR( * )
00230 *     ..
00231 *
00232 *  =====================================================================
00233 *
00234 *     .. Parameters ..
00235 *
00236       COMPLEX            CZERO
00237       PARAMETER          ( CZERO = ( 0.0E0, 0.0E0 ) )
00238       REAL               ZERO
00239       PARAMETER          ( ZERO = 0.0E0 )
00240 *     ..
00241 *
00242 *     .. Local Scalars ..
00243 *
00244       INTEGER            ISUB, JSUB
00245       COMPLEX            CTEMP
00246 *     ..
00247 *
00248 *     .. External Functions ..
00249 *
00250       REAL               SLARAN
00251       COMPLEX            CLARND
00252       EXTERNAL           SLARAN, CLARND
00253 *     ..
00254 *
00255 *     .. Intrinsic Functions ..
00256 *
00257       INTRINSIC          CONJG
00258 *     ..
00259 *
00260 *-----------------------------------------------------------------------
00261 *
00262 *     .. Executable Statements ..
00263 *
00264 *
00265 *     Check for I and J in range
00266 *
00267       IF( I.LT.1 .OR. I.GT.M .OR. J.LT.1 .OR. J.GT.N ) THEN
00268          CLATM2 = CZERO
00269          RETURN
00270       END IF
00271 *
00272 *     Check for banding
00273 *
00274       IF( J.GT.I+KU .OR. J.LT.I-KL ) THEN
00275          CLATM2 = CZERO
00276          RETURN
00277       END IF
00278 *
00279 *     Check for sparsity
00280 *
00281       IF( SPARSE.GT.ZERO ) THEN
00282          IF( SLARAN( ISEED ).LT.SPARSE ) THEN
00283             CLATM2 = CZERO
00284             RETURN
00285          END IF
00286       END IF
00287 *
00288 *     Compute subscripts depending on IPVTNG
00289 *
00290       IF( IPVTNG.EQ.0 ) THEN
00291          ISUB = I
00292          JSUB = J
00293       ELSE IF( IPVTNG.EQ.1 ) THEN
00294          ISUB = IWORK( I )
00295          JSUB = J
00296       ELSE IF( IPVTNG.EQ.2 ) THEN
00297          ISUB = I
00298          JSUB = IWORK( J )
00299       ELSE IF( IPVTNG.EQ.3 ) THEN
00300          ISUB = IWORK( I )
00301          JSUB = IWORK( J )
00302       END IF
00303 *
00304 *     Compute entry and grade it according to IGRADE
00305 *
00306       IF( ISUB.EQ.JSUB ) THEN
00307          CTEMP = D( ISUB )
00308       ELSE
00309          CTEMP = CLARND( IDIST, ISEED )
00310       END IF
00311       IF( IGRADE.EQ.1 ) THEN
00312          CTEMP = CTEMP*DL( ISUB )
00313       ELSE IF( IGRADE.EQ.2 ) THEN
00314          CTEMP = CTEMP*DR( JSUB )
00315       ELSE IF( IGRADE.EQ.3 ) THEN
00316          CTEMP = CTEMP*DL( ISUB )*DR( JSUB )
00317       ELSE IF( IGRADE.EQ.4 .AND. ISUB.NE.JSUB ) THEN
00318          CTEMP = CTEMP*DL( ISUB ) / DL( JSUB )
00319       ELSE IF( IGRADE.EQ.5 ) THEN
00320          CTEMP = CTEMP*DL( ISUB )*CONJG( DL( JSUB ) )
00321       ELSE IF( IGRADE.EQ.6 ) THEN
00322          CTEMP = CTEMP*DL( ISUB )*DL( JSUB )
00323       END IF
00324       CLATM2 = CTEMP
00325       RETURN
00326 *
00327 *     End of CLATM2
00328 *
00329       END
 All Files Functions