LAPACK  3.4.1
LAPACK: Linear Algebra PACKage
dlatm3.f
Go to the documentation of this file.
00001 *> \brief \b DLATM3
00002 *
00003 *  =========== DOCUMENTATION ===========
00004 *
00005 * Online html documentation available at 
00006 *            http://www.netlib.org/lapack/explore-html/ 
00007 *
00008 *  Definition:
00009 *  ===========
00010 *
00011 *       DOUBLE PRECISION FUNCTION DLATM3( M, N, I, J, ISUB, JSUB, KL, KU,
00012 *                        IDIST, 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 *       DOUBLE PRECISION   SPARSE
00020 *       ..
00021 *  
00022 *       .. Array Arguments ..
00023 *  
00024 *       INTEGER            ISEED( 4 ), IWORK( * )
00025 *       DOUBLE PRECISION   D( * ), DL( * ), DR( * )
00026 *       ..
00027 *  
00028 *
00029 *> \par Purpose:
00030 *  =============
00031 *>
00032 *> \verbatim
00033 *>
00034 *>    DLATM3 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. DLATM3 is called by the
00038 *>    DLATMR 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 DLATMR which has already checked the parameters.
00041 *>
00042 *>    Use of DLATM3 differs from SLATM2 in the order in which the random
00043 *>    number generator is called to fill in random matrix entries.
00044 *>    With DLATM2, the generator is called to fill in the pivoted matrix
00045 *>    columnwise. With DLATM3, the generator is called to fill in the
00046 *>    matrix columnwise, after which it is pivoted. Thus, DLATM3 can
00047 *>    be used to construct random matrices which differ only in their
00048 *>    order of rows and/or columns. DLATM2 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 => UNIFORM( 0, 1 )
00132 *>           2 => UNIFORM( -1, 1 )
00133 *>           3 => NORMAL( 0, 1 )
00134 *>           Not modified.
00135 *> \endverbatim
00136 *>
00137 *> \param[in,out] ISEED
00138 *> \verbatim
00139 *>          ISEED is INTEGER array of dimension ( 4 )
00140 *>           Seed for random number generator.
00141 *>           Changed on exit.
00142 *> \endverbatim
00143 *>
00144 *> \param[in] D
00145 *> \verbatim
00146 *>          D is DOUBLE PRECISION array of dimension ( MIN( I , J ) )
00147 *>           Diagonal entries of matrix. Not modified.
00148 *> \endverbatim
00149 *>
00150 *> \param[in] IGRADE
00151 *> \verbatim
00152 *>          IGRADE is INTEGER
00153 *>           Specifies grading of matrix as follows:
00154 *>           0  => no grading
00155 *>           1  => matrix premultiplied by diag( DL )
00156 *>           2  => matrix postmultiplied by diag( DR )
00157 *>           3  => matrix premultiplied by diag( DL ) and
00158 *>                         postmultiplied by diag( DR )
00159 *>           4  => matrix premultiplied by diag( DL ) and
00160 *>                         postmultiplied by inv( diag( DL ) )
00161 *>           5  => matrix premultiplied by diag( DL ) and
00162 *>                         postmultiplied by diag( DL )
00163 *>           Not modified.
00164 *> \endverbatim
00165 *>
00166 *> \param[in] DL
00167 *> \verbatim
00168 *>          DL is DOUBLE PRECISION array ( I or J, as appropriate )
00169 *>           Left scale factors for grading matrix.  Not modified.
00170 *> \endverbatim
00171 *>
00172 *> \param[in] DR
00173 *> \verbatim
00174 *>          DR is DOUBLE PRECISION array ( I or J, as appropriate )
00175 *>           Right scale factors for grading matrix.  Not modified.
00176 *> \endverbatim
00177 *>
00178 *> \param[in] IPVTNG
00179 *> \verbatim
00180 *>          IPVTNG is INTEGER
00181 *>           On entry specifies pivoting permutations as follows:
00182 *>           0 => none.
00183 *>           1 => row pivoting.
00184 *>           2 => column pivoting.
00185 *>           3 => full pivoting, i.e., on both sides.
00186 *>           Not modified.
00187 *> \endverbatim
00188 *>
00189 *> \param[in] IWORK
00190 *> \verbatim
00191 *>          IWORK is INTEGER array ( I or J, as appropriate )
00192 *>           This array specifies the permutation used. The
00193 *>           row (or column) originally in position K is in
00194 *>           position IWORK( K ) after pivoting.
00195 *>           This differs from IWORK for DLATM2. Not modified.
00196 *> \endverbatim
00197 *>
00198 *> \param[in] SPARSE
00199 *> \verbatim
00200 *>          SPARSE is DOUBLE PRECISION between 0. and 1.
00201 *>           On entry specifies the sparsity of the matrix
00202 *>           if sparse matix is to be generated.
00203 *>           SPARSE should lie between 0 and 1.
00204 *>           A uniform ( 0, 1 ) random number x is generated and
00205 *>           compared to SPARSE; if x is larger the matrix entry
00206 *>           is unchanged and if x is smaller the entry is set
00207 *>           to zero. Thus on the average a fraction SPARSE of the
00208 *>           entries will be set to zero.
00209 *>           Not modified.
00210 *> \endverbatim
00211 *
00212 *  Authors:
00213 *  ========
00214 *
00215 *> \author Univ. of Tennessee 
00216 *> \author Univ. of California Berkeley 
00217 *> \author Univ. of Colorado Denver 
00218 *> \author NAG Ltd. 
00219 *
00220 *> \date November 2011
00221 *
00222 *> \ingroup double_matgen
00223 *
00224 *  =====================================================================
00225       DOUBLE PRECISION FUNCTION DLATM3( M, N, I, J, ISUB, JSUB, KL, KU,
00226      $                 IDIST, ISEED, D, IGRADE, DL, DR, IPVTNG, IWORK,
00227      $                 SPARSE )
00228 *
00229 *  -- LAPACK auxiliary routine (version 3.4.0) --
00230 *  -- LAPACK is a software package provided by Univ. of Tennessee,    --
00231 *  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
00232 *     November 2011
00233 *
00234 *     .. Scalar Arguments ..
00235 *
00236       INTEGER            I, IDIST, IGRADE, IPVTNG, ISUB, J, JSUB, KL,
00237      $                   KU, M, N
00238       DOUBLE PRECISION   SPARSE
00239 *     ..
00240 *
00241 *     .. Array Arguments ..
00242 *
00243       INTEGER            ISEED( 4 ), IWORK( * )
00244       DOUBLE PRECISION   D( * ), DL( * ), DR( * )
00245 *     ..
00246 *
00247 *  =====================================================================
00248 *
00249 *     .. Parameters ..
00250 *
00251       DOUBLE PRECISION   ZERO
00252       PARAMETER          ( ZERO = 0.0D0 )
00253 *     ..
00254 *
00255 *     .. Local Scalars ..
00256 *
00257       DOUBLE PRECISION   TEMP
00258 *     ..
00259 *
00260 *     .. External Functions ..
00261 *
00262       DOUBLE PRECISION   DLARAN, DLARND
00263       EXTERNAL           DLARAN, DLARND
00264 *     ..
00265 *
00266 *-----------------------------------------------------------------------
00267 *
00268 *     .. Executable Statements ..
00269 *
00270 *
00271 *     Check for I and J in range
00272 *
00273       IF( I.LT.1 .OR. I.GT.M .OR. J.LT.1 .OR. J.GT.N ) THEN
00274          ISUB = I
00275          JSUB = J
00276          DLATM3 = ZERO
00277          RETURN
00278       END IF
00279 *
00280 *     Compute subscripts depending on IPVTNG
00281 *
00282       IF( IPVTNG.EQ.0 ) THEN
00283          ISUB = I
00284          JSUB = J
00285       ELSE IF( IPVTNG.EQ.1 ) THEN
00286          ISUB = IWORK( I )
00287          JSUB = J
00288       ELSE IF( IPVTNG.EQ.2 ) THEN
00289          ISUB = I
00290          JSUB = IWORK( J )
00291       ELSE IF( IPVTNG.EQ.3 ) THEN
00292          ISUB = IWORK( I )
00293          JSUB = IWORK( J )
00294       END IF
00295 *
00296 *     Check for banding
00297 *
00298       IF( JSUB.GT.ISUB+KU .OR. JSUB.LT.ISUB-KL ) THEN
00299          DLATM3 = ZERO
00300          RETURN
00301       END IF
00302 *
00303 *     Check for sparsity
00304 *
00305       IF( SPARSE.GT.ZERO ) THEN
00306          IF( DLARAN( ISEED ).LT.SPARSE ) THEN
00307             DLATM3 = ZERO
00308             RETURN
00309          END IF
00310       END IF
00311 *
00312 *     Compute entry and grade it according to IGRADE
00313 *
00314       IF( I.EQ.J ) THEN
00315          TEMP = D( I )
00316       ELSE
00317          TEMP = DLARND( IDIST, ISEED )
00318       END IF
00319       IF( IGRADE.EQ.1 ) THEN
00320          TEMP = TEMP*DL( I )
00321       ELSE IF( IGRADE.EQ.2 ) THEN
00322          TEMP = TEMP*DR( J )
00323       ELSE IF( IGRADE.EQ.3 ) THEN
00324          TEMP = TEMP*DL( I )*DR( J )
00325       ELSE IF( IGRADE.EQ.4 .AND. I.NE.J ) THEN
00326          TEMP = TEMP*DL( I ) / DL( J )
00327       ELSE IF( IGRADE.EQ.5 ) THEN
00328          TEMP = TEMP*DL( I )*DL( J )
00329       END IF
00330       DLATM3 = TEMP
00331       RETURN
00332 *
00333 *     End of DLATM3
00334 *
00335       END
 All Files Functions