TESTING/MATGEN/clatms.f(3)

NAME
TESTING/MATGEN/clatms.f

SYNOPSIS

  Functions/Subroutines
subroutine clatms (m, n, dist, iseed, sym, d, mode, cond, dmax, kl, ku, pack, a, lda, work, info)
CLATMS

Function/Subroutine Documentation

  subroutine clatms (integer m, integer n, character dist, integer, dimension( 4 ) iseed, character sym, real, dimension( * ) d, integer mode, real cond, real dmax, integer kl, integer ku, character pack, complex, dimension( lda, * ) a, integer lda, complex, dimension( * ) work, integer info)

CLATMS

Purpose:

    !>
    !>    CLATMS generates random matrices with specified singular values
    !>    (or hermitian with specified eigenvalues)
    !>    for testing LAPACK programs.
    !>
    !>    CLATMS 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,
    !>              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 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 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 hermitian or symmetric, < .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 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 lower triangle in banded format (if hermitian or
    !>               lower triangular)
    !>         store the upper triangle in banded format (if hermitian or
    !>               upper 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
    M

    !>          M is INTEGER
    !>           The number of rows of A. Not modified.
    !>

    N

    !>          N is INTEGER
    !>           The number of columns of A. N must equal M if the matrix
    !>           is symmetric or hermitian (i.e., if SYM is not 'N')
    !>           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.
    !>           '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 CLATMS
    !>           to continue the same random number sequence.
    !>           Changed on exit.
    !>

    SYM

    !>          SYM is CHARACTER*1
    !>           If SYM='H', the generated matrix is hermitian, with
    !>             eigenvalues specified by D, COND, MODE, and DMAX; they
    !>             may be positive, negative, or zero.
    !>           If SYM='P', the generated matrix is hermitian, with
    !>             eigenvalues (= singular values) specified by D, COND,
    !>             MODE, and DMAX; they will not be negative.
    !>           If SYM='N', the generated matrix is nonsymmetric, with
    !>             singular values specified by D, COND, MODE, and DMAX;
    !>             they will not be negative.
    !>           If SYM='S', the generated matrix is (complex) symmetric,
    !>             with singular values specified by D, COND, MODE, and
    !>             DMAX; they will not be negative.
    !>           Not modified.
    !>

    D

    !>          D is REAL array, dimension ( MIN( M, N ) )
    !>           This array is used to specify the singular values or
    !>           eigenvalues of A (see SYM, above.)  If MODE=0, then D is
    !>           assumed to contain the singular/eigenvalues, otherwise
    !>           they will be computed according to MODE, COND, and DMAX,
    !>           and placed in D.
    !>           Modified if MODE is nonzero.
    !>

    MODE

    !>          MODE is INTEGER
    !>           On entry this describes how the singular/eigenvalues are to
    !>           be specified:
    !>           MODE = 0 means use D 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.
    !>           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 positive, D has entries ranging from
    !>              1 to 1/COND, if negative, from 1/COND to 1,
    !>           If SYM='H', and MODE is neither 0, 6, nor -6, then
    !>              the elements of D will also be multiplied by a random
    !>              sign (i.e., +1 or -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))); thus, the maximum absolute eigen- 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).
    !>           Not modified.
    !>

    KL

    !>          KL is INTEGER
    !>           This specifies the lower bandwidth of the  matrix. For
    !>           example, KL=0 implies upper triangular, KL=1 implies upper
    !>           Hessenberg, and KL being at least M-1 means that the matrix
    !>           has full lower bandwidth.  KL must equal KU if the matrix
    !>           is symmetric or hermitian.
    !>           Not modified.
    !>

    KU

    !>          KU is INTEGER
    !>           This specifies the upper bandwidth of the  matrix. For
    !>           example, KU=0 implies lower triangular, KU=1 implies lower
    !>           Hessenberg, and KU being at least N-1 means that the matrix
    !>           has full upper bandwidth.  KL must equal KU if the matrix
    !>           is symmetric or hermitian.
    !>           Not modified.
    !>

    PACK

    !>          PACK is CHARACTER*1
    !>           This specifies packing of matrix as follows:
    !>           'N' => no packing
    !>           'U' => zero out all subdiagonal entries (if symmetric
    !>                  or hermitian)
    !>           'L' => zero out all superdiagonal entries (if symmetric
    !>                  or hermitian)
    !>           'C' => store the upper triangle columnwise (only if the
    !>                  matrix is symmetric, hermitian, or upper triangular)
    !>           'R' => store the lower triangle columnwise (only if the
    !>                  matrix is symmetric, hermitian, or lower triangular)
    !>           'B' => store the lower triangle in band storage scheme
    !>                  (only if the matrix is symmetric, hermitian, or
    !>                  lower triangular)
    !>           'Q' => store the upper triangle in band storage scheme
    !>                  (only if the matrix is symmetric, hermitian, or
    !>                  upper 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                    - use 'Z'
    !>           PB, SB, HB, or TB     - use 'B' or 'Q'
    !>           PP, SP, HB, or TP     - use 'C' or 'R'
    !>
    !>           If two calls to CLATMS differ only in the PACK parameter,
    !>           they will generate mathematically equivalent matrices.
    !>           Not modified.
    !>

    A

    !>          A is COMPLEX array, dimension ( LDA, N )
    !>           On exit A is 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.
    !>           Modified.
    !>

    LDA

    !>          LDA is INTEGER
    !>           LDA specifies the first dimension of A as declared in the
    !>           calling program.  If PACK='N', 'U', 'L', 'C', or 'R', then
    !>           LDA must be at least M.  If PACK='B' or 'Q', then LDA must
    !>           be at least MIN( KL, M-1) (which is equal to MIN(KU,N-1)).
    !>           If PACK='Z', LDA must be large enough to hold the packed
    !>           array: MIN( KU, N-1) + MIN( KL, M-1) + 1.
    !>           Not modified.
    !>

    WORK

    !>          WORK is COMPLEX array, dimension ( 3*MAX( N, M ) )
    !>           Workspace.
    !>           Modified.
    !>

    INFO

    !>          INFO is INTEGER
    !>           Error code.  On exit, INFO will be set to one of the
    !>           following values:
    !>             0 => normal return
    !>            -1 => M negative or unequal to N and SYM='S', 'H', or 'P'
    !>            -2 => N negative
    !>            -3 => DIST illegal string
    !>            -5 => SYM illegal string
    !>            -7 => MODE not in range -6 to 6
    !>            -8 => COND less than 1.0, and MODE neither -6, 0 nor 6
    !>           -10 => KL negative
    !>           -11 => KU negative, or SYM is not 'N' and KU is not equal to
    !>                  KL
    !>           -12 => PACK illegal string, or PACK='U' or 'L', and SYM='N';
    !>                  or PACK='C' or 'Q' and SYM='N' and KL is not zero;
    !>                  or PACK='R' or 'B' and SYM='N' and KU is not zero;
    !>                  or PACK='U', 'L', 'C', 'R', 'B', or 'Q', and M is not
    !>                  N.
    !>           -14 => LDA is less than M, or PACK='Z' and LDA is less than
    !>                  MIN(KU,N-1) + MIN(KL,M-1) + 1.
    !>            1  => Error return from SLATM1
    !>            2  => Cannot scale to DMAX (max. sing. value is 0)
    !>            3  => Error return from CLAGGE, CLAGHE or CLAGSY
    !>

Author
    Univ. of Tennessee

    Univ. of California Berkeley

    Univ. of Colorado Denver

    NAG Ltd.

Definition at line 330 of file clatms.f.

Author

Generated automatically by Doxygen for LAPACK from the source code.