--- name: "dlatme.f" section: "3" platform: "linux" package: "lapack-doc" version: "3.12.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/dlatme.f" --- # dlatme.f(3) ## NAME TESTING/MATGEN/dlatme.f ## SYNOPSIS ### Functions/Subroutines subroutine **dlatme** (n, dist, iseed, d, mode, cond, dmax, ei, rsign, upper, sim, ds, modes, conds, kl, ku, anorm, a, lda, work, info)\ **DLATME** ## Function/Subroutine Documentation ### subroutine dlatme (integer n, character dist, integer, dimension( 4 ) iseed, double precision, dimension( \* ) d, integer mode, double precision cond, double precision dmax, character, dimension( \* ) ei, character rsign, character upper, character sim, double precision, dimension( \* ) ds, integer modes, double precision conds, integer kl, integer ku, double precision anorm, double precision, dimension( lda, \* ) a, integer lda, double precision, dimension( \* ) work, integer info) **DLATME** **Purpose:** ``` !> !> DLATME generates random non-symmetric square matrices with !> specified eigenvalues for testing LAPACK programs. !> !> DLATME operates by applying the following sequence of !> operations: !> !> 1. Set the diagonal to D, where D may be input or !> computed according to MODE, COND, DMAX, and RSIGN !> as described below. !> !> 2. If complex conjugate pairs are desired (MODE=0 and EI(1)='R', !> or MODE=5), certain pairs of adjacent elements of D are !> interpreted as the real and complex parts of a complex !> conjugate pair; A thus becomes block diagonal, with 1x1 !> and 2x2 blocks. !> !> 3. If UPPER='T', the upper triangle of A is set to random values !> out of distribution DIST. !> !> 4. If SIM='T', A is multiplied on the left by a random matrix !> X, whose singular values are specified by DS, MODES, and !> CONDS, and on the right by X inverse. !> !> 5. If KL < N-1, the lower bandwidth is reduced to KL using !> Householder transformations. If KU < N-1, the upper !> bandwidth is reduced to KU. !> !> 6. If ANORM is not negative, the matrix is scaled to have !> maximum-element-norm ANORM. !> !> (Note: since the matrix cannot be reduced beyond Hessenberg form, !> no packing options are available.) !> ``` **Parameters** *N* ``` !> N is INTEGER !> The number of columns (or rows) of A. Not modified. !> ``` *DIST* ``` !> DIST is CHARACTER*1 !> On entry, DIST specifies the type of distribution to be used !> to generate the random eigen-/singular values, and for the !> upper triangle (see UPPER). !> 'U' => UNIFORM( 0, 1 ) ( 'U' for uniform ) !> 'S' => UNIFORM( -1, 1 ) ( 'S' for symmetric ) !> 'N' => NORMAL( 0, 1 ) ( 'N' for normal ) !> Not modified. !> ``` *ISEED* ``` !> ISEED is INTEGER array, dimension ( 4 ) !> On entry ISEED specifies the seed of the random number !> generator. They should lie between 0 and 4095 inclusive, !> and ISEED(4) should 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 ISEED are changed on !> exit, and can be used in the next call to DLATME !> to continue the same random number sequence. !> Changed on exit. !> ``` *D* ``` !> D is DOUBLE PRECISION array, dimension ( N ) !> This array is used to specify the eigenvalues of A. If !> MODE=0, then D is assumed to contain the eigenvalues (but !> see the description of EI), otherwise they will be !> computed according to MODE, COND, DMAX, and RSIGN and !> placed in D. !> Modified if MODE is nonzero. !> ``` *MODE* ``` !> MODE is INTEGER !> On entry this describes how the eigenvalues are to !> be specified: !> MODE = 0 means use D (with EI) as input !> MODE = 1 sets D(1)=1 and D(2:N)=1.0/COND !> MODE = 2 sets D(1:N-1)=1 and D(N)=1.0/COND !> MODE = 3 sets D(I)=COND**(-(I-1)/(N-1)) !> MODE = 4 sets D(i)=1 - (i-1)/(N-1)*(1 - 1/COND) !> MODE = 5 sets D to random numbers in the range !> ( 1/COND , 1 ) such that their logarithms !> are uniformly distributed. Each odd-even pair !> of elements will be either used as two real !> eigenvalues or as the real and imaginary part !> of a complex conjugate pair of eigenvalues; !> the choice of which is done is random, with !> 50-50 probability, for each pair. !> MODE = 6 set D to random numbers from same distribution !> as the rest of the matrix. !> MODE < 0 has the same meaning as ABS(MODE), except that !> the order of the elements of D is reversed. !> Thus if MODE is between 1 and 4, D has entries ranging !> from 1 to 1/COND, if between -1 and -4, D has entries !> ranging from 1/COND to 1, !> Not modified. !> ``` *COND* ``` !> COND is DOUBLE PRECISION !> On entry, this is used as described under MODE above. !> If used, it must be >= 1. Not modified. !> ``` *DMAX* ``` !> DMAX is DOUBLE PRECISION !> If MODE is neither -6, 0 nor 6, the contents of D, as !> computed according to MODE and COND, will be scaled by !> DMAX / max(abs(D(i))). Note that DMAX need not be !> positive: if DMAX is negative (or zero), D will be !> scaled by a negative number (or zero). !> Not modified. !> ``` *EI* ``` !> EI is CHARACTER*1 array, dimension ( N ) !> If MODE is 0, and EI(1) is not ' ' (space character), !> this array specifies which elements of D (on input) are !> real eigenvalues and which are the real and imaginary parts !> of a complex conjugate pair of eigenvalues. The elements !> of EI may then only have the values 'R' and 'I'. If !> EI(j)='R' and EI(j+1)='I', then the j-th eigenvalue is !> CMPLX( D(j) , D(j+1) ), and the (j+1)-th is the complex !> conjugate thereof. If EI(j)=EI(j+1)='R', then the j-th !> eigenvalue is D(j) (i.e., real). EI(1) may not be 'I', !> nor may two adjacent elements of EI both have the value 'I'. !> If MODE is not 0, then EI is ignored. If MODE is 0 and !> EI(1)=' ', then the eigenvalues will all be real. !> Not modified. !> ``` *RSIGN* ``` !> RSIGN is CHARACTER*1 !> If MODE is not 0, 6, or -6, and RSIGN='T', then the !> elements of D, as computed according to MODE and COND, will !> be multiplied by a random sign (+1 or -1). If RSIGN='F', !> they will not be. RSIGN may only have the values 'T' or !> 'F'. !> Not modified. !> ``` *UPPER* ``` !> UPPER is CHARACTER*1 !> If UPPER='T', then the elements of A above the diagonal !> (and above the 2x2 diagonal blocks, if A has complex !> eigenvalues) will be set to random numbers out of DIST. !> If UPPER='F', they will not. UPPER may only have the !> values 'T' or 'F'. !> Not modified. !> ``` *SIM* ``` !> SIM is CHARACTER*1 !> If SIM='T', then A will be operated on by a , i.e., multiplied on the left by a matrix X and !> on the right by X inverse. X = U S V, where U and V are !> random unitary matrices and S is a (diagonal) matrix of !> singular values specified by DS, MODES, and CONDS. If !> SIM='F', then A will not be transformed. !> Not modified. !> ``` *DS* ``` !> DS is DOUBLE PRECISION array, dimension ( N ) !> This array is used to specify the singular values of X, !> in the same way that D specifies the eigenvalues of A. !> If MODE=0, the DS contains the singular values, which !> may not be zero. !> Modified if MODE is nonzero. !> ``` *MODES* ``` !> MODES is INTEGER !> ``` *CONDS* ``` !> CONDS is DOUBLE PRECISION !> Same as MODE and COND, but for specifying the diagonal !> of S. MODES=-6 and +6 are not allowed (since they would !> result in randomly ill-conditioned eigenvalues.) !> ``` *KL* ``` !> KL is INTEGER !> This specifies the lower bandwidth of the matrix. KL=1 !> specifies upper Hessenberg form. If KL is at least N-1, !> then A will have full lower bandwidth. KL must be at !> least 1. !> Not modified. !> ``` *KU* ``` !> KU is INTEGER !> This specifies the upper bandwidth of the matrix. KU=1 !> specifies lower Hessenberg form. If KU is at least N-1, !> then A will have full upper bandwidth; if KU and KL !> are both at least N-1, then A will be dense. Only one of !> KU and KL may be less than N-1. KU must be at least 1. !> Not modified. !> ``` *ANORM* ``` !> ANORM is DOUBLE PRECISION !> If ANORM is not negative, then A will be scaled by a non- !> negative real number to make the maximum-element-norm of A !> to be ANORM. !> Not modified. !> ``` *A* ``` !> A is DOUBLE PRECISION array, dimension ( LDA, N ) !> On exit A is the desired test matrix. !> Modified. !> ``` *LDA* ``` !> LDA is INTEGER !> LDA specifies the first dimension of A as declared in the !> calling program. LDA must be at least N. !> Not modified. !> ``` *WORK* ``` !> WORK is DOUBLE PRECISION array, dimension ( 3*N ) !> Workspace. !> Modified. !> ``` *INFO* ``` !> INFO is INTEGER !> Error code. On exit, INFO will be set to one of the !> following values: !> 0 => normal return !> -1 => N negative !> -2 => DIST illegal string !> -5 => MODE not in range -6 to 6 !> -6 => COND less than 1.0, and MODE neither -6, 0 nor 6 !> -8 => EI(1) is not ' ' or 'R', EI(j) is not 'R' or 'I', or !> two adjacent elements of EI are 'I'. !> -9 => RSIGN is not 'T' or 'F' !> -10 => UPPER is not 'T' or 'F' !> -11 => SIM is not 'T' or 'F' !> -12 => MODES=0 and DS has a zero singular value. !> -13 => MODES is not in the range -5 to 5. !> -14 => MODES is nonzero and CONDS is less than 1. !> -15 => KL is less than 1. !> -16 => KU is less than 1, or KL and KU are both less than !> N-1. !> -19 => LDA is less than N. !> 1 => Error return from DLATM1 (computing D) !> 2 => Cannot scale to DMAX (max. eigenvalue is 0) !> 3 => Error return from DLATM1 (computing DS) !> 4 => Error return from DLARGE !> 5 => Zero singular value from DLATM1. !> ``` **Author** Univ. of Tennessee Univ. of California Berkeley Univ. of Colorado Denver NAG Ltd. Definition at line **327** of file **dlatme.f**. ## Author Generated automatically by Doxygen for LAPACK from the source code.