LAPACK  3.4.2 LAPACK: Linear Algebra PACKage
clatm2.f
Go to the documentation of this file.
1 *> \brief \b CLATM2
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 CLATM2( M, N, I, J, KL, KU, IDIST, ISEED, D,
12 * IGRADE, DL, DR, IPVTNG, IWORK, SPARSE )
13 *
14 * .. Scalar Arguments ..
15 *
16 * INTEGER I, IDIST, IGRADE, IPVTNG, J, KL, KU, M, N
17 * REAL SPARSE
18 * ..
19 *
20 * .. Array Arguments ..
21 *
22 * INTEGER ISEED( 4 ), IWORK( * )
23 * COMPLEX D( * ), DL( * ), DR( * )
24 * ..
25 *
26 *
27 *> \par Purpose:
28 * =============
29 *>
30 *> \verbatim
31 *>
32 *> CLATM2 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 *> CLATMR 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 CLATMR which has already checked the parameters.
37 *>
38 *> Use of CLATM2 differs from CLATM3 in the order in which the random
39 *> number generator is called to fill in random matrix entries.
40 *> With CLATM2, the generator is called to fill in the pivoted matrix
41 *> columnwise. With CLATM3, the generator is called to fill in the
42 *> matrix columnwise, after which it is pivoted. Thus, CLATM3 can
43 *> be used to construct random matrices which differ only in their
44 *> order of rows and/or columns. CLATM2 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 => real and imaginary parts each UNIFORM( 0, 1 )
115 *> 2 => real and imaginary parts each UNIFORM( -1, 1 )
116 *> 3 => real and imaginary parts each NORMAL( 0, 1 )
117 *> 4 => complex number uniform in DISK( 0 , 1 )
118 *> Not modified.
119 *> \endverbatim
120 *>
121 *> \param[in,out] ISEED
122 *> \verbatim
123 *> ISEED is INTEGER array of dimension ( 4 )
124 *> Seed for random number generator.
125 *> Changed on exit.
126 *> \endverbatim
127 *>
128 *> \param[in] D
129 *> \verbatim
130 *> D is COMPLEX array of dimension ( MIN( I , J ) )
131 *> Diagonal entries of matrix. Not modified.
132 *> \endverbatim
133 *>
135 *> \verbatim
137 *> Specifies grading of matrix as follows:
138 *> 0 => no grading
139 *> 1 => matrix premultiplied by diag( DL )
140 *> 2 => matrix postmultiplied by diag( DR )
141 *> 3 => matrix premultiplied by diag( DL ) and
142 *> postmultiplied by diag( DR )
143 *> 4 => matrix premultiplied by diag( DL ) and
144 *> postmultiplied by inv( diag( DL ) )
145 *> 5 => matrix premultiplied by diag( DL ) and
146 *> postmultiplied by diag( CONJG(DL) )
147 *> 6 => matrix premultiplied by diag( DL ) and
148 *> postmultiplied by diag( DL )
149 *> Not modified.
150 *> \endverbatim
151 *>
152 *> \param[in] DL
153 *> \verbatim
154 *> DL is COMPLEX array ( I or J, as appropriate )
155 *> Left scale factors for grading matrix. Not modified.
156 *> \endverbatim
157 *>
158 *> \param[in] DR
159 *> \verbatim
160 *> DR is COMPLEX array ( I or J, as appropriate )
161 *> Right scale factors for grading matrix. Not modified.
162 *> \endverbatim
163 *>
164 *> \param[in] IPVTNG
165 *> \verbatim
166 *> IPVTNG is INTEGER
167 *> On entry specifies pivoting permutations as follows:
168 *> 0 => none.
169 *> 1 => row pivoting.
170 *> 2 => column pivoting.
171 *> 3 => full pivoting, i.e., on both sides.
172 *> Not modified.
173 *> \endverbatim
174 *>
175 *> \param[out] IWORK
176 *> \verbatim
177 *> IWORK is INTEGER array ( I or J, as appropriate )
178 *> This array specifies the permutation used. The
179 *> row (or column) in position K was originally in
180 *> position IWORK( K ).
181 *> This differs from IWORK for CLATM3. Not modified.
182 *> \endverbatim
183 *>
184 *> \param[in] SPARSE
185 *> \verbatim
186 *> SPARSE is REAL
187 *> Value between 0. and 1.
188 *> On entry specifies the sparsity of the matrix
189 *> if sparse matix is to be generated.
190 *> SPARSE should lie between 0 and 1.
191 *> A uniform ( 0, 1 ) random number x is generated and
192 *> compared to SPARSE; if x is larger the matrix entry
193 *> is unchanged and if x is smaller the entry is set
194 *> to zero. Thus on the average a fraction SPARSE of the
195 *> entries will be set to zero.
196 *> Not modified.
197 *> \endverbatim
198 *
199 * Authors:
200 * ========
201 *
202 *> \author Univ. of Tennessee
203 *> \author Univ. of California Berkeley
204 *> \author Univ. of Colorado Denver
205 *> \author NAG Ltd.
206 *
207 *> \date November 2011
208 *
209 *> \ingroup complex_matgen
210 *
211 * =====================================================================
212  COMPLEX FUNCTION clatm2( M, N, I, J, KL, KU, IDIST, ISEED, D,
213  \$ igrade, dl, dr, ipvtng, iwork, sparse )
214 *
215 * -- LAPACK auxiliary routine (version 3.4.0) --
216 * -- LAPACK is a software package provided by Univ. of Tennessee, --
217 * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
218 * November 2011
219 *
220 * .. Scalar Arguments ..
221 *
222  INTEGER i, idist, igrade, ipvtng, j, kl, ku, m, n
223  REAL sparse
224 * ..
225 *
226 * .. Array Arguments ..
227 *
228  INTEGER iseed( 4 ), iwork( * )
229  COMPLEX d( * ), dl( * ), dr( * )
230 * ..
231 *
232 * =====================================================================
233 *
234 * .. Parameters ..
235 *
236  COMPLEX czero
237  parameter( czero = ( 0.0e0, 0.0e0 ) )
238  REAL zero
239  parameter( zero = 0.0e0 )
240 * ..
241 *
242 * .. Local Scalars ..
243 *
244  INTEGER isub, jsub
245  COMPLEX ctemp
246 * ..
247 *
248 * .. External Functions ..
249 *
250  REAL slaran
251  COMPLEX clarnd
252  EXTERNAL slaran, clarnd
253 * ..
254 *
255 * .. Intrinsic Functions ..
256 *
257  INTRINSIC conjg
258 * ..
259 *
260 *-----------------------------------------------------------------------
261 *
262 * .. Executable Statements ..
263 *
264 *
265 * Check for I and J in range
266 *
267  IF( i.LT.1 .OR. i.GT.m .OR. j.LT.1 .OR. j.GT.n ) THEN
268  clatm2 = czero
269  return
270  END IF
271 *
272 * Check for banding
273 *
274  IF( j.GT.i+ku .OR. j.LT.i-kl ) THEN
275  clatm2 = czero
276  return
277  END IF
278 *
279 * Check for sparsity
280 *
281  IF( sparse.GT.zero ) THEN
282  IF( slaran( iseed ).LT.sparse ) THEN
283  clatm2 = czero
284  return
285  END IF
286  END IF
287 *
288 * Compute subscripts depending on IPVTNG
289 *
290  IF( ipvtng.EQ.0 ) THEN
291  isub = i
292  jsub = j
293  ELSE IF( ipvtng.EQ.1 ) THEN
294  isub = iwork( i )
295  jsub = j
296  ELSE IF( ipvtng.EQ.2 ) THEN
297  isub = i
298  jsub = iwork( j )
299  ELSE IF( ipvtng.EQ.3 ) THEN
300  isub = iwork( i )
301  jsub = iwork( j )
302  END IF
303 *
305 *
306  IF( isub.EQ.jsub ) THEN
307  ctemp = d( isub )
308  ELSE
309  ctemp = clarnd( idist, iseed )
310  END IF
312  ctemp = ctemp*dl( isub )
313  ELSE IF( igrade.EQ.2 ) THEN
314  ctemp = ctemp*dr( jsub )
315  ELSE IF( igrade.EQ.3 ) THEN
316  ctemp = ctemp*dl( isub )*dr( jsub )
317  ELSE IF( igrade.EQ.4 .AND. isub.NE.jsub ) THEN
318  ctemp = ctemp*dl( isub ) / dl( jsub )
319  ELSE IF( igrade.EQ.5 ) THEN
320  ctemp = ctemp*dl( isub )*conjg( dl( jsub ) )
321  ELSE IF( igrade.EQ.6 ) THEN
322  ctemp = ctemp*dl( isub )*dl( jsub )
323  END IF
324  clatm2 = ctemp
325  return
326 *
327 * End of CLATM2
328 *
329  END