LAPACK  3.4.1
LAPACK: Linear Algebra PACKage
zlatm2.f
Go to the documentation of this file.
00001 *> \brief \b ZLATM2
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*16   FUNCTION ZLATM2( M, N, I, J, KL, KU, IDIST,
00012 *                        ISEED, D, IGRADE, DL, DR, IPVTNG, IWORK, SPARSE )
00013 * 
00014 *       .. Scalar Arguments ..
00015 *  
00016 *       INTEGER            I, IDIST, IGRADE, IPVTNG, J, KL, KU, M, N
00017 *       DOUBLE PRECISION   SPARSE
00018 *       ..
00019 *  
00020 *       .. Array Arguments ..
00021 *  
00022 *       INTEGER            ISEED( 4 ), IWORK( * )
00023 *       COMPLEX*16         D( * ), DL( * ), DR( * )
00024 *       ..
00025 *  
00026 *
00027 *> \par Purpose:
00028 *  =============
00029 *>
00030 *> \verbatim
00031 *>
00032 *>    ZLATM2 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 *>    ZLATMR 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 ZLATMR which has already checked the parameters.
00037 *>
00038 *>    Use of ZLATM2 differs from CLATM3 in the order in which the random
00039 *>    number generator is called to fill in random matrix entries.
00040 *>    With ZLATM2, the generator is called to fill in the pivoted matrix
00041 *>    columnwise. With ZLATM3, the generator is called to fill in the
00042 *>    matrix columnwise, after which it is pivoted. Thus, ZLATM3 can
00043 *>    be used to construct random matrices which differ only in their
00044 *>    order of rows and/or columns. ZLATM2 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*16 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*16 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*16 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 ZLATM3. Not modified.
00182 *> \endverbatim
00183 *>
00184 *> \param[in] SPARSE
00185 *> \verbatim
00186 *>          SPARSE is DOUBLE PRECISION between 0. and 1.
00187 *>           On entry specifies the sparsity of the matrix
00188 *>           if sparse matix is to be generated.
00189 *>           SPARSE should lie between 0 and 1.
00190 *>           A uniform ( 0, 1 ) random number x is generated and
00191 *>           compared to SPARSE; if x is larger the matrix entry
00192 *>           is unchanged and if x is smaller the entry is set
00193 *>           to zero. Thus on the average a fraction SPARSE of the
00194 *>           entries will be set to zero.
00195 *>           Not modified.
00196 *> \endverbatim
00197 *
00198 *  Authors:
00199 *  ========
00200 *
00201 *> \author Univ. of Tennessee 
00202 *> \author Univ. of California Berkeley 
00203 *> \author Univ. of Colorado Denver 
00204 *> \author NAG Ltd. 
00205 *
00206 *> \date November 2011
00207 *
00208 *> \ingroup complex16_matgen
00209 *
00210 *  =====================================================================
00211       COMPLEX*16   FUNCTION ZLATM2( M, N, I, J, KL, KU, IDIST,
00212      $                 ISEED, D, IGRADE, DL, DR, IPVTNG, IWORK, SPARSE )
00213 *
00214 *  -- LAPACK auxiliary routine (version 3.4.0) --
00215 *  -- LAPACK is a software package provided by Univ. of Tennessee,    --
00216 *  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
00217 *     November 2011
00218 *
00219 *     .. Scalar Arguments ..
00220 *
00221       INTEGER            I, IDIST, IGRADE, IPVTNG, J, KL, KU, M, N
00222       DOUBLE PRECISION   SPARSE
00223 *     ..
00224 *
00225 *     .. Array Arguments ..
00226 *
00227       INTEGER            ISEED( 4 ), IWORK( * )
00228       COMPLEX*16         D( * ), DL( * ), DR( * )
00229 *     ..
00230 *
00231 *  =====================================================================
00232 *
00233 *     .. Parameters ..
00234 *
00235       COMPLEX*16         CZERO
00236       PARAMETER          ( CZERO = ( 0.0D0, 0.0D0 ) )
00237       DOUBLE PRECISION   ZERO
00238       PARAMETER          ( ZERO = 0.0D0 )
00239 *     ..
00240 *
00241 *     .. Local Scalars ..
00242 *
00243       INTEGER            ISUB, JSUB
00244       COMPLEX*16         CTEMP
00245 *     ..
00246 *
00247 *     .. External Functions ..
00248 *
00249       DOUBLE PRECISION   DLARAN
00250       COMPLEX*16         ZLARND
00251       EXTERNAL           DLARAN, ZLARND
00252 *     ..
00253 *
00254 *     .. Intrinsic Functions ..
00255 *
00256       INTRINSIC          DCONJG
00257 *     ..
00258 *
00259 *-----------------------------------------------------------------------
00260 *
00261 *     .. Executable Statements ..
00262 *
00263 *
00264 *     Check for I and J in range
00265 *
00266       IF( I.LT.1 .OR. I.GT.M .OR. J.LT.1 .OR. J.GT.N ) THEN
00267          ZLATM2 = CZERO
00268          RETURN
00269       END IF
00270 *
00271 *     Check for banding
00272 *
00273       IF( J.GT.I+KU .OR. J.LT.I-KL ) THEN
00274          ZLATM2 = CZERO
00275          RETURN
00276       END IF
00277 *
00278 *     Check for sparsity
00279 *
00280       IF( SPARSE.GT.ZERO ) THEN
00281          IF( DLARAN( ISEED ).LT.SPARSE ) THEN
00282             ZLATM2 = CZERO
00283             RETURN
00284          END IF
00285       END IF
00286 *
00287 *     Compute subscripts depending on IPVTNG
00288 *
00289       IF( IPVTNG.EQ.0 ) THEN
00290          ISUB = I
00291          JSUB = J
00292       ELSE IF( IPVTNG.EQ.1 ) THEN
00293          ISUB = IWORK( I )
00294          JSUB = J
00295       ELSE IF( IPVTNG.EQ.2 ) THEN
00296          ISUB = I
00297          JSUB = IWORK( J )
00298       ELSE IF( IPVTNG.EQ.3 ) THEN
00299          ISUB = IWORK( I )
00300          JSUB = IWORK( J )
00301       END IF
00302 *
00303 *     Compute entry and grade it according to IGRADE
00304 *
00305       IF( ISUB.EQ.JSUB ) THEN
00306          CTEMP = D( ISUB )
00307       ELSE
00308          CTEMP = ZLARND( IDIST, ISEED )
00309       END IF
00310       IF( IGRADE.EQ.1 ) THEN
00311          CTEMP = CTEMP*DL( ISUB )
00312       ELSE IF( IGRADE.EQ.2 ) THEN
00313          CTEMP = CTEMP*DR( JSUB )
00314       ELSE IF( IGRADE.EQ.3 ) THEN
00315          CTEMP = CTEMP*DL( ISUB )*DR( JSUB )
00316       ELSE IF( IGRADE.EQ.4 .AND. ISUB.NE.JSUB ) THEN
00317          CTEMP = CTEMP*DL( ISUB ) / DL( JSUB )
00318       ELSE IF( IGRADE.EQ.5 ) THEN
00319          CTEMP = CTEMP*DL( ISUB )*DCONJG( DL( JSUB ) )
00320       ELSE IF( IGRADE.EQ.6 ) THEN
00321          CTEMP = CTEMP*DL( ISUB )*DL( JSUB )
00322       END IF
00323       ZLATM2 = CTEMP
00324       RETURN
00325 *
00326 *     End of ZLATM2
00327 *
00328       END
 All Files Functions