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