Generates a general
nmatrix with specific singular values.
?latmsroutine generates random matrices with specified singular values, or symmetric/Hermitian matrices with specified eigenvalues for testing LAPACK programs.
It applies this sequence of operations:
- Set the diagonal tod, wheredis input or computed according tomode,cond,dmax, andsymas described in Input Parameters.
- Generate a matrix with the appropriate band structure, by one of two methods:
- Method A
- Generate a densem-by-nmatrix by multiplyingdon the left and the right by random unitary matrices, then:
- Reduce the bandwidth according toklandku, 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, much as in QR; then convert the bandwidth-1 to a bandwidth-2 matrix, etc.Note that for reasonably small bandwidths (relative tomandn) this requires less storage, as a dense matrix is not generated. Also, for symmetric or Hermitian matrices, only one triangle is generated.
Method A is chosen if the bandwidth is a large fraction of the order of the matrix, and
ldais at least
m(so a dense matrix can be stored.) Method B is chosen if the bandwidth is small (less than (1/2)*
nfor symmetric or Hermitian or less than .3*
mfor nonsymmetric), or
ldais less than
mand not less than the bandwidth.
Pack the matrix if desired, using one of the methods specified by the
If Method B is chosen and band format is specified, then the matrix is generated in the band format and no repacking is necessary.
<datatype>placeholder, if present, is used for the C interface data types in the C interface section above. See C Interface Conventions for the C interface principal conventions and type definitions.
- Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).
- The number of rows of the matrixA().m≥0
- The number of columns of the matrixA().n≥0
- Specifies the type of distribution to be used to generate the random singular values or eigenvalues:
- 'U': uniform distribution (0, 1)
- 'S': symmetric uniform distribution (-1, 1)
- 'N': normal distribution (0, 1)
- Array with size 4.Specifies the seed of the random number generator. Values should lie between 0 and 4095 inclusive, andshould be odd. The random number generator uses a linear congruential sequence limited to small integers, and so should produce machine independent random numbers. The values of the array are modified, and can be used in the next call toiseed?latmsto continue the same random number sequence.
- Ifsym='S' or 'H', the generated matrix is symmetric or Hermitian, with eigenvalues specified byd,cond,mode, anddmax; they can be positive, negative, or zero.Ifsym='P', the generated matrix is symmetric or Hermitian, with eigenvalues (which are singular, non-negative values) specified byd,cond,mode, anddmax.Ifsym='N', the generated matrix is nonsymmetric, with singular, non-negative values specified byd,cond,mode, anddmax.
- Array, size (MIN(m,n))This array is used to specify the singular values or eigenvalues ofA(see the description ofsym). Ifmode=0, thendis assumed to contain the eigenvalues or singular values, otherwise elements ofdare computed according tomode,cond, anddmax.
- Describes how the singular/eigenvalues are specified.
mode< 0 has the same meaning as ABS(mode), except that the order of the elements ofdis reversed. Thus, ifmodeis positive,dhas entries ranging from 1 to 1/cond, if negative, from 1/condto 1.Ifsym='S' or 'H', andmodeis not 0, 6, nor -6, then the elements ofdare also given a random sign (multiplied by +1 or -1).
- mode= 0: usedas input
- mode= 1: setandd = 1d[1:n- 1] = 1.0/cond
- mode= 2: setandd[0:n- 2] = 1d[n- 1] = 1.0/cond
- mode= 3: setd[i] =cond-i/(n- 1)
- mode= 4: set)d[i] = 1 -i/(n- 1)*(1 - 1/cond
- mode= 5: set elements ofdto random numbers in the range (1/cond, 1) such that their logarithms are uniformly distributed.
- mode= 6: set elements ofdto random numbers from same distribution as the rest of the matrix.
- Used in settingdas described for themodeparameter. If used,cond≥1.
- Ifmodeis not -6, 0 nor 6, the contents ofd, as computed according tomodeandcond, are scaled by; thus, the maximum absolute eigenvalue or singular value (the norm) isdmax/ max(abs(d[i-1]))abs(.dmax)dmaxneed not be positive: ifdmaxis negative (or zero),dwill be scaled by a negative number (or zero).
- Specifies the lower bandwidth of the matrix. For example,kl=0 implies upper triangular,kl=1 implies upper Hessenberg, andklbeing at leastm- 1 means that the matrix has full lower bandwidth.klmust equalkuif the matrix is symmetric or Hermitian.
- Specifies the upper bandwidth of the matrix. For example,ku=0 implies lower triangular,ku=1 implies lower Hessenberg, andkubeing at leastn- 1 means that the matrix has full upper bandwidth.klmust equalkuif the matrix is symmetric or Hermitian.
- Specifies packing of matrix:
Using these options, the various LAPACK packed and banded storage schemes can be obtained:'Z''B''Q''C''R'GB: general bandxPB: symmetric positive definite bandxxSB: symmetric bandxxHB: Hermitian bandxxTB: triangular bandxxPP: symmetric positive definite packedxxSP: symmetric packedxxHP: Hermitian packedxxTP: triangular packedxxIf two calls to?latmsdiffer only in thepackparameter, they generate mathematically equivalent matrices.
- 'N': no packing
- 'U': zero out all subdiagonal entries (if symmetric or Hermitian)
- 'L': zero out all superdiagonal entries (if symmetric or Hermitian)
- 'B': store the lower triangle in band storage scheme (only if matrix symmetric, Hermitian, or lower triangular)
- 'Q': store the upper triangle in band storage scheme (only if matrix symmetric, Hermitian, or upper triangular)
- 'Z': store the entire matrix in band storage scheme (pivoting can be provided for by using this option to storeAin the trailing rows of the allocated storage)
- ldaspecifies the first dimension ofaas declared in the calling program.Ifpack='N', 'U', 'L', 'C', or 'R', thenldamust be at leastmfor column major or at least.nfor row majorIfpack='B' or 'Q', thenldamust be at leastMIN((which is equal to MIN(kl,m- 1)ku,n- 1)).Ifpack='Z',ldamust be large enough to hold the packed array:MIN(.ku,n- 1) + MIN(kl,m- 1) + 1
- The arrayiseedcontains the updated seed.
- The arraydcontains the updated seed.The arraydis not modified ifmode= 0.
- Array of sizeldabyn.The arrayacontains the generatedm-by-nmatrixA.ais first generated in full (unpacked) form, and then packed, if so specified bypack. Thus, the firstmelements of the firstncolumns are always modified. Ifpackspecifies a packed or banded storage scheme, allldaelements of the firstncolumns are modified; the elements of the array which do not correspond to elements of the generated matrix are set to zero.
This function returns a value
, the execution is successful.