LAPACK  3.5.0
LAPACK: Linear Algebra PACKage
 All Classes Files Functions Variables Typedefs Macros
dlatm2.f
Go to the documentation of this file.
1 *> \brief \b DLATM2
2 *
3 * =========== DOCUMENTATION ===========
4 *
5 * Online html documentation available at
6 * http://www.netlib.org/lapack/explore-html/
7 *
8 * Definition:
9 * ===========
10 *
11 * DOUBLE PRECISION FUNCTION DLATM2( M, N, I, J, KL, KU, IDIST,
12 * ISEED, D, IGRADE, DL, DR, IPVTNG, IWORK, SPARSE )
13 *
14 * .. Scalar Arguments ..
15 *
16 * INTEGER I, IDIST, IGRADE, IPVTNG, J, KL, KU, M, N
17 * DOUBLE PRECISION SPARSE
18 * ..
19 *
20 * .. Array Arguments ..
21 *
22 * INTEGER ISEED( 4 ), IWORK( * )
23 * DOUBLE PRECISION D( * ), DL( * ), DR( * )
24 * ..
25 *
26 *
27 *> \par Purpose:
28 * =============
29 *>
30 *> \verbatim
31 *>
32 *> DLATM2 returns the (I,J) entry of a random matrix of dimension
33 *> (M, N) described by the other paramters. It is called by the
34 *> DLATMR routine in order to build random test matrices. No error
35 *> checking on parameters is done, because this routine is called in
36 *> a tight loop by DLATMR which has already checked the parameters.
37 *>
38 *> Use of DLATM2 differs from SLATM3 in the order in which the random
39 *> number generator is called to fill in random matrix entries.
40 *> With DLATM2, the generator is called to fill in the pivoted matrix
41 *> columnwise. With DLATM3, the generator is called to fill in the
42 *> matrix columnwise, after which it is pivoted. Thus, DLATM3 can
43 *> be used to construct random matrices which differ only in their
44 *> order of rows and/or columns. DLATM2 is used to construct band
45 *> matrices while avoiding calling the random number generator for
46 *> entries outside the band (and therefore generating random numbers
47 *>
48 *> The matrix whose (I,J) entry is returned is constructed as
49 *> follows (this routine only computes one entry):
50 *>
51 *> If I is outside (1..M) or J is outside (1..N), return zero
52 *> (this is convenient for generating matrices in band format).
53 *>
54 *> Generate a matrix A with random entries of distribution IDIST.
55 *>
56 *> Set the diagonal to D.
57 *>
58 *> Grade the matrix, if desired, from the left (by DL) and/or
59 *> from the right (by DR or DL) as specified by IGRADE.
60 *>
61 *> Permute, if desired, the rows and/or columns as specified by
62 *> IPVTNG and IWORK.
63 *>
64 *> Band the matrix to have lower bandwidth KL and upper
65 *> bandwidth KU.
66 *>
67 *> Set random entries to zero as specified by SPARSE.
68 *> \endverbatim
69 *
70 * Arguments:
71 * ==========
72 *
73 *> \param[in] M
74 *> \verbatim
75 *> M is INTEGER
76 *> Number of rows of matrix. Not modified.
77 *> \endverbatim
78 *>
79 *> \param[in] N
80 *> \verbatim
81 *> N is INTEGER
82 *> Number of columns of matrix. Not modified.
83 *> \endverbatim
84 *>
85 *> \param[in] I
86 *> \verbatim
87 *> I is INTEGER
88 *> Row of entry to be returned. Not modified.
89 *> \endverbatim
90 *>
91 *> \param[in] J
92 *> \verbatim
93 *> J is INTEGER
94 *> Column of entry to be returned. Not modified.
95 *> \endverbatim
96 *>
97 *> \param[in] KL
98 *> \verbatim
99 *> KL is INTEGER
100 *> Lower bandwidth. Not modified.
101 *> \endverbatim
102 *>
103 *> \param[in] KU
104 *> \verbatim
105 *> KU is INTEGER
106 *> Upper bandwidth. Not modified.
107 *> \endverbatim
108 *>
109 *> \param[in] IDIST
110 *> \verbatim
111 *> IDIST is INTEGER
112 *> On entry, IDIST specifies the type of distribution to be
113 *> used to generate a random matrix .
114 *> 1 => UNIFORM( 0, 1 )
115 *> 2 => UNIFORM( -1, 1 )
116 *> 3 => NORMAL( 0, 1 )
117 *> Not modified.
118 *> \endverbatim
119 *>
120 *> \param[in,out] ISEED
121 *> \verbatim
122 *> ISEED is INTEGER array of dimension ( 4 )
123 *> Seed for random number generator.
124 *> Changed on exit.
125 *> \endverbatim
126 *>
127 *> \param[in] D
128 *> \verbatim
129 *> D is DOUBLE PRECISION array of dimension ( MIN( I , J ) )
130 *> Diagonal entries of matrix. Not modified.
131 *> \endverbatim
132 *>
133 *> \param[in] IGRADE
134 *> \verbatim
135 *> IGRADE is INTEGER
136 *> Specifies grading of matrix as follows:
137 *> 0 => no grading
138 *> 1 => matrix premultiplied by diag( DL )
139 *> 2 => matrix postmultiplied by diag( DR )
140 *> 3 => matrix premultiplied by diag( DL ) and
141 *> postmultiplied by diag( DR )
142 *> 4 => matrix premultiplied by diag( DL ) and
143 *> postmultiplied by inv( diag( DL ) )
144 *> 5 => matrix premultiplied by diag( DL ) and
145 *> postmultiplied by diag( DL )
146 *> Not modified.
147 *> \endverbatim
148 *>
149 *> \param[in] DL
150 *> \verbatim
151 *> DL is DOUBLE PRECISION array ( I or J, as appropriate )
152 *> Left scale factors for grading matrix. Not modified.
153 *> \endverbatim
154 *>
155 *> \param[in] DR
156 *> \verbatim
157 *> DR is DOUBLE PRECISION array ( I or J, as appropriate )
158 *> Right scale factors for grading matrix. Not modified.
159 *> \endverbatim
160 *>
161 *> \param[in] IPVTNG
162 *> \verbatim
163 *> IPVTNG is INTEGER
164 *> On entry specifies pivoting permutations as follows:
165 *> 0 => none.
166 *> 1 => row pivoting.
167 *> 2 => column pivoting.
168 *> 3 => full pivoting, i.e., on both sides.
169 *> Not modified.
170 *> \endverbatim
171 *>
172 *> \param[out] IWORK
173 *> \verbatim
174 *> IWORK is INTEGER array ( I or J, as appropriate )
175 *> This array specifies the permutation used. The
176 *> row (or column) in position K was originally in
177 *> position IWORK( K ).
178 *> This differs from IWORK for DLATM3. Not modified.
179 *> \endverbatim
180 *>
181 *> \param[in] SPARSE
182 *> \verbatim
183 *> SPARSE is DOUBLE PRECISION between 0. and 1.
184 *> On entry specifies the sparsity of the matrix
185 *> if sparse matix is to be generated.
186 *> SPARSE should lie between 0 and 1.
187 *> A uniform ( 0, 1 ) random number x is generated and
188 *> compared to SPARSE; if x is larger the matrix entry
189 *> is unchanged and if x is smaller the entry is set
190 *> to zero. Thus on the average a fraction SPARSE of the
191 *> entries will be set to zero.
192 *> Not modified.
193 *> \endverbatim
194 *
195 * Authors:
196 * ========
197 *
198 *> \author Univ. of Tennessee
199 *> \author Univ. of California Berkeley
200 *> \author Univ. of Colorado Denver
201 *> \author NAG Ltd.
202 *
203 *> \date November 2011
204 *
205 *> \ingroup double_matgen
206 *
207 * =====================================================================
208  DOUBLE PRECISION FUNCTION dlatm2( M, N, I, J, KL, KU, IDIST,
209  $ iseed, d, igrade, dl, dr, ipvtng, iwork, sparse )
210 *
211 * -- LAPACK auxiliary routine (version 3.4.0) --
212 * -- LAPACK is a software package provided by Univ. of Tennessee, --
213 * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
214 * November 2011
215 *
216 * .. Scalar Arguments ..
217 *
218  INTEGER i, idist, igrade, ipvtng, j, kl, ku, m, n
219  DOUBLE PRECISION sparse
220 * ..
221 *
222 * .. Array Arguments ..
223 *
224  INTEGER iseed( 4 ), iwork( * )
225  DOUBLE PRECISION d( * ), dl( * ), dr( * )
226 * ..
227 *
228 * =====================================================================
229 *
230 * .. Parameters ..
231 *
232  DOUBLE PRECISION zero
233  parameter( zero = 0.0d0 )
234 * ..
235 *
236 * .. Local Scalars ..
237 *
238  INTEGER isub, jsub
239  DOUBLE PRECISION temp
240 * ..
241 *
242 * .. External Functions ..
243 *
244  DOUBLE PRECISION dlaran, dlarnd
245  EXTERNAL dlaran, dlarnd
246 * ..
247 *
248 *-----------------------------------------------------------------------
249 *
250 * .. Executable Statements ..
251 *
252 *
253 * Check for I and J in range
254 *
255  IF( i.LT.1 .OR. i.GT.m .OR. j.LT.1 .OR. j.GT.n ) THEN
256  dlatm2 = zero
257  RETURN
258  END IF
259 *
260 * Check for banding
261 *
262  IF( j.GT.i+ku .OR. j.LT.i-kl ) THEN
263  dlatm2 = zero
264  RETURN
265  END IF
266 *
267 * Check for sparsity
268 *
269  IF( sparse.GT.zero ) THEN
270  IF( dlaran( iseed ).LT.sparse ) THEN
271  dlatm2 = zero
272  RETURN
273  END IF
274  END IF
275 *
276 * Compute subscripts depending on IPVTNG
277 *
278  IF( ipvtng.EQ.0 ) THEN
279  isub = i
280  jsub = j
281  ELSE IF( ipvtng.EQ.1 ) THEN
282  isub = iwork( i )
283  jsub = j
284  ELSE IF( ipvtng.EQ.2 ) THEN
285  isub = i
286  jsub = iwork( j )
287  ELSE IF( ipvtng.EQ.3 ) THEN
288  isub = iwork( i )
289  jsub = iwork( j )
290  END IF
291 *
292 * Compute entry and grade it according to IGRADE
293 *
294  IF( isub.EQ.jsub ) THEN
295  temp = d( isub )
296  ELSE
297  temp = dlarnd( idist, iseed )
298  END IF
299  IF( igrade.EQ.1 ) THEN
300  temp = temp*dl( isub )
301  ELSE IF( igrade.EQ.2 ) THEN
302  temp = temp*dr( jsub )
303  ELSE IF( igrade.EQ.3 ) THEN
304  temp = temp*dl( isub )*dr( jsub )
305  ELSE IF( igrade.EQ.4 .AND. isub.NE.jsub ) THEN
306  temp = temp*dl( isub ) / dl( jsub )
307  ELSE IF( igrade.EQ.5 ) THEN
308  temp = temp*dl( isub )*dl( jsub )
309  END IF
310  dlatm2 = temp
311  RETURN
312 *
313 * End of DLATM2
314 *
315  END