
          F02 -- Eigenvalues and Eigenvectors           Introduction -- F02
                                    Chapter F02
                           Eigenvalues and Eigenvectors

          1. Scope of the Chapter

          This chapter is concerned with computing

          --    eigenvalues and eigenvectors of a matrix

          --    eigenvalues and eigenvectors of generalized matrix
                eigenvalue problems

          --    singular values and singular vectors of a matrix.

          2. Background to the Problems

          2.1. Eigenvalue Problems

          In the most usual form of eigenvalue problem we are given a
          square n by n matrix A and wish to compute (lambda) (an
          eigenvalue) and x/=0 (an eigenvector) which satisfy the equation

                                    Ax=(lambda)x

          Such problems are called 'standard' eigenvalue problems in
          contrast to 'generalized' eigenvalue problems where we wish to
          satisfy the equation

                                    Ax=(lambda)Bx

          B also being a square n by n matrix.

          Section 2.1.1 and Section 2.1.2 discuss, respectively, standard
          and generalized eigenvalue problems where the matrices involved
          are dense; Section 2.1.3 discusses both types of problem in the
          case where A and B are sparse (and symmetric).

          2.1.1.  Standard eigenvalue problems

          Some of the routines in this chapter find all the n eigenvalues,
          some find all the n eigensolutions (eigenvalues and corresponding
          eigenvectors), and some find a selected group of eigenvalues
          and/or eigenvectors. The matrix A may be:

          (i)   general (real or complex)

          (ii)  real symmetric, or

          (iii) complex Hermitian (so that if a  =(alpha)+i(beta) then
                                               ij
                a  =(alpha)-i(beta)).
                 ji

          In all cases the computation starts with a similarity
                          -1
          transformation S  AS=T, where S is non-singular and is the
          product of fairly simple matrices, and T has an 'easier form'
          than A so that its eigensolutions are easily determined. The
          matrices A and T, of course, have the same eigenvalues, and if y
          is an eigenvector of T then Sy is the corresponding eigenvector
          of A.

          In case (i) (general real or complex A), the selected form of T
          is an upper Hessenberg matrix (t  =0 if i-j>1) and S is the
                                          ij
          product of n-2 stabilised elementary transformation matrices.
          There is no easy method of computing selected eigenvalues of a
          Hessenberg matrix, so that all eigenvalues are always calculated.
          In the real case this computation is performed via the Francis QR
          algorithm with double shifts, and in the complex case by means of
          the LR algorithm. If the eigenvectors are required they are
          computed by back-substitution following the QR and LR algorithm.

          In case (ii) (real and symmetric A) the selected simple form of T
          is a tridiagonal matrix (t  =0 if |i-j|>1), and S is the product
                                    ij
          of n-2 orthogonal Householder transformation matrices. If only
          selected eigenvalues are required, they are obtained by the
          method of bisection using the Sturm sequence property, and the
          corresponding eigenvectors of T are computed by inverse
          iteration. If all eigenvalues are required, they are computed
          from T via the QL algorithm (an adaptation of the QR algorithm),
          and the corresponding eigenvectors of T are the product of the
          transformations for the QL reduction. In all cases the
          corresponding eigenvectors of A are recovered from the
          computation of x=Sy.

          In case (iii) (complex Hermitian A) analogous transformations as
          in case (ii) are used. T has complex elements in off-diagonal
          positions, but a simple diagonal similarity transformation is
          then used to produce a real tridiagonal form, after which the QL
          algorithm and succeeding methods described in the previous
          paragraph are used to complete the solution.

          2.1.2.  Generalized eigenvalue problems

          Here we distinguish as a special case those problems in which
          both A and B are symmetric and B is positive-definite and well-
          conditioned with respect to inversion (i.e., all the eigenvalues
          of B are significantly greater than zero). Such problems can be
          satisfactorily treated by first reducing them to case (ii) of
          Section 2.1.1 and then using the methods described there to
                                                              T
          compute the eigensolutions. If B is factorized as LL  (L lower
          triangular), then Ax=(lambda)Bx is equivalent to the standard
                                                   -1   T -1        T
          symmetric problem Ry=(lambda)y, where R=L  A(L )   and y=L x.
          After finding an eigenvector y of R, the required x is computed
                                     T
          by back-substitution in y=L x.

          For generalized problems of the form Ax=(lambda)Bx which do not
          fall into the special case, the QZ algorithm is provided.

          In order to appreciate the domain in which this algorithm is
          appropriate we remark first that when B is non-singular the
          problem Ax=(lambda)Bx is fully equivalent to the problem
            -1
          (B  A)x=(lambda)x; both the eigenvalues and eigenvectors being
          the same. When A is non-singular Ax=(lambda)Bx is equivalent to
                        -1
          the problem (A  B)x=(mu)x; the eigenvalues (mu) being the
          reciprocals of the required eigenvalues and the eigenvectors
          remaining the same. In theory then, provided at least one of the
          matrices A and B is non-singular, the generalized problem
          Ax=(lambda)Bx could be solved via the standard problem
          Cx=(lambda)x with an appropriate matrix C, and as far as economy
          of effort is concerned this is quite satisfactory. However, in
          practice, for this reduction to be satisfactory from the
          standpoint of numerical stability, one requires more than the
                                                                -1
          mere non-singularity of A or B. It is necessary that B  A (or
           -1
          A  B) should not only exist but that B (or A) should be well-
          conditioned with respect to inversion. The nearer B (or A) is to
                                               -1       -1
          singularity the more unsatisfactory B  A (or A  B) will be as a
          vehicle for determining the required eigenvalues. Unfortunately
                                                                        -1
          one cannot counter ill-conditioning in B (or A) by computing B  A
               -1
          (or A  B) accurately to single precision using iterative
          refinement. Well-determined eigenvalues of the original
          Ax=(lambda)Bx may be poorly determined even by the correctly
                              -1       -1
          rounded version of B  A (or A  B). The situation may in some
          instances be saved by the observation that if Ax=(lambda)Bx then
          (A-kB)x=((lambda)-k)Bx. Hence if A-kB is non-singular we may
                                            -1
          solve the standard problem [(A-kB)  B]x=(mu)x and for numerical
          stability we require only that (A-kB) be well-conditioned with
          respect to inversion.

          In practice one may well be in a situation where no k is known
          for which (A-kB) is well-conditioned with respect to inversion
          and indeed (A-kB) may be singular for all k. The QZ algorithm is
          designed to deal directly with the problem Ax=(lambda)Bx itself
          and its performance is unaffected by singularity or near-
          singularity of A, B or A-kB.

          2.1.3.  Sparse symmetric problems

          If the matrices A and B are large and sparse (i.e., only a small
          proportion of the elements are non-zero), then the methods
          described in the previous Section are unsuitable, because in
          reducing the problem to a simpler form, much of the sparsity of
          the problem would be lost; hence the computing time and the
          storage required would be very large. Instead, for symmetric
          problems, the method of simultaneous iteration may be used to
          determine selected eigenvalues and the corresponding
          eigenvectors. The routine provided has been designed to handle
          both symmetric and generalized symmetric problems.

          2.2. Singular Value Problems

          The singular value decomposition of an m by n real matrix A is
          given by

                                            T
                                       A=QDP ,

          where Q is an m by m orthogonal matrix, P is an n by n orthogonal
          matrix and D is an m by n diagonal matrix with non-negative
          diagonal elements. The first k==min(m,n) columns of Q and P are
          the left- and right-hand singular vectors of A and the k diagonal
          elements of D are the singular values.

          When A is complex then the singular value decomposition is given
          by

                                            H
                                       A=QDP ,

                                      H                                   T
          where Q and P are unitary, P  denotes the complex conjugate of P
          and D is as above for the real case.

          If the matrix A has column means of zero, then AP is the matrix
          of principal components of A and the singular values are the
          square roots of the sample variances of the observations with
          respect to the principal components. (See also Chapter G03.)

          Routines are provided to return the singular values and vectors
          of a general real or complex matrix.

          3. Recommendations on Choice and Use of Routines

          3.1. General Discussion

          There is one routine, F02FJF, which is designed for sparse
          symmetric eigenvalue problems, either standard or generalized.
          The remainder of the routines are designed for dense matrices.

          3.2. Eigenvalue and Eigenvector Routines

          These reduce the matrix A to a simpler form by a similarity
                          -1
          transformation S  AS=T where T is an upper Hessenberg or
          tridiagonal matrix, compute the eigensolutions of T, and then
          recover the eigenvectors of A via the matrix S. The eigenvectors
          are normalised so that

                                      n
                                      --     2
                                      >  |x | =1
                                      --   r
                                      r=1

          x  being the rth component of the eigenvector x, and so that the
           r
          element of largest modulus is real if x is complex. For problems
          of the type Ax=(lambda)Bx with A and B symmetric and B positive-
                                                             T
          definite, the eigenvectors are normalised so that x Bx=1, x
          always being real for such problems.

          3.3. Singular Value and Singular Vector Routines

          These reduce the matrix A to real bidiagonal form, B say, by
                                      T
          orthogonal transformations Q AP=B in the real case, and by
                                   H
          unitary transformations Q AP=B in the complex case, and the
          singular values and vectors are computed via this bidiagonal
          form. The singular values are returned in descending order.

          3.4. Decision Trees

          (i)  Eigenvalues and Eigenvectors


                   Please see figure in printed Reference Manual


          (ii)  Singular Values and Singular Vectors


                   Please see figure in printed Reference Manual

          F02 -- Eigenvalues and Eigenvectors               Contents -- F02
          Chapter F02

          Eigenvalues and Eigenvectors

          F02AAF  All eigenvalues of real symmetric matrix

          F02ABF  All eigenvalues and eigenvectors of real symmetric matrix

          F02ADF  All eigenvalues of generalized real symmetric-definite
                  eigenproblem

          F02AEF  All eigenvalues and eigenvectors of generalized real
                  symmetric-definite eigenproblem

          F02AFF  All eigenvalues of real matrix

          F02AGF  All eigenvalues and eigenvectors of real matrix

          F02AJF  All eigenvalues of complex matrix

          F02AKF  All eigenvalues and eigenvectors of complex matrix

          F02AWF  All eigenvalues of complex Hermitian matrix

          F02AXF  All eigenvalues and eigenvectors of complex Hermitian
                  matrix

          F02BBF  Selected eigenvalues and eigenvectors of real symmetric
                  matrix

          F02BJF  All eigenvalues and optionally eigenvectors of
                  generalized eigenproblem by QZ algorithm, real matrices

          F02FJF  Selected eigenvalues and eigenvectors of sparse symmetric
                  eigenproblem

          F02WEF  SVD of real matrix

          F02XEF  SVD of complex matrix

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02AAF
                  F02AAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02AAF calculates all the eigenvalues of a real symmetric matrix.

          2. Specification

                 SUBROUTINE F02AAF (A, IA, N, R, E, IFAIL)
                 INTEGER          IA, N, IFAIL
                 DOUBLE PRECISION A(IA,N), R(N), E(N)

          3. Description

          This routine reduces the real symmetric matrix A to a real
          symmetric tridiagonal matrix using Householder's method. The
          eigenvalues of the tridiagonal matrix are then determined using
          the QL algorithm.

          4. References

          [1]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  A(IA,N) -- DOUBLE PRECISION array               Input/Output
               On entry: the lower triangle of the n by n symmetric matrix
               A. The elements of the array above the diagonal need not be
               set. On exit: the elements of A below the diagonal are
               overwritten, and the rest of the array is unchanged.

           2:  IA -- INTEGER                                          Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which F02AAF is called.
               Constraint: IA >= N.

           3:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A.

           4:  R(N) -- DOUBLE PRECISION array                        Output
               On exit: the eigenvalues in ascending order.

           5:  E(N) -- DOUBLE PRECISION array                     Workspace

           6:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               Failure in F02AVF(*) indicating that more than 30*N
               iterations are required to isolate all the eigenvalues.

          7. Accuracy

          The accuracy of the eigenvalues depends on the sensitivity of the
          matrix to rounding errors produced in tridiagonalisation. For a
          detailed error analysis see Wilkinson and Reinsch [1] pp 222 and
          235.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          9. Example

          To calculate all the eigenvalues of the real symmetric matrix:

                               ( 0.5  0.0  2.3 -2.6)
                               ( 0.0  0.5 -1.4 -0.7)
                               ( 2.3 -1.4  0.5  0.0).
                               (-2.6 -0.7  0.0  0.5)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02ABF
                  F02ABF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02ABF calculates all the eigenvalues and eigenvectors of a real
          symmetric matrix.

          2. Specification

                 SUBROUTINE F02ABF (A, IA, N, R, V, IV, E, IFAIL)
                 INTEGER          IA, N, IV, IFAIL
                 DOUBLE PRECISION A(IA,N), R(N), V(IV,N), E(N)

          3. Description

          This routine reduces the real symmetric matrix A to a real
          symmetric tridiagonal matrix by Householder's method. The
          eigenvalues and eigenvectors are calculated using the QL
          algorithm.

          4. References

          [1]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  A(IA,N) -- DOUBLE PRECISION array                      Input
               On entry: the lower triangle of the n by n symmetric matrix
               A. The elements of the array above the diagonal need not be
               set. See also Section 8.

           2:  IA -- INTEGER                                          Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which F02ABF is called.
               Constraint: IA >= N.

           3:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A.

           4:  R(N) -- DOUBLE PRECISION array                        Output
               On exit: the eigenvalues in ascending order.

           5:  V(IV,N) -- DOUBLE PRECISION array                     Output
               On exit: the normalised eigenvectors, stored by columns;
               the ith column corresponds to the ith eigenvalue. The
               eigenvectors are normalised so that the sum of squares of
               the elements is equal to 1.

           6:  IV -- INTEGER                                          Input
               On entry:
               the first dimension of the array V as declared in the
               (sub)program from which F02ABF is called.
               Constraint: IV >= N.

           7:  E(N) -- DOUBLE PRECISION array                     Workspace

           8:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               Failure in F02AMF(*) indicating that more than 30*N
               iterations are required to isolate all the eigenvalues.

          7. Accuracy

          The eigenvectors are always accurately orthogonal but the
          accuracy of the individual eigenvectors is dependent on their
          inherent sensitivity to changes in the original matrix. For a
          detailed error analysis see Wilkinson and Reinsch [1] pp 222 and
          235.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          Unless otherwise stated in the Users' Note for your
          implementation, the routine may be called with the same actual
          array supplied for parameters A and V, in which case the
          eigenvectors will overwrite the original matrix. However this is
          not standard Fortran 77, and may not work on all systems.

          9. Example

          To calculate all the eigenvalues and eigenvectors of the real
          symmetric matrix:

                               ( 0.5  0.0  2.3 -2.6)
                               ( 0.0  0.5 -1.4 -0.7)
                               ( 2.3 -1.4  0.5  0.0).
                               (-2.6 -0.7  0.0  0.5)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02ADF
                  F02ADF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02ADF calculates all the eigenvalues of  Ax=(lambda)Bx,  where A
          is a real symmetric matrix and B is a real symmetric positive-
          definite matrix.

          2. Specification

                 SUBROUTINE F02ADF (A, IA, B, IB, N, R, DE, IFAIL)
                 INTEGER          IA, IB, N, IFAIL
                 DOUBLE PRECISION A(IA,N), B(IB,N), R(N), DE(N)

          3. Description

          The problem is reduced to the standard symmetric eigenproblem
          using Cholesky's method to decompose B into triangular matrices,
              T
          B=LL , where L is lower triangular. Then Ax=(lambda)Bx implies
            -1  -T   T             T
          (L  AL  )(L x)=(lambda)(L x); hence the eigenvalues of
          Ax=(lambda)Bx are those of Py=(lambda)y where P is the symmetric
                  -1  -T
          matrix L  AL  . Householder's method is used to tridiagonalise
          the matrix P and the eigenvalues are then found using the QL
          algorithm.

          4. References

          [1]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  A(IA,N) -- DOUBLE PRECISION array               Input/Output
               On entry: the upper triangle of the n by n symmetric matrix
               A. The elements of the array below the diagonal need not be
               set. On exit: the lower triangle of the array is
               overwritten. The rest of the array is unchanged.

           2:  IA -- INTEGER                                          Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which F02ADF is called.
               Constraint: IA >= N.

           3:  B(IB,N) -- DOUBLE PRECISION array               Input/Output
               On entry: the upper triangle of the n by n symmetric
               positive-definite matrix B. The elements of the array below
               the diagonal need not be set. On exit: the elements below
               the diagonal are overwritten. The rest of the array is
               unchanged.

           4:  IB -- INTEGER                                          Input
               On entry:
               the first dimension of the array B as declared in the
               (sub)program from which F02ADF is called.
               Constraint: IB >= N.

           5:  N -- INTEGER                                           Input
               On entry: n, the order of the matrices A and B.

           6:  R(N) -- DOUBLE PRECISION array                        Output
               On exit: the eigenvalues in ascending order.

           7:  DE(N) -- DOUBLE PRECISION array                    Workspace

           8:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               Failure in F01AEF(*); the matrix B is not positive-definite
               possibly due to rounding errors.

          IFAIL= 2
               Failure in F02AVF(*), more than 30*N iterations are required
               to isolate all the eigenvalues.

          7. Accuracy

          In general this routine is very accurate. However, if B is ill-
          conditioned with respect to inversion, the eigenvalues could be
          inaccurately determined. For a detailed error analysis see
          Wilkinson and Reinsch [1] pp 310, 222 and 235.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          9. Example

          To calculate all the eigenvalues of the general symmetric
          eigenproblem Ax=(lambda) Bx where A is the symmetric matrix:

                                (0.5  1.5  6.6   4.8)
                                (1.5  6.5 16.2   8.6)
                                (6.6 16.2 37.6   9.8)
                                (4.8  8.6  9.8 -17.1)

          and B is the symmetric positive-definite matrix:

                                    (1  3  4  1)
                                    (3 13 16 11)
                                    (4 16 24 18).
                                    (1 11 18 27)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02AEF
                  F02AEF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02AEF calculates all the eigenvalues and eigenvectors of
          Ax=(lambda)Bx,  where A is a real symmetric matrix and B is a
          real symmetric positive-definite matrix.

          2. Specification

                 SUBROUTINE F02AEF (A, IA, B, IB, N, R, V, IV, DL, E, IFAIL)
                 INTEGER          IA, IB, N, IV, IFAIL
                 DOUBLE PRECISION A(IA,N), B(IB,N), R(N), V(IV,N), DL(N), E
                1                 (N)

          3. Description

          The problem is reduced to the standard symmetric eigenproblem
          using Cholesky's method to decompose B into triangular matrices
              T
          B=LL , where L is lower triangular. Then Ax=(lambda)Bx implies
            -1  -T   T             T
          (L  AL  )(L x)=(lambda)(L x); hence the eigenvalues of
          Ax=(lambda)Bx are those of Py=(lambda)y, where P is the symmetric
                  -1  -T
          matrix L  AL  . Householder's method is used to tridiagonalise
          the matrix P and the eigenvalues are found using the QL
          algorithm. An eigenvector z of the derived problem is related to
                                                         T
          an eigenvector x of the original problem by z=L x. The
          eigenvectors z are determined using the QL algorithm and are
                              T
          normalised so that z z=1; the eigenvectors of the original
                                                  T
          problem are then determined by solving L x=z, and are normalised
                   T
          so that x Bx=1.

          4. References

          [1]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  A(IA,N) -- DOUBLE PRECISION array               Input/Output

               On entry: the upper triangle of the n by n symmetric matrix
               A. The elements of the array below the diagonal need not be
               set. On exit: the lower triangle of the array is
               overwritten. The rest of the array is unchanged. See also
               Section 8.

           2:  IA -- INTEGER                                          Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which F02AEF is called.
               Constraint: IA >= N.

           3:  B(IB,N) -- DOUBLE PRECISION array               Input/Output
               On entry: the upper triangle of the n by n symmetric
               positive-definite matrix B. The elements of the array below
               the diagonal need not be set. On exit: the elements below
               the diagonal are overwritten. The rest of the array is
               unchanged.

           4:  IB -- INTEGER                                          Input
               On entry:
               the first dimension of the array B as declared in the
               (sub)program from which F02AEF is called.
               Constraint: IB >= N.

           5:  N -- INTEGER                                           Input
               On entry: n, the order of the matrices A and B.

           6:  R(N) -- DOUBLE PRECISION array                        Output
               On exit: the eigenvalues in ascending order.

           7:  V(IV,N) -- DOUBLE PRECISION array                     Output
               On exit: the normalised eigenvectors, stored by columns;
               the ith column corresponds to the ith eigenvalue. The
                                                      T
               eigenvectors x are normalised so that x Bx=1. See also
               Section 8.

           8:  IV -- INTEGER                                          Input
               On entry:
               the first dimension of the array V as declared in the
               (sub)program from which F02AEF is called.
               Constraint: IV >= N.

           9:  DL(N) -- DOUBLE PRECISION array                    Workspace

          10:  E(N) -- DOUBLE PRECISION array                     Workspace

          11:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.
               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               Failure in F01AEF(*); the matrix B is not positive-definite,
               possibly due to rounding errors.

          IFAIL= 2
               Failure in F02AMF(*); more than 30*N iterations are required
               to isolate all the eigenvalues.

          7. Accuracy

          In general this routine is very accurate. However, if B is ill-
          conditioned with respect to inversion, the eigenvectors could be
          inaccurately determined. For a detailed error analysis see
          Wilkinson and Reinsch [1] pp 310, 222 and 235.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          Unless otherwise stated in the Users' Note for your
          implementation, the routine may be called with the same actual
          array supplied for parameters A and V, in which case the
          eigenvectors will overwrite the original matrix A. However this
          is not standard Fortran 77, and may not work on all systems.

          9. Example

          To calculate all the eigenvalues and eigenvectors of the general
          symmetric eigenproblem Ax=(lambda) Bx where A is the symmetric
          matrix:

                                (0.5  1.5  6.6   4.8)
                                (1.5  6.5 16.2   8.6)
                                (6.6 16.2 37.6   9.8)
                                (4.8  8.6  9.8 -17.1)

          and B is the symmetric positive-definite matrix:

                                    (1  3  4  1)
                                    (3 13 16 11)
                                    (4 16 24 18).
                                    (1 11 18 27)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02AFF
                  F02AFF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02AFF calculates all the eigenvalues of a real unsymmetric
          matrix.

          2. Specification

                 SUBROUTINE F02AFF (A, IA, N, RR, RI, INTGER, IFAIL)
                 INTEGER          IA, N, INTGER(N), IFAIL
                 DOUBLE PRECISION A(IA,N), RR(N), RI(N)

          3. Description

          The matrix A is first balanced and then reduced to upper
          Hessenberg form using stabilised elementary similarity
          transformations. The eigenvalues are then found using the QR
          algorithm for real Hessenberg matrices.

          4. References

          [1]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  A(IA,N) -- DOUBLE PRECISION array               Input/Output
               On entry: the n by n matrix A. On exit: the array is
               overwritten.

           2:  IA -- INTEGER                                          Input
               On entry:
               the dimension of the array A as declared in the (sub)program
               from which F02AFF is called.
               Constraint: IA >= N.

           3:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A.

           4:  RR(N) -- DOUBLE PRECISION array                       Output
               On exit: the real parts of the eigenvalues.

           5:  RI(N) -- DOUBLE PRECISION array                       Output
               On exit: the imaginary parts of the eigenvalues.

           6:  INTGER(N) -- INTEGER array                            Output
               On exit: INTGER(i) contains the number of iterations used
               to find the ith eigenvalue. If INTGER(i) is negative, the i
               th eigenvalue is the second of a pair found simultaneously.

               Note that the eigenvalues are found in reverse order,
               starting with the nth.

           7:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               More than 30*N iterations are required to isolate all the
               eigenvalues.

          7. Accuracy

          The accuracy of the results depends on the original matrix and
          the multiplicity of the roots. For a detailed error analysis see
          Wilkinson and Reinsch [1] pp 352 and 367.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          9. Example

          To calculate all the eigenvalues of the real matrix:

                               (  1.5 0.1  4.5 -1.5)
                               (-22.5 3.5 12.5 -2.5)
                               ( -2.5 0.3  4.5 -2.5).
                               ( -2.5 0.1  4.5  2.5)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02AGF
                  F02AGF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02AGF calculates all the eigenvalues and eigenvectors of a real
          unsymmetric matrix.

          2. Specification

                 SUBROUTINE F02AGF (A, IA, N, RR, RI, VR, IVR, VI, IVI,
                1                   INTGER, IFAIL)
                 INTEGER          IA, N, IVR, IVI, INTGER(N), IFAIL
                 DOUBLE PRECISION A(IA,N), RR(N), RI(N), VR(IVR,N), VI
                1                 (IVI,N)

          3. Description

          The matrix A is first balanced and then reduced to upper
          Hessenberg form using real stabilised elementary similarity
          transformations. The eigenvalues and eigenvectors of the
          Hessenberg matrix are calculated using the QR algorithm. The
          eigenvectors of the Hessenberg matrix are back-transformed to
          give the eigenvectors of the original matrix A.

          4. References

          [1]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  A(IA,N) -- DOUBLE PRECISION array               Input/Output
               On entry: the n by n matrix A. On exit: the array is
               overwritten.

           2:  IA -- INTEGER                                          Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which F02AGF is called.
               Constraint: IA >= N.

           3:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A.

           4:  RR(N) -- DOUBLE PRECISION array                       Output
               On exit: the real parts of the eigenvalues.

           5:  RI(N) -- DOUBLE PRECISION array                       Output
               On exit: the imaginary parts of the eigenvalues.

           6:  VR(IVR,N) -- DOUBLE PRECISION array                   Output
               On exit: the real parts of the eigenvectors, stored by
               columns. The ith column corresponds to the ith eigenvalue.
               The eigenvectors are normalised so that the sum of the
               squares of the moduli of the elements is equal to 1 and the
               element of largest modulus is real. This ensures that real
               eigenvalues have real eigenvectors.

           7:  IVR -- INTEGER                                         Input
               On entry:
               the first dimension of the array VR as declared in the
               (sub)program from which F02AGF is called.
               Constraint: IVR >= N.

           8:  VI(IVI,N) -- DOUBLE PRECISION array                   Output
               On exit: the imaginary parts of the eigenvectors, stored by
               columns. The ith column corresponds to the ith eigenvalue.

           9:  IVI -- INTEGER                                         Input
               On entry:
               the first dimension of the array VI as declared in the
               (sub)program from which F02AGF is called.
               Constraint: IVI >= N.

          10:  INTGER(N) -- INTEGER array                            Output
               On exit: INTGER(i) contains the number of iterations used
               to find the ith eigenvalue. If INTGER(i) is negative, the i
               th eigenvalue is the second of a pair found simultaneously.

               Note that the eigenvalues are found in reverse order,
               starting with the nth.

          11:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               More than 30*N iterations are required to isolate all the
               eigenvalues.

          7. Accuracy

          The accuracy of the results depends on the original matrix and
          the multiplicity of the roots. For a detailed error analysis see
          Wilkinson and Reinsch [1] pp 352 and 390.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          9. Example

          To calculate all the eigenvalues and eigenvectors of the real
          matrix:

                               (  1.5 0.1  4.5 -1.5)
                               (-22.5 3.5 12.5 -2.5)
                               ( -2.5 0.3  4.5 -2.5).
                               ( -2.5 0.1  4.5  2.5)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02AJF
                  F02AJF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02AJF calculates all the eigenvalues of a complex matrix.

          2. Specification

                 SUBROUTINE F02AJF (AR, IAR, AI, IAI, N, RR, RI, INTGER,
                1                   IFAIL)
                 INTEGER          IAR, IAI, N, INTGER(N), IFAIL
                 DOUBLE PRECISION AR(IAR,N), AI(IAI,N), RR(N), RI(N)

          3. Description

          The complex matrix A is first balanced and then reduced to upper
          Hessenberg form using stabilised elementary similarity
          transformations. The eigenvalues are then found using the
          modified LR algorithm for complex Hessenberg matrices.

          4. References

          [1]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  AR(IAR,N) -- DOUBLE PRECISION array             Input/Output
               On entry: the real parts of the elements of the n by n
               complex matrix A. On exit: the array is overwritten.

           2:  IAR -- INTEGER                                         Input
               On entry:
               the first dimension of the array AR as declared in the
               (sub)program from which F02AJF is called.
               Constraint: IAR >= N.

           3:  AI(IAI,N) -- DOUBLE PRECISION array             Input/Output
               On entry: the imaginary parts of the elements of the n by n
               complex matrix A. On exit: the array is overwritten.

           4:  IAI -- INTEGER                                         Input
               On entry:
               the first dimension of the array AI as declared in the
               (sub)program from which F02AJF is called.
               Constraint: IAI >= N.

           5:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A.

           6:  RR(N) -- DOUBLE PRECISION array                       Output
               On exit: the real parts of the eigenvalues.

           7:  RI(N) -- DOUBLE PRECISION array                       Output
               On exit: the imaginary parts of the eigenvalues.

           8:  INTGER(N) -- INTEGER array                         Workspace

           9:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               More than 30*N iterations are required to isolate all the
               eigenvalues.

          7. Accuracy

          The accuracy of the results depends on the original matrix and
          the multiplicity of the roots. For a detailed error analysis see
          Wilkinson and Reinsch [1] pp 352 and 401.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          9. Example

          To calculate all the eigenvalues of the complex matrix:

                     (-21.0-5.0i      24.60i 13.6+10.2i     4.0i)
                     (     22.5i 26.00-5.00i  7.5-10.0i 2.5     )
                     ( -2.0+1.5i  1.68+2.24i  4.5-5.0i  1.5+2.0i).
                     (     -2.5i -2.60       -2.7+3.6i  2.5-5.0i)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02AKF
                  F02AKF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02AKF calculates all the eigenvalues and eigenvectors of a
          complex matrix.

          2. Specification

                 SUBROUTINE F02AKF (AR, IAR, AI, IAI, N, RR, RI, VR, IVR,
                1                   VI, IVI, INTGER, IFAIL)
                 INTEGER          IAR, IAI, N, IVR, IVI, INTGER(N), IFAIL
                 DOUBLE PRECISION AR(IAR,N), AI(IAI,N), RR(N), RI(N), VR
                1                 (IVR,N), VI(IVI,N)

          3. Description

          The complex matrix A is first balanced and then reduced to upper
          Hessenberg form by stabilised elementary similarity
          transformations. The eigenvalues and eigenvectors of the
          Hessenberg matrix are calculated using the LR algorithm. The
          eigenvectors of the Hessenberg matrix are back-transformed to
          give the eigenvectors of the original matrix.

          4. References

          [1]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  AR(IAR,N) -- DOUBLE PRECISION array             Input/Output
               On entry: the real parts of the elements of the n by n
               complex matrix A. On exit: the array is overwritten.

           2:  IAR -- INTEGER                                         Input
               On entry:
               the first dimension of the array AR as declared in the
               (sub)program from which F02AKF is called.
               Constraint: IAR >= N.

           3:  AI(IAI,N) -- DOUBLE PRECISION array             Input/Output
               On entry: the imaginary parts of the elements of the n by n
               complex matrix A. On exit: the array is overwritten.

           4:  IAI -- INTEGER                                         Input
               On entry:
               the first dimension of the array AI as declared in the
               (sub)program from which F02AKF is called.
               Constraint: IAI >= N.

           5:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A.

           6:  RR(N) -- DOUBLE PRECISION array                       Output
               On exit: the real parts of the eigenvalues.

           7:  RI(N) -- DOUBLE PRECISION array                       Output
               On exit: the imaginary parts of the eigenvalues.

           8:  VR(IVR,N) -- DOUBLE PRECISION array                   Output
               On exit: the real parts of the eigenvectors, stored by
               columns. The ith column corresponds to the ith eigenvalue.
               The eigenvectors are normalised so that the sum of squares
               of the moduli of the elements is equal to 1 and the element
               of largest modulus is real.

           9:  IVR -- INTEGER                                         Input
               On entry:
               the first dimension of the array VR as declared in the
               (sub)program from which F02AKF is called.
               Constraint: IVR >= N.

          10:  VI(IVI,N) -- DOUBLE PRECISION array                   Output
               On exit: the imaginary parts of the eigenvectors, stored by
               columns. The ith column corresponds to the ith eigenvalue.

          11:  IVI -- INTEGER                                         Input
               On entry:
               the first dimension of the array VI as declared in the
               (sub)program from which F02AKF is called.
               Constraint: IVI >= N.

          12:  INTGER(N) -- INTEGER array                         Workspace

          13:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               More than 30*N iterations are required to isolate all the
               eigenvalues.

          7. Accuracy

          The accuracy of the results depends on the conditioning of the
          original matrix and the multiplicity of the roots. For a detailed
          error analysis see Wilkinson and Reinsch [1] pp 352 and 390.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          9. Example

          To calculate all the eigenvalues and eigenvectors of the complex
          matrix:

                     (-21.0-5.0i      24.60i 13.6+10.2i     4.0i)
                     (     22.5i 26.00-5.00i  7.5-10.0i 2.5     )
                     ( -2.0+1.5i  1.68+2.24i  4.5-5.0i  1.5+2.0i).
                     (     -2.5i -2.60       -2.7+3.6i  2.5-5.0i)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02AWF
                  F02AWF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02AWF calculates all the eigenvalues of a complex Hermitian
          matrix.

          2. Specification

                 SUBROUTINE F02AWF (AR, IAR, AI, IAI, N, R, WK1, WK2, WK3,
                1                   IFAIL)
                 INTEGER          IAR, IAI, N, IFAIL
                 DOUBLE PRECISION AR(IAR,N), AI(IAI,N), R(N), WK1(N),
                1                 WK2(N), WK3(N)

          3. Description

          The complex Hermitian matrix A is first reduced to a real
          tridiagonal matrix by n-2 unitary transformations, and a
          subsequent diagonal transformation. The eigenvalues are then
          derived using the QL algorithm, an adaptation of the QR
          algorithm.

          4. References

          [1]   Peters G (1967) NPL Algorithms Library. Document No.
                F1/04/A.

          [2]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  AR(IAR,N) -- DOUBLE PRECISION array             Input/Output
               On entry: the real parts of the elements of the lower
               triangle of the n by n complex Hermitian matrix A. Elements
               of the array above the diagonal need not be set. On exit:
               the array is overwritten.

           2:  IAR -- INTEGER                                         Input
               On entry:
               the first dimension of the array AR as declared in the
               (sub)program from which F02AWF is called.
               Constraint: IAR >= N.

           3:  AI(IAI,N) -- DOUBLE PRECISION array             Input/Output
               On entry: the imaginary parts of the elements of the lower
               triangle of the n by n complex Hermitian matrix A. Elements
               of the array above the diagonal need not be set. On exit:
               the array is overwritten.

           4:  IAI -- INTEGER                                         Input
               On entry:
               the first dimension of the array AI as declared in the
               (sub)program from which F02AWF is called.
               Constraint: IAI >= N.

           5:  N -- INTEGER                                           Input
               On entry: n, the order of the complex Hermitian matrix, A.

           6:  R(N) -- DOUBLE PRECISION array                        Output
               On exit: the eigenvalues in ascending order.

           7:  WK1(N) -- DOUBLE PRECISION array                   Workspace

           8:  WK2(N) -- DOUBLE PRECISION array                   Workspace

           9:  WK3(N) -- DOUBLE PRECISION array                   Workspace

          10:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               More than 30*N iterations are required to isolate all the
               eigenvalues.

          7. Accuracy

          For a detailed error analysis see Peters [1] page 3 and Wilkinson
          and Reinsch [2] page 235.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          9. Example

          To calculate all the eigenvalues of the complex Hermitian matrix:

                      (0.50        0.00       1.84+1.38i  2.08-1.56i)
                      (0.00        0.50       1.12+0.84i -0.56+0.42i)
                      (1.84-1.38i  1.12-0.84i 0.50        0.00      ).
                      (2.08+1.56i -0.56-0.42i 0.00        0.50      )

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02AXF
                  F02AXF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02AXF calculates all the eigenvalues and eigenvectors of a
          complex Hermitian matrix.

          2. Specification

                 SUBROUTINE F02AXF (AR, IAR, AI, IAI, N, R, VR, IVR, VI,
                1                   IVI, WK1, WK2, WK3, IFAIL)
                 INTEGER          IAR, IAI, N, IVR, IVI, IFAIL
                 DOUBLE PRECISION AR(IAR,N), AI(IAI,N), R(N), VR(IVR,N), VI
                1                 (IVI,N), WK1(N), WK2(N), WK3(N)

          3. Description

          The complex Hermitian matrix is first reduced to a real
          tridiagonal matrix by n-2 unitary transformations and a
          subsequent diagonal transformation. The eigenvalues and
          eigenvectors are then derived using the QL algorithm, an
          adaptation of the QR algorithm.

          4. References

          [1]   Peters G (1967) NPL Algorithms Library. Document No.
                F2/03/A.

          [2]   Peters G (1967) NPL Algorithms Library. Document No.
                F1/04/A.

          5. Parameters

           1:  AR(IAR,N) -- DOUBLE PRECISION array                    Input
               On entry: the real parts of the elements of the lower
               triangle of the n by n complex Hermitian matrix A. Elements
               of the array above the diagonal need not be set. See also
               Section 8.

           2:  IAR -- INTEGER                                         Input
               On entry:
               the first dimension of the array AR as declared in the
               (sub)program from which F02AXF is called.
               Constraint: IAR >= N.

           3:  AI(IAI,N) -- DOUBLE PRECISION array                    Input
               On entry: the imaginary parts of the elements of the lower
               triangle of the n by n complex Hermitian matrix A. Elements
               of the array above the diagonal need not be set. See also
               Section 8.

           4:  IAI -- INTEGER                                         Input
               On entry:
               the first dimension of the array AI as declared in the
               (sub)program from which F02AXF is called.
               Constraint: IAI >= N.

           5:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix, A.

           6:  R(N) -- DOUBLE PRECISION array                        Output
               On exit: the eigenvalues in ascending order.

           7:  VR(IVR,N) -- DOUBLE PRECISION array                   Output
               On exit: the real parts of the eigenvectors, stored by
               columns. The ith column corresponds to the ith eigenvector.
               The eigenvectors are normalised so that the sum of the
               squares of the moduli of the elements is equal to 1 and the
               element of largest modulus is real. See also Section 8.

           8:  IVR -- INTEGER                                         Input
               On entry:
               the first dimension of the array VR as declared in the
               (sub)program from which F02AXF is called.
               Constraint: IVR >= N.

           9:  VI(IVI,N) -- DOUBLE PRECISION array                   Output
               On exit: the imaginary parts of the eigenvectors, stored by
               columns. The ith column corresponds to the ith eigenvector.
               See also Section 8.

          10:  IVI -- INTEGER                                         Input
               On entry:
               the first dimension of the array VI as declared in the
               (sub)program from which F02AXF is called.
               Constraint: IVI >= N.

          11:  WK1(N) -- DOUBLE PRECISION array                   Workspace

          12:  WK2(N) -- DOUBLE PRECISION array                   Workspace

          13:  WK3(N) -- DOUBLE PRECISION array                   Workspace

          14:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               More than 30*N iterations are required to isolate all the
               eigenvalues.

          IFAIL= 2
               The diagonal elements of AI are not all zero, i.e., the
               complex matrix is not Hermitian.

          7. Accuracy

          The eigenvectors are always accurately orthogonal but the
          accuracy of the individual eigenvalues and eigenvectors is
          dependent on their inherent sensitivity to small changes in the
          original matrix. For a detailed error analysis see Peters [1]
          page 3 and [2] page 3.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          Unless otherwise stated in the implementation document, the
          routine may be called with the same actual array supplied for
          parameters AR and VR, and for AI and VI, in which case the
          eigenvectors will overwrite the original matrix A. However this
          is not standard Fortran 77, and may not work on all systems.

          9. Example

          To calculate the eigenvalues and eigenvectors of the complex
          Hermitian matrix:

                      (0.50        0.00       1.84+1.38i  2.08-1.56i)
                      (0.00        0.50       1.12+0.84i -0.56+0.42i)
                      (1.84-1.38i  1.12-0.84i 0.50        0.00      ).
                      (2.08+1.56i -0.56-0.42i 0.00        0.50      )

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02BBF
                  F02BBF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02BBF calculates selected eigenvalues and eigenvectors of a real
          symmetric matrix by reduction to tridiagonal form, bisection and
          inverse iteration, where the selected eigenvalues lie within a
          given interval.

          2. Specification

                 SUBROUTINE F02BBF (A, IA, N, ALB, UB, M, MM, R, V, IV, D,
                1                   E, E2, X, G, C, ICOUNT, IFAIL)
                 INTEGER          IA, N, M, MM, IV, ICOUNT(M), IFAIL
                 DOUBLE PRECISION A(IA,N), ALB, UB, R(M), V(IV,M), D(N), E
                1                 (N), E2(N), X(N,7), G(N)
                 LOGICAL          C(N)

          3. Description

          The real symmetric matrix A is reduced to a symmetric tridiagonal
          matrix T by Householder's method. The eigenvalues which lie
          within a given interval [l,u], are calculated by the method of
          bisection. The corresponding eigenvectors of T are calculated by
          inverse iteration. A back-transformation is then performed to
          obtain the eigenvectors of the original matrix A.

          4. References

          [1]   Wilkinson J H and Reinsch C (1971) Handbook for Automatic
                Computation II, Linear Algebra. Springer-Verlag.

          5. Parameters

           1:  A(IA,N) -- DOUBLE PRECISION array               Input/Output
               On entry: the lower triangle of the n by n symmetric matrix
               A. The elements of the array above the diagonal need not be
               set. On exit: the elements of A below the diagonal are
               overwritten, and the rest of the array is unchanged.

           2:  IA -- INTEGER                                          Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which F02BBF is called.
               Constraint: IA >= N.

           3:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A.

           4:  ALB -- DOUBLE PRECISION                                Input

           5:  UB -- DOUBLE PRECISION                                 Input
               On entry: l and u, the lower and upper end-points of the
               interval within which eigenvalues are to be calculated.

           6:  M -- INTEGER                                           Input
               On entry: an upper bound for the number of eigenvalues
               within the interval.

           7:  MM -- INTEGER                                         Output
               On exit: the actual number of eigenvalues within the
               interval.

           8:  R(M) -- DOUBLE PRECISION array                        Output
               On exit: the eigenvalues, not necessarily in ascending
               order.

           9:  V(IV,M) -- DOUBLE PRECISION array                     Output
               On exit: the eigenvectors, stored by columns. The ith
               column corresponds to the ith eigenvalue. The eigenvectors
               are normalised so that the sum of the squares of the
               elements are equal to 1.

          10:  IV -- INTEGER                                          Input
               On entry:
               the first dimension of the array V as declared in the
               (sub)program from which F02BBF is called.
               Constraint: IV >= N.

          11:  D(N) -- DOUBLE PRECISION array                     Workspace

          12:  E(N) -- DOUBLE PRECISION array                     Workspace

          13:  E2(N) -- DOUBLE PRECISION array                    Workspace

          14:  X(N,7) -- DOUBLE PRECISION array                   Workspace

          15:  G(N) -- DOUBLE PRECISION array                     Workspace

          16:  C(N) -- LOGICAL array                              Workspace

          17:  ICOUNT(M) -- INTEGER array                            Output
               On exit: ICOUNT(i) contains the number of iterations for
               the ith eigenvalue.

          18:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               M is less than the number of eigenvalues in the given
               interval. On exit MM contains the number of eigenvalues in
               the interval. Rerun with this value for M.

          IFAIL= 2
               More than 5 iterations are required to determine any one
               eigenvector.

          7. Accuracy

          There is no guarantee of the accuracy of the eigenvectors as the
          results depend on the original matrix and the multiplicity of the
          roots. For a detailed error analysis see Wilkinson and Reinsch
          [1] pp 222 and 436.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n

          This subroutine should only be used when less than 25% of the
          eigenvalues and the corresponding eigenvectors are required. Also
          this subroutine is less efficient with matrices which have
          multiple eigenvalues.

          9. Example

          To calculate the eigenvalues lying between -2.0 and 3.0, and the
          corresponding eigenvectors of the real symmetric matrix:

                               ( 0.5  0.0  2.3 -2.6)
                               ( 0.0  0.5 -1.4 -0.7)
                               ( 2.3 -1.4  0.5  0.0).
                               (-2.6 -0.7  0.0  0.5)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02BJF
                  F02BJF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02BJF calculates all the eigenvalues and, if required, all the
          eigenvectors of the generalized eigenproblem  Ax=(lambda)Bx
          where A and B are real, square matrices, using the QZ algorithm.

          2. Specification

                 SUBROUTINE F02BJF (N, A, IA, B, IB, EPS1, ALFR, ALFI,
                1                   BETA, MATV, V, IV, ITER, IFAIL)
                 INTEGER          N, IA, IB, IV, ITER(N), IFAIL
                 DOUBLE PRECISION A(IA,N), B(IB,N), EPS1, ALFR(N), ALFI(N),
                1                 BETA(N), V(IV,N)
                 LOGICAL          MATV

          3. Description

          All the eigenvalues and, if required, all the eigenvectors of the
          generalized eigenproblem Ax=(lambda)Bx where A and B are real,
          square matrices, are determined using the QZ algorithm. The QZ
          algorithm consists of 4 stages:

          (a)   A is reduced to upper Hessenberg form and at the same time
                B is reduced to upper triangular form.

          (b)   A is further reduced to quasi-triangular form while the
                triangular form of B is maintained.

          (c)   The quasi-triangular form of A is reduced to triangular
                form and the eigenvalues extracted. This routine does not
                actually produce the eigenvalues (lambda) , but instead
                                                         j
                returns (alpha)  and (beta)  such that

                               j           j
                        (lambda) =(alpha) /(beta) ,   j=1,2,...,.n
                                j        j       j
                The division by (beta)  becomes the responsibility of the
                                      j
                user's program, since (beta)  may be zero indicating an
                                            j
                infinite eigenvalue. Pairs of complex eigenvalues occur
                with (alpha) /(beta)  and (alpha)   /(beta)    complex
                            j       j            j+1       j+1

                conjugates, even though (alpha)  and (alpha)    are not
                                               j            j+1
                conjugate.

          (d)   If the eigenvectors are required (MATV = .TRUE.), they are
                obtained from the triangular matrices and then transformed
                back into the original co-ordinate system.

          4. References

          [1]   Moler C B and Stewart G W (1973) An Algorithm for
                Generalized Matrix Eigenproblems. SIAM J. Numer. Anal. 10
                241--256.

          [2]   Ward R C (1975) The Combination Shift QZ Algorithm. SIAM J.
                Numer. Anal. 12 835--853.

          [3]   Wilkinson J H (1979) Kronecker's Canonical Form and the QZ
                Algorithm. Linear Algebra and Appl. 28 285--303.

          5. Parameters

           1:  N -- INTEGER                                           Input
               On entry: n, the order of the matrices A and B.

           2:  A(IA,N) -- DOUBLE PRECISION array               Input/Output
               On entry: the n by n matrix A. On exit: the array is
               overwritten.

           3:  IA -- INTEGER                                          Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which F02BJF is called.
               Constraint: IA >= N.

           4:  B(IB,N) -- DOUBLE PRECISION array               Input/Output
               On entry: the n by n matrix B. On exit: the array is
               overwritten.

           5:  IB -- INTEGER                                          Input
               On entry:
               the first dimension of the array B as declared in the
               (sub)program from which F02BJF is called.
               Constraint: IB >= N.

           6:  EPS1 -- DOUBLE PRECISION                               Input
               On entry: the tolerance used to determine negligible
               elements. If EPS1 > 0.0, an element will be considered
               negligible if it is less than EPS1 times the norm of its
               matrix. If EPS1 <= 0.0, machine precision is used in place
               of EPS1. A positive value of EPS1 may result in faster
               execution but less accurate results.

           7:  ALFR(N) -- DOUBLE PRECISION array                     Output

           8:  ALFI(N) -- DOUBLE PRECISION array                     Output
               On exit: the real and imaginary parts of (alpha) , for
                                                               j
               j=1,2,...,n.

           9:  BETA(N) -- DOUBLE PRECISION array                     Output
               On exit: (beta) , for j=1,2,...,n.
                               j

          10:  MATV -- LOGICAL                                        Input
               On entry: MATV must be set .TRUE. if the eigenvectors are
               required, otherwise .FALSE..

          11:  V(IV,N) -- DOUBLE PRECISION array                     Output
               On exit: if MATV = .TRUE., then
                    (i)if the jth eigenvalue is real, the jth column of V
                    contains its eigenvector;

                    (ii) if the jth and (j+1)th eigenvalues form a complex
                    pair, the jth and (j+1)th columns of V contain the
                    real and imaginary parts of the eigenvector associated
                    with the first eigenvalue of the pair. The conjugate
                    of this vector is the eigenvector for the conjugate
                    eigenvalue.
               Each eigenvector is normalised so that the component of
               largest modulus is real and the sum of squares of the moduli
               equal one.

               If MATV = .FALSE., V is not used.

          12:  IV -- INTEGER                                          Input
               On entry:
               the first dimension of the array V as declared in the
               (sub)program from which F02BJF is called.
               Constraint: IV >= N.

          13:  ITER(N) -- INTEGER array                              Output
               On exit: ITER(j) contains the number of iterations needed
               to obtain the jth eigenvalue. Note that the eigenvalues are
               obtained in reverse order, starting with the nth.

          14:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= i
               More than 30*N iterations are required to determine all the
               diagonal 1 by 1 or 2 by 2 blocks of the quasi-triangular
               form in the second step of the QZ algorithm. IFAIL is set to
               the index i of the eigenvalue at which this failure occurs.
               If the soft failure option is used, (alpha)  and (beta)  are
                                                          j           j
               correct for j=i+1,i+2,...,n, but V does not contain any
               correct eigenvectors.

          7. Accuracy

          The computed eigenvalues are always exact for a problem
          (A+E)x=(lambda)(B+F)x where ||E||/||A|| and ||F||/||B||
          are both of the order of max(EPS1,(epsilon)), EPS1 being defined
          as in Section 5 and (epsilon) being the machine precision.

          Note: interpretation of results obtained with the QZ algorithm
          often requires a clear understanding of the effects of small
          changes in the original data. These effects are reviewed in
          Wilkinson [3], in relation to the significance of small values of
          (alpha)  and (beta) . It should be noted that if (alpha)  and
                 j           j                                    j
          (beta)  are both small for any j, it may be that no reliance can
                j
          be placed on any of the computed eigenvalues
          (lambda) =(alpha) /(beta) . The user is recommended to study [3]
                  i        i       i
          and, if in difficulty, to seek expert advice on determining the
          sensitivity of the eigenvalues to perturbations in the data.

          8. Further Comments

                                                                          3
          The time taken by the routine is approximately proportional to n
          and also depends on the value chosen for parameter EPS1.

          9. Example

          To find all the eigenvalues and eigenvectors of Ax=(lambda) Bx
          where

                                 (3.9 12.5 -34.5 -0.5)
                                 (4.3 21.5 -47.5  7.5)
                               A=(4.3 21.5 -43.5  3.5)
                                 (4.4 26.0 -46.0  6.0)

          and

                                      (1 2 -3 1)
                                      (1 3 -5 4)
                                    B=(1 3 -4 3).
                                      (1 3 -4 4)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02FJF
                  F02FJF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          To find eigenvalues and eigenvectors of a real sparse symmetric
          or generalized symmetric eigenvalue problem.

          2. Specification

                 SUBROUTINE F02FJF (N, M, K, NOITS, TOL, DOT, IMAGE, MONIT,
                1                   NOVECS, X, NRX, D, WORK, LWORK, RWORK,
                2                   LRWORK, IWORK, LIWORK, IFAIL)
                 INTEGER          N, M, K, NOITS, NOVECS, NRX, LWORK,
                1                 LRWORK, IWORK(LIWORK), LIWORK, IFAIL
                 DOUBLE PRECISION TOL, DOT, X(NRX,K), D(K), WORK(LWORK),
                1                 RWORK(LRWORK)
                 EXTERNAL         DOT, IMAGE, MONIT

          3. Description

          F02FJF finds the m eigenvalues of largest absolute value and the
          corresponding eigenvectors for the real eigenvalue problem

                                  Cx=(lambda)x                          (1)

          where C is an n by n matrix such that

                                         T
                                     BC=C B                             (2)

          for a given positive-definite matrix B. C is said to be B-
          symmetric. Different specifications of C allow for the solution
          of a variety of eigenvalue problems. For example, when

                                                     T
                              C=A and B=I where   A=A

          the routine finds the m eigenvalues of largest absolute magnitude
          for the standard symmetric eigenvalue problem

                                 Ax=(lambda)x.                          (3)

          The routine is intended for the case where A is sparse.

          As a second example, when

                                          -1
                                       C=B  A

          where

                                           T
                                        A=A

          the routine finds the m eigenvalues of largest absolute magnitude
          for the generalized symmetric eigenvalue problem

                                 Ax=(lambda)Bx.                         (4)

          The routine is intended for the case where A and B are sparse.

          The routine does not require C explicitly, but C is specified via
          a user-supplied routine IMAGE which, given an n element vector z,
          computes the image w given by

                                        w=Cz.

                                                       -1
          For instance, in the above example, where C=B  A, routine IMAGE
          will need to solve the positive-definite system of equations
          Bw=Az for w.

          To find the m eigenvalues of smallest absolute magnitude of (3)
                           -1
          we can choose C=A   and hence find the reciprocals of the
          required eigenvalues, so that IMAGE will need to solve Aw=z for
                                                         -1
          w, and correspondingly for (4) we can choose C=A  B and solve
          Aw=Bz for w.

          A table of examples of choice of IMAGE is given in Table 3.1. It
          should be remembered that the routine also returns the
          corresponding eigenvectors and that B is positive-definite.
          Throughout A is assumed to be symmetric and, where necessary,
          non-singularity is also assumed.

          Eigenvalues             Problem
          Required

                      Ax=(lambda)x     (B=I)Ax=(lambda)Bx ABx=(lambda)x

          Largest     Compute          Solve              Compute
                      w=Az             Bw=Az              w=ABz

          Smallest    Solve            Solve              Solve
          (Find       Aw=z             Aw=Bz              Av=z,  Bw=(nu)
          1/(lambda))

          Furthest    Compute          Solve              Compute
          from        w=(A-(sigma)I)z  Bw=(A-(sigma)B)z   w=(AB-(sigma)I)z
          (sigma)
          (Find
          (lambda)-
          (sigma))

          Closest to Solve             Solve              Solve
          (sigma)    (A-(sigma)I)w=z   (A-(sigma)B)w=Bz   (AB-(sigma)I)w=z
          (Find 1/((
          lambda)-
          (sigma)))


                                     Table 3.1
                   The Requirement of IMAGE for Various Problems

          The matrix B also need not be supplied explicitly, but is
          specified via a user-supplied routine DOT which, given n element
                                                                 T
          vectors z and w, computes the generalized dot product w Bz.

          F02FJF is based upon routine SIMITZ (see Nikolai [1]), which is
          itself a derivative of the Algol procedure ritzit (see
          Rutishauser [4]), and uses the method of simultaneous (subspace)
          iteration. (See Parlett [2] for description, analysis and advice
          on the use of the method.)

          The routine performs simultaneous iteration on k>m vectors.
          Initial estimates to p<=k eigenvectors, corresponding to the p
          eigenvalues of C of largest absolute value, may be supplied by
          the user to F02FJF. When possible k should be chosen so that the
          kth eigenvalue is not too close to the m required eigenvalues,
          but if k is initially chosen too small then F02FJF may be re-
          entered, supplying approximations to the k eigenvectors found so
          far and with k then increased.

          At each major iteration F02FJF solves an r by r (r<=k) eigenvalue
          sub-problem in order to obtain an approximation to the
          eigenvalues for which convergence has not yet occurred. This
          approximation is refined by Chebyshev acceleration.

          4. References

          [1]   Nikolai P J (1979) Algorithm 538: Eigenvectors and
                eigenvalues of real generalized symmetric matrices by
                simultaneous iteration. ACM Trans. Math. Softw. 5 118--125.

          [2]   Parlett B N (1980) The Symmetric Eigenvalue Problem.
                Prentice-Hall.

          [3]   Rutishauser H (1969) Computational aspects of F L Bauer's
                simultaneous iteration method. Num. Math. 13 4--13.

          [4]   Rutishauser H (1970) Simultaneous iteration method for
                symmetric matrices. Num. Math. 16 205--223.

          5. Parameters

           1:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix C. Constraint: N >= 1.

           2:  M -- INTEGER                                    Input/Output
               On entry: m, the number of eigenvalues required.
                                            '
               Constraint: M >= 1. On exit: m, the number of eigenvalues
               actually found. It is equal to m if IFAIL = 0 on exit, and
               is less than m if IFAIL = 2, 3 or 4. See Section 6 and
               Section 8 for further information.

           3:  K -- INTEGER                                           Input
               On entry: the number of simultaneous iteration vectors to be
               used. Too small a value of K may inhibit convergence, while
               a larger value of K incurs additional storage and additional
               work per iteration. Suggested value: K = M + 4 will often be
               a reasonable choice in the absence of better information.
               Constraint: M < K <= N.

           4:  NOITS -- INTEGER                                Input/Output
               On entry: the maximum number of major iterations (eigenvalue
               sub-problems) to be performed. If NOITS <= 0, then the value
               100 is used in place of NOITS. On exit: the number of
               iterations actually performed.

           5:  TOL -- DOUBLE PRECISION                                Input
               On entry: a relative tolerance to be used in accepting
               eigenvalues and eigenvectors. If the eigenvalues are
               required to about t significant figures, then TOL should be
                              -t
               set to about 10  . d  is accepted as an eigenvalue as soon
                                   i
               as two successive approximations to d  differ by less than
                                                    i
                 ~                   ~
               (|d |*TOL)/10,  where d  is the latest aproximation to d .
                  i                   i                                i
               Once an eigenvalue has been accepted, then an eigenvector is
               accepted as soon as  (d f )/(d -d )<TOL, where f  is the
                                      i i    i  k              i
               normalised residual of the current approximation to the
               eigenvector (see Section 8 for further information). The
               values of the f  and d  can be printed from routine MONIT.
                              i      i
               If TOL is supplied outside the range ((epsilon), 1.0), where
               (epsilon) is the machine precision, then the value (epsilon)
               is used in place of TOL.

           6:  DOT -- DOUBLE PRECISION FUNCTION, supplied by the user.
                                                         External Procedure
                                          T
               DOT must return the value w Bz for given vectors w and z.
               For the standard eigenvalue problem, where B=I, DOT must
                                       T
               return the dot product w z.

               Its specification is:

                      DOUBLE PRECISION FUNCTION DOT (IFLAG, N, Z, W,
                     1                               RWORK, LRWORK,
                     2                               IWORK, LIWORK)
                      INTEGER          IFLAG, N, LRWORK, IWORK(LIWORK),
                     1                 LIWORK
                      DOUBLE PRECISION Z(N), W(N), RWORK(LRWORK)

                1:  IFLAG -- INTEGER                           Input/Output
                    On entry: IFLAG is always non-negative. On exit: IFLAG
                    may be used as a flag to indicate a failure in the
                                    T
                    computation of w Bz. If IFLAG is negative on exit from
                    DOT, then F02FJF will exit immediately with IFAIL set
                    to IFLAG. Note that in this case DOT must still be
                    assigned a value.

                2:  N -- INTEGER                                      Input
                    On entry: the number of elements in the vectors z and w
                    and the order of the matrix B.

                3:  Z(N) -- DOUBLE PRECISION array                    Input
                                                      T
                    On entry: the vector z for which w Bz is required.

                4:  W(N) -- DOUBLE PRECISION array                    Input
                                                      T
                    On entry: the vector w for which w Bz is required.

                5:  RWORK(LRWORK) -- DOUBLE PRECISION array  User Workspace


                6:  LRWORK -- INTEGER                                 Input


                7:  IWORK(LIWORK) -- INTEGER array           User Workspace


                8:  LIWORK -- INTEGER                                 Input
                    DOT is called from F02FJF with the parameters RWORK,
                    LRWORK, IWORK and LIWORK as supplied to F02FJF. The
                    user is free to use the arrays RWORK and IWORK to
                    supply information to DOT and to IMAGE as an
                    alternative to using COMMON.
               DOT must be declared as EXTERNAL in the (sub)program
               from which F02FJF is called. Parameters denoted as
               Input must not be changed by this procedure.

           7:  IMAGE -- SUBROUTINE, supplied by the user.
                                                         External Procedure
               IMAGE must return the vector w=Cz for a given vector z.

               Its specification is:

                      SUBROUTINE IMAGE (IFLAG, N, Z, W, RWORK, LRWORK,
                     1                  IWORK, LIWORK)
                      INTEGER          IFLAG, N, LRWORK, IWORK(LIWORK),
                     1                 LIWORK
                      DOUBLE PRECISION Z(N), W(N), RWORK(LRWORK)

                1:  IFLAG -- INTEGER                           Input/Output
                    On entry: IFLAG is always non-negative. On exit: IFLAG
                    may be used as a flag to indicate a failure in the
                    computation of w. If IFLAG is negative on exit from
                    IMAGE, then F02FJF will exit immediately with IFAIL set
                    to IFLAG.

                2:  N -- INTEGER                                      Input
                    On entry: n, the number of elements in the vectors w
                    and z, and the order of the matrix C.

                3:  Z(N) -- DOUBLE PRECISION array                    Input
                    On entry: the vector z for which Cz is required.

                4:  W(N) -- DOUBLE PRECISION array                   Output
                    On exit: the vector w=Cz.

                5:  RWORK(LRWORK) -- DOUBLE PRECISION array  User Workspace

                6:  LRWORK -- INTEGER                                 Input

                7:  IWORK(LIWORK) -- INTEGER array           User Workspace

                8:  LIWORK -- INTEGER                                 Input
                    IMAGE is called from F02FJF with the parameters RWORK,
                    LRWORK, IWORK and LIWORK as supplied to F02FJF. The
                    user is free to use the arrays RWORK and IWORK to
                    supply information to IMAGE and DOT as an alternative
                    to using COMMON.
               IMAGE must be declared as EXTERNAL in the (sub)program
               from which F02FJF is called. Parameters denoted as
               Input must not be changed by this procedure.

           8:  MONIT -- SUBROUTINE, supplied by the user.
                                                         External Procedure
               MONIT is used to monitor the progress of F02FJF. MONIT may
               be the dummy subroutine F02FJZ if no monitoring is actually
               required. (F02FJZ is included in the NAG Foundation Library
               and so need not be supplied by the user. The routine name
               F02FJZ may be implementation dependent: see the Users' Note
               for your implementation for details.) MONIT is called after
               the solution of each eigenvalue sub-problem and also just
               prior to return from F02FJF. The parameters ISTATE and
               NEXTIT allow selective printing by MONIT.

               Its specification is:

                      SUBROUTINE MONIT (ISTATE, NEXTIT, NEVALS,
                     1                  NEVECS, K, F, D)
                      INTEGER          ISTATE, NEXTIT, NEVALS, NEVECS,
                     1                 K
                      DOUBLE PRECISION F(K), D(K)

                1:  ISTATE -- INTEGER                                 Input
                    On entry: ISTATE specifies the state of F02FJF and will
                    have values as follows:
                    ISTATE = 0
                          No eigenvalue or eigenvector has just been
                          accepted.

                    ISTATE = 1
                          One or more eigenvalues have been accepted since
                          the last call to MONIT.

                    ISTATE = 2
                          One or more eigenvectors have been accepted since
                          the last call to MONIT.

                    ISTATE = 3
                          One or more eigenvalues and eigenvectors have
                          been accepted since the last call to MONIT.

                    ISTATE = 4
                          Return from F02FJF is about to occur.

                2:  NEXTIT -- INTEGER                                 Input
                    On entry: the number of the next iteration.

                3:  NEVALS -- INTEGER                                 Input
                    On entry: the number of eigenvalues accepted so far.

                4:  NEVECS -- INTEGER                                 Input
                    On entry: the number of eigenvectors accepted so far.

                5:  K -- INTEGER                                      Input
                    On entry: k, the number of simultaneous iteration
                    vectors.

                6:  F(K) -- DOUBLE PRECISION array                    Input
                    On entry: a vector of error quantities measuring the
                    state of convergence of the simultaneous iteration
                    vectors. See the parameter TOL of F02FJF above and
                    Section 8 for further details. Each element of F is
                    initially set to the value 4.0 and an element remains
                    at 4.0 until the corresponding vector is tested.

                7:  D(K) -- DOUBLE PRECISION array                    Input
                    On entry: D(i) contains the latest approximation to the
                    absolute value of the ith eigenvalue of C.
               MONIT must be declared as EXTERNAL in the (sub)program
               from which F02FJF is called. Parameters denoted as
               Input must not be changed by this procedure.

           9:  NOVECS -- INTEGER                                      Input
               On entry: the number of approximate vectors that are being
               supplied in X. If NOVECS is outside the range (0,K), then
               the value 0 is used in place of NOVECS.

          10:  X(NRX,K) -- DOUBLE PRECISION array              Input/Output
               On entry: if 0 < NOVECS <= K, the first NOVECS columns of X
               must contain approximations to the eigenvectors
               corresponding to the NOVECS eigenvalues of largest absolute
               value of C. Supplying approximate eigenvectors can be useful
               when reasonable approximations are known, or when the
               routine is being restarted with a larger value of K.
               Otherwise it is not necessary to supply approximate vectors,
               as simultaneous iteration vectors will be generated randomly
               by the routine. On exit: if IFAIL = 0, 2, 3 or 4, the first
               m' columns contain the eigenvectors corresponding to the
               eigenvalues returned in the first m' elements of D (see
               below); and the next k-m'-1 columns contain approximations
               to the eigenvectors corresponding to the approximate
               eigenvalues returned in the next k-m'-1 elements of D. Here
               m' is the value returned in M (see above), the number of
               eigenvalues actually found. The kth column is used as
               workspace.

          11:  NRX -- INTEGER                                         Input
               On entry:
               the first dimension of the array X as declared in the
               (sub)program from which F02FJF is called.
               Constraint: NRX >= N.

          12:  D(K) -- DOUBLE PRECISION array                        Output
               On exit: if IFAIL = 0, 2, 3 or 4, the first m' elements
               contain the first m' eigenvalues in decreasing order of
               magnitude; and the next k-m'-1 elements contain
               approximations to the next k-m'-1 eigenvalues. Here m' is
               the value returned in M (see above), the number of
               eigenvalues actually found. D(k) contains the value e where
               (-e,e) is the latest interval over which Chebyshev
               acceleration is performed.

          13:  WORK(LWORK) -- DOUBLE PRECISION array              Workspace

          14:  LWORK -- INTEGER                                       Input
               On entry: the length of the array WORK, as declared in the
               (sub)program from which F02FJF is called. Constraint:
               LWORK>=3*K+max(K*K,2*N).

          15:  RWORK(LRWORK) -- DOUBLE PRECISION array       User Workspace
               RWORK is not used by F02FJF, but is passed directly to
               routines DOT and IMAGE and may be used to supply information
               to these routines.

          16:  LRWORK -- INTEGER                                      Input
               On entry: the length of the array RWORK, as declared in the
               (sub)program from which F02FJF is called. Constraint: LRWORK
               >= 1.

          17:  IWORK(LIWORK) -- INTEGER array                User Workspace
               IWORK is not used by F02FJF, but is passed directly to
               routines DOT and IMAGE and may be used to supply information
               to these routines.

          18:  LIWORK -- INTEGER                                      Input
               On entry: the length of the array IWORK, as declared in the
               (sub)program from which F02FJF is called. Constraint: LIWORK
               >= 1.

          19:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. Users who are
               unfamiliar with this parameter should refer to the Essential
               Introduction for details.

               On exit: IFAIL = 0 unless the routine detects an error or
               gives a warning (see Section 6).

               For this routine, because the values of output parameters
               may be useful even if IFAIL /=0 on exit, users are
               recommended to set IFAIL to -1 before entry. It is then
               essential to test the value of IFAIL on exit. To suppress
               the output of an error message when soft failure occurs, set
               IFAIL to 1.

          6. Error Indicators and Warnings

          Errors or warnings specified by the routine:


          IFAIL< 0
               A negative value of IFAIL indicates an exit from F02FJF
               because the user has set IFLAG negative in DOT or IMAGE. The
               value of IFAIL will be the same as the user's setting of
               IFLAG.

          IFAIL= 1
               On entry N < 1,

               or       M < 1,

               or       M >= K,

               or       K > N,

               or       NRX < N,

               or       LWORK <3*K+max(K*K*N),

               or       LRWORK < 1,

               or       LIWORK < 1.

          IFAIL= 2
               Not all the requested eigenvalues and vectors have been
               obtained. Approximations to the rth eigenvalue are
               oscillating rapidly indicating that severe cancellation is
               occurring in the rth eigenvector and so M is returned as (r-
               1). A restart with a larger value of K may permit
               convergence.

          IFAIL= 3
               Not all the requested eigenvalues and vectors have been
               obtained. The rate of convergence of the remaining
               eigenvectors suggests that more than NOITS iterations would
               be required and so the input value of M has been reduced. A
               restart with a larger value of K may permit convergence.

          IFAIL= 4
               Not all the requested eigenvalues and vectors have been
               obtained. NOITS iterations have been performed. A restart,
               possibly with a larger value of K, may permit convergence.

          IFAIL= 5
               This error is very unlikely to occur, but indicates that
               convergence of the eigenvalue sub-problem has not taken
               place. Restarting with a different set of approximate
               vectors may allow convergence. If this error occurs the user
               should check carefully that F02FJF is being called
               correctly.

          7. Accuracy

          Eigenvalues and eigenvectors will normally be computed to the
          accuracy requested by the parameter TOL, but eigenvectors
          corresponding to small or to close eigenvalues may not always be
          computed to the accuracy requested by the parameter TOL. Use of
          the routine MONIT to monitor acceptance of eigenvalues and
          eigenvectors is recommended.

          8. Further Comments

          The time taken by the routine will be principally determined by
          the time taken to solve the eigenvalue sub-problem and the time
          taken by the routines DOT and IMAGE. The time taken to solve an
                                                                    2
          eigenvalue sub-problem is approximately proportional to nk . It
          is important to be aware that several calls to DOT and IMAGE may
          occur on each major iteration.

          As can be seen from Table 3.1, many applications of F02FJF will
          require routine IMAGE to solve a system of linear equations. For
          example, to find the smallest eigenvalues of Ax=(lambda)Bx, IMAGE
          needs to solve equations of the form Aw=Bz for w and routines
          from Chapters F01 and F04 of the NAG Foundation Library will
          frequently be useful in this context. In particular, if A is a
          positive-definite variable band matrix, F04MCF may be used after
          A has been factorized by F01MCF. Thus factorization need be
          performed only once prior to calling F02FJF. An illustration of
          this type of use is given in the example program in Section 9.

                           ~
          An approximation d , to the ith eigenvalue, is accepted as soon
                            h
             ~
          as d  and the previous approximation differ by less than
              h
           ~
          |d |*TOL/10. Eigenvectors are accepted in groups corresponding to
            h
          clusters of eigenvalues that are equal, or nearly equal, in
          absolute value and that have already been accepted. If d  is the
                                                                  r
          last eigenvalue in such a group and we define the residual r  as
                                                                      j

                                      r =Cx -y
                                       j   j  r

          where y  is the projection of Cx , with respect to B, onto the
                 r                        j
          space spanned by x ,x ,...,x  and x  is the current approximation
                            1  2      r      j
          to the jth eigenvector, then the value f  returned in MONIT is
                                                  i
          given by

                                                       2  T
                        f =max||r || /||Cx ||     ||x|| =x Bx
                         i       j  B     j  B         B

          and each vector in the group is accepted as an eigenvector if

                                (|d |f )/(|d |-e)<TOL
                                   r  r     r

                                                   ~
          where e is the current approximation to |d |. The values of the
                                                    k
          f  are systematically increased if the convergence criteria
           i
          appear to be too strict. See Rutishauser [4] for further details.

          The algorithm implemented by F02FJF differs slightly from SIMITZ
          (Nikolai [1]) in that the eigenvalue sub-problem is solved using
          the singular value decomposition of the upper triangular matrix R
                                                                         T
          of the Gram-Schmidt factorization of Cx , rather than forming R R
                                                 r

          9. Example

          To find the four eigenvalues of smallest absolute value and
          corresponding eigenvectors for the generalized symmetric
          eigenvalue problem Ax=(lambda)Bx, where A and B are the 16 by 16
          matrices

                           (1 a     a                      )
                           (a 1 a     a                    )
                           (  a 1 a     a                  )
                           (    a 1 a     a                )
                           (a     a 1 a     a              )
                           (  a     a 1 a     a            )
                           (    a     a 1 a     a          )
                           (      a     a 1 a     a        )
                         A=(        a     a 1 a     a      )
                           (          a     a 1 a     a    )
                           (            a     a 1 a     a  )
                           (              a     a 1 a     a)
                           (                a     a 1 a    )
                           (                  a     a 1 a  )
                           (                    a     a 1 a)
                           (                      a     a 1)

                    1
          where a=- -
                    4

                           (1 b                            )
                           (b 1 b                          )
                           (  b 1 b                        )
                           (    b 1 b                      )
                           (      b 1 b                    )
                           (        b 1 b                  )
                           (          b 1 b                )
                         B=(            b 1 b              )
                           (              b 1 b            )
                           (                b 1 b          )
                           (                  b 1 b        )
                           (                    b 1 b      )
                           (                      b 1 b    )
                           (                        b 1 b  )
                           (                          b 1 b)

                    1
          where b=- -
                    2

          TOL is taken as 0.0001 and 6 iteration vectors are used. F01MAF
          is used to factorize the matrix A, prior to calling F02FJF, and
          F04MAF is used within IMAGE to solve the equations Aw=Bz for w.
          Details of the factorization of A are passed from F01MAF to
          F04MAF by means of the COMMON block BLOCK1.

          Output from MONIT occurs each time ISTATE is non-zero. Note that
          the required eigenvalues are the reciprocals of the eigenvalues
          returned by F02FJF.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02WEF
                  F02WEF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02WEF returns all, or part, of the singular value decomposition
          of a general real matrix.

          2. Specification

                 SUBROUTINE F02WEF (M, N, A, LDA, NCOLB, B, LDB, WANTQ, Q,
                1                   LDQ, SV, WANTP, PT, LDPT, WORK, IFAIL)
                 INTEGER          M, N, LDA, NCOLB, LDB, LDQ, LDPT, IFAIL
                 DOUBLE PRECISION A(LDA,*), B(LDB,*), Q(LDQ,*), SV(*), PT
                1                 (LDPT,*), WORK(*)
                 LOGICAL          WANTQ, WANTP

          3. Description

          The m by n matrix A is factorized as

                                            T
                                       A=QDP ,

          where

                (S)
              D=(0),          m>n,

              D=S,            m=n,

              D=(S 0),        m<n,

          Q is an m by m orthogonal matrix, P is an n by n orthogonal
          matrix and S is a min(m,n) by min(m,n) diagonal matrix with non-
          negative diagonal elements, sv ,sv ,...,sv        , ordered such
                                        1   2       min(m,n)
          that

                            sv >=sv >=...>=sv        >=0.
                              1    2         min(m,n)

          The first min(m,n) columns of Q are the left-hand singular
          vectors of A, the diagonal elements of S are the singular values
          of A and the first min(m,n) columns of P are the right-hand
          singular vectors of A.

          Either or both of the left-hand and right-hand singular vectors
          of A may be requested and the matrix C given by

                                          T
                                       C=Q B,

          where B is an m by ncolb given matrix, may also be requested.

          The routine obtains the singular value decomposition by first
          reducing A to upper triangular form by means of Householder
          transformations, from the left when m>=n and from the right when
          m<n. The upper triangular form is then reduced to bidiagonal form
          by Givens plane rotations and finally the QR algorithm is used to
          obtain the singular value decomposition of the bidiagonal form.

          Good background descriptions to the singular value decomposition
          are given in Dongarra et al [1], Hammarling [2] and Wilkinson [3]
          DSVDC.

          Note that if K is any orthogonal diagonal matrix so that

                                         T
                                       KK =I,

          (so that K has elements +1 or -1 on the diagonal)

          then

                                               T
                                    A=(QK)D(PK)

          is also a singular value decomposition of A.

          4. References

          [1]   Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979)
                LINPACK Users' Guide. SIAM, Philadelphia.

          [2]   Hammarling S (1985) The Singular Value Decomposition in
                Multivariate Statistics. ACM Signum Newsletter. 20, 3 2--25.

          [3]   Wilkinson J H (1978) Singular Value Decomposition -- Basic
                Aspects. Numerical Software -- Needs and Availability. (ed D
                A H Jacobs) Academic Press.

          5. Parameters

           1:  M -- INTEGER                                           Input
               On entry: the number of rows, m, of the matrix A.
               Constraint: M >= 0.

               When M = 0 then an immediate return is effected.

           2:  N -- INTEGER                                           Input
               On entry: the number of columns, n, of the matrix A.
               Constraint: N >= 0.

               When N = 0 then an immediate return is effected.

           3:  A(LDA,*) -- DOUBLE PRECISION array              Input/Output
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the leading m by n part of the array A must
               contain the matrix A whose singular value decomposition is
               required. On exit: if M >= N and WANTQ = .TRUE., then the
               leading m by n part of A will contain the first n columns of
               the orthogonal matrix Q.

               If M < N and WANTP = .TRUE., then the leading m by n part of
                                                                         T
               A will contain the first m rows of the orthogonal matrix P .

               If M >= N and WANTQ = .FALSE. and WANTP = .TRUE., then the
               leading n by n part of A will contain the first n rows of
                                      T
               the orthogonal matrix P .

               Otherwise the leading m by n part of A is used as internal
               workspace.

           4:  LDA -- INTEGER                                         Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which F02WEF is called.
               Constraint: LDA >= max(1,M).

           5:  NCOLB -- INTEGER                                       Input
               On entry: ncolb, the number of columns of the matrix B.
               When NCOLB = 0 the array B is not referenced. Constraint:
               NCOLB >= 0.

           6:  B(LDB,*) -- DOUBLE PRECISION array              Input/Output
               Note: the second dimension of the array B must be at least
               max(1,ncolb) On entry: if NCOLB > 0, the leading m by ncolb
               part of the array B must contain the matrix to be
               transformed. On exit: B is overwritten by the m by ncolb
                        T
               matrix  Q B.

           7:  LDB -- INTEGER                                         Input
               On entry:
               the first dimension of the array B as declared in the
               (sub)program from which F02WEF is called.
               Constraint: if NCOLB > 0 then LDB >= max(1,M).

           8:  WANTQ -- LOGICAL                                       Input
               On entry: WANTQ must be .TRUE., if the left-hand singular
               vectors are required. If WANTQ = .FALSE., then the array Q
               is not referenced.

           9:  Q(LDQ,*) -- DOUBLE PRECISION array                    Output
               Note: the second dimension of the array Q must be at least
               max(1,M).
               On exit: if M < N and WANTQ = .TRUE., the leading m by m
               part of the array Q will contain the orthogonal matrix Q.
               Otherwise the array Q is not referenced.

          10:  LDQ -- INTEGER                                         Input
               On entry:
               the first dimension of the array Q as declared in the
               (sub)program from which F02WEF is called.
               Constraint: if M < N and WANTQ = .TRUE., LDQ >= max(1,M).

          11:  SV(*) -- DOUBLE PRECISION array                       Output
               Note: the length of SV must be at least min(M,N). On exit:
               the min(M,N) diagonal elements of the matrix S.

          12:  WANTP -- LOGICAL                                       Input
               On entry: WANTP must be .TRUE. if the right-hand singular
               vectors are required. If WANTP = .FALSE., then the array PT
               is not referenced.

          13:  PT(LDPT,*) -- DOUBLE PRECISION array                  Output
               Note: the second dimension of the array PT must be at least
               max(1,N).
               On exit: if M >= N and WANTQ and WANTP are .TRUE., the
               leading n by n part of the array PT will contain the
                                  T
               orthogonal matrix P . Otherwise the array PT is not
               referenced.

          14:  LDPT -- INTEGER                                        Input
               On entry:
               the first dimension of the array PT as declared in the
               (sub)program from which F02WEF is called.
               Constraint: if M >= N and WANTQ and WANTP are .TRUE., LDPT
               >= max(1,N).

          15:  WORK(*) -- DOUBLE PRECISION array                     Output
               Note: the length of WORK must be at least max(1,lwork),
               where lwork must be as given in the following table:

               M >= N
               WANTQ is .TRUE. and WANTP = .TRUE.
                                2
                     lwork=max(N +5*(N-1),N+NCOLB,4)

               WANTQ = .TRUE. and WANTP = .FALSE.
                                2
                     lwork=max(N +4*(N-1),N+NCOLB,4)

               WANTQ = .FALSE. and WANTP = .TRUE.
                     lwork=max(3*(N-1),2) when NCOLB = 0

                     lwork=max(5*(N-1),2) when NCOLB > 0

               WANTQ = .FALSE. and WANTP = .FALSE.
                     lwork=max(2*(N-1),2) when NCOLB = 0

                     lwork=max(3*(N-1),2) when NCOLB > 0

               M < N
               WANTQ = .TRUE. and WANTP = .TRUE.
                                2
                     lwork=max(M +5*(M-1),2)

               WANTQ = .TRUE. and WANTP = .FALSE.
                     lwork=max(3*(M-1),1)

               WANTQ = .FALSE. and WANTP = .TRUE.
                                2
                     lwork=max(M +3*(M-1),2) when NCOLB = 0

                                2
                     lwork=max(M +5*(M-1),2) when NCOLB > 0

               WANTQ = .FALSE. and WANTP = .FALSE.
                     lwork=max(2*(M-1),1) when NCOLB = 0

                     lwork=max(3*(M-1),1) when NCOLB > 0
               On exit: WORK(min(M,N)) contains the total number of
               iterations taken by the R algorithm.

               The rest of the array is used as workspace.

          16:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL=-1
               One or more of the following conditions holds:
                    M < 0,

                    N < 0,

                    LDA < M,

                    NCOLB < 0,

                    LDB < M and NCOLB > 0,

                    LDQ < M and M < N and WANTQ = .TRUE.,

                    LDPT < N and M >= N and WANTQ = .TRUE., and WANTP = .
                    TRUE..

          IFAIL> 0
               The QR algorithm has failed to converge in 50*min(m,n)
               iterations. In this case SV(1), SV(2),..., SV(IFAIL) may not
               have been found correctly and the remaining singular values
               may not be the smallest. The matrix A will nevertheless have
                                        T
               been factorized as  A=QEP ,  where the leading min(m,n) by
               min(m,n) part of E is a bidiagonal matrix with SV(1), SV(2),
               ..., SV(min(m,n)) as the diagonal elements and WORK(1), WORK
               (2),..., WORK(min(m,n)-1) as the super-diagonal elements.

               This failure is not likely to occur.

          7. Accuracy

          The computed factors Q, D and P satisfy the relation

                                         T
                                      QDP =A+E,

          where

                             ||E||<=c(epsilon)||A||,

          (epsilon) being the machine precision, c is a modest function of
          m and n and ||.|| denotes the spectral (two) norm. Note that
          ||A||=sv .
                  1

          8. Further Comments

          Following the use of this routine the rank of A may be estimated
          by a call to the INTEGER FUNCTION F06KLF(*). The statement:

                 IRANK = F06KLF(MIN(M, N), SV, 1, TOL)

          returns the value (k-1) in IRANK, where k is the smallest integer
          for which SV(k)<tol*SV(1), where tol is the tolerance supplied in
          TOL, so that IRANK is an estimate of the rank of S and thus also
          of A. If TOL is supplied as negative then the machine precision
          is used in place of TOL.

          9. Example

          9.1. Example 1

          To find the singular value decomposition of the 5 by 3 matrix

                                    (2.0  2.5  2.5)
                                    (2.0  2.5  2.5)
                                  A=(1.6 -0.4  2.8)
                                    (2.0 -0.5  0.5)
                                    (1.2 -0.3 -2.9)

                                    T
          together with the vector Q b for the vector

                                        ( 1.1)
                                        ( 0.9)
                                      b=( 0.6)
                                        ( 0.0)
                                        (-0.8)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

          9.2. Example 2

          To find the singular value decomposition of the 3 by 5 matrix

                               (2.0 2.0  1.6  2.0  1.2)
                             A=(2.5 2.5 -0.4 -0.5 -0.3)
                               (2.5 2.5  2.8  0.5 -2.9)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          F02 -- Eigenvalue and Eigenvectors                         F02XEF
                  F02XEF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          F02XEF returns all, or part, of the singular value decomposition
          of a general complex matrix.

          2. Specification

                 SUBROUTINE F02XEF (M, N, A, LDA, NCOLB, B, LDB, WANTQ, Q,
                1                   LDQ, SV, WANTP, PH, LDPH, RWORK, CWORK,
                2                   IFAIL)
                 INTEGER                   M, N, LDA, NCOLB, LDB, LDQ, LDPH,
                1                          IFAIL
                 DOUBLE PRECISION          SV(*), RWORK(*)
                 COMPLEX(KIND=KIND(1.0D0)) A(LDA,*), B(LDB,*), Q(LDQ,*),
                1                          PH(LDPH,*), CWORK(*)
                 LOGICAL                   WANTQ, WANTP

          3. Description

          The m by n matrix A is factorized as

                                            H
                                       A=QDP ,

          where

                (S)
              D=(0)           m>n,

              D=S,            m=n,

              D=(S 0),        m<n,

          Q is an m by m unitary matrix, P is an n by n unitary matrix and
          S is a min(m,n) by min(m,n) diagonal matrix with real non-
          negative diagonal elements, sv ,sv ,...,sv        , ordered such
                                        1   2       min(m,n)
          that

                            sv >=sv >=...>=sv        >=0.
                              1    2         min(m,n)

          The first min(m,n) columns of Q are the left-hand singular
          vectors of A, the diagonal elements of S are the singular values
          of A and the first min(m,n) columns of P are the right-hand
          singular vectors of A.

          Either or both of the left-hand and right-hand singular vectors
          of A may be requested and the matrix C given by

                                          H
                                       C=Q B,

          where B is an m by ncolb given matrix, may also be requested.

          The routine obtains the singular value decomposition by first
          reducing A to upper triangular form by means of Householder
          transformations, from the left when m>=n and from the right when
          m<n. The upper triangular form is then reduced to bidiagonal form
          by Givens plane rotations and finally the QR algorithm is used to
          obtain the singular value decomposition of the bidiagonal form.

          Good background descriptions to the singular value decomposition
          are given in Dongarra et al [1], Hammarling [2] and Wilkinson [3]
          ZSVDC.

          Note that if K is any unitary diagonal matrix so that

                                         H
                                       KK =I,

          then

                                               H
                                    A=(QK)D(PK)

          is also a singular value decomposition of A.

          4. References

          [1]   Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979)
                LINPACK Users' Guide. SIAM, Philadelphia.

          [2]   Hammarling S (1985) The Singular Value Decomposition in
                Multivariate Statistics. ACM Signum Newsletter. 20, 3 2--25.

          [3]   Wilkinson J H (1978) Singular Value Decomposition -- Basic
                Aspects. Numerical Software -- Needs and Availability. (ed D
                A H Jacobs) Academic Press.

          5. Parameters

           1:  M -- INTEGER                                           Input
               On entry: the number of rows, m, of the matrix A.
               Constraint: M >= 0.

               When M = 0 then an immediate return is effected.

           2:  N -- INTEGER                                           Input
               On entry: the number of columns, n, of the matrix A.
               Constraint: N >= 0.

               When N = 0 then an immediate return is effected.

           3:  A(LDA,*) -- COMPLEX(KIND(1.0D)) array           Input/Output
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the leading m by n part of the array A must
               contain the matrix A whose singular value decomposition is
               required. On exit: if M >= N and WANTQ = .TRUE., then the
               leading m by n part of A will contain the first n columns of
               the unitary matrix Q.
               If M < N and WANTP = .TRUE., then the leading m by n part of
                                                                      H
               A will contain the first m rows of the unitary matrix P .
               will contain the first m rows of the unitary matrix P If M
               >= N and WANTQ = .FALSE. and WANTP = .TRUE., then the
               leading n by n part of A will contain the first n
                                           H
               rows of the unitary matrix P . Otherwise the leading m by n
               part of A is used as internal workspace.

           4:  LDA -- INTEGER                                         Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which F02XEF is called.
               Constraint: LDA >= max(1,M).

           5:  NCOLB -- INTEGER                                       Input
               On entry: ncolb, the number of columns of the matrix B.
               When NCOLB = 0 the array B is not referenced. Constraint:
               NCOLB >= 0.

           6:  B(LDB,*) -- COMPLEX(KIND(1.0D)) array           Input/Output
               Note: the second dimension of the array B must be at least
               max(1,NCOLB).
               On entry: if NCOLB > 0, the leading m by ncolb part of the
               array B must contain the matrix to be transformed. On exit:
                                                          H
               B is overwritten by the m by ncolb matrix Q B.

           7:  LDB -- INTEGER                                         Input
               On entry:
               the first dimension of the array B as declared in the
               (sub)program from which F02XEF is called.
               Constraint: if NCOLB > 0, then LDB >= max(1,M).

           8:  WANTQ -- LOGICAL                                       Input
               On entry: WANTQ must be .TRUE. if the left-hand singular
               vectors are required. If WANTQ = .FALSE. then the array Q is
               not referenced.

           9:  Q(LDQ,*) -- COMPLEX(KIND(1.0D)) array                 Output
               Note: the second dimension of the array Q must be at least
               max(1,M).
               On exit: if M < N and WANTQ = .TRUE., the leading m by m
               part of the array Q will contain the unitary matrix Q.
               Otherwise the array Q is not referenced.

          10:  LDQ -- INTEGER                                         Input
               On entry:
               the first dimension of the array Q as declared in the
               (sub)program from which F02XEF is called.
               Constraint: if M < N and WANTQ = .TRUE., LDQ >= max(1,M).

          11:  SV(*) -- DOUBLE PRECISION array                       Output
               Note: the length of SV must be at least min(M,N). On exit:
               the min(m,n) diagonal elements of the matrix S.

          12:  WANTP -- LOGICAL                                       Input
               On entry: WANTP must be .TRUE. if the right-hand singular
               vectors are required. If WANTP = .FALSE. then the array PH
               is not referenced.

          13:  PH(LDPH,*) -- DOUBLE PRECISION array                  Output
               Note: the second dimension of the array PH must be at least
               max(1,N).
               On exit: if M >= N and WANTQ and WANTP are .TRUE., the
               leading n by n part of the array PH will contain the unitary
                       H
               matrix P . Otherwise the array PH is not referenced.

          14:  LDPH -- INTEGER                                        Input
               On entry:
               the first dimension of the array PH as declared in the
               (sub)program from which F02XEF is called.
               Constraint: if M >= N and WANTQ and WANTP are .TRUE.,  LDPH
               >= max(1,N).

          15:  RWORK(*) -- DOUBLE PRECISION array                    Output
               Note: the length of RWORK must be at least max(1,lrwork),
               where lrwork must satisfy:
               lrwork=2*(min(M,N)-1) when
                     NCOLB = 0 and WANTQ and WANTP are .FALSE.,

               lrwork=3*(min(M,N)-1) when
                     either NCOLB = 0 and WANTQ = .FALSE. and WANTP = .
                     TRUE., or WANTP = .FALSE. and one or both of NCOLB > 0
                     and WANTQ = .TRUE.

               lrwork=5*(min(M,N)-1)
                     otherwise.
               On exit: RWORK(min(M,N)) contains the total number of
               iterations taken by the QR algorithm.

               The rest of the array is used as workspace.

          16:  CWORK(*) -- COMPLEX(KIND(1.0D)) array              Workspace
               Note: the length of CWORK must be at least max(1,lcwork),
               where lcwork must satisfy:
                             2
               lcwork=N+max(N ,NCOLB) when
                     M >= N and WANTQ and WANTP are both .TRUE.

                             2
               lcwork=N+max(N +N,NCOLB) when
                     M >= N and WANTQ = .TRUE., but WANTP = .FALSE.

               lcwork=N+max(N,NCOLB) when
                     M >= N and WANTQ = .FALSE.

                       2
               lcwork=M +M when
                     M < N and WANTP = .TRUE.

               lcwork = M when
                     M < N and WANTP = .FALSE.

          17:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL=-1
               One or more of the following conditions holds:
                    M < 0,

                    N < 0,

                    LDA < M,

                    NCOLB < 0,

                    LDB < M and NCOLB > 0,

                    LDQ < M and M < N and WANTQ = .TRUE.,

                    LDPH < N and M >= N and WANTQ = .TRUE. and WANTP = .
                    TRUE..

          IFAIL> 0
               The QR algorithm has failed to converge in 50*min(m,n)
               iterations. In this case SV(1), SV(2),..., SV(IFAIL) may not
               have been found correctly and the remaining singular values
               may not be the smallest. The matrix A will nevertheless have
                                        H
               been factorized as  A=QEP   where the leading min(m,n) by
               min(m,n) part of E is a bidiagonal matrix with SV(1), SV(2),
               ..., SV(min(m,n)) as the diagonal elements and RWORK(1),
               RWORK(2),..., RWORK(min(m,n)-1) as the super-diagonal
               elements.

               This failure is not likely to occur.

          7. Accuracy

          The computed factors Q, D and P satisfy the relation

                                         H
                                      QDP =A+E,

          where

                             ||E||<=c(epsilon)||A||,

          (epsilon) being the machine precision, c is a modest function of
          m and n and ||.|| denotes the spectral (two) norm. Note that
          ||A||=sv .
                  1

          8. Further Comments

          Following the use of this routine the rank of A may be estimated
          by a call to the INTEGER FUNCTION F06KLF(*). The statement:


                  IRANK = F06KLF(MIN(M, N), SV, 1, TOL)

          returns the value (k-1) in IRANK, where k is the smallest integer
          for which SV(k)<tol*SV(1), where tol is the tolerance supplied in
          TOL, so that IRANK is an estimate of the rank of S and thus also
          of A. If TOL is supplied as negative then the machine precision
          is used in place of TOL.

          9. Example

          9.1. Example 1

          To find the singular value decomposition of the 5 by 3 matrix

                             (    0.5i -0.5+1.5i -1.0+1.0i)
                             (0.4+0.3i  0.9+1.3i  0.2+1.4i)
                           A=(0.4      -0.4+0.4i  1.8     )
                             (0.3-0.4i  0.1+0.7i  0.0     )
                             (   -0.3i  0.3+0.3i      2.4i)

                                    H
          together with the vector Q b for the vector

                                     (-0.55+1.05i)
                                     ( 0.49+0.93i)
                                   b=( 0.56-0.16i)
                                     ( 0.39+0.23i)
                                     ( 1.13+0.83i)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

          9.2. Example 2

          To find the singular value decompostition of the 3 by 5 matrix

                   (     0.5i 0.4-0.3i  0.4      0.3+0.4i     0.3i)
                 A=(-0.5-1.5i 0.9-1.3i -0.4-0.4i 0.1-0.7i 0.3-0.3i)
                   (-1.0-1.0i 0.2-1.4i  1.8      0.0         -2.4i)

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.


