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