|
|
◆ dlatmr()
| void dlatmr |
( |
int |
m, |
|
|
int |
n, |
|
|
char |
dist, |
|
|
int |
iseed[], |
|
|
char |
sym, |
|
|
double |
d[], |
|
|
int |
mode, |
|
|
double |
cond, |
|
|
double |
dmax, |
|
|
char |
rsign, |
|
|
char |
grade, |
|
|
double |
dl[], |
|
|
int |
model, |
|
|
double |
condl, |
|
|
double |
dr[], |
|
|
int |
moder, |
|
|
double |
condr, |
|
|
char |
pivtng, |
|
|
int |
ipivot[], |
|
|
int |
kl, |
|
|
int |
ku, |
|
|
double |
sparse, |
|
|
double |
anorm, |
|
|
char |
pack, |
|
|
int |
lda, |
|
|
double |
a[], |
|
|
int |
iwork[], |
|
|
int * |
info |
|
) |
| |
Generates random matrices with specified diagonal elements
- Purpose
- This routine generates random matrices of various types.
dlatmr operates by applying the following sequence of operations:
Generate a matrix A with random entries of distribution dist which is symmetric if sym = 'S', and nonsymmetric if sym = 'N'.
Set the diagonal to d, where d may be input or computed according to mode, cond, dmax, and rsign as described below.
Grade the matrix, if desired, from the left and/or right as specified by grade. The inputs dl, model, condl, dr, moder and condr also determine the grading as described below.
Permute, if desired, the rows and/or columns as specified by pivtng and ipivot.
Set random entries to zero, if desired, to get a random sparse matrix as specified by sparse.
Make A a band matrix, if desired, by zeroing out the matrix outside a band of lower bandwidth kl and upper bandwidth ku.
Scale A, if desired, to have maximum entry anorm.
Pack the matrix if desired. Options specified by pack are:
- no packing.
- zero out upper half (if symmetric).
- zero out lower half (if symmetric).
- store the upper half columnwise (if symmetric or upper triangular).
- store the lower half columnwise (if symmetric or lower triangular) (same as upper half rowwise if symmetric).
- store the upper triangle in banded format (if symmetric).
- store the lower triangle in banded format (if symmetric).
- store the entire matrix in banded format.
Note: If two calls to dlatmr differ only in the pack parameter, they will generate mathematically equivalent matrices. If two calls to dlatmr both have full bandwidth (kl = m-1 and ku = n-1), and differ only in the pivtng and pack parameters, then the matrices generated will differ only in the order of the rows and/or columns, and otherwise contain the same data. This consistency cannot be and is not maintained with less than full bandwidth.
- Parameters
-
| [in] | m | Number of rows of the matrix A. (m >= 0) (m must equal to n if the matrix is symmetric (i.e., if sym = 'H' or 'S')) |
| [in] | n | Number of columns of the matrix A. (n >= 0) |
| [in] | dist | The type of distribution to be used to generate a random matrix:
= 'U': Uniform distribution on (0, 1).
= 'S': Uniform distribution on (-1, 1).
= 'N': Normal distribution on (0, 1). |
| [in,out] | iseed[] | Array iseed[liseed] (liseed >= 4)
[in] The seed of the random number generator. (0 <= iseed[i] <= 4095, and iseed[3] should be odd)
[out] The values of iseed[] are changed on exit, and can be used in the next call to continue the same random number sequence. |
| [in] | sym | = 'S' or 'H': Generated matrix is symmetric.
= 'N': Generated matrix is nonsymmetric. |
| [in,out] | d[] | Array d[ld] (ld >= min(m, n))
[in] If mode = 0, d[] specifies the diagonal entries of the diagonal of A.
[out] If mode != 0, d[] is set according to mode and cond as described below. |
| [in] | mode | Describes how d[] is to be used:
= 0: Use d[] as input.
= 1: d[0] = 1 and d[1] to d[n-1] = 1/cond.
= 2: d[0] to d[n-2] = 1 and d[n-1] = 1/cond.
= 3: d[i] = cond^(-i/(n-1)) (i = 0 to n-1).
= 4: d[i] = 1-i/(n-1)*(1-1/cond) (i = 0 to n-1).
= 5: Random numbers in the range (1/cond, 1) such that their logarithms are uniformly distributed.
= 6: Random numbers from same distribution as the rest of the matrix.
< 0: Same as |mode| but the order of the elements of d[] is reversed. Thus if mode is positive, d[] has entries ranging from 1 to 1/cond, if negative, from 1/cond to 1. |
| [in] | cond | To be used as described under mode above. (cond >= 1) |
| [in] | dmax | If mode != -6, 0 nor 6, the contents of d[] will be scaled by dmax/max(abs(d[i])), so that maximum absolute entry of diagonal is abs(dmax). If dmax is negative (or zero), diagonal will be scaled by a negative number (or zero). |
| [in] | rsign | If mode neither -6, 0 nor 6, specifies sign of diagonal as follows:
= 'T': Diagonal entries are multiplied by 1 or -1 with probability 0.5.
= 'F': Diagonal unchanged. |
| [in] | grade | Specifies grading of matrix as follows:
= 'N': No grading.
= 'L': Matrix is premultiplied by diag(dl) (only if matrix is nonsymmetric).
= 'R': Matrix is postmultiplied by diag(dr) (only if matrix is nonsymmetric).
= 'B': Matrix is premultiplied by diag(dl) and postmultiplied by diag(dr) (only if matrix is nonsymmetric)
= 'S', 'H': Matrix is premultiplied by diag(dl) and postmultiplied by diag(dl) ('S' for symmetric, or 'H' for Hermitian)
= 'E': Matrix is premultiplied by diag(dl) and postmultiplied by inv(diag(dl)) ('E' for eigenvalue invariance) (only if matrix is nonsymmetric) (m = n) |
| [in,out] | dl[] | Array dl[ldl] (ldl >= m)
Not referenced if grade = 'N' or 'R'.
[in] If model = 0, this array specifies the diagonal entries of a diagonal matrix used as described under grade above. If grade = 'E', dl[] cannot have zero entries.
[out] If model != 0, dl[] will be set according to model and condl, analogous to the way d[] is set according to mode and cond (except there is no dmax parameter for dl[]). |
| [in] | model | This specifies how the diagonal array dl[] is to be computed, just as mode specifies how d[] is to be computed. |
| [in] | condl | When model is not zero, this specifies the condition number of the computed dl[]. (condl >= 1) |
| [in,out] | dr[] | Array dr[ldr] (ldr >= n)
Not referenced if grade = 'N', 'L', 'H', 'S' or 'E'.
[in] If moder = 0, this array specifies the diagonal entries of a diagonal matrix used as described under grade above.
[out] If moder != 0, dr[] will be set according to moder and condr, analogous to the way d[] is set according to mode and cond (except there is no dmax parameter for dr[]). |
| [in] | moder | This specifies how the diagonal array dr[] is to be computed, just as mode specifies how d[] is to be computed. |
| [in] | condr | When moder is not zero, this specifies the condition number of the computed dr[]. (condr >= 1) |
| [in] | pivtng | Specifies pivoting permutations as follows:
= 'N' or ' ': None.
= 'L': Left or row pivoting (matrix must be nonsymmetric).
= 'R': Right or column pivoting (matrix must be nonsymmetric).
= 'B' or 'F': Both or full pivoting, i.e. on both sides (m = n).
If two calls to dlatmr both have full bandwidth (kl = m-1 and ku = n-1), and differ only in the pivtng and pack parameters, then the matrices generated will differ only in the order of the rows and/or columns, and otherwise contain the same data. This consistency cannot be maintained with less than full bandwidth. |
| [in] | ipivot[] | Array ipivot[lipivot] (lipivot >= n or m)
This array specifies the permutation used. After the basic matrix is generated, the rows, columns, or both are permuted. If, say, row pivoting is selected, dlatmr starts with the last row and interchanges the m-th and ipivot[m-1]-th rows, then moves to the next-to-last row, interchanging the (m-1)-th and the ipivot[m-2]-th rows, and so on. In terms of "2-cycles", the permutation is (1 ipivot[0]) (2 ipivot[1]) ... (m ipivot[m-1]) where the rightmost cycle is applied first.
Not referenced if pivtng = 'N'. |
| [in] | sparse | Specifies the sparsity of the matrix if a sparse matrix is to be generated (0 <= sparse <= 1). To generate a sparse matrix, for each matrix entry a uniform (0, 1) random number x is generated and compared to sparse; if x is larger the matrix entry is unchanged and if x is smaller the entry is set to zero. Thus on the average a fraction sparse of the entries will be set to zero. |
| [in] | kl | The lower bandwidth of the matrix. (kl >= 0) For example, kl = 0 implies upper triangular, kl = 1 implies upper Hessenberg, and kl at least m-1 implies the matrix is not banded. Must equal ku if matrix is symmetric. |
| [in] | ku | The upper bandwidth of the matrix. (ku >= 0) For example, ku = 0 implies lower triangular, ku = 1 implies lower Hessenberg, and ku at least n-1 implies the matrix is not banded. Must equal kl if matrix is symmetric. |
| [in] | anorm | Specifies maximum entry of output matrix (output matrix will by multiplied by a constant so that its largest absolute entry equal anorm) if anorm is nonnegative. If anorm is negative no scaling is done. |
| [in] | pack | Specifies packing of matrix as follows:
= 'N': No packing.
= 'U': Zero out all sub-diagonal entries. (if symmetric)
= 'L': Zero out all super-diagonal entries. (if symmetric)
= 'C': Store the upper triangle columnwise. (only if matrix symmetric or sqaure upper triangular)
= 'R': Store the lower triangle columnwise. (only if matrix symmetric or square lower triangular) (same as upper half rowwise if symmetric)
= 'Q': Store the upper triangle in band storage scheme. (only if matrix symmetric)
= 'B': Store the lower triangle in band storage scheme. (only if matrix symmetric)
= 'Z': Store the entire matrix in band storage scheme. (pivoting can be provided for by using this option to store A in the trailing rows of the allocated storage)
Using these options, the various LAPACK packed and banded storage schemes can be obtained:
GB: 'Z'
PB, SB or TB: 'Q' or 'B'
PP, SP or TP: 'C' or 'R'
If two calls to dlatmr differ only in the pack parameter, they will generate mathematically equivalent matrices. |
| [in] | lda | Leading dimension of two dimensional array a[][]. (lda >= max(1, m) if pack = 'N', 'U' or 'L', lda >= 1 if pack = 'C' or 'R', lda >= min(ku + 1, n) if pack = 'Q' or 'B', lda >= min(ku, n-1)+min(kl, m-1)+1 if pack = 'Z') |
| [out] | a[][] | Array a[la][lda] (la >= n)
The desired test matrix. Only those entries of A which are significant on output will be referenced (even if A is in packed or band storage format). The 'unoccupied corners' of A in band format will be zeroed out. |
| [out] | iwork[] | Array iwork[liwork] (liwork >= m or n)
Work array.
Not referenced if pivtng = 'N'. |
| [out] | info | = 0: Successful exit
= -1: The argument m had an illegal value (m < 0 or (m != n and sym = 'S' or 'H'))
= -2: The argument n had an illegal value (n < 0)
= -3: The argument dist had an illegal value (dist != 'U', 'S' nor 'N')
= -5: The argument sym had an illegal value (sym != 'S', 'H' nor 'N')
= -7: The argument mode had an illegal value (mode < -6 or mode > 6)
= -8: The argument cond had an illegal value (cond < 1)
= -10: The argument rsign had an illegal value (rsign != 'T' nor 'F')
= -11: The argument grade had an illegal value (grade != 'N', 'L', 'R', 'B', 'S', 'H' nor 'E')
= -12: The argument dl had an illegal value (grade = 'E' and dl[] contains 0)
= -13: The argument model had an illegal value (model < -6 or model > 6)
= -14: The argument condl had an illegal value (condl < 1)
= -16: The argument moder had an illegal value (moder < -6 or moder > 6)
= -17: The argument condr had an illegal value (condr < 1)
= -18: The argument pivtng had an illegal value (pivtng != 'N', ' ', 'L', 'R', 'B' nor 'F')
= -19: The argument ipivot had an illegal value (invalid ipivot[] value(s))
= -20: The argument kl had an illegal value (kl < 0)
= -21: The argument ku had an illegal value (ku < 0 or (sym = 'S' or 'H' and kl != ku))
= -22: The argument sparse had an illegal value (sparse < 0 or sparse > 1)
= -24: The argument pack had an illegal value (pack != 'N', 'U', 'L', 'C', 'R', 'Q', 'B' nor 'Z')
= -25: The argument lda had an illegal value (lda too small)
= 1: Error return from dlatm1 (computing d[])
= 2: Cannot scale to dmax (max. singular value is 0)
= 3: Error return from dlatm1 (computing dl[])
= 4: Error return from dlatm1 (computing dr[])
= 5: anorm is positive, but matrix, constructed prior to attempting to scale it to have norm anorm, is zero. |
- Reference
- LAPACK
|
1.9.7