dlatme dlatmr dlatms dlatmt

dlatmt() void dlatmt ( int  m, int  n, char  dist, int  iseed[], char  sym, double  d[], int  mode, double  cond, double  dmax, int  rank, int  kl, int  ku, char  pack, int  lda, double  a[], double  work[], int *  info  ) Generates random matrices with specified singular values or symmetric random matrices with specified eigenvalues (with specified rank of matrix) Purpose This routine generates random matrices with specified singular values (or symmetric with specified eigenvalues). dlatmt operates by applying the following sequence of operations: Set the diagonal to d, where d may be input or computed according to mode, cond, dmax, and sym as described below. Generate a matrix with the appropriate band structure, by one of two methods: Method A: Generate a dense m x n matrix by multiplying d on the left and the right by random unitary matrices, then reduce the bandwidth according to kl and ku, using Householder transformations. Method B: Convert the bandwidth-0 (i.e., diagonal) matrix to a bandwidth-1 matrix using Givens rotations, "chasing" out-of-band elements back, such as in QR; then convert the bandwidth-1 to a bandwidth-2 matrix, etc. Note that for reasonably small bandwidths (relative to m and n) this requires less storage, as a dense matrix is not generated. Also, for symmetric matrices, only one triangle is generated. Method A is chosen if the bandwidth is a large fraction of the order of the matrix, and lda is at least m (so a dense matrix can be stored). Method B is chosen if the bandwidth is small (< 1/2 n for symmetric, < 0.3 n+m for non-symmetric), or lda is less than m and not less than the bandwidth. 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). store the upper triangle in banded format (if symmetric or upper triangular). store the lower triangle in banded format (if symmetric or lower triangular). store the entire matrix in banded format. If Method B is chosen, and band format is specified, then the matrix will be generated in the band format, so no repacking will be necessary. 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 = 'S', 'H' or 'P')) [in] n Number of columns of the matrix A (n >= 0) [in] dist The type of distribution to be used to generate the random eigenvalues/singular values. = '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': The generated matrix is symmetric with eigenvalues specified by d[], cond, mode and dmax; they may be positive, negative or zero. = 'P': The generated matrix is symmetric with eigenvalues (= singular values) specified by d[], cond, mode and dmax; they will not be negative. = 'N': The generated matrix is nonsymmetric, with singular values specified by d[], cond, mode and dmax; they will not be negative. [in,out] d[] Array d[ld] (ld >= min(m, n)) [in] If mode = 0, d[] specifies the eigenvalues or singular values of A (see sym above). [out] If mode != 0, d[] is computed and set according to mode, cond and dmax as described below. [in] mode Describes how the eigenvalues or singular values are to be specified: = 0: Use d[] as input. = 1: d[0] = 1 and d[1] to d[rank-1] = 1/cond. = 2: d[0] to d[rank-2] = 1 and d[rank-1] = 1/cond. = 3: d[i] = cond^(-i/(rank-1)) (i = 0 to rank-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. If sym = 'S' or 'H' and mode != 0, 6 nor -6, the elements of d[] will also be multiplied by a random sign (i.e., +1 or -1). [in] cond To be used as described under mode above (cond >= 1) [in] dmax If mode != 0, 6 nor -6, the contents of d[], as computed according to mode and cond, will be scaled by dmax/max(abs(d[i])); thus, the maximum absolute eigenvalue or singular value (which is to say the norm) will be abs(dmax). Note that dmax need not be positive: if dmax is negative (or zero), d[] will be scaled by a negative number (or zero). [in] rank The rank of matrix to be generated for modes 1, 2 or 3. (1 <= rank <= n) d[rank to n-1] will be 0. [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 means that the matrix has full lower bandwidth. kl 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 means that the matrix has full upper bandwidth. ku must equal kl if matrix is symmetric. [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 upper triangular) = 'R': Store the lower triangle columnwise. (only if matrix symmetric or lower triangular) (same as upper half rowwise if symmetric) = 'Q': Store the upper triangle in band storage scheme. (only if matrix symmetric or upper triangular) = 'B': Store the lower triangle in band storage scheme. (only if matrix symmetric or lower triangular) = '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 dlatmt differ only in the pack parameter, they will generate mathematically equivalent matrices. [in] lda Leading dimension of two dimensional array a[][]. (lda >= m if pack = 'N', 'U', 'L', 'C', or 'R'; lda >= min(kl, m-1) (which is equal to min(ku, n-1)) 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. A is first generated in full (unpacked) form, and then packed, if so specified by pack. Thus, the first m elements of the first n columns will always be modified. If pack specifies a packed or banded storage scheme, all lda elements of the first n columns will be modified; the elements of the array which do not correspond to elements of the generated matrix are set to zero. [out] work[] Array work[lwork] (lwork >= 3*max(m, n)) Work array. [out] info = 0: Successful exit = -1: The argument m had an illegal value (m < 0 or (m != n and sym = 'S', 'H' or 'P')) = -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', 'P' 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 rank had an illegal value (rank < 1 or rank > n when mode = 1, 2 or 3) = -11: The argument kl had an illegal value (kl < 0) = -12: The argument ku had an illegal value (ku < 0 or (sym = 'S', 'H' or 'P' and kl != ku)) = -13: The argument pack had an illegal value (pack != 'N', 'U', 'L', 'C', 'R', 'Q', 'B' nor 'Z') = -14: The argument lda had an illegal value (lda too small) = 1: Error return from dlatm7 = 2: Cannot scale to dmax (max. singular value is 0) = 3: Error return from dlagge or dlagsy Reference LAPACK