TESTING/MATGEN/slatme.f(3)

NAME
TESTING/MATGEN/slatme.f

SYNOPSIS

  Functions/Subroutines
subroutine slatme (n, dist, iseed, d, mode, cond, dmax, ei, rsign, upper, sim, ds, modes, conds, kl, ku, anorm, a, lda, work, info)
SLATME

Function/Subroutine Documentation

  subroutine slatme (integer n, character dist, integer, dimension( 4 ) iseed, real, dimension( * ) d, integer mode, real cond, real dmax, character, dimension( * ) ei, character rsign, character upper, character sim, real, dimension( * ) ds, integer modes, real conds, integer kl, integer ku, real anorm, real, dimension( lda, * ) a, integer lda, real, dimension( * ) work, integer info)

SLATME

Purpose:

        SLATME generates random non-symmetric square matrices with
        specified eigenvalues for testing LAPACK programs.
        SLATME 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 SLATME
               to continue the same random number sequence.
               Changed on exit.

    D

              D is REAL 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 REAL
               On entry, this is used as described under MODE above.
               If used, it must be >= 1. Not modified.

    DMAX

              DMAX is REAL
               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 'similarity
               transform', 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 REAL 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 REAL
               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 REAL
               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 REAL 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 REAL 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 SLATM1 (computing D)
                2  => Cannot scale to DMAX (max. eigenvalue is 0)
                3  => Error return from SLATM1 (computing DS)
                4  => Error return from SLARGE
                5  => Zero singular value from SLATM1.

Author
    Univ. of Tennessee

    Univ. of California Berkeley

    Univ. of Colorado Denver

    NAG Ltd.

Definition at line 327 of file slatme.f.

Author

Generated automatically by Doxygen for LAPACK from the source code.