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