Zlatme Zlatmr Zlatms Zlatmt

Zlatms() Sub Zlatms ( M As  Long, N As  Long, Dist As  String, Iseed() As  Long, Sym As  String, D() As  Double, Mode As  Long, Cond As  Double, Dmax As  Double, Kl As  Long, Ku As  Long, Pack As  String, A() As  Complex, Info As  Long  ) Generates random matrices with specified singular values or Hermitian random matrices with specified eigenvalues (complex matrices) Purpose This routine generates random matrices with specified singular values (or Hermitian with specified eigenvalues). Zlatms 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 Hermitian or 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 the number of rows of array A() is at least M (so a dense matrix can be stored). Method B is chosen if the bandwidth is small (< 1/2 N for Hermitian or symmetric, < 0.3 N+M for non-symmetric), or the number of rows of array A() 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 Hermitian). zero out lower half (if Hermitian). store the upper half columnwise (if Hermitian or upper triangular). store the lower half columnwise (if Hermitian or lower triangular) store the upper triangle in banded format (if Hermitian or upper triangular). store the lower triangle in banded format (if Hermitian 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 Hermitian or symmetric (i.e., if Sym = "H", "S" 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 - 1) (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 = "H": The generated matrix is Hermitian 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. = "S": The generated matrix is (complex) symmetric with 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 - 1) (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(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. 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] 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 or Hermitian. [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 or Hermitian. [in] Pack Specifies packing of matrix as follows: = "N": No packing. = "U": Zero out all sub-diagonal entries. (if Hermitian or symmetric) = "L": Zero out all super-diagonal entries. (if Hermitian or symmetric) = "C": Store the upper triangle columnwise. (only if matrix is Hermitian, symmetric or upper triangular) = "R": Store the lower triangle columnwise. (only if matrix is Hermitian, symmetric or lower triangular) = "Q": Store the upper triangle in band storage scheme. (only if matrix is Hermitian, symmetric or upper triangular) = "B": Store the lower triangle in band storage scheme. (only if matrix is Hermitian, 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, HB or TB: "Q" or "B"   PP, SP, HP or TP: "C" or "R" If two calls to Zlatms differ only in the pack parameter, they will generate mathematically equivalent matrices. [out] A() Array A(LA1 - 1, LA2 - 1) (LA1 >= M (Pack = "N", "U" "L", "C" or "R"), min(Kl, M-1) (= min(Ku, N-1)) (Pack = "Q" or "B"), min(Ku, N-1) + min(Kl, M-1) + 1 (Pack = "Z"), LA2 >= 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 (minimum required LA1) 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] 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") = -4: The argument Iseed() is invalid. = -5: The argument Sym had an illegal value. (Sym <> "S", "H", "P" nor "N") = -6: The argument D() is invalid. = -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 Kl had an illegal value. (Kl < 0) = -11: The argument Ku had an illegal value. (Ku < 0 or (Sym = "S", "H" or "P" and Kl <> Ku)) = -12: The argument Pack had an illegal value. (Pack <> "N", "U", "L", "C", "R", "Q", "B" nor "Z") = -13: The argument A() is invalid. = 1: Error return from Dlatm1. = 2: Cannot scale to Dmax. (Max. singular value is 0) = 3: Error return from Zlagge, Zlaghe or Zlagsy. Reference LAPACK