TESTING/EIG/zchkbd.f(3)    Library Functions Manual    TESTING/EIG/zchkbd.f(3)

NAME
       TESTING/EIG/zchkbd.f

SYNOPSIS
   Functions/Subroutines
       subroutine zchkbd (nsizes, mval, nval, ntypes, dotype, nrhs, iseed,
           thresh, a, lda, bd, be, s1, s2, x, ldx, y, z, q, ldq, pt, ldpt, u,
           vt, work, lwork, rwork, nout, info)
           ZCHKBD

Function/Subroutine Documentation
   subroutine zchkbd (integer nsizes, integer, dimension( * ) mval, integer,
       dimension( * ) nval, integer ntypes, logical, dimension( * ) dotype,
       integer nrhs, integer, dimension( 4 ) iseed, double precision thresh,
       complex*16, dimension( lda, * ) a, integer lda, double precision,
       dimension( * ) bd, double precision, dimension( * ) be, double
       precision, dimension( * ) s1, double precision, dimension( * ) s2,
       complex*16, dimension( ldx, * ) x, integer ldx, complex*16, dimension(
       ldx, * ) y, complex*16, dimension( ldx, * ) z, complex*16, dimension(
       ldq, * ) q, integer ldq, complex*16, dimension( ldpt, * ) pt, integer
       ldpt, complex*16, dimension( ldpt, * ) u, complex*16, dimension( ldpt,
       * ) vt, complex*16, dimension( * ) work, integer lwork, double
       precision, dimension( * ) rwork, integer nout, integer info)
       ZCHKBD

       Purpose:


            ZCHKBD checks the singular value decomposition (SVD) routines.

            ZGEBRD reduces a complex general m by n matrix A to real upper or
            lower bidiagonal form by an orthogonal transformation: Q' * A * P = B
            (or A = Q * B * P').  The matrix B is upper bidiagonal if m >= n
            and lower bidiagonal if m < n.

            ZUNGBR generates the orthogonal matrices Q and P' from ZGEBRD.
            Note that Q and P are not necessarily square.

            ZBDSQR computes the singular value decomposition of the bidiagonal
            matrix B as B = U S V'.  It is called three times to compute
               1)  B = U S1 V', where S1 is the diagonal matrix of singular
                   values and the columns of the matrices U and V are the left
                   and right singular vectors, respectively, of B.
               2)  Same as 1), but the singular values are stored in S2 and the
                   singular vectors are not computed.
               3)  A = (UQ) S (P'V'), the SVD of the original matrix A.
            In addition, ZBDSQR has an option to apply the left orthogonal matrix
            U to a matrix X, useful in least squares applications.

            For each pair of matrix dimensions (M,N) and each selected matrix
            type, an M by N matrix A and an M by NRHS matrix X are generated.
            The problem dimensions are as follows
               A:          M x N
               Q:          M x min(M,N) (but M x M if NRHS > 0)
               P:          min(M,N) x N
               B:          min(M,N) x min(M,N)
               U, V:       min(M,N) x min(M,N)
               S1, S2      diagonal, order min(M,N)
               X:          M x NRHS

            For each generated matrix, 14 tests are performed:

            Test ZGEBRD and ZUNGBR

            (1)   | A - Q B PT | / ( |A| max(M,N) ulp ), PT = P'

            (2)   | I - Q' Q | / ( M ulp )

            (3)   | I - PT PT' | / ( N ulp )

            Test ZBDSQR on bidiagonal matrix B

            (4)   | B - U S1 VT | / ( |B| min(M,N) ulp ), VT = V'

            (5)   | Y - U Z | / ( |Y| max(min(M,N),k) ulp ), where Y = Q' X
                                                             and   Z = U' Y.
            (6)   | I - U' U | / ( min(M,N) ulp )

            (7)   | I - VT VT' | / ( min(M,N) ulp )

            (8)   S1 contains min(M,N) nonnegative values in decreasing order.
                  (Return 0 if true, 1/ULP if false.)

            (9)   0 if the true singular values of B are within THRESH of
                  those in S1.  2*THRESH if they are not.  (Tested using
                  DSVDCH)

            (10)  | S1 - S2 | / ( |S1| ulp ), where S2 is computed without
                                              computing U and V.

            Test ZBDSQR on matrix A

            (11)  | A - (QU) S (VT PT) | / ( |A| max(M,N) ulp )

            (12)  | X - (QU) Z | / ( |X| max(M,k) ulp )

            (13)  | I - (QU)'(QU) | / ( M ulp )

            (14)  | I - (VT PT) (PT'VT') | / ( N ulp )

            The possible matrix types are

            (1)  The zero matrix.
            (2)  The identity matrix.

            (3)  A diagonal matrix with evenly spaced entries
                 1, ..., ULP  and random signs.
                 (ULP = (first number larger than 1) - 1 )
            (4)  A diagonal matrix with geometrically spaced entries
                 1, ..., ULP  and random signs.
            (5)  A diagonal matrix with 'clustered' entries 1, ULP, ..., ULP
                 and random signs.

            (6)  Same as (3), but multiplied by SQRT( overflow threshold )
            (7)  Same as (3), but multiplied by SQRT( underflow threshold )

            (8)  A matrix of the form  U D V, where U and V are orthogonal and
                 D has evenly spaced entries 1, ..., ULP with random signs
                 on the diagonal.

            (9)  A matrix of the form  U D V, where U and V are orthogonal and
                 D has geometrically spaced entries 1, ..., ULP with random
                 signs on the diagonal.

            (10) A matrix of the form  U D V, where U and V are orthogonal and
                 D has 'clustered' entries 1, ULP,..., ULP with random
                 signs on the diagonal.

            (11) Same as (8), but multiplied by SQRT( overflow threshold )
            (12) Same as (8), but multiplied by SQRT( underflow threshold )

            (13) Rectangular matrix with random entries chosen from (-1,1).
            (14) Same as (13), but multiplied by SQRT( overflow threshold )
            (15) Same as (13), but multiplied by SQRT( underflow threshold )

            Special case:
            (16) A bidiagonal matrix with random entries chosen from a
                 logarithmic distribution on [ulp^2,ulp^(-2)]  (I.e., each
                 entry is  e^x, where x is chosen uniformly on
                 [ 2 log(ulp), -2 log(ulp) ] .)  For *this* type:
                 (a) ZGEBRD is not called to reduce it to bidiagonal form.
                 (b) the bidiagonal is  min(M,N) x min(M,N); if M<N, the
                     matrix will be lower bidiagonal, otherwise upper.
                 (c) only tests 5--8 and 14 are performed.

            A subset of the full set of matrix types may be selected through
            the logical array DOTYPE.

       Parameters
           NSIZES

                     NSIZES is INTEGER
                     The number of values of M and N contained in the vectors
                     MVAL and NVAL.  The matrix sizes are used in pairs (M,N).

           MVAL

                     MVAL is INTEGER array, dimension (NM)
                     The values of the matrix row dimension M.

           NVAL

                     NVAL is INTEGER array, dimension (NM)
                     The values of the matrix column dimension N.

           NTYPES

                     NTYPES is INTEGER
                     The number of elements in DOTYPE.   If it is zero, ZCHKBD
                     does nothing.  It must be at least zero.  If it is MAXTYP+1
                     and NSIZES is 1, then an additional type, MAXTYP+1 is
                     defined, which is to use whatever matrices are in A and B.
                     This is only useful if DOTYPE(1:MAXTYP) is .FALSE. and
                     DOTYPE(MAXTYP+1) is .TRUE. .

           DOTYPE

                     DOTYPE is LOGICAL array, dimension (NTYPES)
                     If DOTYPE(j) is .TRUE., then for each size (m,n), a matrix
                     of type j will be generated.  If NTYPES is smaller than the
                     maximum number of types defined (PARAMETER MAXTYP), then
                     types NTYPES+1 through MAXTYP will not be generated.  If
                     NTYPES is larger than MAXTYP, DOTYPE(MAXTYP+1) through
                     DOTYPE(NTYPES) will be ignored.

           NRHS

                     NRHS is INTEGER
                     The number of columns in the 'right-hand side' matrices X, Y,
                     and Z, used in testing ZBDSQR.  If NRHS = 0, then the
                     operations on the right-hand side will not be tested.
                     NRHS must be at least 0.

           ISEED

                     ISEED is INTEGER array, dimension (4)
                     On entry ISEED specifies the seed of the random number
                     generator. The array elements should be between 0 and 4095;
                     if not they will be reduced mod 4096.  Also, ISEED(4) must
                     be odd.  The values of ISEED are changed on exit, and can be
                     used in the next call to ZCHKBD to continue the same random
                     number sequence.

           THRESH

                     THRESH is DOUBLE PRECISION
                     The threshold value for the test ratios.  A result is
                     included in the output file if RESULT >= THRESH.  To have
                     every test ratio printed, use THRESH = 0.  Note that the
                     expected value of the test ratios is O(1), so THRESH should
                     be a reasonably small multiple of 1, e.g., 10 or 100.

           A

                     A is COMPLEX*16 array, dimension (LDA,NMAX)
                     where NMAX is the maximum value of N in NVAL.

           LDA

                     LDA is INTEGER
                     The leading dimension of the array A.  LDA >= max(1,MMAX),
                     where MMAX is the maximum value of M in MVAL.

           BD

                     BD is DOUBLE PRECISION array, dimension
                                 (max(min(MVAL(j),NVAL(j))))

           BE

                     BE is DOUBLE PRECISION array, dimension
                                 (max(min(MVAL(j),NVAL(j))))

           S1

                     S1 is DOUBLE PRECISION array, dimension
                                 (max(min(MVAL(j),NVAL(j))))

           S2

                     S2 is DOUBLE PRECISION array, dimension
                                 (max(min(MVAL(j),NVAL(j))))

           X

                     X is COMPLEX*16 array, dimension (LDX,NRHS)

           LDX

                     LDX is INTEGER
                     The leading dimension of the arrays X, Y, and Z.
                     LDX >= max(1,MMAX).

           Y

                     Y is COMPLEX*16 array, dimension (LDX,NRHS)

           Z

                     Z is COMPLEX*16 array, dimension (LDX,NRHS)

           Q

                     Q is COMPLEX*16 array, dimension (LDQ,MMAX)

           LDQ

                     LDQ is INTEGER
                     The leading dimension of the array Q.  LDQ >= max(1,MMAX).

           PT

                     PT is COMPLEX*16 array, dimension (LDPT,NMAX)

           LDPT

                     LDPT is INTEGER
                     The leading dimension of the arrays PT, U, and V.
                     LDPT >= max(1, max(min(MVAL(j),NVAL(j)))).

           U

                     U is COMPLEX*16 array, dimension
                                 (LDPT,max(min(MVAL(j),NVAL(j))))

           VT

                     VT is COMPLEX*16 array, dimension
                                 (LDPT,max(min(MVAL(j),NVAL(j))))

           WORK

                     WORK is COMPLEX*16 array, dimension (LWORK)

           LWORK

                     LWORK is INTEGER
                     The number of entries in WORK.  This must be at least
                     3(M+N) and  M(M + max(M,N,k) + 1) + N*min(M,N)  for all
                     pairs  (M,N)=(MM(j),NN(j))

           RWORK

                     RWORK is DOUBLE PRECISION array, dimension
                                 (5*max(min(M,N)))

           NOUT

                     NOUT is INTEGER
                     The FORTRAN unit number for printing out error messages
                     (e.g., if a routine returns IINFO not equal to 0.)

           INFO

                     INFO is INTEGER
                     If 0, then everything ran OK.
                      -1: NSIZES < 0
                      -2: Some MM(j) < 0
                      -3: Some NN(j) < 0
                      -4: NTYPES < 0
                      -6: NRHS  < 0
                      -8: THRESH < 0
                     -11: LDA < 1 or LDA < MMAX, where MMAX is max( MM(j) ).
                     -17: LDB < 1 or LDB < MMAX.
                     -21: LDQ < 1 or LDQ < MMAX.
                     -23: LDP < 1 or LDP < MNMAX.
                     -27: LWORK too small.
                     If  ZLATMR, CLATMS, ZGEBRD, ZUNGBR, or ZBDSQR,
                         returns an error code, the
                         absolute value of it is returned.

           -----------------------------------------------------------------------

                Some Local Variables and Parameters:
                ---- ----- --------- --- ----------

                ZERO, ONE       Real 0 and 1.
                MAXTYP          The number of types defined.
                NTEST           The number of tests performed, or which can
                                be performed so far, for the current matrix.
                MMAX            Largest value in NN.
                NMAX            Largest value in NN.
                MNMIN           min(MM(j), NN(j)) (the dimension of the bidiagonal
                                matrix.)
                MNMAX           The maximum value of MNMIN for j=1,...,NSIZES.
                NFAIL           The number of tests which have exceeded THRESH
                COND, IMODE     Values to be passed to the matrix generators.
                ANORM           Norm of A; passed to matrix generators.

                OVFL, UNFL      Overflow and underflow thresholds.
                RTOVFL, RTUNFL  Square roots of the previous 2 values.
                ULP, ULPINV     Finest relative precision and its inverse.

                        The following four arrays decode JTYPE:
                KTYPE(j)        The general type (1-10) for type 'j'.
                KMODE(j)        The MODE value to be passed to the matrix
                                generator for type 'j'.
                KMAGN(j)        The order of magnitude ( O(1),
                                O(overflow^(1/2) ), O(underflow^(1/2) )

       Author
           Univ. of Tennessee

           Univ. of California Berkeley

           Univ. of Colorado Denver

           NAG Ltd.

       Definition at line 411 of file zchkbd.f.

Author
       Generated automatically by Doxygen for LAPACK from the source code.

LAPACK                          Version 3.12.0         TESTING/EIG/zchkbd.f(3)