zlatmr.f - Man Page

TESTING/MATGEN/zlatmr.f

Synopsis

Functions/Subroutines

subroutine zlatmr (m, n, dist, iseed, sym, d, mode, cond, dmax, rsign, grade, dl, model, condl, dr, moder, condr, pivtng, ipivot, kl, ku, sparse, anorm, pack, a, lda, iwork, info)
ZLATMR

Function/Subroutine Documentation

subroutine zlatmr (integer m, integer n, character dist, integer, dimension( 4 ) iseed, character sym, complex*16, dimension( * ) d, integer mode, double precision cond, complex*16 dmax, character rsign, character grade, complex*16, dimension( * ) dl, integer model, double precision condl, complex*16, dimension( * ) dr, integer moder, double precision condr, character pivtng, integer, dimension( * ) ipivot, integer kl, integer ku, double precision sparse, double precision anorm, character pack, complex*16, dimension( lda, * ) a, integer lda, integer, dimension( * ) iwork, integer info)

ZLATMR

Purpose:

    ZLATMR generates random matrices of various types for testing
    LAPACK programs.

    ZLATMR operates by applying the following sequence of
    operations:

      Generate a matrix A with random entries of distribution DIST
         which is symmetric if SYM='S', Hermitian if SYM='H', and
         nonsymmetric if SYM='N'.

      Set the diagonal to D, where D may be input or
         computed according to MODE, COND, DMAX and RSIGN
         as described below.

      Grade the matrix, if desired, from the left and/or right
         as specified by GRADE. The inputs DL, MODEL, CONDL, DR,
         MODER and CONDR also determine the grading as described
         below.

      Permute, if desired, the rows and/or columns as specified by
         PIVTNG and IPIVOT.

      Set random entries to zero, if desired, to get a random sparse
         matrix as specified by SPARSE.

      Make A a band matrix, if desired, by zeroing out the matrix
         outside a band of lower bandwidth KL and upper bandwidth KU.

      Scale A, if desired, to have maximum entry ANORM.

      Pack the matrix if desired. Options specified by PACK are:
         no packing
         zero out upper half (if symmetric or Hermitian)
         zero out lower half (if symmetric or Hermitian)
         store the upper half columnwise (if symmetric or Hermitian
             or square upper triangular)
         store the lower half columnwise (if symmetric or Hermitian
             or square lower triangular)
             same as upper half rowwise if symmetric
             same as conjugate upper half rowwise if Hermitian
         store the lower triangle in banded format
             (if symmetric or Hermitian)
         store the upper triangle in banded format
             (if symmetric or Hermitian)
         store the entire matrix in banded format

    Note: If two calls to ZLATMR differ only in the PACK parameter,
          they will generate mathematically equivalent matrices.

          If two calls to ZLATMR both have full bandwidth (KL = M-1
          and KU = N-1), and differ only in the PIVTNG and PACK
          parameters, then the matrices generated will differ only
          in the order of the rows and/or columns, and otherwise
          contain the same data. This consistency cannot be and
          is not maintained with less than full bandwidth.
Parameters

M

          M is INTEGER
           Number of rows of A. Not modified.

N

          N is INTEGER
           Number of columns of A. Not modified.

DIST

          DIST is CHARACTER*1
           On entry, DIST specifies the type of distribution to be used
           to generate a random matrix .
           'U' => real and imaginary parts are independent
                  UNIFORM( 0, 1 )  ( 'U' for uniform )
           'S' => real and imaginary parts are independent
                  UNIFORM( -1, 1 ) ( 'S' for symmetric )
           'N' => real and imaginary parts are independent
                  NORMAL( 0, 1 )   ( 'N' for normal )
           'D' => uniform on interior of unit disk ( 'D' for disk )
           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 ZLATMR
           to continue the same random number sequence.
           Changed on exit.

SYM

          SYM is CHARACTER*1
           If SYM='S', generated matrix is symmetric.
           If SYM='H', generated matrix is Hermitian.
           If SYM='N', generated matrix is nonsymmetric.
           Not modified.

D

          D is COMPLEX*16 array, dimension (min(M,N))
           On entry this array specifies the diagonal entries
           of the diagonal of A.  D may either be specified
           on entry, or set according to MODE and COND as described
           below. If the matrix is Hermitian, the real part of D
           will be taken. May be changed on exit if MODE is nonzero.

MODE

          MODE is INTEGER
           On entry describes how D is to be used:
           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,
           Not modified.

COND

          COND is DOUBLE PRECISION
           On entry, used as described under MODE above.
           If used, it must be >= 1. Not modified.

DMAX

          DMAX is COMPLEX*16
           If MODE neither -6, 0 nor 6, the diagonal is scaled by
           DMAX / max(abs(D(i))), so that maximum absolute entry
           of diagonal is abs(DMAX). If DMAX is complex (or zero),
           diagonal will be scaled by a complex number (or zero).

RSIGN

          RSIGN is CHARACTER*1
           If MODE neither -6, 0 nor 6, specifies sign of diagonal
           as follows:
           'T' => diagonal entries are multiplied by a random complex
                  number uniformly distributed with absolute value 1
           'F' => diagonal unchanged
           Not modified.

GRADE

          GRADE is CHARACTER*1
           Specifies grading of matrix as follows:
           'N'  => no grading
           'L'  => matrix premultiplied by diag( DL )
                   (only if matrix nonsymmetric)
           'R'  => matrix postmultiplied by diag( DR )
                   (only if matrix nonsymmetric)
           'B'  => matrix premultiplied by diag( DL ) and
                         postmultiplied by diag( DR )
                   (only if matrix nonsymmetric)
           'H'  => matrix premultiplied by diag( DL ) and
                         postmultiplied by diag( CONJG(DL) )
                   (only if matrix Hermitian or nonsymmetric)
           'S'  => matrix premultiplied by diag( DL ) and
                         postmultiplied by diag( DL )
                   (only if matrix symmetric or nonsymmetric)
           'E'  => matrix premultiplied by diag( DL ) and
                         postmultiplied by inv( diag( DL ) )
                         ( 'S' for similarity )
                   (only if matrix nonsymmetric)
                   Note: if GRADE='S', then M must equal N.
           Not modified.

DL

          DL is COMPLEX*16 array, dimension (M)
           If MODEL=0, then on entry this array specifies the diagonal
           entries of a diagonal matrix used as described under GRADE
           above. If MODEL is not zero, then DL will be set according
           to MODEL and CONDL, analogous to the way D is set according
           to MODE and COND (except there is no DMAX parameter for DL).
           If GRADE='E', then DL cannot have zero entries.
           Not referenced if GRADE = 'N' or 'R'. Changed on exit.

MODEL

          MODEL is INTEGER
           This specifies how the diagonal array DL is to be computed,
           just as MODE specifies how D is to be computed.
           Not modified.

CONDL

          CONDL is DOUBLE PRECISION
           When MODEL is not zero, this specifies the condition number
           of the computed DL.  Not modified.

DR

          DR is COMPLEX*16 array, dimension (N)
           If MODER=0, then on entry this array specifies the diagonal
           entries of a diagonal matrix used as described under GRADE
           above. If MODER is not zero, then DR will be set according
           to MODER and CONDR, analogous to the way D is set according
           to MODE and COND (except there is no DMAX parameter for DR).
           Not referenced if GRADE = 'N', 'L', 'H' or 'S'.
           Changed on exit.

MODER

          MODER is INTEGER
           This specifies how the diagonal array DR is to be computed,
           just as MODE specifies how D is to be computed.
           Not modified.

CONDR

          CONDR is DOUBLE PRECISION
           When MODER is not zero, this specifies the condition number
           of the computed DR.  Not modified.

PIVTNG

          PIVTNG is CHARACTER*1
           On entry specifies pivoting permutations as follows:
           'N' or ' ' => none.
           'L' => left or row pivoting (matrix must be nonsymmetric).
           'R' => right or column pivoting (matrix must be
                  nonsymmetric).
           'B' or 'F' => both or full pivoting, i.e., on both sides.
                         In this case, M must equal N

           If two calls to ZLATMR both have full bandwidth (KL = M-1
           and KU = N-1), and differ only in the PIVTNG and PACK
           parameters, then the matrices generated will differ only
           in the order of the rows and/or columns, and otherwise
           contain the same data. This consistency cannot be
           maintained with less than full bandwidth.

IPIVOT

          IPIVOT is INTEGER array, dimension (N or M)
           This array specifies the permutation used.  After the
           basic matrix is generated, the rows, columns, or both
           are permuted.   If, say, row pivoting is selected, ZLATMR
           starts with the *last* row and interchanges the M-th and
           IPIVOT(M)-th rows, then moves to the next-to-last row,
           interchanging the (M-1)-th and the IPIVOT(M-1)-th rows,
           and so on.  In terms of '2-cycles', the permutation is
           (1 IPIVOT(1)) (2 IPIVOT(2)) ... (M IPIVOT(M))
           where the rightmost cycle is applied first.  This is the
           *inverse* of the effect of pivoting in LINPACK.  The idea
           is that factoring (with pivoting) an identity matrix
           which has been inverse-pivoted in this way should
           result in a pivot vector identical to IPIVOT.
           Not referenced if PIVTNG = 'N'. Not modified.

KL

          KL is INTEGER
           On entry specifies the lower bandwidth of the  matrix. For
           example, KL=0 implies upper triangular, KL=1 implies upper
           Hessenberg, and KL at least M-1 implies the matrix is not
           banded. Must equal KU if matrix is symmetric or Hermitian.
           Not modified.

KU

          KU is INTEGER
           On entry specifies the upper bandwidth of the  matrix. For
           example, KU=0 implies lower triangular, KU=1 implies lower
           Hessenberg, and KU at least N-1 implies the matrix is not
           banded. Must equal KL if matrix is symmetric or Hermitian.
           Not modified.

SPARSE

          SPARSE is DOUBLE PRECISION
           On entry specifies the sparsity of the matrix if a sparse
           matrix is to be generated. SPARSE should lie between
           0 and 1. To generate a sparse matrix, for each matrix entry
           a uniform ( 0, 1 ) random number x is generated and
           compared to SPARSE; if x is larger the matrix entry
           is unchanged and if x is smaller the entry is set
           to zero. Thus on the average a fraction SPARSE of the
           entries will be set to zero.
           Not modified.

ANORM

          ANORM is DOUBLE PRECISION
           On entry specifies maximum entry of output matrix
           (output matrix will by multiplied by a constant so that
           its largest absolute entry equal ANORM)
           if ANORM is nonnegative. If ANORM is negative no scaling
           is done. Not modified.

PACK

          PACK is CHARACTER*1
           On entry 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 matrix symmetric or Hermitian or
                   square upper triangular)
           'R' => store the lower triangle columnwise
                  (only if matrix symmetric or Hermitian or
                   square lower triangular)
                  (same as upper half rowwise if symmetric)
                  (same as conjugate upper half rowwise if Hermitian)
           'B' => store the lower triangle in band storage scheme
                  (only if matrix symmetric or Hermitian)
           'Q' => store the upper triangle in band storage scheme
                  (only if matrix symmetric or Hermitian)
           '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, HB or TB     - use 'B' or 'Q'
           PP, HP or TP     - use 'C' or 'R'

           If two calls to ZLATMR differ only in the PACK parameter,
           they will generate mathematically equivalent matrices.
           Not modified.

A

          A is COMPLEX*16 array, dimension (LDA,N)
           On exit A is the desired test matrix. Only those
           entries of A which are significant on output
           will be referenced (even if A is in packed or band
           storage format). The 'unoccupied corners' of A in
           band format will be zeroed out.

LDA

          LDA is INTEGER
           on entry LDA specifies the first dimension of A as
           declared in the calling program.
           If PACK='N', 'U' or 'L', LDA must be at least max ( 1, M ).
           If PACK='C' or 'R', LDA must be at least 1.
           If PACK='B', or 'Q', LDA must be MIN ( KU+1, N )
           If PACK='Z', LDA must be at least KUU+KLL+1, where
           KUU = MIN ( KU, N-1 ) and KLL = MIN ( KL, M-1 )
           Not modified.

IWORK

          IWORK is INTEGER array, dimension (N or M)
           Workspace. Not referenced if PIVTNG = 'N'. Changed on exit.

INFO

          INFO is INTEGER
           Error parameter on exit:
             0 => normal return
            -1 => M negative or unequal to N and SYM='S' or 'H'
            -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 => MODE neither -6, 0 nor 6 and RSIGN illegal string
           -11 => GRADE illegal string, or GRADE='E' and
                  M not equal to N, or GRADE='L', 'R', 'B', 'S' or 'E'
                  and SYM = 'H', or GRADE='L', 'R', 'B', 'H' or 'E'
                  and SYM = 'S'
           -12 => GRADE = 'E' and DL contains zero
           -13 => MODEL not in range -6 to 6 and GRADE= 'L', 'B', 'H',
                  'S' or 'E'
           -14 => CONDL less than 1.0, GRADE='L', 'B', 'H', 'S' or 'E',
                  and MODEL neither -6, 0 nor 6
           -16 => MODER not in range -6 to 6 and GRADE= 'R' or 'B'
           -17 => CONDR less than 1.0, GRADE='R' or 'B', and
                  MODER neither -6, 0 nor 6
           -18 => PIVTNG illegal string, or PIVTNG='B' or 'F' and
                  M not equal to N, or PIVTNG='L' or 'R' and SYM='S'
                  or 'H'
           -19 => IPIVOT contains out of range number and
                  PIVTNG not equal to 'N'
           -20 => KL negative
           -21 => KU negative, or SYM='S' or 'H' and KU not equal to KL
           -22 => SPARSE not in range 0. to 1.
           -24 => PACK illegal string, or PACK='U', 'L', 'B' or 'Q'
                  and SYM='N', or PACK='C' and SYM='N' and either KL
                  not equal to 0 or N not equal to M, or PACK='R' and
                  SYM='N', and either KU not equal to 0 or N not equal
                  to M
           -26 => LDA too small
             1 => Error return from ZLATM1 (computing D)
             2 => Cannot scale diagonal to DMAX (max. entry is 0)
             3 => Error return from ZLATM1 (computing DL)
             4 => Error return from ZLATM1 (computing DR)
             5 => ANORM is positive, but matrix constructed prior to
                  attempting to scale it to have norm ANORM, is zero
Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Definition at line 486 of file zlatmr.f.

Author

Generated automatically by Doxygen for LAPACK from the source code.

Referenced By

The man page zlatmr(3) is an alias of zlatmr.f(3).

Tue Nov 28 2023 12:08:43 Version 3.12.0 LAPACK