LAPACK  3.5.0 LAPACK: Linear Algebra PACKage
zlatm2.f
Go to the documentation of this file.
1 *> \brief \b ZLATM2
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*16 FUNCTION ZLATM2( 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 * COMPLEX*16 D( * ), DL( * ), DR( * )
24 * ..
25 *
26 *
27 *> \par Purpose:
28 * =============
29 *>
30 *> \verbatim
31 *>
32 *> ZLATM2 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 *> ZLATMR 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 ZLATMR which has already checked the parameters.
37 *>
38 *> Use of ZLATM2 differs from CLATM3 in the order in which the random
39 *> number generator is called to fill in random matrix entries.
40 *> With ZLATM2, the generator is called to fill in the pivoted matrix
41 *> columnwise. With ZLATM3, the generator is called to fill in the
42 *> matrix columnwise, after which it is pivoted. Thus, ZLATM3 can
43 *> be used to construct random matrices which differ only in their
44 *> order of rows and/or columns. ZLATM2 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*16 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*16 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*16 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 ZLATM3. Not modified.
182 *> \endverbatim
183 *>
184 *> \param[in] SPARSE
185 *> \verbatim
186 *> SPARSE is DOUBLE PRECISION between 0. and 1.
187 *> On entry specifies the sparsity of the matrix
188 *> if sparse matix is to be generated.
189 *> SPARSE should lie between 0 and 1.
190 *> A uniform ( 0, 1 ) random number x is generated and
191 *> compared to SPARSE; if x is larger the matrix entry
192 *> is unchanged and if x is smaller the entry is set
193 *> to zero. Thus on the average a fraction SPARSE of the
194 *> entries will be set to zero.
195 *> Not modified.
196 *> \endverbatim
197 *
198 * Authors:
199 * ========
200 *
201 *> \author Univ. of Tennessee
202 *> \author Univ. of California Berkeley
203 *> \author Univ. of Colorado Denver
204 *> \author NAG Ltd.
205 *
206 *> \date November 2011
207 *
208 *> \ingroup complex16_matgen
209 *
210 * =====================================================================
211  COMPLEX*16 FUNCTION zlatm2( M, N, I, J, KL, KU, IDIST,
212  \$ iseed, d, igrade, dl, dr, ipvtng, iwork, sparse )
213 *
214 * -- LAPACK auxiliary routine (version 3.4.0) --
215 * -- LAPACK is a software package provided by Univ. of Tennessee, --
216 * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
217 * November 2011
218 *
219 * .. Scalar Arguments ..
220 *
221  INTEGER i, idist, igrade, ipvtng, j, kl, ku, m, n
222  DOUBLE PRECISION sparse
223 * ..
224 *
225 * .. Array Arguments ..
226 *
227  INTEGER iseed( 4 ), iwork( * )
228  COMPLEX*16 d( * ), dl( * ), dr( * )
229 * ..
230 *
231 * =====================================================================
232 *
233 * .. Parameters ..
234 *
235  COMPLEX*16 czero
236  parameter( czero = ( 0.0d0, 0.0d0 ) )
237  DOUBLE PRECISION zero
238  parameter( zero = 0.0d0 )
239 * ..
240 *
241 * .. Local Scalars ..
242 *
243  INTEGER isub, jsub
244  COMPLEX*16 ctemp
245 * ..
246 *
247 * .. External Functions ..
248 *
249  DOUBLE PRECISION dlaran
250  COMPLEX*16 zlarnd
251  EXTERNAL dlaran, zlarnd
252 * ..
253 *
254 * .. Intrinsic Functions ..
255 *
256  INTRINSIC dconjg
257 * ..
258 *
259 *-----------------------------------------------------------------------
260 *
261 * .. Executable Statements ..
262 *
263 *
264 * Check for I and J in range
265 *
266  IF( i.LT.1 .OR. i.GT.m .OR. j.LT.1 .OR. j.GT.n ) THEN
267  zlatm2 = czero
268  RETURN
269  END IF
270 *
271 * Check for banding
272 *
273  IF( j.GT.i+ku .OR. j.LT.i-kl ) THEN
274  zlatm2 = czero
275  RETURN
276  END IF
277 *
278 * Check for sparsity
279 *
280  IF( sparse.GT.zero ) THEN
281  IF( dlaran( iseed ).LT.sparse ) THEN
282  zlatm2 = czero
283  RETURN
284  END IF
285  END IF
286 *
287 * Compute subscripts depending on IPVTNG
288 *
289  IF( ipvtng.EQ.0 ) THEN
290  isub = i
291  jsub = j
292  ELSE IF( ipvtng.EQ.1 ) THEN
293  isub = iwork( i )
294  jsub = j
295  ELSE IF( ipvtng.EQ.2 ) THEN
296  isub = i
297  jsub = iwork( j )
298  ELSE IF( ipvtng.EQ.3 ) THEN
299  isub = iwork( i )
300  jsub = iwork( j )
301  END IF
302 *
304 *
305  IF( isub.EQ.jsub ) THEN
306  ctemp = d( isub )
307  ELSE
308  ctemp = zlarnd( idist, iseed )
309  END IF
311  ctemp = ctemp*dl( isub )
312  ELSE IF( igrade.EQ.2 ) THEN
313  ctemp = ctemp*dr( jsub )
314  ELSE IF( igrade.EQ.3 ) THEN
315  ctemp = ctemp*dl( isub )*dr( jsub )
316  ELSE IF( igrade.EQ.4 .AND. isub.NE.jsub ) THEN
317  ctemp = ctemp*dl( isub ) / dl( jsub )
318  ELSE IF( igrade.EQ.5 ) THEN
319  ctemp = ctemp*dl( isub )*dconjg( dl( jsub ) )
320  ELSE IF( igrade.EQ.6 ) THEN
321  ctemp = ctemp*dl( isub )*dl( jsub )
322  END IF
323  zlatm2 = ctemp
324  RETURN
325 *
326 * End of ZLATM2
327 *
328  END