path: root/src/hyper/pages/nagf.ht

\begin{page}{manpageXXf}{NAG On-line Documentation: f}
\beginscroll
\begin{verbatim}



     F(3NAG)           Foundation Library (12/10/92)           F(3NAG)



          F -- Linear Algebra                             Introduction -- F
                                     Chapter F
                                  Linear Algebra

          1. Introduction

          The F Chapters of the Library are concerned with linear algebra
          and cover a large area. This general introduction is intended to
          help users decide which particular F Chapter is relevant to their
          problem. There are F Chapters with the following titles:

               F01 -- Matrix Factorizations

               F02 -- Eigenvalues and Eigenvectors

               F04 -- Simultaneous Linear Equations

               F06 -- Linear Algebra Support Routines

               F07 -- Linear Equations (LAPACK)

          The principal problem areas addressed by the above Chapters are:

               Systems of linear equations

               Linear least-squares problems

               Eigenvalue and singular value problems

          The solution of these problems usually involves several matrix
          operations, such as a matrix factorization followed by the
          solution of the factorized form, and the routines for these
          operations themselves utilize lower level support routines;
          typically routines from Chapter F06. Most users will not normally
          need to be concerned with these support routines.

          NAG has been involved in a project, called LAPACK [1], to develop
          a linear algebra package for modern high-performance computers
          and some of the routines developed within that project are
          incorporated into the Library as Chapter F07. It should be
          emphasised that, while the LAPACK project has been concerned with
          high-performance computers, the routines do not compromise
          efficiency on conventional machines.

          For background information on numerical algorithms for the
          solution of linear algebra problems see Golub and Van Loan [4].
          For some problem areas the user has the choice of selecting a
          single routine to solve the problem, a so-called Black Box
          routine, or selecting more than one routine to solve the problem,
          such as a factorization routine followed by a solve routine, so-
          called General Purpose routines. The following sections indicate
          which chapters are relevant to particular problem areas.

          2. Linear Equations

          The Black Box routines for solving linear equations of the form

                                  Ax=b  and  AX=B,

          where A is an n by n real or complex, non-singular matrix, are to
          be found in Chapter F04. Such equations can also be solved by
          selecting a General Purpose factorization routine from Chapter
          F01 and combining it with a solve routine in Chapter F04, or by
          selecting a factorization and a solve routine from Chapter F07.

          There are routines to cater for a variety of types of matrix,
          including general, symmetric or Hermitian, symmetric or Hermitian
          positive definite, tridiagonal, skyline and sparse matrices.

          In order to select the appropriate routine, users are recommended
          to consult the F04 Chapter Introduction in the first instance.

          3. Linear Least-squares

          Routines for solving linear least-squares problems of the form


                                      T
                            minimize r r,  where  r=b-Ax,
                             x

          where A is an m by n, possibly rank deficient, matrix are to be
          found in Chapter F04. Linear least-squares problems can also be
          solved by routines in the statistical Chapter G02.

          In order to select the appropriate routine, users are recommended
          to consult the F04 Chapter Introduction in the first instance,
          but users with additional statistical requirements may prefer to
          consult the G02 Chapter Introduction.

          4. Eigenvalue Problems and Singular Value Problems

          Routines for solving standard matrix eigenvalue problems of the
          form


                                    Ax=(lambda)x,

          where A is an n by n real or complex matrix, and generalized
          matrix eigenvalue problems of the form


                                    Ax=(lambda)Bx

          where B is also an n by n matrix are to be found in Chapter F02.

          There are routines to cater for various types of matrices,
          including general, symmetric or Hermitian and sparse matrices.

          Similarly, the routines for finding singular values and/or
          singular vectors of an m by n real or complex matrix A are to be
          found in Chapter F02.

          In order to select the appropriate routine, users are recommended
          to consult the F02 Chapter Introduction in the first instance.

          5. Matrix Factorizations

          Routines for various sorts of matrix factorization are to be
          found in Chapters F01 and F07 together with associated
          transformation routines. In order to select the appropriate
          routine users are recommended to consult the F01 Chapter
          Introduction in the first instance.

          6. Support Routines

          Chapter F06 contains a variety of routines to perform elementary
          algebraic operations involving scalars, vectors and matrices,
          such as setting up a plane rotation, performing a dot product and
          computing a matrix-vector product. Chapter F06 contains routines
          that meet the specification of the BLAS (Basic Linear Algebra
          Subprograms) [5, 3, 2]. The routines in this chapter will not
          normally be required by the general user, but are intended for
          use by those who require to build specialist linear algebra
          modules. The BLAS are extensively used by other NAG Foundation
          Library routines.

          References

          [1]   Anderson E, Bai Z, Bischof C, Demmel J, Dongarra J J, Du
                Croz J, Greenbaum A, Hammarling S, McKenney A, Ostrouchov S
                and Sorensen D (1992) LAPACK Users' Guide. SIAM
                Philadelphia.

          [2]   Dongarra J J, Du Croz J J, Duff I S and Hammarling S (1990)
                A Set of Level 3 Basic Linear Algebra Subprograms. ACM
                Trans. Math. Softw. 16 1--28.

          [3]   Dongarra J J, Du Croz J J, Hammarling S and Hanson R J
                (1988) An Extended Set of FORTRAN Basic Linear Algebra
                Subprograms. ACM Trans. Math. Softw. 14 1--32.

          [4]   Golub G H and Van Loan C F (1989) Matrix Computations (2nd
                Edition). Johns Hopkins University Press, Baltimore,
                Maryland.

          [5]   Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979)
                Basic Linear Algebra Subprograms for Fortran Usage. ACM
                Trans. Math. Softw. 5 308--325.

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

          [7]   Wilkinson J H (1965) The Algebraic Eigenvalue Problem.
                Clarendon Press.

          [8]   Wilkinson J H (1977) Some Recent Advances in Numerical
                Linear Algebra. The State of the Art in Numerical Analysis.
                (ed D A H Jacobs) Academic Press.

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

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

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01}{NAG On-line Documentation: f01}
\beginscroll
\begin{verbatim}



     F01(3NAG)         Foundation Library (12/10/92)         F01(3NAG)



          F01 -- Matrix Factorization                   Introduction -- F01
                                    Chapter F01
                               Matrix Factorization

          1. Scope of the Chapter

          This chapter provides facilities for matrix factorizations and
          associated transformations.

          2. Background to the Problems

          An n by n matrix may be factorized as

                                            T
                                      A=PLUQ ,

          where L and U are respectively lower and uper triangular
          matrices, and P and Q are permutation matrices. This is called an
          LU factorization. For general dense matrices it is usual to
          choose Q=I and to then choose P to ensure that the factorization
          is numerically stable. For sparse matrices, judicious choice of P
          and Q ensures numerical stability as well as maintaining as much
          sparsity as possible in the factors L and U. The LU factorization
          is normally used in connection with the solution of the linear
          equations


                                        Ax=b,

          whose solution, x, may then be obtained by solving in succession
          the simpler equations

                                    T
                                Ly=P b,  Uz=y,  x=Qz

          the first by forward substitution and the second by backward
          substitution. Routines to perform this solution are to be found
          in Chapter F04.

                                                                      T
          When A is symmetric positive-definite then we can choose U=L  and
          Q=P, to give the Cholesky factorization. This factorization is
          numerically stable without permutations, but in the sparse case
          the permutations can again be used to try to maintain sparsity.
          The Cholesky factorization is sometimes expressed as

                                           T T
                                     A=PLDL P ,

          where D is a diagonal matrix with positive diagonal elements and
          L is unit lower triangular.

          The LU factorization can also be performed on rectangular
          matrices, but in this case it is more usual to perform a QR
          factorization. When A is an m by n (m>=n) matrix this is given by


                                          (R)
                                       A=Q(0),

          where R is an n by n upper triangular matrix and Q is an
          orthogonal (unitary in the complex case) matrix.

          3. Recommendations on Choice and Use of Routines

          Routine F07ADF performs the LU factorization of a real m by n
          dense matrix.

          The LU factorization of a sparse matrix is performed by routine
          F01BRF. Following the use of F01BRF, matrices with the same
          sparsity pattern may be factorized by routine F01BSF.

          The Cholesky factorization of a real symmetric positive-definite
          dense matrix is performed by routine F07FDF.

          Routine F01MCF performs the Cholesky factorization of a real
          symmetric positive-definite variable band (skyline) matrix, and a
          general sparse symmetric positive-definite matrix may be
          factorized using routine F01MAF.

          The QR factorization of an m by n (m>=n) matrix is performed by
          routine F01QCF in the real case, and F01RCF in the complex case.
          Following the use of F01QCF, operations with Q may be performed
          using routine F01QDF and some, or all, of the columns of Q may be
          formed using routine F01QEF. Routines F01RDF and F01REF perform
          the same tasks following the use of F01RCF.


          F01 -- Matrix Factorizations                      Contents -- F01
          Chapter F01

          Matrix Factorizations

          F01BRF  LU factorization of real sparse matrix

          F01BSF  LU factorization of real sparse matrix with known
                  sparsity pattern

                    T
          F01MAF  LL  factorization of real sparse symmetric positive-
                  definite matrix

                     T
          F01MCF  LDL  factorization of real symmetric positive-definite
                  variable-bandwidth matrix

          F01QCF  QR factorization of real m by n matrix (m>=n)

                                                                      T
          F01QDF  Operations with orthogonal matrices, compute QB or Q B
                  after factorization by F01QCF

          F01QEF  Operations with orthogonal matrices, form columns of Q
                  after factorization by F01QCF

          F01RCF  QR factorization of complex m by n matrix (m>=n)

                                                                   H
          F01RDF  Operations with unitary matrices, compute QB or Q B after
                  factorization by F01RCF

          F01REF  Operations with unitary matrices, form columns of Q after
                  factorization by F01RCF

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01brf}{NAG On-line Documentation: f01brf}
\beginscroll
\begin{verbatim}



     F01BRF(3NAG)      Foundation Library (12/10/92)      F01BRF(3NAG)



          F01 -- Matrix Factorizations                               F01BRF
                  F01BRF -- 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

          F01BRF factorizes a real sparse matrix. The routine either forms
          the LU factorization of a permutation of the entire matrix, or,
          optionally, first permutes the matrix to block lower triangular
          form and then only factorizes the diagonal blocks.

          2. Specification

                 SUBROUTINE F01BRF (N, NZ, A, LICN, IRN, LIRN, ICN, PIVOT,
                1                   IKEEP, IW, W, LBLOCK, GROW, ABORT,
                2                   IDISP, IFAIL)
                 INTEGER          N, NZ, LICN, IRN(LIRN), LIRN, ICN(LICN),
                1                 IKEEP(5*N), IW(8*N), IDISP(10), IFAIL
                 DOUBLE PRECISION A(LICN), PIVOT, W(N)
                 LOGICAL          LBLOCK, GROW, ABORT(4)

          3. Description

          Given a real sparse matrix A, this routine may be used to obtain
          the LU factorization of a permutation of A,

                                       PAQ=LU

          where P and Q are permutation matrices, L is unit lower
          triangular and U is upper triangular. The routine uses a sparse
          variant of Gaussian elimination, and the pivotal strategy is
          designed to compromise between maintaining sparsity and
          controlling loss of accuracy through round-off.

          Optionally the routine first permutes the matrix into block lower
          triangular form and then only factorizes the diagonal blocks. For
          some matrices this gives a considerable saving in storage and
          execution time.

          Extensive data checks are made; duplicated non-zeros can be
          accumulated.

          The factorization is intended to be used by F04AXF to solve
                                                      T
          sparse systems of linear equations Ax=b or A x=b. If several
          matrices of the same sparsity pattern are to be factorized,
          F01BSF should be used for the second and subsequent matrices.

          The method is fully described by Duff [1].

          4. References

          [1]   Duff I S (1977) MA28 -- a set of Fortran subroutines for
                sparse unsymmetric linear equations. A.E.R.E. Report R.8730.
                HMSO.

          5. Parameters

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

           2:  NZ -- INTEGER                                          Input
               On entry: the number of non-zero elements in the matrix A.
               Constraint: NZ > 0.

           3:  A(LICN) -- DOUBLE PRECISION array               Input/Output
               On entry: A(i), for i = 1,2,...,NZ must contain the non-
               zero elements of the sparse matrix A. They can be in any
               order since the routine will reorder them. On exit: the non-
               zero elements in the LU factorization. The array must not be
               changed by the user between a call of this routine and a
               call of F04AXF.

           4:  LICN -- INTEGER                                        Input
               On entry:
               the dimension of the arrays A and ICN as declared in the
               (sub)program from which F01BRF is called.
               Since the factorization is returned in A and ICN, LICN
               should be large enough to accommodate this and should
               ordinarily be 2 to 4 times as large as NZ. Constraint: LICN
               >= NZ.

           5:  IRN(LIRN) -- INTEGER array                      Input/Output
               On entry: IRN(i), for i = 1,2,...,NZ must contain the row
               index of the non-zero element stored in A(i). On exit: the
               array is overwritten and is not needed for subsequent calls
               of F01BSF or F04AXF.

           6:  LIRN -- INTEGER                                        Input
               On entry:
               the dimension of the array IRN as declared in the
               (sub)program from which F01BRF is called.
               It need not be as large as LICN; normally it will not need
               to be very much greater than NZ. Constraint: LIRN >= NZ.

           7:  ICN(LICN) -- INTEGER array                      Input/Output
               On entry: ICN(i), for i = 1,2,...,NZ must contain the
               column index of the non-zero element stored in A(i). On
               exit: the column indices of the non-zero elements in the
               factorization. The array must not be changed by the user
               between a call of this routine and subsequent calls of
               F01BSF or F04AXF.

           8:  PIVOT -- DOUBLE PRECISION                              Input
               On entry: PIVOT should have a value in the range 0.0 <=
               PIVOT <= 0.9999 and is used to control the choice of pivots.
               If PIVOT < 0.0, the value 0.0 is assumed, and if PIVOT > 0.
               9999, the value 0.9999 is assumed. When searching a row for
               a pivot, any element is excluded which is less than PIVOT
               times the largest of those elements in the row available as
               pivots. Thus decreasing PIVOT biases the algorithm to
               maintaining sparsity at the expense of stability. Suggested
               value: PIVOT = 0.1 has been found to work well on test
               examples.

           9:  IKEEP(5*N) -- INTEGER array                           Output
               On exit: indexing information about the factorization. The
               array must not be changed by the user between a call of this
               routine and calls of F01BSF or F04AXF.

          10:  IW(8*N) -- INTEGER array                           Workspace

          11:  W(N) -- DOUBLE PRECISION array                        Output
               On exit: if GROW = .TRUE., W(1) contains an estimate (an
               upper bound) of the increase in size of elements encountered
               during the factorization (see GROW); the rest of the array
               is used as workspace.

               If GROW = .FALSE., the array is not used.

          12:  LBLOCK -- LOGICAL                                      Input
               On entry: if LBLOCK = .TRUE., the matrix is pre-ordered
               into block lower triangular form before the LU factorization
               is performed; otherwise the entire matrix is factorized.
               Suggested value: LBLOCK = .TRUE. unless the matrix is known
               to be irreducible.

          13:  GROW -- LOGICAL                                        Input
               On entry: if GROW = .TRUE., then on exit W(1) contains an
               estimate (an upper bound) of the increase in size of
               elements encountered during the factorization. If the matrix
               is well-scaled (see Section 8.2), then a high value for W(1)
               indicates that the LU factorization may be inaccurate and
               the user should be wary of the results and perhaps increase
               the parameter PIVOT for subsequent runs (see Section 7).
               Suggested value: GROW = .TRUE..

          14:  ABORT(4) -- LOGICAL array                              Input
               On entry:
                    if ABORT(1) = .TRUE., the routine will exit
                    immediately on detecting a structural singularity (one
                    that depends on the pattern of non-zeros) and return

                    IFAIL = 1; otherwise it will complete the
                    factorization (see Section 8.3).

                    If ABORT(2) = .TRUE., the routine will exit
                    immediately on detecting a numerical singularity (one
                    that depends on the numerical values) and return IFAIL
                    = 2; otherwise it will complete the factorization (see
                    Section 8.3).

                    If ABORT(3) = .TRUE., the routine will exit
                    immediately (with IFAIL = 5) when the arrays A and ICN
                    are filled up by the previously factorized, active and
                    unfactorized parts of the matrix; otherwise it
                    continues so that better guidance on necessary array
                    sizes can be given in IDISP(6) and IDISP(7), and will
                    exit with IFAIL in the range 4 to 6. Note that there
                    is always an immediate error exit if the array IRN is
                    too small.

                    If ABORT(4) = .TRUE., the routine exits immediately
                    (with IFAIL = 13) if it finds duplicate elements in
                    the input matrix. If ABORT(4) = .FALSE., the routine
                    proceeds using a value equal to the sum of the
                    duplicate elements. In either case details of each
                    duplicate element are output on the current advisory
                    message unit (see X04ABF), unless suppressed by the
                    value of IFAIL on entry.
                Suggested values:
                    ABORT(1) = .TRUE.

                    ABORT(2) = .TRUE.

                    ABORT(3) = .FALSE.

                    ABORT(4) = .TRUE..

          15:  IDISP(10) -- INTEGER array                            Output
               On exit: IDISP is used to communicate information about the
               factorization to the user and also between a call of F01BRF
               and subsequent calls to F01BSF or F04AXF.
                    IDISP(1) and IDISP(2), indicate the position in arrays
                    A and ICN of the first and last elements in the LU
                    factorization of the diagonal blocks. (IDISP(2) gives
                    the number of non-zeros in the factorization.)

                    IDISP(3) and IDISP(4), monitor the adequacy of 'elbow
                    room' in the arrays IRN and A/ICN respectively, by
                    giving the number of times that the data in these
                    arrays has been compressed during the factorization to
                    release more storage. If either IDISP(3) or IDISP(4)
                    is quite large (say greater than 10), it will probably
                    pay the user to increase the size of the corresponding
                    array(s) for subsequent runs. If either is very low or
                    zero, then the user can perhaps save storage by
                    reducing the size of the corresponding array(s).

                    IDISP(5), gives an upper bound on the rank of the
                    matrix.

                    IDISP(6) and IDISP(7), give the minimum size of arrays
                    IRN and A/ICN respectively which would enable a
                    successful run on an identical matrix (but some '
                    elbow-room' should be allowed - see Section 8).

                    IDISP(8) to (10), are only used if LBLOCK = .TRUE..

                    IDISP(8), gives the structural rank of the matrix.

                    IDISP(9), gives the number of diagonal blocks.

                    IDISP(10), gives the size of the largest diagonal
                    block.

                    IDISP(1) and IDISP(2), must not be changed by the user
                    between a call of F01BRF and subsequent calls to
                    F01BSF or F04AXF.

          16:  IFAIL -- INTEGER                                Input/Output
               For this routine, the normal use of IFAIL is extended to
               control the printing of error and warning messages as well
               as specifying hard or soft failure (see the Essential
               Introduction).

               Before entry, IFAIL must be set to a value with the decimal
               expansion cba, where each of the decimal digits c, b and a
               must have a value of 0 or 1.
               a=0   specifies hard failure, otherwise soft failure;

               b=0   suppresses error messages, otherwise error messages
                     will be printed (see Section 6);

               c=0   suppresses warning messages, otherwise warning
                     messages will be printed (see Section 6).
               The recommended value for inexperienced users is 110 (i.e.,
               hard failure with all messages printed).

               Unless the routine detects an error (see Section 6), IFAIL
               contains 0 on exit.

          6. Error Indicators and Warnings

          Errors detected by the routine:

          For each error, an explanatory error message is output on the
          current error message unit (as defined by X04AAF), unless
          suppressed by the value of IFAIL on entry.

          IFAIL=-2
               Successful factorization of a numerically singular matrix
               (which may also be structurally singular) (see Section 8.3).

          IFAIL=-1
               Successful factorization of a structurally singular matrix
               (see Section 8.3).

          IFAIL= 1
               The matrix is structurally singular and the factorization
               has been abandoned (ABORT(1) was .TRUE. on entry).

          IFAIL= 2
               The matrix is numerically singular and the factorization has
               been abandoned (ABORT(2) was .TRUE. on entry).

          IFAIL= 3
               LIRN is too small: there is not enough space in the array
               IRN to continue the factorization. The user is recommended
               to try again with LIRN (and the length of IRN) equal to at
               least IDISP(6) + N/2.

          IFAIL= 4
               LICN is much too small: there is much too little space in
               the arrays A and ICN to continue the factorization.

          IFAIL= 5
               LICN is too small: there is not enough space in the arrays A
               and ICN to store the factorization. If ABORT(3) was .FALSE.
               on entry, the factorization has been completed but some of
               the LU factors have been discarded to create space, IDISP(7)
               then gives the minimum value of LICN (i.e., the minimum
               length of A and ICN) required for a successful factorization
               of the same matrix.

          IFAIL= 6
               LICN and LIRN are both too small: effectively this is a
               combination of IFAIL = 3 and IFAIL = 5 (with ABORT(3) = .
               FALSE.).

          IFAIL= 7
               LICN is too small: there is not enough space in the arrays A
               and ICN for the permutation to block triangular form.

          IFAIL= 8
               On entry N <= 0.

          IFAIL= 9
               On entry NZ <= 0.

          IFAIL= 10
               On entry LICN < NZ.

          IFAIL= 11
               On entry LIRN < NZ.

          IFAIL= 12
               On entry an element of the input matrix has a row or column
               index (i.e., an element of IRN or ICN) outside the range 1
               to N.

          IFAIL= 13
               Duplicate elements have been found in the input matrix and
               the factorization has been abandoned (ABORT(4) = .TRUE. on
               entry).

          7. Accuracy

          The factorization obtained is exact for a perturbed matrix whose
          (i,j)th element differs from a   by less than 3(epsilon)(rho)m
                                        ij                              ij
          where (epsilon) is the machine precision, (rho) is the growth
          value returned in W(1) if GROW = .TRUE., and m   the number of
                                                        ij
          Gaussian elimination operations applied to element (i,j). The
          value of m   is not greater than n and is usually much less.
                    ij
          Small (rho) values therefore guarantee accurate results, but
          unfortunately large (rho) values may give a very pessimistic
          indication of accuracy.

          8. Further Comments

          8.1. Timing

          The time required may be estimated very roughly from the number
          (tau) of non-zeros in the factorized form (output as IDISP(2))
          and for this routine and its associates is

                             2
               F01BRF: 5(tau) /n units

                            2
               F01BSF: (tau) /n units

               F04AXF: 2(tau) units

          where our unit is the time for the inner loop of a full matrix
                                                                  1 3
          code (e.g. solving a full set of equations takes about  -n
                                                                  3
          units). Note that the faster F01BSF time makes it well worthwhile
          to use this for a sequence of problems with the same pattern.

          It should be appreciated that (tau) varies widely from problem to
          problem. For network problems it may be little greater than NZ,
          the number of non-zeros in A; for discretisation of 2-dimensional
          and 3-dimensional partial differential equations it may be about
                       1 5/3
          3nlog n and  -n   , respectively.
               2       2

          The time taken to find the block lower triangular form (LBLOCK =
          it is not found (LBLOCK = .FALSE.). If the matrix is irreducible
          (IDISP(9) = 1 after a call with LBLOCK = .TRUE.) then this time
          is wasted. Otherwise, particularly if the largest block is small
          (IDISP(10)<<n), the consequent savings are likely to be greater.

          The time taken to estimate growth (GROW = .TRUE.) is typically
          under 2% of the overall time.

          The overall time may be substantially increased if there is
          inadequate 'elbow-room' in the arrays A, IRN and ICN. When the
          sizes of the arrays are minimal (IDISP(6) and IDISP(7)) it can
          execute as much as three times slower. Values of IDISP(3) and
          IDISP(4) greater than about 10 indicate that it may be worthwhile
          to increase array sizes.

          8.2. Scaling

          The use of a relative pivot tolerance PIVOT essentially
          presupposes that the matrix is well-scaled, i.e., that the matrix
          elements are broadly comparable in size. Practical problems are
          often naturally well-scaled but particular care is needed for
          problems containing mixed types of variables (for example
          millimetres and neutron fluxes).

          8.3. Singular and Rectangular Systems

          It is envisaged that this routine will almost always be called
          for square non-singular matrices and that singularity indicates
          an error condition. However, even if the matrix is singular it is
          possible to complete the factorization. It is even possible for
          F04AXF to solve a set of equations whose matrix is singular
          provided the set is consistent.

          Two forms of singularity are possible. If the matrix would be
          singular for any values of the non-zeros (e.g. if it has a whole
          row of zeros), then we say it is structurally singular, and
          continue only if ABORT(1) = .FALSE.. If the matrix is non-
          singular by virtue of the particular values of the non-zeros,
          then we say that it is numerically singular and continue only if
          ABORT(2) = .FALSE..

          Rectangular matrices may be treated by setting N to the larger of
          the number of rows and numbers of columns and setting ABORT(1) =

          Note: the soft failure option should be used (last digit of IFAIL
          = 1) if the user wishes to factorize singular matrices with ABORT
          (1) or ABORT(2) set to .FALSE..

          8.4. Duplicated Non-zeros

          The matrix A may consist of a sum of contributions from different
          sub-systems (for example finite elements). In such cases the user
          may rely on this routine to perform assembly, since duplicated
          elements are summed.

          9. Example

          To factorize the real sparse matrix:

                                 ( 5  0  0  0 0  0)
                                 ( 0  2 -1  2 0  0)
                                 ( 0  0  3  0 0  0)
                                 (-2  0  0  1 1  0).
                                 (-1  0  0 -1 2 -3)
                                 (-1 -1  0  0 0  6)

          This example program simply prints out some information about the
          factorization as returned by F01BRF in W(1) and IDISP. Normally
          the call of F01BRF would be followed by a call of F04AXF (see
          Example for F04AXF).

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01bsf}{NAG On-line Documentation: f01bsf}
\beginscroll
\begin{verbatim}



     F01BSF(3NAG)      Foundation Library (12/10/92)      F01BSF(3NAG)



          F01 -- Matrix Factorizations                               F01BSF
                  F01BSF -- 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

          F01BSF factorizes a real sparse matrix using the pivotal sequence
          previously obtained by F01BRF when a matrix of the same sparsity
          pattern was factorized.

          2. Specification

                 SUBROUTINE F01BSF (N, NZ, A, LICN, IVECT, JVECT, ICN,
                1                   IKEEP, IW, W, GROW, ETA, RPMIN, ABORT,
                2                   IDISP, IFAIL)
                 INTEGER          N, NZ, LICN, IVECT(NZ), JVECT(NZ), ICN
                1                 (LICN), IKEEP(5*N), IW(8*N), IDISP(2),
                2                 IFAIL
                 DOUBLE PRECISION A(LICN), W(N), ETA, RPMIN
                 LOGICAL          GROW, ABORT

          3. Description

          This routine accepts as input a real sparse matrix of the same
          sparsity pattern as a matrix previously factorized by a call of
          F01BRF. It first applies to the matrix the same permutations as
          were used by F01BRF, both for permutation to block triangular
          form and for pivoting, and then performs Gaussian elimination to
          obtain the LU factorization of the diagonal blocks.

          Extensive data checks are made; duplicated non-zeros can be
          accumulated.

          The factorization is intended to be used by F04AXF to solve
                                                      T
          sparse systems of linear equations Ax=b or A x=b.

          F01BSF is much faster than F01BRF and in some applications it is
          expected that there will be many calls of F01BSF for each call of
          F01BRF.

          The method is fully described in Duff [1].

          4. References

          [1]   Duff I S (1977) MA28 -- a set of Fortran subroutines for
                sparse unsymmetric linear equations. A.E.R.E. Report R.8730.
                HMSO.

          5. Parameters

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

           2:  NZ -- INTEGER                                          Input
               On entry: the number of non-zeros in the matrix A.
               Constraint: NZ > 0.

           3:  A(LICN) -- DOUBLE PRECISION array               Input/Output
               On entry: A(i), for i = 1,2,...,NZ must contain the non-
               zero elements of the sparse matrix A. They can be in any
               order since the routine will reorder them. On exit: the non-
               zero elements in the factorization. The array must not be
               changed by the user between a call of this routine and a
               call of F04AXF.

           4:  LICN -- INTEGER                                        Input
               On entry:
               the dimension of the arrays A and ICN as declared in the
               (sub)program from which F01BSF is called.
               It should have the same value as it had for F01BRF.
               Constraint: LICN >= NZ.

           5:  IVECT(NZ) -- INTEGER array                             Input

           6:  JVECT(NZ) -- INTEGER array                             Input
               On entry: IVECT(i) and JVECT(i), for i = 1,2,...,NZ must
               contain the row index and the column index respectively of
               the non-zero element stored in A(i).

           7:  ICN(LICN) -- INTEGER array                             Input
               On entry: the same information as output by F01BRF. It must
               not be changed by the user between a call of this routine
               and a call of F04AXF.

           8:  IKEEP(5*N) -- INTEGER array                            Input
               On entry: the same indexing information about the
               factorization as output from F01BRF. It must not be changed
               between a call of this routine and a call of F04AXF.

           9:  IW(8*N) -- INTEGER array                           Workspace

          10:  W(N) -- DOUBLE PRECISION array                        Output
               On exit: if GROW = .TRUE., W(1) contains an estimate (an
               upper bound) of the increase in size of elements encountered
               during the factorization (see GROW); the rest of the array
               is used as workspace.

               If GROW = .FALSE., the array is not used.

          11:  GROW -- LOGICAL                                        Input
               On entry: if GROW = .TRUE., then on exit W(1) contains an
               estimate (an upper bound) of the increase in size of
               elements encountered during the factorization. If the matrix
               is well-scaled (see Section 8.2), then a high value for W(1)
               indicates that the LU factorization may be inaccurate and
               the user should be wary of the results and perhaps increase
               the parameter PIVOT for subsequent runs (see Section 7).

          12:  ETA -- DOUBLE PRECISION                                Input
               On entry: the relative pivot threshold below which an error
               diagnostic is provoked and IFAIL is set to 7. If ETA is
               greater than 1.0, then no check on pivot size is made.
                                        -4
               Suggested value: ETA = 10  .

          13:  RPMIN -- DOUBLE PRECISION                             Output
               On exit: if ETA is less than 1.0, then RPMIN gives the
               smallest ratio of the pivot to the largest element in the
               row of the corresponding upper triangular factor thus
               monitoring the stability of the factorization. If RPMIN is
               very small it may be advisable to perform a new
               factorization using F01BRF.

          14:  ABORT -- LOGICAL                                       Input
               On entry: if ABORT = .TRUE., the routine exits immediately
               (with IFAIL = 8) if it finds duplicate elements in the input
               matrix. If ABORT = .FALSE., the routine proceeds using a
               value equal to the sum of the duplicate elements. In either
               case details of each duplicate element are output on the
               current advisory message unit (see X04ABF), unless
               suppressed by the value of IFAIL on entry. Suggested value:
               ABORT = .TRUE..

          15:  IDISP(2) -- INTEGER array                              Input
               On entry: IDISP(1) and IDISP(2) must be unchanged since the
               previous call of F01BRF.

          16:  IFAIL -- INTEGER                                Input/Output
               For this routine, the normal use of IFAIL is extended to
               control the printing of error and warning messages as well
               as specifying hard or soft failure (see the Essential
               Introduction).

               Before entry, IFAIL must be set to a value with the decimal
               expansion cba, where each of the decimal digits c, b and a
               must have a value of 0 or 1.
               a=0   specifies hard failure, otherwise soft failure;

               b=0   suppresses error messages, otherwise error messages
                     will be printed (see Section 6);

               c=0   suppresses warning messages, otherwise warning
                     messages will be printed (see Section 6).
               The recommended value for inexperienced users is 110 (i.e.,
               hard failure with all messages printed).

               Unless the routine detects an error (see Section 6), IFAIL
               contains 0 on exit.

          6. Error Indicators and Warnings

          Errors detected by the routine:

          For each error, an explanatory error message is output on the
          current error message unit (as defined by X04AAF), unless
          suppressed by the value of IFAIL on entry.

          IFAIL= 1
               On entry N <= 0.

          IFAIL= 2
               On entry NZ <= 0.

          IFAIL= 3
               On entry LICN < NZ.

          IFAIL= 4
               On entry an element of the input matrix has a row or column
               index (i.e., an element of IVECT or JVECT) outside the range
               1 to N.

          IFAIL= 5
               The input matrix is incompatible with the matrix factorized
               by the previous call of F01BRF (see Section 8).

          IFAIL= 6
               The input matrix is numerically singular.

          IFAIL= 7
               A very small pivot has been detected (see Section 5, ETA).
               The factorization has been completed but is potentially
               unstable.

          IFAIL= 8
               Duplicate elements have been found in the input matrix and
               the factorization has been abandoned (ABORT = .TRUE. on
               entry).

          7. Accuracy

          The factorization obtained is exact for a perturbed matrix whose
          (i,j)th element differs from a   by less than 3(epsilon)(rho)m
                                        ij                              ij
          where (epsilon) is the machine precision, (rho) is the growth
          value returned in W(1) if GROW = .TRUE., and m   the number of
                                                        ij
          Gaussian elimination operations applied to element (i,j).

          If (rho) = W(1) is very large or RPMIN is very small, then a
          fresh call of F01BRF is recommended.

          8. Further Comments

          If the user has a sequence of problems with the same sparsity
          pattern then this routine is recommended after F01BRF has been
          called for one such problem. It is typically 4 to 7 times faster
          but is potentially unstable since the previous pivotal sequence
          is used. Further details on timing are given in document F01BRF.

          If growth estimation is performed (GROW = .TRUE.), then the time
          increases by between 5% and 10%. Pivot size monitoring (ETA <= 1.
          0) involves a similar overhead.

          We normally expect this routine to be entered with a matrix
          having the same pattern of non-zeros as was earlier presented to
          F01BRF. However there is no record of this pattern, but rather a
          record of the pattern including all fill-ins. Therefore we permit
          additional non-zeros in positions corresponding to fill-ins.

          If singular matrices are being treated then it is also required
          that the present matrix be sufficiently like the previous one for
          the same permutations to be suitable for factorization with the
          same set of zero pivots.

          9. Example

          To factorize the real sparse matrices

                                 ( 5  0  0  0 0  0)
                                 ( 0  2 -1  2 0  0)
                                 ( 0  0  3  0 0  0)
                                 (-2  0  0  1 1  0)
                                 (-1  0  0 -1 2 -3)
                                 (-1 -1  0  0 0  6)

          and

                                (10  0  0  0  0  0)
                                ( 0 12 -3 -1  0  0)
                                ( 0  0 15  0  0  0)
                                (-2  0  0 10 -1  0).
                                (-1  0  0 -5  1 -1)
                                (-1 -2  0  0  0  6)

          This example program simply prints the values of W(1) and RPMIN
          returned by F01BSF. Normally the calls of F01BRF and F01BSF would
          be followed by calls of F04AXF.

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01maf}{NAG On-line Documentation: f01maf}
\beginscroll
\begin{verbatim}



     F01MAF(3NAG)      Foundation Library (12/10/92)      F01MAF(3NAG)



          F01 -- Matrix Factorizations                               F01MAF
                  F01MAF -- 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

          F01MAF computes an incomplete Cholesky factorization of a real
          sparse symmetric positive-definite matrix A.

          2. Specification

                 SUBROUTINE F01MAF (N, NZ, A, LICN, IRN, LIRN, ICN, DROPTL,
                1                   DENSW, WKEEP, IKEEP, IWORK, ABORT,
                2                   INFORM, IFAIL)
                 INTEGER          N, NZ, LICN, IRN(LIRN), LIRN, ICN(LICN),
                1                 IKEEP(2*N), IWORK(6*N), INFORM(4), IFAIL
                 DOUBLE PRECISION A(LICN), DROPTL, DENSW, WKEEP(3*N)
                 LOGICAL          ABORT(3)

          3. Description

          F01MAF computes an incomplete Cholesky factorization

                                      T T
                                C=PLDL P ,   WAW=C+E

          for the sparse symmetric positive-definite matrix A, where P is a
          permutation matrix, L is a unit lower triangular matrix, D is a
          diagonal matrix with positive diagonal elements, E is an error
          matrix representing elements dropped during the factorization and
          diagonal elements that have been modified to ensure that C is
          positive-definite, and W is a diagonal matrix, chosen to make the
          diagonal elements of WAW unity.

           -1  -1
          W  CW   is a pre-conditioning matrix for A, and the factorization
          of C is intended to be used by F04MAF to solve systems of linear
          equations Ax=b.

          The permutation matrix P is chosen to reduce the amount of fill-
          in that occurs in L and the user-supplied parameter DROPTL can
          also be used to control the amount of fill-in that occurs.

          Full details on the factorization can be found in Munksgaard [1].

          F01MAF is based on the Harwell Library routine MA31A.

          4. References

          [1]   Munksgaard N (1980) Solving Sparse Symmetric Sets of Linear
                Equations by Pre-conditioned Conjugate Gradients. ACM Trans.
                Math. Softw. 6 206--219.

          5. Parameters

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

           2:  NZ -- INTEGER                                          Input
               On entry: the number of non-zero elements in the upper
               triangular part of the matrix A, including the number of
               elements on the leading diagonal. Constraint: NZ >= N.

           3:  A(LICN) -- DOUBLE PRECISION array               Input/Output
               On entry: the first NZ elements of the array A must contain
               the non-zero elements of the upper triangular part of the
               sparse positive-definite symmetric matrix A, including the
               elements on the leading diagonal. On exit: the first (NZ-N)
               elements of A contain the elements above the diagonal of the
               matrix WAW, where W is a diagonal matrix whose ith diagonal
                              -1/2
               element is w =a    . These elements are returned in order by
                           i  ii
               rows and the value returned in ICN(k) gives the column index
               of the element returned in A(k). The value w  is returned in
                                                           i
               the ith element of the array WKEEP. The remaining LROW-NZ+N
               elements of A, where LROW is the value returned in INFORM(1),
               return details of the factorization for use by F04MAF.

           4:  LICN -- INTEGER                                        Input
               On entry:
               the dimension of the array A as declared in the (sub)program
               from which F01MAF is called.
               If fill-in is expected during the factorization, then a
               larger value of LICN will allow fewer elements to be dropped
               during the factorization, thus giving a more accurate
               factorization, which in turn will almost certainly mean that
               fewer iterations will be required by F04MAF. Constraint:
               LICN>=2*NZ.

           5:  IRN(LIRN) -- INTEGER array                      Input/Output
               On entry: IRN(k), for k = 1,2,...,NZ must contain the row
               index of the non-zero element of the matrix A supplied in A
               (k). On exit: the first LCOL elements of IRN, where LCOL is
               the value returned in INFORM(2), return details of the
               factorization for use by F04MAF.

           6:  LIRN -- INTEGER                                        Input
               On entry:
               the dimension of the array IRN as declared in the
               (sub)program from which F01MAF is called.
               LIRN must be at least NZ, but, as with LICN, if fill-in is
               expected then a larger value of LIRN will allow a more
               accurate factorization. For this purpose LIRN should exceed
               NZ by the same amount that LICN exceeds 2*NZ. Constraint:
               LIRN >= NZ.

           7:  ICN(LICN) -- INTEGER array                      Input/Output
               On entry: ICN(k), for k = 1,2,...,NZ must contain the column
               index of the non-zero element of the matrix A supplied in A
               (k). Thus a  =A(k), where i = IRN(k) and j = ICN(k). On
                          ij
               exit: the first (NZ-N) elements of ICN give the column
               indices of the first (NZ-N) elements returned in A. The
               remaining LROW - NZ + N elements of ICN return details of
               the factorization for use by F04MAF.

           8:  DROPTL -- DOUBLE PRECISION                      Input/Output
               On entry: a value in the range [-1.0,1.0] to be used as a
               tolerance in deciding whether or not to drop elements during
                                                                     (k+1)
               the factorization. At the kth pivot step the element a
                                                                     ij
               is dropped if it would cause fill-in and if
                                                   

                               (k+1)              / (k) (k)
                             |a     |<|DROPTL|*  / a   a   .
                               ij              \/   ii  jj
               If DROPTL is supplied as negative, then it is not altered
               during the factorization and so is unchanged on exit, but if
               DROPTL is supplied as positive then it may be altered by the
               routine with the aim of obtaining an accurate factorization
               in the space available. If DROPTL is supplied as -1.0, then
               no fill-in will occur during the factorization; and if
               DROPTL is supplied as 0.0 then a complete factorization is
               performed. On exit: may be overwritten with the value used
               by the routine in order to obtain an accurate factorization
               in the space available, if DROPTL > 0.0 on entry.

           9:  DENSW -- DOUBLE PRECISION                       Input/Output
               On entry: a value in the range [0.0,1.0] to be used in
               deciding whether or not to regard the active part of the
               matrix at the kth pivot step as being full. If the ratio of
               non-zero elements to the total number of elements is greater
               than or equal to DENSW, then the active part is regarded as
               full. If DENSW < 1.0, then the storage used is likely to
               increase compared to the case where DENSW = 0, but the
               execution time is likely to decrease. Suggested value: DENSW
               = 0.8. On exit: if on entry DENSW is not in the range
               [0.0,1.0], then it is set to 0.8. Otherwise it is unchanged.

          10:  WKEEP(3*N) -- DOUBLE PRECISION array                  Output
               On exit: information which must be passed unchanged to
               F04MAF. The first N elements contain the values w , for
                                                                i
               i=1,2,...,n, and the next N elements contain the diagonal
               elements of D.

          11:  IKEEP(2*N) -- INTEGER array                           Output
               On exit: information which must be passed unchanged to
               F04MAF.

          12:  IWORK(6*N) -- INTEGER array                        Workspace

          13:  ABORT(3) -- LOGICAL array                              Input
               On entry:
                    if ABORT(1) = .TRUE., the routine will exit
                    immediately on detecting duplicate elements and return
                    IFAIL = 5. Otherwise when ABORT(1) = .FALSE., the
                    calculations will continue using the sum of the
                    duplicate entries. In either case details of the
                    duplicate elements are output on the current advisory
                    message unit (see X04ABF), unless suppressed by the
                    value of IFAIL on entry.

                    If ABORT(2) = .TRUE., the routine will exit
                    immediately on detecting a zero or negative pivot
                    element and return IFAIL = 6. Otherwise when ABORT(2)
                    = .FALSE., the zero or negative pivot element will be
                    modified to ensure positive-definiteness and a message
                    will be printed on the current advisory message unit,
                    unless suppressed by the value of IFAIL on entry.

                    If ABORT(3) = .TRUE., the routine will exit
                    immediately if the arrays A and ICN have been filled
                    up and return IFAIL = 7. Otherwise when ABORT(3) = .
                    FALSE., the data in the arrays is compressed to
                    release more storage and a message will be printed on
                    the current advisory message unit, unless suppressed
                    by the value of IFAIL on entry. If DROPTL is positive
                    on entry, it may be modified in order to allow a
                    factorization to be completed in the available space.
               Suggested values:
                    ABORT(1) = .TRUE.,

                    ABORT(2) = .TRUE.,

                    ABORT(3) = .TRUE..

          14:  INFORM(4) -- INTEGER array                            Output
               On exit:
                    INFORM(1) returns the number of elements of A and ICN
                    that have been used by the routine. Thus at least the
                    first INFORM(1) elements of A and of ICN must be
                    supplied to F04MAF.

                    Similarly, INFORM(2) returns the number of elements of
                    IRN that have been used by the routine and so at least
                    the first INFORM(2) elements must be supplied to
                    F04MAF.

                    INFORM(3) returns the number of entries supplied in A
                    that corresponded to diagonal and duplicate elements.
                    If no duplicate entries were found, then INFORM(3)
                    will return the value of N.

                    INFORM(4) returns the value k of the pivot step from
                    which the active matrix was regarded as full.
               INFORM must be passed unchanged to F04MAF.

          15:  IFAIL -- INTEGER                                Input/Output
               For this routine, the normal use of IFAIL is extended to
               control the printing of error and warning messages as well
               as specifying hard or soft failure (see the Essential
               Introduction).

               Before entry, IFAIL must be set to a value with the decimal
               expansion cba, where each of the decimal digits c, b and a
               must have a value of 0 or 1.
               a=0   specifies hard failure, otherwise soft failure;

               b=0   suppresses error messages, otherwise error messages
                     will be printed (see Section 6);

               c=0   suppresses warning messages, otherwise warning
                     messages will be printed (see Section 6).
               The recommended value for inexperienced users is 110 (i.e.,
               hard failure with all messages printed).

               Unless the routine detects an error (see Section 6), IFAIL
               contains 0 on exit.

          6. Error Indicators and Warnings

          Errors detected by the routine:

          For each error, an explanatory error message is output on the
          current error message unit (as defined by X04AAF), unless
          suppressed by the value of IFAIL on entry.

          IFAIL= 1
               On entry N < 1,

               or       NZ < N,

               or       LIRN < NZ,

               or       LICN<2*NZ.

          IFAIL= 2
               One of the conditions 0 < IRN(k) <= ICN(k) <= N is not
               satisfied so that A(k) is not in the upper triangle of the
               matrix. No further computation is attempted.

          IFAIL= 3
               One of the diagonal elements of the matrix A is zero or
               negative so that A is not positive-definite. No further
               computation is attempted.

          IFAIL= 4
               The available space has been used and no further
               compressions are possible. The user should either increase
               DROPTL, or allocate more space to A, IRN and ICN.

               For all the remaining values of IFAIL the computations will
               continue in the case of soft failure, so that more than one
               advisory message may be printed.

          IFAIL= 5
               Duplicate elements have been detected and ABORT(1) = .TRUE..

          IFAIL= 6
               A zero or negative pivot element has been detected during
               the factorization and ABORT(2) = .TRUE..

               This should not happen if A is an M-matrix (see Munksgaard
               [1]), but may occur for other types of positive-definite
               matrix.

          IFAIL= 7
               The available space has been used and ABORT(3) = .TRUE..

          7. Accuracy

          The accuracy of the factorization will be determined by the size
          of the elements that are dropped and the size of the
          modifications made to the diagonal elements. If these sizes are
          small then the computed factors will correspond to a matrix close
          to A and the number of iterations required by F04MAF will be
          small. The more incomplete the factorization, the higher the
          number of iterations required by F04MAF.

          8. Further Comments

          The time taken by the routine will depend upon the sparsity
          pattern of the matrix and the number of fill-ins that occur
          during the factorization. At the very least the time taken can be
          expected to be roughly proportional to n(tau), where (tau) is the
          number of non-zeros.
          The routine is intended for use with positive-definite matrices,
          but the user is warned that it will not necessarily detect non-
          positive-definiteness. Indeed the routine may return a
          factorization that can satisfactorily be used by F04MAF even when
          A is not positive-definite, but this should not be relied upon as
          F04MAF may not converge.

          9. Example

          The example program illustrates the use of F01MAF in conjunction
          with F04MAF to solve the 16 linear equations Ax=b, where

                          (1 z     z                      )
                          (z 1 z     z                    )
                          (  z 1 z     z                  )
                          (    z 1 0     z                )
                          (z     0 1 z     z              )
                          (  z     z 1 z     z            )
                          (    z     z 1 z     z          )
                          (      z     z 1 0     z        )
                        A=(        z     0 1 z     z      ).
                          (          z     z 1 z     z    )
                          (            z     z 1 z     z  )
                          (              z     z 1 0     z)
                          (                z     0 1 z    )
                          (                  z     z 1 z  )
                          (                    z     z 1 z)
                          (                      z     z 1)

           T ( 1  1  1  1  1      1  1      1  1  1  1  1)
          b =( -  -  -  -  - 0 0  -  - 0 0  -  -  -  -  -),
             ( 2  4  4  2  4      4  4      4  2  4  4  2)

                    1
          where z=- -.
                    4

          The n by n matrix A arises in the solution of Laplace's equation
          in a unit square, using a 5-point formula with a 6 by 6
          discretisation, with unity on the boundaries.

          The drop tolerance, DROPTL, is taken as 0.1, and the density
          factor, DENSW, is taken as 0.8. The value IFAIL = 111 is used so
          that advisory and error messages will be printed, but soft
          failure would occur if IFAIL were returned as non-zero.

          A relative accuracy of about 0.0001 is requested in the solution
          from F04MAF, with a maximum of 50 iterations.

          The example program for F02FJF illustrates the use of F01MAF and
          F04MAF in solving an eigenvalue problem.

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01mcf}{NAG On-line Documentation: f01mcf}
\beginscroll
\begin{verbatim}



     F01MCF(3NAG)      Foundation Library (12/10/92)      F01MCF(3NAG)



          F01 -- Matrix Factorizations                               F01MCF
                  F01MCF -- 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

          F01MCF computes the Cholesky factorization of a real symmetric
          positive-definite variable-bandwidth matrix.

          2. Specification

                 SUBROUTINE F01MCF (N, A, LAL, NROW, AL, D, IFAIL)
                 INTEGER          N, LAL, NROW(N), IFAIL
                 DOUBLE PRECISION A(LAL), AL(LAL), D(N)

          3. Description

          This routine determines the unit lower triangular matrix L and
                                                                   T
          the diagonal matrix D in the Cholesky factorization A=LDL  of a
          symmetric positive-definite variable-bandwidth matrix A of order
          n. (Such a matrix is sometimes called a 'sky-line' matrix.)

          The matrix A is represented by the elements lying within the
          envelope of its lower triangular part, that is, between the first
          non-zero of each row and the diagonal (see Section 9 for an
          example). The width NROW(i) of the ith row is the number of
          elements between the first non-zero element and the element on
          the diagonal, inclusive. Although, of course, any matrix
          possesses an envelope as defined, this routine is primarily
          intended for the factorization of symmetric positive-definite
          matrices with an average bandwidth which is small compared with n
          (also see Section 8).

          The method is based on the property that during Cholesky
          factorization there is no fill-in outside the envelope.

          The determination of L and D is normally the first of two steps
          in the solution of the system of equations Ax=b. The remaining
                                        T
          step, viz. the solution of LDL x=b may be carried out using
          F04MCF.

          4. References

          [1]   Jennings A (1966) A Compact Storage Scheme for the Solution
                of Symmetric Linear Simultaneous Equations. Comput. J. 9
                281--285.

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

          5. Parameters

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

           2:  A(LAL) -- DOUBLE PRECISION array                       Input
               On entry: the elements within the envelope of the lower
               triangle of the positive-definite symmetric matrix A, taken
               in row by row order. The following code assigns the matrix
               elements within the envelope to the correct elements of the
               array:

                     K = 0
                     DO 20 I = 1, N
                     DO 10 J = I-NROW(I)+1, I
                     K = K + 1
                     A(K) = matrix (I,J)
                     10    CONTINUE
                     20 CONTINUE

               See also Section 8.

           3:  LAL -- INTEGER                                         Input
               On entry: the smaller of the dimensions of the arrays A and
               AL as declared in the calling (sub)program from which F01MCF
               is called. Constraint: LAL >= NROW(1) + NROW(2) +... + NROW(
               n).

           4:  NROW(N) -- INTEGER array                               Input
               On entry: NROW(i) must contain the width of row i of the
               matrix A, i.e., the number of elements between the first
               (leftmost) non-zero element and the element on the diagonal,
               inclusive. Constraint: 1 <= NROW(i) <= i, for i=1,2,...,n.

           5:  AL(LAL) -- DOUBLE PRECISION array                     Output
               On exit: the elements within the envelope of the lower
               triangular matrix L, taken in row by row order. The envelope
               of L is identical to that of the lower triangle of A. The
               unit diagonal elements of L are stored explicitly. See also
               Section 8.

           6:  D(N) -- DOUBLE PRECISION array                        Output
               On exit: the diagonal elements of the the diagonal matrix D
               . Note that the determinant of A is equal to the product of
               these diagonal elements. If the value of the determinant is
               required it should not be determined by forming the product
               explicitly, because of the possibility of overflow or
               underflow. The logarithm of the determinant may safely be
               formed from the sum of the logarithms of the diagonal
               elements.

           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
               On entry N < 1,

               or       for some i, NROW(i) < 1 or NROW(i) > i,

               or       LAL < NROW(1) + NROW(2) +... + NROW(N).

          IFAIL= 2
               A is not positive-definite, or this property has been
               destroyed by rounding errors. The factorization has not been
               completed.

          IFAIL= 3
               A is not positive-definite, or this property has been
               destroyed by rounding errors. The factorization has been
               completed but may be very inaccurate (see Section 7).

          7. Accuracy

          If IFAIL = 0 on exit, then the computed L and D satisfy the
                      T
          relation LDL =A+F, where

                                        2
                              ||F|| <=km (epsilon)max a
                                   2                 i ii

          and

                                       2
                             ||F|| <=km (epsilon)||A|| ,
                                  2                   2

          where k is a constant of order unity, m is the largest value of
          NROW(i), and (epsilon) is the machine precision. See Wilkinson
          and Reinsch [2], pp 25--27, 54--55. If IFAIL = 3 on exit, then
          the factorization has been completed although the matrix was not
          positive-definite. However the factorization may be very
          inaccurate and should be used only with great caution. For
          instance, if it is used to solve a set of equations Ax=b using
          F04MCF, the residual vector b-Ax should be checked.

          8. Further Comments

          The time taken by the routine is approximately proportional to
          the sum of squares of the values of NROW(i).

          The distribution of row widths may be very non-uniform without
          undue loss of efficiency. Moreover, the routine has been designed
          to be as competitive as possible in speed with routines designed
          for full or uniformly banded matrices, when applied to such
          matrices.

          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 AL, in which case L
          overwrites the lower triangle of A. However this is not standard
          Fortran 77 and may not work in all implementations.

          9. Example

          To obtain the Cholesky factorization of the symmetric matrix,
          whose lower triangle is:

                                 (1               )
                                 (2  5            )
                                 (0  3 13         )
                                 (0  0  0 16      ).
                                 (5 14 18  8 55   )
                                 (0  0  0 24 17 77)

          For this matrix, the elements of NROW must be set to 1, 2, 2, 1,
          5, 3, and the elements within the envelope must be supplied in
          row order as:

          1, 2, 5, 3, 13, 16, 5, 14, 18, 8, 55, 24, 17, 77.


          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01qcf}{NAG On-line Documentation: f01qcf}
\beginscroll
\begin{verbatim}



     F01QCF(3NAG)      Foundation Library (12/10/92)      F01QCF(3NAG)



          F01 -- Matrix Factorizations                               F01QCF
                  F01QCF -- 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

          F01QCF finds the QR factorization of the real m by n matrix A,
          where m>=n.

          2. Specification

                 SUBROUTINE F01QCF (M, N, A, LDA, ZETA, IFAIL)
                 INTEGER          M, N, LDA, IFAIL
                 DOUBLE PRECISION A(LDA,*), ZETA(*)

          3. Description

          The m by n matrix A is factorized as

                    (R)
                 A=Q(0)       when m>n,

                 A=QR         when m=n,

          where Q is an m by m orthogonal matrix and R is an n by n upper
          triangular matrix. The factorization is obtained by Householder's
          method. The kth transformation matrix, Q , which is used to
                                                  k
          introduce zeros into the kth column of A is given in the form

                                         (I 0 )
                                      Q =(0 T )
                                       k (   k)

          where

                                             T
                                     T =I-u u ,
                                      k    k k

                                       ((zeta) )
                                       (      k)
                                    u =(z      ),
                                     k ( k     )

          (zeta)  is a scalar and z  is an (m-k) element vector. (zeta)
                k                  k                                   k
          and z  are chosen to annihilate the elements below the triangular
               k
          part of A.

          The vector u  is returned in the kth element of the array ZETA
                      k
          and in the kth column of A, such that (zeta)  is in ZETA(k) and
                                                      k
          the elements of z  are in A(k+1,k),...,A(m,k). The elements of R
                           k
          are returned in the upper triangular part of A.

          Q is given by

                                                 T
                                  Q=(Q Q   ...Q ) .
                                      n n-1    1

          Good background descriptions to the QR factorization are given in
          Dongarra et al [1] and Golub and Van Loan [2], but note that this
          routine is not based upon LINPACK routine DQRDC.

          4. References

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

          [2]   Golub G H and Van Loan C F (1989) Matrix Computations (2nd
                Edition). Johns Hopkins University Press, Baltimore,
                Maryland.

          [3]   Wilkinson J H (1965) The Algebraic Eigenvalue Problem.
                Oxford University Press.

          5. Parameters

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

           2:  N -- INTEGER                                           Input
               On entry: n, the number of columns of A.

               When N = 0 then an immediate return is effected.
               Constraint: N >= 0.

           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 to be factorized. On exit: the n by n
               upper triangular part of A will contain the upper triangular
               matrix R and the m by n strictly lower triangular part of A
               will contain details of the factorization as described in
               Section 3.

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

           5:  ZETA(*) -- DOUBLE PRECISION array                     Output
               Note: the dimension of the array ZETA must be at least max
               (1,n) On exit: ZETA(k) contains the scalar (zeta)  for the k
                                                                k
               th transformation. If T =I then ZETA(k)=0.0, otherwise ZETA(
                                      k
               k) contains (zeta)  as described in Section 3 and (zeta)  is
                                 k                                     k

               always in the range (1.0, \/2.0).

           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:

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

          IFAIL=-1
               On entry M < N,

               or       N < 0,

               or       LDA < M.

          7. Accuracy

          The computed factors Q and R satisfy the relation

                                       (R)
                                      Q(0)=A+E,

          where

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

          and (epsilon) is the machine precision (see X02AJF(*)), c is a
          modest function of m and n and |||.||| denotes the spectral (two)
          norm.

          8. Further Comments

          The approximate number of floating-point operations is given by
            2
          2n (3m-n)/3.

          Following the use of this routine the operations

                                                 T
                                 B:=QB  and  B:=Q B,

          where B is an m by k matrix, can be performed by calls to F01QDF.
          The operation B:=QB can be obtained by the call:


                IFAIL = 0
                CALL F01QDF('No transpose', 'Separate', M, N, A, LDA, ZETA,
               *            K, B, LDB, WORK, IFAIL)

                  T
          and B:=Q B can be obtained by the call:


                IFAIL = 0
                CALL F01QDF('Transpose', 'Separate', M, N, A, LDA, ZETA,
               *            K, B, LDB, WORK, IFAIL)

          In both cases WORK must be a k element array that is used as
          workspace. If B is a one-dimensional array (single column) then
          the parameter LDB can be replaced by M. See F01QDF for further
          details.

          The first k columns of the orthogonal matrix Q can either be
          obtained by setting B to the first k columns of the unit matrix
          and using the first of the above two calls, or by calling F01QEF,
          which overwrites the k columns of Q on the first k columns of the
          array A. Q is obtained by the call:


               CALL F01QEF('Separate', M, N, K, A, LDA, ZETA, WORK, IFAIL)

          As above WORK must be a k element array. If k is larger than N,
          then A must have been declared to have at least k columns.

          Operations involving the matrix R can readily be performed by the
          Level 2 BLAS routines DTRSV and DTRMV (see Chapter F06), but note
          that no test for near singularity of R is incorporated in DTRSV.
          If R is singular, or nearly singular then F02WUF(*) can be used
          to determine the singular value decomposition of R.

          9. Example

          To obtain the QR factorization 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)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01qdf}{NAG On-line Documentation: f01qdf}
\beginscroll
\begin{verbatim}



     F01QDF(3NAG)      Foundation Library (12/10/92)      F01QDF(3NAG)



          F01 -- Matrix Factorizations                               F01QDF
                  F01QDF -- 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

          F01QDF performs one of the transformations

                                               T
                                  B:=QB or B:=Q B,

          where B is an m by ncolb real matrix and Q is an m by m
          orthogonal matrix, given as the product of Householder
          transformation matrices.

          This routine is intended for use following F01QCF or F01QFF(*).

          2. Specification

                 SUBROUTINE F01QDF (TRANS, WHERET, M, N, A, LDA, ZETA,
                1                   NCOLB, B, LDB, WORK, IFAIL)
                 INTEGER          M, N, LDA, NCOLB, LDB, IFAIL
                 DOUBLE PRECISION A(LDA,*), ZETA(*), B(LDB,*), WORK(*)
                 CHARACTER*1      TRANS, WHERET

          3. Description

          Q is assumed to be given by

                                                 T
                                  Q=(Q Q   ...Q ) ,
                                      n n-1    1

          Q  being given in the form
           k

                                         (I 0 )
                                      Q =(0 T )
                                       k (   k)

          where

                                             T
                                     T =I-u u ,
                                      k    k k

                                       ((zeta) )
                                       (      k)
                                    u =(z      ),
                                     k ( k     )

          (zeta)  is a scalar and z  is an (m-k) element vector. z  must be
                k                  k                              k
          supplied in the kth column of A in elements A(k+1,k),...,A(m,k)
          and (zeta)  must be supplied either in A(k,k) or in ZETA(k),
                    k
          depending upon the parameter WHERET.

          To obtain Q explicitly B may be set to I and pre-multiplied by Q.
                                                 T
          This is more efficient than obtaining Q .

          4. References

          [1]   Golub G H and Van Loan C F (1989) Matrix Computations (2nd
                Edition). Johns Hopkins University Press, Baltimore,
                Maryland.

          [2]   Wilkinson J H (1965) The Algebraic Eigenvalue Problem.
                Oxford University Press.

          5. Parameters

           1:  TRANS -- CHARACTER*1                                   Input
               On entry: the operation to be performed as follows:
               TRANS = 'N' (No transpose)
                     Perform the operation B:=QB.

               TRANS = 'T' or 'C' (Transpose)
                                               T
                     Perform the operation B:=Q B.
                Constraint: TRANS must be one of 'N', 'T' or 'C'.

           2:  WHERET -- CHARACTER*1                                  Input
               On entry: indicates where the elements of (zeta) are to be
               found as follows:
               WHERET = 'I' (In A)
                     The elements of (zeta) are in A.

               WHERET = 'S' (Separate)
                     The elements of (zeta) are separate from A, in ZETA.
               Constraint: WHERET must be one of 'I' or 'S'.

           3:  M -- INTEGER                                           Input
               On entry: m, the number of rows of A. Constraint: M >= N.

           4:  N -- INTEGER                                           Input
               On entry: n, the number of columns of A.

               When N = 0 then an immediate return is effected.
               Constraint: N >= 0.

           5:  A(LDA,*) -- DOUBLE PRECISION array                     Input
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the leading m by n strictly lower triangular part
               of the array A must contain details of the matrix Q. In
               addition, when WHERET = 'I', then the diagonal elements of A
               must contain the elements of (zeta) as described under the
               argument ZETA below.

               When WHERET = 'S', the diagonal elements of the array A are
               referenced, since they are used temporarily to store the
               (zeta) , but they contain their original values on return.
                     k

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

           7:  ZETA(*) -- DOUBLE PRECISION array                      Input
               Note: when WHERET = 'S', the dimension of the array ZETA
               must be greater than or equal to max(1,N). On entry: if
               WHERET = 'S', the array ZETA must contain the elements of
               (zeta). If ZETA(k) = 0.0 then T  is assumed to be I
                                              k
               otherwise ZETA(k) is assumed to contain (zeta) .
                                                             k

               When WHERET = 'I', ZETA is not referenced.

           8:  NCOLB -- INTEGER                                       Input
               On entry: ncolb, number of columns of B.

               When NCOLB = 0 then an immediate return is effected.
               Constraint: NCOLB >= 0.

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

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

          11:  WORK(*) -- DOUBLE PRECISION array                  Workspace
               Note: the dimension of the array WORK must be at least
               max(1,NCOLB).

          12:  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
               On entry TRANS /= 'N', 'T' or 'C',

               or       WHERET /= 'I' or 'S',

               or       M < N,

               or       N < 0,

               or       LDA < M,

               or       NCOLB < 0,

               or       LDB < M.

          7. Accuracy

                                                T
          Letting C denote the computed matrix Q B, C satisfies the
          relation

                                       QC=B+E,

          where

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

          and (epsilon) the machine precision (see X02AJF(*)), c is a
          modest function of m and |||.||| denotes the spectral (two) norm.
          An equivalent result holds for the computed matrix QB. See also
          Section 7 of F01QCF.

          8. Further Comments

          The approximate number of floating-point operations is given by
          2n(2m-n)ncolb.

          9. Example

                                T
          To obtain the matrix Q B for the matrix B given by

                                     ( 1.1  0.00)
                                     ( 0.9  0.00)
                                   B=( 0.6  1.32)
                                     ( 0.0  1.10)
                                     (-0.8 -0.26)

          following the QR factorization of the 5 by 3 matrix A given by

                                   (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)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01qef}{NAG On-line Documentation: f01qef}
\beginscroll
\begin{verbatim}



     F01QEF(3NAG)      Foundation Library (12/10/92)      F01QEF(3NAG)



          F01 -- Matrix Factorizations                               F01QEF
                  F01QEF -- 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

          F01QEF returns the first ncolq columns of the real m by m
          orthogonal matrix Q, where Q is given as the product of
          Householder transformation matrices.

          This routine is intended for use following F01QCF or F01QFF(*).

          2. Specification

                 SUBROUTINE F01QEF (WHERET, M, N, NCOLQ, A, LDA, ZETA,
                1                   WORK, IFAIL)
                 INTEGER          M, N, NCOLQ, LDA, IFAIL
                 DOUBLE PRECISION A(LDA,*), ZETA(*), WORK(*)
                 CHARACTER*1      WHERET

          3. Description

          Q is assumed to be given by

                                                 T
                                  Q=(Q Q   ...Q ) ,
                                      n n-1    1

          Q  being given in the form
           k

                                         (I 0 )
                                      Q =(0 T )
                                       k (   k)

          where

                                             T
                                     T =I-u u ,
                                      k    k k

                                       ((zeta) )
                                       (      k)
                                    u =(z      ),
                                     k ( k     )

          (zeta)  is a scalar and z  is an (m-k) element vector. z  must be
                k                  k                              k
          supplied in the kth column of A in elements A(k+1,k),...,A(m,k)
          and (zeta)  must be supplied either in A(k,k) or in ZETA(k),
                    k
          depending upon the parameter WHERET.

          4. References

          [1]   Golub G H and Van Loan C F (1989) Matrix Computations (2nd
                Edition). Johns Hopkins University Press, Baltimore,
                Maryland.

          [2]   Wilkinson J H (1965) The Algebraic Eigenvalue Problem.
                Oxford University Press.

          5. Parameters

           1:  WHERET -- CHARACTER*1                                  Input
               On entry: indicates where the elements of (zeta) are to be
               found as follows:
               WHERET = 'I' (In A)
                     The elements of (zeta) are in A.

               WHERET = 'S' (Separate)
                     The elements of (zeta) are separate from A, in ZETA.
               Constraint: WHERET must be one of 'I' or 'S'.

           2:  M -- INTEGER                                           Input
               On entry: m, the number of rows of A. Constraint: M >= N.

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

           4:  NCOLQ -- INTEGER                                       Input
               On entry: ncolq, the required number of columns of Q.
               Constraint: 0 <= NCOLQ <= M.

               When NCOLQ = 0 then an immediate return is effected.

           5:  A(LDA,*) -- DOUBLE PRECISION array              Input/Output
               Note: the second dimension of the array A must be at least
               max(1,N,NCOLQ).
               On entry: the leading m by n strictly lower triangular part
               of the array A must contain details of the matrix Q. In
               addition, when WHERET = 'I', then the diagonal elements of A
               must contain the elements of (zeta) as described under the
               argument ZETA below. On exit: the first NCOLQ columns of the
               array A are overwritten by the first NCOLQ columns of the m
               by m orthogonal matrix Q. When N = 0 then the first NCOLQ
               columns of A are overwritten by the first NCOLQ columns of
               the identity matrix.

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

           7:  ZETA(*) -- DOUBLE PRECISION array                      Input
               Note: the dimension of the array ZETA must be at least
               max(1,N).
               On entry: with WHERET = 'S', the array ZETA must contain the
               elements of (zeta). If ZETA(k) = 0.0 then T  is assumed to
                                                          k
               be I, otherwise ZETA(k) is assumed to contain (zeta) .
                                                                   k

               When WHERET = 'I', the array ZETA is not referenced.

           8:  WORK(*) -- DOUBLE PRECISION array                  Workspace
               Note: the dimension of the array WORK must be at least
               max(1,NCOLQ).

           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:

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

          IFAIL=-1
               On entry WHERET /= 'I' or 'S',

               or       M < N,

               or       N < 0,

               or       NCOLQ < 0 or NCOLQ > M,

               or       LDA < M.

          7. Accuracy

          The computed matrix Q satisfies the relation

                                       Q=P+E,

          where P is an exactly orthogonal matrix and

                                 ||E||<=c(epsilon)

          (epsilon) is the machine precision (see X02AJF(*)), c is a modest
          function of m and |||.||| denotes the spectral (two) norm. See
          also Section 7 of F01QCF.

          8. Further Comments

          The approximate number of floating-point operations required is
          given by

               2
               -n{(3m-n)(2ncolq-n)-n(ncolq-n)},    ncolq>n,
               3

               2     2
               -ncolq (3m-ncolq),                  ncolq<=n.
               3

          9. Example

          To obtain the 5 by 5 orthogonal matrix Q following the QR
          factorization of the 5 by 3 matrix A given by

                                   (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)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01rcf}{NAG On-line Documentation: f01rcf}
\beginscroll
\begin{verbatim}



     F01RCF(3NAG)      Foundation Library (12/10/92)      F01RCF(3NAG)



          F01 -- Matrix Factorizations                               F01RCF
                  F01RCF -- 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

          F01RCF finds the QR factorization of the complex m by n matrix A,
          where m>=n.

          2. Specification

                 SUBROUTINE   F01RCF (M, N, A, LDA, THETA, IFAIL)
                 INTEGER              M, N, LDA, IFAIL
                 COMPLEX(KIND(1.0D0)) A(LDA,*), THETA(*)

          3. Description

          The m by n matrix A is factorized as

                    (R)
                 A=Q(0)       when m>n,

                 A=QR         when m=n,

          where Q is an m by m unitary matrix and R is an n by n upper
          triangular matrix with real diagonal elements.

          The factorization is obtained by Householder's method. The kth
          transformation matrix, Q , which is used to introduce zeros into
                                  k
          the kth column of A is given in the form

                                        (I 0 )
                                     Q =(0 T ),
                                      k (   k)

          where

                                                 H
                                 T =I-(gamma) u u ,
                                  k          k k k

                                       ((zeta) )
                                       (      k)
                                    u =(z      ),
                                     k ( k     )

          (gamma)  is a scalar for which Re (gamma) =1.0, (zeta)  is a real
                 k                                 k            k
          scalar and z  is an (m-k) element vector. (gamma) , (zeta)  and
                      k                                    k        k
          z  are chosen to annihilate the elements below the triangular
           k
          part of A and to make the diagonal elements real.

          The scalar (gamma)  and the vector u  are returned in the kth
                            k                 k
          element of the array THETA and in the kth column of A, such that
          (theta) , given by
                 k

                           (theta) =((zeta) ,Im(gamma) ),
                                  k        k          k

          is in THETA(k) and the elements of z  are in a     ,...,a   . The
                                              k         k+1,k      m,k
          elements of R are returned in the upper triangular part of A.

          Q is given by

                                                 H
                                  Q=(Q Q   ...Q ) .
                                      n n-1    1

          A good background description to the QR factorization is given in
          Dongarra et al [1], but note that this routine is not based upon
          LINPACK routine ZQRDC.

          4. References

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

          [2]   Wilkinson J H (1965) The Algebraic Eigenvalue Problem.
                Oxford University Press.

          5. Parameters

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

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

               When N = 0 then an immediate return is effected.

           3:  A(LDA,*) -- COMPLEX(KIND(1.0D0)) 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 to be factorized. On exit: the n by n
               upper triangular part of A will contain the upper triangular
               matrix R, with the imaginary parts of the diagonal elements
               set to zero, and the m by n strictly lower triangular part
               of A will contain details of the factorization as described
               above.

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

           5:  THETA(*) -- COMPLEX(KIND(1.0D)) array                 Output
               Note: the dimension of the array THETA must be at least
               max(1,N).
               On exit: the scalar (theta)  for the kth transformation. If
                                          k
               T =I then THETA(k) = 0.0; if
                k
                                ((alpha) 0)
                             T =(      0 I)   Re(alpha)<0.0,
                              k
               then THETA(k)=(alpha); otherwise THETA(k) contains THETA(k)
               as described in Section 3 and Re(THETA(k)) is always in the
                             

               range (1.0, \/2.0).

           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:

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

          IFAIL=-1
               On entry M < N,

               or       N < 0,

               or       LDA < M.

          7. Accuracy
          The computed factors Q and R satisfy the relation

                                       (R)
                                      Q(0)=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.

          8. Further Comments

          The approximate number of real floating-point operations is given
               2
          by 8n (3m-n)/3.

          Following the use of this routine the operations

                                                 H
                                 B:=QB  and  B:=Q B,

          where B is an m by k matrix, can be performed by calls to F01RDF.
          The operation B:=QB can be obtained by the call:


                IFAIL = 0
                CALL F01RDF(`No conjugate', 'Separate', M, N, A, LDA, THETA,
               *            K, B, LDB, WORK, IFAIL)

                  H
          and B:=Q B can be obtained by the call:


                IFAIL = 0
                CALL F01RDF(`Conjugate', 'Separate', M, N, A, LDA, THETA,
               *            K, B, LDB, WORK, IFAIL)

          In both cases WORK must be a k element array that is used as
          workspace. If B is a one-dimensional array (single column) then
          the parameter LDB can be replaced by M. See F01RDF for further
          details.

          The first k columns of the unitary matrix Q can either be
          obtained by setting B to the first k columns of the unit matrix
          and using the first of the above two calls, or by calling F01REF,
          which overwrites the k columns of Q on the first k columns of the
          array A. Q is obtained by the call:


                CALL F01REF(`Separate', M, N, K, A, LDA, THETA, WORK, IFAIL)

          As above, WORK must be a k element array. If k is larger than n,
          then A must have been declared to have at least k columns.

          Operations involving the matrix R can readily be performed by the
          Level 2 BLAS routines ZTRSV and ZTRMV (see Chapter F06), but note
          that no test for near singularity of R is incorporated in ZTRSV.
          If R is singular, or nearly singular, then F02XUF(*) can be used
          to determine the singular value decomposition of R.

          9. Example

          To obtain the QR factorization 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    )

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01rdf}{NAG On-line Documentation: f01rdf}
\beginscroll
\begin{verbatim}



     F01RDF(3NAG)      Foundation Library (12/10/92)      F01RDF(3NAG)



          F01 -- Matrix Factorizations                               F01RDF
                  F01RDF -- 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

          F01RDF performs one of the transformations

                                               H
                                  B:=QB or B:=Q B,

          where B is an m by ncolb complex matrix and Q is an m by m
          unitary matrix, given as the product of Householder
          transformation matrices.

          This routine is intended for use following F01RCF or F01RFF(*).

          2. Specification

                 SUBROUTINE F01RDF (TRANS, WHERET, M, N, A, LDA, THETA,
                1                   NCOLB, B, LDB, WORK, IFAIL)
                 INTEGER              M, N, LDA, NCOLB, LDB, IFAIL
                 COMPLEX(KIND(1.0D0)) A(LDA,*), THETA(*), B(LDB,*), WORK(*)
                 CHARACTER*1          TRANS, WHERET

          3. Description

          The unitary matrix Q is assumed to be given by

                                                 H
                                  Q=(Q Q   ...Q ) ,
                                      n n-1    1

          Q  being given in the form
           k

                                        (I 0 )
                                     Q =(0 T ),
                                      k (   k)

          where

                                                 H
                                 T =I-(gamma) u u ,
                                  k          k k k

                                       ((zeta) )
                                       (      k)
                                    u =(z      ),
                                     k ( k     )

          (gamma)  is a scalar for which Re (gamma) =1.0, (zeta)  is a real
                 k                                 k            k
          scalar and z  is an (m-k) element vector.
                      k

          z  must be supplied in the kth column of A in elements
           k
          a     ,...,a    and (theta) , given by
           k+1,k      m,k            k

                           (theta) =((zeta) ,Im (gamma) ),
                                  k        k           k

          must be supplied either in a    or in THETA(k), depending upon
                                      k,k
          the parameter WHERET.

          To obtain Q explicitly B may be set to I and pre-multiplied by Q.
                                                 H
          This is more efficient than obtaining Q . Alternatively, F01REF
          may be used to obtain Q overwritten on A.

          4. References

          [1]   Wilkinson J H (1965) The Algebraic Eigenvalue Problem.
                Oxford University Press.

          5. Parameters

           1:  TRANS -- CHARACTER*1                                   Input
               On entry: the operation to be performed as follows:
               TRANS = 'N' (No transpose)
                     Perform the operation B:=QB.

               TRANS = 'C' (Conjugate transpose)
                                               H
                     Perform the operation B:=Q B.
               Constraint: TRANS must be one of 'N' or 'C'.

           2:  WHERET -- CHARACTER*1                                  Input
               On entry: the elements of (theta) are to be found as
               follows:
               WHERET = 'I' (In A)
                     The elements of (theta) are in A.

               WHERET = 'S' (Separate)
                     The elements of (theta) are separate from A, in THETA.
               Constraint: WHERET must be one of 'I' or 'S'.

           3:  M -- INTEGER                                           Input
               On entry: m, the number of rows of A. Constraint: M >= N.

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

               When N = 0 then an immediate return is effected.

           5:  A(LDA,*) -- COMPLEX(KIND(1.0D)) array                  Input
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the leading m by n strictly lower triangular part
               of the array A must contain details of the matrix Q. In
               addition, when WHERET = 'I', then the diagonal elements of A
               must contain the elements of (theta) as described under the
               argument THETA below.

               When WHERET = 'S', then the diagonal elements of the array A
               are referenced, since they are used temporarily to store the
               (zeta) , but they contain their original values on return.
                     k

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

           7:  THETA(*) -- COMPLEX(KIND(1.0D)) array                  Input
               Note: the dimension of the array THETA must be at least
               max(1,N).
               On entry: with WHERET = 'S', the array THETA must contain
               the elements of (theta). If THETA(k)=0.0 then T  is assumed
                                                              k
               to be I; if THETA(k)=(alpha), with Re(alpha)<0.0, then T  is
                                                                       k
               assumed to be of the form
                                        ((alpha) 0)
                                     T =(0       I);
                                      k
               otherwise THETA(k) is assumed to contain (theta)  given by
                                                               k
               (theta) =((zeta) ,Im(gamma) ).
                      k        k          k

               When WHERET = 'I', the array THETA is not referenced, and
               may be dimensioned of length 1.

           8:  NCOLB -- INTEGER                                       Input
               On entry: ncolb, the number of columns of B. Constraint:
               NCOLB >= 0.
               When NCOLB = 0 then an immediate return is effected.

           9:  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: the leading m by ncolb part of the array B must
               contain the matrix to be transformed. On exit: B is
               overwritten by the transformed matrix.

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

          11:  WORK(*) -- COMPLEX(KIND(1.0D)) array               Workspace
               Note: the dimension of the array WORK must be at least
               max(1,NCOLB).

          12:  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
               On entry TRANS /= 'N' or 'C',

               or       WHERET /= 'I' or 'S',

               or       M < N,

               or       N < 0,

               or       LDA < M,

               or       NCOLB < 0,

               or       LDB < M.

          7. Accuracy

          Letting C denote the computed matrix Q B, C satisfies the
          relation

                                       QC=B+E,

          where

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

          (epsilon) being the machine precision, c is a modest function of
          m and |||.||| denotes the spectral (two) norm. An equivalent
          result holds for the computed matrix QB. See also Section 7 of
          F01RCF.

          8. Further Comments

          The approximate number of real floating-point operations is given
          by 8n(2m-n)ncolb.

          9. Example

                                H
          To obtain the matrix Q B for the matrix B given by

                               (-0.55+1.05i  0.45+1.05i)
                               ( 0.49+0.93i  1.09+0.13i)
                             B=( 0.56-0.16i  0.64+0.16i)
                               ( 0.39+0.23i -0.39-0.23i)
                               ( 1.13+0.83i -1.13+0.77i)

          following the QR factorization of the 5 by 3 matrix A given by

                             (  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)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf01ref}{NAG On-line Documentation: f01ref}
\beginscroll
\begin{verbatim}



     F01REF(3NAG)      Foundation Library (12/10/92)      F01REF(3NAG)



          F01 -- Matrix Factorizations                               F01REF
                  F01REF -- 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

          F01REF returns the first ncolq columns of the complex m by m
          unitary matrix Q, where Q is given as the product of Householder
          transformation matrices.

          This routine is intended for use following F01RCF.

          2. Specification

                 SUBROUTINE F01REF (WHERET, M, N, NCOLQ, A, LDA, THETA,
                1                   WORK, IFAIL)
                 INTEGER              M, N, NCOLQ, LDA, IFAIL
                 COMPLEX(KIND(1.0D0)) A(LDA,*), THETA(*), WORK(*)
                 CHARACTER*1          WHERET

          3. Description

          The unitary matrix Q is assumed to be given by

                                                 H
                                  Q=(Q Q   ...Q ) ,
                                      n n-1    1

          Q  being given in the form
           k

                                        (I 0 )
                                     Q =(0 T ),
                                      k (   k)

          where

                                                 H
                                 T =I-(gamma) u u ,
                                  k          k k k

                                       ((zeta) )
                                       (      k)
                                    u =(z      ),
                                     k ( k     )

          (gamma)  is a scalar for which Re (gamma) =1.0, (zeta)  is a real
                 k                                 k            k

          scalar and z  is an (m-k) element vector.
                      k

          z  must be supplied in the kth column of A in elements
           k
          a     ,...,a    and (theta) , given by
           k+1,k      m,k            k

                           (theta) =((zeta) ,Im (gamma) ),
                                  k        k           k

          must be supplied either in a    or in THETA(k) depending upon the
                                      k,k
          parameter WHERET.

          4. References

          [1]   Wilkinson J H (1965) The Algebraic Eigenvalue Problem.
                Oxford University Press.

          5. Parameters

           1:  WHERET -- CHARACTER*1                                  Input
               On entry: the elements of (theta) are to be found as
               follows:
               WHERET = 'I' (In A)
                     The elements of (theta) are in A.

               WHERET = 'S' (Separate)
                     The elements of (theta) are separate from A, in THETA.
               Constraint: WHERET must be one of 'I' or 'S'.

           2:  M -- INTEGER                                           Input
               On entry: m, the number of rows of A. Constraint: M >= N.

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

           4:  NCOLQ -- INTEGER                                       Input
               On entry: ncolq, the required number of columns of Q.
               Constraint: 0 <= NCOLQ <= M.

               When NCOLQ = 0 then an immediate return is effected.

           5:  A(LDA,*) -- COMPLEX(KIND(1.0D)) array           Input/Output
               Note: the second dimension of the array A must be at least
               max(1,N,NCOLQ).
               On entry: the leading m by n strictly lower triangular part
               of the array A must contain details of the matrix Q. In
               addition, when WHERET = 'I', then the diagonal elements of A
               must contain the elements of (theta) as described under the
               argument THETA below. On exit: the first NCOLQ columns of
               the array A are overwritten by the first NCOLQ columns of
               the m by m unitary matrix Q. When N = 0 then the first NCOLQ
               columns of A are overwritten by the first NCOLQ columns of
               the unit matrix.

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

           7:  THETA(*) -- COMPLEX(KIND(1.0D)) array                  Input
               Note: the dimension of the array THETA must be at least
               max(1,N).
               On entry: if WHERET = 'S', the array THETA must contain the
               elements of (theta). If THETA(k)=0.0 then T  is assumed to
                                                          k
               be I; if THETA(k)=(alpha), with Re(alpha)<0.0, then T  is
                                                                    k
               assumed to be of the form
                                        ((alpha) 0)
                                     T =(   0    I);
                                      k
               otherwise THETA(k) is assumed to contain (theta)  given by
                                                               k
               (theta) =((zeta) ,Im(gamma) ).
                      k        k          k

               When WHERET = 'I', the array THETA is not referenced.

           8:  WORK(*) -- COMPLEX(KIND(1.0D)) array               Workspace
               Note: the dimension of the array WORK must be at least
               max(1,NCOLQ).

           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:

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

          IFAIL=-1
               On entry WHERET /= 'I' or 'S',

               or       M < N,

               or       N < 0,

               or       NCOLQ < 0 or NCOLQ > M,

               or       LDA < M.

          7. Accuracy

          The computed matrix Q satisfies the relation

                                       Q=P+E,

          where P is an exactly unitary matrix and

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

          (epsilon) being the machine precision, c is a modest function of
          m and |||.||| denotes the spectral (two) norm. See also Section 7
          of F01RCF.

          8. Further Comments

          The approximate number of real floating-point operations required
          is given by

               8
               -n{(3m-n)(2ncolq-n)-n(ncolq-n)},  ncolq>n
               3

               8     2
               -ncolq (3m-ncolq),                ncolq<=n
               3

          9. Example

          To obtain the 5 by 5 unitary matrix Q following the QR
          factorization of the 5 by 3 matrix A given by

                             (    0.5i -0.5+1.5i -1.0+1.4i)
                             (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)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02}{NAG On-line Documentation: f02}
\beginscroll
\begin{verbatim}



     F02(3NAG)         Foundation Library (12/10/92)         F02(3NAG)



          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

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02aaf}{NAG On-line Documentation: f02aaf}
\beginscroll
\begin{verbatim}



     F02AAF(3NAG)      Foundation Library (12/10/92)      F02AAF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02abf}{NAG On-line Documentation: f02abf}
\beginscroll
\begin{verbatim}



     F02ABF(3NAG)      Foundation Library (12/10/92)      F02ABF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02adf}{NAG On-line Documentation: f02adf}
\beginscroll
\begin{verbatim}



     F02ADF(3NAG)      Foundation Library (12/10/92)      F02ADF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02aef}{NAG On-line Documentation: f02aef}
\beginscroll
\begin{verbatim}



     F02AEF(3NAG)      Foundation Library (12/10/92)      F02AEF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02aff}{NAG On-line Documentation: f02aff}
\beginscroll
\begin{verbatim}



     F02AFF(3NAG)      Foundation Library (12/10/92)      F02AFF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02agf}{NAG On-line Documentation: f02agf}
\beginscroll
\begin{verbatim}



     F02AGF(3NAG)      Foundation Library (12/10/92)      F02AGF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02ajf}{NAG On-line Documentation: f02ajf}
\beginscroll
\begin{verbatim}



     F02AJF(3NAG)      Foundation Library (12/10/92)      F02AJF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02akf}{NAG On-line Documentation: f02akf}
\beginscroll
\begin{verbatim}



     F02AKF(3NAG)      Foundation Library (12/10/92)      F02AKF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02awf}{NAG On-line Documentation: f02awf}
\beginscroll
\begin{verbatim}



     F02AWF(3NAG)      Foundation Library (12/10/92)      F02AWF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02axf}{NAG On-line Documentation: f02axf}
\beginscroll
\begin{verbatim}



     F02AXF(3NAG)      Foundation Library (12/10/92)      F02AXF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02bbf}{NAG On-line Documentation: f02bbf}
\beginscroll
\begin{verbatim}



     F02BBF(3NAG)      Foundation Library (12/10/92)      F02BBF(3NAG)



          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.
\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02bjf}{NAG On-line Documentation: f02bjf}
\beginscroll
\begin{verbatim}



     F02BJF(3NAG)      Foundation Library (12/10/92)      F02BJF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02fjf}{NAG On-line Documentation: f02fjf}
\beginscroll
\begin{verbatim}



     F02FJF(3NAG)      Foundation Library (12/10/92)      F02FJF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02wef}{NAG On-line Documentation: f02wef}
\beginscroll
\begin{verbatim}



     F02WEF(3NAG)      Foundation Library (12/10/92)      F02WEF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf02xef}{NAG On-line Documentation: f02xef}
\beginscroll
\begin{verbatim}



     F02XEF(3NAG)      Foundation Library (12/10/92)      F02XEF(3NAG)



          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04}{NAG On-line Documentation: f04}
\beginscroll
\begin{verbatim}



     F04(3NAG)         Foundation Library (12/10/92)         F04(3NAG)



          F04 -- Simultaneous Linear Equations          Introduction -- F04
                                    Chapter F04
                           Simultaneous Linear Equations

          1. Scope of the Chapter

          This chapter, together with two routines in Chapter F07, is
          concerned with the solution of the matrix equation AX=B, where B
          may be a single vector or a matrix of multiple right-hand sides.
          The matrix A may be real, complex, symmetric, Hermitian positive-
          definite, or sparse. It may also be rectangular, in which case a
          least-squares solution is obtained.

          2. Background to the Problems

          A set of linear equations may be written in the form

                                        Ax=b

          where the known matrix A, with real or complex coefficients, is
          of size m by n, (m rows and n columns), the known right-hand
          vector b has m components (m rows and one column), and the
          required solution vector x has n components (n rows and one
          column). There may sometimes be p vectors b , i=1,2,...,p on the
                                                     i
          right-hand side and the equations may then be written as

                                        AX=B

          the required matrix X having as its p columns the solutions of
          Ax =b , i=1,2,...,p. Some routines deal with the latter case, but
            i  i
          for clarity only the case p=1 is discussed here.

          The most common problem, the determination of the unique solution
          of Ax=b, occurs when m=n and A is non-singular, that is rank(A)=n
          problem, discussed in Section 2.2 below, is the determination of
          the least-squares solution of Ax~=b, i.e., the determination of a
          vector x which minimizes the Euclidean length (two norm) of the
          residual vector r=b-Ax. The usual case has m>n and rank(A)=n, in
          which case x is unique.

          2.1. Unique Solution of Ax=b

          Most of the routines in this chapter, as well as two routines in
          Chapter F07, solve this particular problem. The solution is
          obtained by performing either an LU factorization, or a Cholesky
          factorization, as discussed in Section 2 of the F01 Chapter
          Introduction.

          Two of the routines in this chapter use a process called
          iterative refinement to improve the initial solution in order to
          obtain a solution that is correct to working accuracy. It should
          be emphasised that if A and b are not known exactly then not all
          the figures in this solution may be meaningful. To be more
          precise, if x is the exact solution of the equations


                                        Ax=b

              

          and x is the solution of the perturbed equations

                                          

                                     (A+E)x=b+e,

                                         ||E||
          then, provided that (kappa)(A) -------<=1,
                                         ||A||

                   

                 ||x-x||        (kappa)(A)      ( ||E||   ||e|| )
                 ------- <= --------------------( ----- + ----- ),
                  ||x||                  ||E||  ( ||A||   ||b|| )
                            1-(kappa)(A) -----
                                         ||A||

                                   -1
          where (kappa)(A)=||A||||A  || is the condition number of A
          with respect to inversion. Thus, if A is ill-conditioned (
                                

          (kappa)(A) is large), x may differ significantly from x. Often
                     ||E||
          (kappa)(A) -----<<1 in which case the above bound effectively
                     ||A||
          reduces to


                        

                      ||x-x||              ( ||E||   ||e|| )
                      ------- <= (kappa)(A)( ----- + ----- ).
                       ||x||               ( ||A||   ||b|| )

          2.2. The Least-squares Solution of Ax~=b

          The least-squares problem is to find a vector x to minimize


                                  T
                                 r r,  where r=b-Ax.

          When m>=n and rank(A)=n then the solution vector x is unique. For
          the cases where x is not unique the routines in this chapter
          obtain the minimal length solution, that is the vector x for
                 T
          which x x is a minimum.

          2.3. Calculating the Inverse of a Matrix

          The routines in this chapter can also be used to calculate the
          inverse of a square matrix A by solving the equation

                                        AX=I,

          where I is the identity matrix.

          3. Recommendations on Choice and Use of Routines

          3.1. General Purpose Routines

          Many of the routines in this chapter perform the complete
          solution of the required equations, but some of the routines, as
          well as the routines in Chapter F07, assume that a prior
          factorization has been performed, using the appropriate
          factorization routine from Chapter F01 or Chapter F07. These, so-
          called, general purpose routines can be useful when explicit
          information on the factorization is required, as well as the
          solution of the equations, or when the solution is required for
          multiple right-hand sides, or for a sequence of right-hand sides.

          Note that some of the routines that perform a complete solution
          also allow multiple right-hand sides.

          3.2. Iterative Refinement

          The routines that perform iterative refinement are more costly
          than those that do not perform iterative refinement, both in
          terms of time and storage, and should only be used if the problem
          really warrants the additional accuracy provided by these
          routines. The storage requirements are approximately doubled,
          while the additional time is not usually prohibitive since the
          initial factorization is used at each iteration.

          3.3. Sparse Matrix Routines

          The routines for sparse matrices should usually be used only when
          the number of non-zero elements is very small, less than 10% of
          the total number of elements of A. Additionally, when the matrix
          is symmetric positive-definite the sparse routines should
          generally be used only when A does not have a (variable) band
          structure.

          There are four routines for solving sparse linear equations, two
          for solving general real systems (F04AXF and F04QAF), one for
          solving symmetric positive-definite systems (F04MAF) and one for
          solving symmetric systems that may, or may not, be positive-
          definite (F04MBF). F04AXF and F04MAF utilise factorizations of
          the matrix A obtained by routines in Chapter F01, while the other
          two routines use iterative techniques and require a user-supplied
                                                             T
          function to compute matrix-vector products Ac and A c for any
          given vector c. The routines requiring factorizations will
          usually be faster and the factorization can be utilised to solve
          for several right-hand sides, but the original matrix has to be
          explicitly supplied and is overwritten by the factorization, and
          the storage requirements will usually be substantially more than
          those of the iterative routines.

          Routines F04MBF and F04QAF both allow the user to supply a pre-
          conditioner.

          F04MBF can be used to solve systems of the form (A-(lambda)I)x=b,
          which can be useful in applications such as Rayleigh quotient
          iteration.

          F04QAF also solves sparse least-squares problems and allows the
          solution of damped (regularized) least-squares problems.

          3.4. Decision Trees

          If at any stage the answer to a question is 'Don't know' this
          should be read as 'No'.

          For those routines that need to be preceded by a factorization
          routine, the appropriate routine name is given in brackets after
          the name of the routine for solving the equations. Note also that
          you may be directed to a routine in Chapter F07.


          3.4.1. Routines for unique solution of Ax=b


                   Please see figure in printed Reference Manual



          3.4.2.  Routines for Least-squares problems


                   Please see figure in printed Reference Manual




          F04 -- Simultaneous Linear Equations              Contents -- F04
          Chapter F04

          Eigenvalues and Eigenvectors

          F04ADF  Approximate solution of complex simultaneous linear
                  equations with multiple right-hand sides

          F04ARF  Approximate solution of real simultaneous linear
                  equations, one right-hand side

          F04ASF  Accurate solution of real symmetric positive-definite
                  simultaneous linear equations, one right-hand side

          F04ATF  Accurate solution of real simultaneous linear equations,
                  one right-hand side

          F04AXF  Approximate solution of real sparse simultaneous linear
                  equations (coefficient matrix already factorized by
                  F01BRF or F01BSF)

          F04FAF  Approximate solution of real symmetric positive-definite
                  tridiagonal simultaneous linear equations, one right-hand
                  side

          F04JGF  Least-squares (if rank = n) or minimal least-squares (if
                  rank <n) solution of m real equations in n unknowns, rank
                  <=n, m>=n

          F04MAF  Real sparse symmetric positive-definite simultaneous
                  linear equations (coefficient matrix already factorized)

          F04MBF  Real sparse symmetric simultaneous linear equations

          F04MCF  Approximate solution of real symmetric positive-definite
                  variable-bandwidth simultaneous linear equations
                  (coefficient matrix already factorized)

          F04QAF  Sparse linear least-squares problem, m real equations in
                  n unknowns

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04adf}{NAG On-line Documentation: f04adf}
\beginscroll
\begin{verbatim}



     F04ADF(3NAG)      Foundation Library (12/10/92)      F04ADF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04ADF
                  F04ADF -- 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

          F04ADF calculates the approximate solution of a set of complex
          linear equations with multiple right-hand sides, using an LU
          factorization with partial pivoting.

          2. Specification

                 SUBROUTINE F04ADF (A, IA, B, IB, N, M, C, IC, WKSPCE,
                1                   IFAIL)
                 INTEGER              IA, IB, N, M, IC, IFAIL
                 DOUBLE PRECISION     WKSPCE(*)
                 COMPLEX(KIND(1.0D0)) A(IA,*), B(IB,*), C(IC,*)

          3. Description

          Given a set of complex linear equations AX=B, the routine first
          computes an LU factorization of A with partial pivoting, PA=LU,
          where P is a permutation matrix, L is lower triangular and U is
          unit upper triangular. The columns x of the solution X are found
          by forward and backward substitution in Ly=Pb and Ux=y, where b
          is a column of the right-hand side matrix B.

          4. References

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

          5. Parameters

           1:  A(IA,*) -- 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 n by n matrix A. On exit: A is overwritten by
               the lower triangular matrix L and the off-diagonal elements
               of the upper triangular matrix U. The unit diagonal elements
               of U are not stored.

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

           3:  B(IB,*) -- COMPLEX(KIND(1.0D)) array                   Input
               Note: the second dimension of the array B must be at least
               max(1,M).
               On entry: the n by m right-hand side matrix B. See also
               Section 8.

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

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

           6:  M -- INTEGER                                           Input
               On entry: m, the number of right-hand sides. Constraint: M
               >= 0.

           7:  C(IC,*) -- COMPLEX(KIND(1.0D)) array                  Output
               Note: the second dimension of the array C must be at least
               max(1,M).
               On exit: the n by m solution matrix X. See also Section 8.

           8:  IC -- INTEGER                                          Input
               On entry:
               the first dimension of the array C as declared in the
               (sub)program from which F04ADF is called.
               Constraint: IC >= max(1,N).

           9:  WKSPCE(*) -- DOUBLE PRECISION array                Workspace
               Note: the dimension of the array WKSPCE must be at least
               max(1,N).

          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:

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

          IFAIL= 1
               The matrix A is singular, possibly due to rounding errors.

          IFAIL= 2
               On entry N < 0,

               or       M < 0,

               or       IA < max(1,N),

               or       IB < max(1,N),

               or       IC < max(1,N).

          7. Accuracy

          The accuracy of the computed solution depends on the conditioning
          of the original matrix. For a detailed error analysis see
          Wilkinson and Reinsch [1] page 106.

          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 B and C, in which case the solution
          vectors will overwrite the right-hand sides. However this is not
          standard Fortran 77, and may not work on all systems.

          9. Example

          To solve the set of linear equations AX=B where

                                   (1  1+2i  2+10i)
                                 A=(1+i  3i -5+14i)
                                   (1+i  5i -8+20i)

          and


                                         (1)
                                       B=(0).
                                         (0)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04arf}{NAG On-line Documentation: f04arf}
\beginscroll
\begin{verbatim}



     F04ARF(3NAG)      Foundation Library (12/10/92)      F04ARF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04ARF
                  F04ARF -- 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

          F04ARF calculates the approximate solution of a set of real
          linear equations with a single right-hand side, using an LU
          factorization with partial pivoting.

          2. Specification

                 SUBROUTINE F04ARF (A, IA, B, N, C, WKSPCE, IFAIL)
                 INTEGER          IA, N, IFAIL
                 DOUBLE PRECISION A(IA,*), B(*), C(*), WKSPCE(*)

          3. Description

          Given a set of linear equations, Ax=b, the routine first computes
          an LU factorization of A with partial pivoting, PA=LU, where P is
          a permutation matrix, L is lower triangular and U is unit upper
          triangular. The approximate solution x is found by forward and
          backward substitution in Ly=Pb and Ux=y, where b is the right-
          hand side.

          4. References

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

          5. Parameters

           1:  A(IA,*) -- DOUBLE PRECISION array               Input/Output
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the n by n matrix A. On exit: A is overwritten by
               the lower triangular matrix L and the off-diagonal elements
               of the upper triangular matrix U. The unit diagonal elements
               of U are not stored.

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

           3:  B(*) -- DOUBLE PRECISION array                         Input
               Note: the dimension of the array B must be at least
               max(1,N).
               On entry: the right-hand side vector b.

           4:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A. Constraint: N >= 0.

           5:  C(*) -- DOUBLE PRECISION array                        Output
               Note: the dimension of the array C must be at least
               max(1,N).
               On exit: the solution vector x.

           6:  WKSPCE(*) -- DOUBLE PRECISION array                Workspace
               Note: the dimension of the array WKSPCE must be at least
               max(1,N).

           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:

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

          IFAIL= 1
               The matrix A is singular, possibly due to rounding errors.

          IFAIL= 2
               On entry N < 0,

               or       IA < max(1,N).

          7. Accuracy

          The accuracy of the computed solution depends on the conditioning
          of the original matrix. For a detailed error analysis see
          Wilkinson and Reinsch [1] page 107.

          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 B and C, in which case the solution
          vector will overwrite the right-hand side. However this is not
          standard Fortran 77, and may not work on all systems.

          9. Example

          To solve the set of linear equations Ax=b where

                                     ( 33  16  72)
                                   A=(-24 -10 -57)
                                     ( -8  -4 -17)

          and


                                        (-359)
                                      b=( 281).
                                        (  85)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04asf}{NAG On-line Documentation: f04asf}
\beginscroll
\begin{verbatim}



     F04ASF(3NAG)      Foundation Library (12/10/92)      F04ASF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04ASF
                  F04ASF -- 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

          F04ASF calculates the accurate solution of a set of real
          symmetric positive-definite linear equations with a single right-
          hand side,  Ax=b, using a Cholesky factorization and iterative
          refinement.

          2. Specification

                 SUBROUTINE F04ASF (A, IA, B, N, C, WK1, WK2, IFAIL)
                 INTEGER          IA, N, IFAIL
                 DOUBLE PRECISION A(IA,*), B(*), C(*), WK1(*), WK2(*)

          3. Description

          Given a set of real linear equations Ax=b, where A is a symmetric
          positive-definite matrix, the routine first computes a Cholesky
                                    T
          factorization of A as A=LL  where L is lower triangular. An
          approximation to x is found by forward and backward substitution.
          The residual vector r=b-Ax is then calculated using additional
                                                                  T
          precision and a correction d to x is found by solving LL d=r. x
          is then replaced by x+d, and this iterative refinement of the
          solution is repeated until machine accuracy is obtained.

          4. References

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

          5. Parameters

           1:  A(IA,*) -- DOUBLE PRECISION array               Input/Output
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the upper triangle of the n by n positive-definite
               symmetric matrix A. The elements of the array below the
               diagonal need not be set. On exit: the elements of the array
               below the diagonal are overwritten; the upper triangle of A
               is unchanged.

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

           3:  B(*) -- DOUBLE PRECISION array                         Input
               Note: the dimension of the array B must be at least
               max(1,N).
               On entry: the right-hand side vector b.

           4:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A. Constraint: N >= 0.

           5:  C(*) -- DOUBLE PRECISION array                        Output
               Note: the dimension of the array C must be at least
               max(1,N).
               On exit: the solution vector x.

           6:  WK1(*) -- DOUBLE PRECISION array                   Workspace
               Note: the dimension of the array WK1 must be at least
               max(1,N).

           7:  WK2(*) -- DOUBLE PRECISION array                   Workspace
               Note: the dimension of the array WK2 must be at least
               max(1,N).

           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:

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

          IFAIL= 1
               The matrix A is not positive-definite, possibly due to
               rounding errors.

          IFAIL= 2
               Iterative refinement fails to improve the solution, i.e.,
               the matrix A is too ill-conditioned.

          IFAIL= 3
               On entry N < 0,

               or       IA < max(1,N).

          7. Accuracy

          The computed solutions should be correct to full machine
          accuracy. For a detailed error analysis see Wilkinson and Reinsch
          [1] page 39.

          8. Further Comments

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

          The routine must not be called with the same name for parameters
          B and C.

          9. Example

          To solve the set of linear equations Ax=b where

                                     (5  7  6  5)
                                     (7 10  8  7)
                                   A=(6  8 10  9)
                                     (5  7  9 10)

          and


                                         (23)
                                         (32)
                                       b=(33).
                                         (31)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04atf}{NAG On-line Documentation: f04atf}
\beginscroll
\begin{verbatim}



     F04ATF(3NAG)      Foundation Library (12/10/92)      F04ATF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04ATF
                  F04ATF -- 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

          F04ATF calculates the accurate solution of a set of real linear
          equations with a single right-hand side, using an LU
          factorization with partial pivoting, and iterative refinement.

          2. Specification

                 SUBROUTINE F04ATF (A, IA, B, N, C, AA, IAA, WKS1, WKS2,
                1                   IFAIL)
                 INTEGER          IA, N, IAA, IFAIL
                 DOUBLE PRECISION A(IA,*), B(*), C(*), AA(IAA,*), WKS1(*),
                1                 WKS2(*)

          3. Description

          Given a set of real linear equations, Ax=b, the routine first
          computes an LU factorization of A with partial pivoting, PA=LU,
          where P is a permutation matrix, L is lower triangular and U is
          unit upper triangular. An approximation to x is found by forward
          and backward substitution in Ly=Pb and Ux=y. The residual vector
          r=b-Ax is then calculated using additional precision, and a
          correction d to x is found by solving LUd=r. x is replaced by x+d
          , and this iterative refinement of the solution is repeated until
          full machine accuracy is obtained.

          4. References

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

          5. Parameters

           1:  A(IA,*) -- DOUBLE PRECISION array                      Input
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the n by n matrix A.

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

           3:  B(*) -- DOUBLE PRECISION array                         Input
               Note: the dimension of the array B must be at least
               max(1,N).
               On entry: the right-hand side vector b.

           4:  N -- INTEGER                                           Input
               On entry: n, the order of the matrix A. Constraint: N >= 0.

           5:  C(*) -- DOUBLE PRECISION array                        Output
               Note: the dimension of the array C must be at least
               max(1,N).
               On exit: the solution vector x.

           6:  AA(IAA,*) -- DOUBLE PRECISION array                   Output
               Note: the second dimension of the array AA must be at least
               max(1,N).
               On exit: the triangular factors L and U, except that the
               unit diagonal elements of U are not stored.

           7:  IAA -- INTEGER                                         Input
               On entry:
               the first dimension of the array AA as declared in the
               (sub)program from which F04ATF is called.
               Constraint: IAA >= max(1,N).

           8:  WKS1(*) -- DOUBLE PRECISION array                  Workspace
               Note: the dimension of the array WKS1 must be at least
               max(1,N).

           9:  WKS2(*) -- DOUBLE PRECISION array                  Workspace
               Note: the dimension of the array WKS2 must be at least
               max(1,N).

          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:

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

          IFAIL= 1
               The matrix A is singular, possibly due to rounding errors.

          IFAIL= 2

               Iterative refinement fails to improve the solution, i.e.,
               the matrix A is too ill-conditioned.

          IFAIL= 3
               On entry N < 0,

               or       IA < max(1,N),

               or       IAA < max(1,N).

          7. Accuracy

          The computed solutions should be correct to full machine
          accuracy. For a detailed error analysis see Wilkinson and Reinsch
          [1] page 107.

          8. Further Comments

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

          The routine must not be called with the same name for parameters
          B and C.

          9. Example

          To solve the set of linear equations Ax=b where

                                     ( 33  16  72)
                                   A=(-24 -10 -57)
                                     ( -8  -4 -17)

          and


                                        (-359)
                                      b=( 281).
                                        (  85)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04axf}{NAG On-line Documentation: f04axf}
\beginscroll
\begin{verbatim}



     F04AXF(3NAG)      Foundation Library (12/10/92)      F04AXF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04AXF
                  F04AXF -- 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

          F04AXF calculates the approximate solution of a set of real
          sparse linear equations with a single right-hand side, Ax=b or
           T
          A x=b, where A has been factorized by F01BRF or F01BSF.

          2. Specification

                 SUBROUTINE F04AXF (N, A, LICN, ICN, IKEEP, RHS, W, MTYPE,
                1                   IDISP, RESID)
                 INTEGER          N, LICN, ICN(LICN), IKEEP(5*N), MTYPE,
                1                 IDISP(2)
                 DOUBLE PRECISION A(LICN), RHS(N), W(N), RESID

          3. Description

                                                              T
          To solve a system of real linear equations Ax=b or A x=b, where A
          is a general sparse matrix, A must first be factorized by F01BRF
          or F01BSF. F04AXF then computes x by block forward or backward
          substitution using simple forward and backward substitution
          within each diagonal block.

          The method is fully described in Duff [1].

          4. References

          [1]   Duff I S (1977) MA28 -- a set of Fortran subroutines for
                sparse unsymmetric linear equations. A.E.R.E. Report R.8730.
                HMSO.

          5. Parameters

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

           2:  A(LICN) -- DOUBLE PRECISION array                      Input
               On entry: the non-zero elements in the factorization of the
               matrix A, as returned by F01BRF or F01BSF.

           3:  LICN -- INTEGER                                        Input
               On entry:
               the dimension of the arrays A and ICN as declared in the
               (sub)program from which F04AXF is called.

           4:  ICN(LICN) -- INTEGER array                             Input
               On entry: the column indices of the non-zero elements of
               the factorization, as returned by F01BRF or F01BSF.

           5:  IKEEP(5*N) -- INTEGER array                            Input
               On entry: the indexing information about the factorization,
               as returned by F01BRF or F01BSF.

           6:  RHS(N) -- DOUBLE PRECISION array                Input/Output
               On entry: the right-hand side vector b. On exit: RHS is
               overwritten by the solution vector x.

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

           8:  MTYPE -- INTEGER                                       Input
               On entry: MTYPE specifies the task to be performed:
                    if MTYPE = 1, solve Ax=b,

                                          T
                    if MTYPE /= 1, solve A x=b.

           9:  IDISP(2) -- INTEGER array                              Input
               On entry: the values returned in IDISP by F01BRF.

          10:  RESID -- DOUBLE PRECISION                             Output
               On exit: the value of the maximum residual,
                        --
               max(|b - > a  x |), over all the unsatisfied equations, in
                     i  -- ij j
                        j
               case F01BRF or F01BSF has been used to factorize a singular
               or rectangular matrix.

          6. Error Indicators and Warnings

          None.

          7. Accuracy

          The accuracy of the computed solution depends on the conditioning
          of the original matrix. Since F04AXF is always used with either
          F01BRF or F01BSF, the user is recommended to set GROW = .TRUE. on
          entry to these routines and to examine the value of W(1) on exit
          (see the routine documents for F01BRF and F01BSF). For a detailed
          error analysis see Duff [1] page 17.

          If storage for the original matrix is available then the error
          can be estimated by calculating the residual

                                                T
                                 r=b-Ax  (or b-A x)

          and calling F04AXF again to find a correction (delta) for x by
          solving

                                             T
                            A(delta)=r  (or A (delta)=r).

          8. Further Comments

          If the factorized form contains (tau) non-zeros (IDISP(2) = (tau)
          ) then the time taken is very approximately 2(tau) times longer
          than the inner loop of full matrix code. Some advantage is taken
                                                        T
          of zeros in the right-hand side when solving A x=b (MTYPE /= 1).

          9. Example

          To solve the set of linear equations Ax=b where

                                  ( 5  0  0  0 0  0)
                                  ( 0  2 -1  2 0  0)
                                  ( 0  0  3  0 0  0)
                                A=(-2  0  0  1 1  0)
                                  (-1  0  0 -1 2 -3)
                                  (-1 -1  0  0 0  6)

          and


                                         (15)
                                         (12)
                                         (18)
                                       b=( 3).
                                         (-6)
                                         ( 0)

          The non-zero elements of A and indexing information are read in
          by the program, as described in the document for F01BRF.

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04faf}{NAG On-line Documentation: f04faf}
\beginscroll
\begin{verbatim}



     F04FAF(3NAG)      Foundation Library (12/10/92)      F04FAF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04FAF
                  F04FAF -- 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

          F04FAF calculates the approximate solution of a set of real
          symmetric positive-definite tridiagonal linear equations.

          2. Specification

                 SUBROUTINE F04FAF (JOB, N, D, E, B, IFAIL)
                 INTEGER          JOB, N, IFAIL
                 DOUBLE PRECISION D(N), E(N), B(N)

          3. Description

          F04FAF is based upon the Linpack routine DPTSL (see Dongarra et
          al [1]) and solves the equations

                                        Tx=b,

          where T is a real n by n symmetric positive-definite tridiagonal
          matrix, using a modified symmetric Gaussian elimination algorithm
                                 T
          to factorize T as T=MKM , where K is diagonal and M is a matrix
          of multipliers as described in Section 8.

          When the input parameter JOB is supplied as 1, then the routine
          assumes that a previous call to F04FAF has already factorized T;
          otherwise JOB must be supplied as 0.

          4. References

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

          5. Parameters

           1:  JOB -- INTEGER                                         Input
               On entry: specifies the job to be performed by F04FAF as
               follows:
               JOB = 0
                     The matrix T is factorized and the equations Tx=b are
                     solved for x.

               JOB = 1
                     The matrix T is assumed to have already been
                     factorized by a previous call to F04FAF with JOB = 0;
                     the equations Tx=b are solved for x.

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

           3:  D(N) -- DOUBLE PRECISION array                  Input/Output
               On entry: if JOB = 0, D must contain the diagonal elements
               of T. If JOB = 1, D must contain the diagonal matrix K, as
               returned by a previous call of F04FAF with JOB = 0. On
               exit: if JOB = 0, D is overwritten by the diagonal matrix K
               of the factorization. If JOB = 1, D is unchanged.

           4:  E(N) -- DOUBLE PRECISION array                  Input/Output
               On entry: if JOB = 0, E must contain the super-diagonal
               elements of T, stored in E(2) to E(n). If JOB = 1, E must
               contain the off-diagonal elements of the matrix M, as
               returned by a previous call of F04FAF with JOB = 0. E(1) is
               not used. On exit: if JOB = 0, E(2) to E(n) are overwritten
               by the off-diagonal elements of the matrix M of the
               factorization. If JOB = 1, E is unchanged.

           5:  B(N) -- DOUBLE PRECISION array                  Input/Output
               On entry: the right-hand side vector b. On exit: B is
               overwritten by the solution vector x.

           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
               On entry N < 1,

               or       JOB /= 0 or 1.

          IFAIL= 2
               The matrix T is either not positive-definite or is nearly
               singular. This failure can only occur when JOB = 0 and
               inspection of the elements of D will give an indication of
               why failure has occurred. If an element of D is close to
               zero, then T is probably nearly singular; if an element of D
               is negative but not close to zero, then T is not positive-
               definite.

          IFAILOverflow
               If overflow occurs during the execution of this routine,
               then either T is very nearly singular or an element of the
               right-hand side vector b is very large. In this latter case
               the equations should be scaled so that no element of b is
               very large. Note that to preserve symmetry it is necessary
                                                            T
               to scale by a transformation of the form (PTP )b=Px, where P
               is a diagonal matrix.

          IFAILUnderflow
               Any underflows that occur during the execution of this
               routine are harmless.

          7. Accuracy

          The computed factorization (see Section 8) will satisfy the
          equation

                                         T
                                      MKM =T+E

          where ||E|| <=2(epsilon)||T|| , p=1,F,infty,
                     p                 p

          (epsilon) being the machine precision. The computed solution of
                                  

          the equations Tx=b, say x, will satisfy an equation of the form

                                           

                                      (T+F)x=b,

          where F can be expected to satisfy a bound of the form

                          ||F||<=(alpha)(epsilon)||T||,

          (alpha) being a modest constant. This implies that the relative
                   

          error in x satisfies

                              

                           ||x-x||
                           -------<=c(T)(alpha)(epsilon),
                            ||x||

          where c(T) is the condition number of T with respect to
                                                   

          inversion. Thus if T is nearly singular, x can be expected to
          have a large relative error.

          8. Further Comments

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

          The routine eliminates the off-diagonal elements of T by
          simultaneously performing symmetric Gaussian elimination from the
          top and the bottom of T. The result is that T is factorized as

                                            T
                                       T=MKM ,

          where K is a diagonal matrix and M is a matrix of the form

                           (1  0  0 ..  0    0 0    .. 0 0    0 )
                           (m  1  0 ..  0    0 0    .. 0 0    0 )
                           ( 2                                  )
                           (0  m  1 ..  0    0 0    .. 0 0    0 )
                           (    3                               )
                           (.  .  . ..  .    . .    .. . .    . )
                           (.  .  . ..  .    . .    .. . .    . )
                           (0  0  0 ..  1    0 0    .. 0 0    0 )
                         M=(0  0  0 ..  m    1 m    .. 0 0    0 )
                           (             j+1    j+2             )
                           (0  0  0 ..  0    0 ..   1 0  0    0 )
                           (.  .  . ..  .    . .    .. . .    . )
                           (.  .  . ..  .    . .    .. . .    . )
                           (0  0  0 ..  0    0 0    .. 1 m    0 )
                           (                              n-1   )
                           (0  0  0 ..  0    0 0    .. 0 1    m )
                           (                                   n)
                           (0  0  0 ..  0    0 0 .   . 0 0    1 )

          j being the integer part of n/2. (For example when n=5,j=2.) The
          diagonal elements of K are returned in D with k  in the ith
                                                         i
          element of D and m  is returned in the ith element of E.
                            i

          The routine fails with IFAIL = 2 if any diagonal element of K is
          non-positive. It should be noted that T may be nearly singular
          even if all the diagonal elements of K are positive, but in this
          case at least one element of K is almost certain to be small
          relative to |||T|||. If there is any doubt as to whether or not T
          is nearly singular, then the user should consider examining the
          diagonal elements of K.

          9. Example

          To solve the symmetric positive-definite equations

                                       Tx =b
                                         1  1

          and

                                       Tx =b
                                         2  2

          where

                         ( 4 -2  0  0 0)       ( 6)      (10)
                         (-2 10 -6  0 0)       ( 9)      ( 4)
                       T=( 0 -6 29 15 0),   b =( 2),  b =( 9).
                         ( 0  0 15 25 8)     1 (14)    2 (65)
                         ( 0  0  0  8 5)       ( 7)      (23)

          The equations are solved by two calls to F04FAF, the first with
          JOB = 0 and the second, using the factorization from the first
          call, with JOB = 1.

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04jgf}{NAG On-line Documentation: f04jgf}
\beginscroll
\begin{verbatim}



     F04JGF(3NAG)      Foundation Library (12/10/92)      F04JGF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04JGF
                  F04JGF -- 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

          F04JGF finds the solution of a linear least-squares problem, Ax=b
          , where A is a real m by n (m>=n) matrix and b is an m element
          vector. If the matrix of observations is not of full rank, then
          the minimal least-squares solution is returned.

          2. Specification

                 SUBROUTINE F04JGF (M, N, A, NRA, B, TOL, SVD, SIGMA,
                1                   IRANK, WORK, LWORK, IFAIL)
                 INTEGER          M, N, NRA, IRANK, LWORK, IFAIL
                 DOUBLE PRECISION A(NRA,N), B(M), TOL, SIGMA, WORK(LWORK)
                 LOGICAL          SVD

          3. Description

          The minimal least-squares solution of the problem Ax=b is the
          vector x of minimum (Euclidean) length which minimizes the length
          of the residual vector r=b-Ax.

          The real m by n (m>=n) matrix A is factorized as

                                          (U)
                                       A=Q(0)

          where Q is an m by m orthogonal matrix and U is an n by n upper
          triangular matrix. If U is of full rank, then the least-squares
          solution is given by

                                        -1    T
                                    x=(U   0)Q b.

          If U is not of full rank, then the singular value decomposition
          of U is obtained so that U is factorized as

                                            T
                                       U=RDP ,

          where R and P are n by n orthogonal matrices and D is the n by n
          diagonal matrix

                       D=diag((sigma) ,(sigma) ,...,(sigma) ),
                                     1        2            n

          with (sigma) >=(sigma) >=...(sigma) >=0, these being the singular
                      1         2            n
          values of A. If the singular values (sigma)   ,...,(sigma)  are
                                                     k+1            n
          negligible, but (sigma)  is not negligible, relative to the data
                                 k
          errors in A, then the rank of A is taken to be k and the minimal
          least-squares solution is given by

                                   ( -1  )( T  )
                                   (S   0)(R  0) T
                                x=P(0 0  )(0 I )Q b,

          where S=diag((sigma) ,(sigma) ,...,(sigma) ).
                              1        2            k

          This routine obtains the factorizations by a call to F02WDF(*).

          The routine also returns the value of the standard error


                      /  T
                     /  r r
          (sigma)=  /   --- ,     if m>k,
                  \/    m-k

                                           T
                 =  0,            if m=k, r r being the residual sum of
                                  squares and k the rank of A.

          4. References

          [1]   Lawson C L and Hanson R J (1974) Solving Least-squares
                Problems. Prentice-Hall.

          5. Parameters

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

           2:  N -- INTEGER                                           Input
               On entry: n, the number of columns of A. Constraint: 1 <= N
               <= M.

           3:  A(NRA,N) -- DOUBLE PRECISION array              Input/Output
               On entry: the m by n matrix A. On exit: if SVD is returned
               as .FALSE., A} is overwritten by details of the QU
               factorization of A (see F02WDF(*) for further details). If
               SVD is returned as .TRUE., the first n rows of A are
               overwritten by the right-hand singular vectors, stored by
               rows; and the remaining rows of the array are used as
               workspace.

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

           5:  B(M) -- DOUBLE PRECISION array                  Input/Output
               On entry: the right-hand side vector b. On exit: the first
               n elements of B contain the minimal least-squares solution
               vector x. The remaining m-n elements are used for workspace.

           6:  TOL -- DOUBLE PRECISION                                Input
               On entry: a relative tolerance to be used to determine the
               rank of A. TOL should be chosen as approximately the largest
               relative error in the elements of A. For example, if the
               elements of A are correct to about 4 significant figures
                                                   -4
               then TOL should be set to about 5*10  . See Section 8 for a
               description of how TOL is used to determine rank. If TOL is
               outside the range ((epsilon),1.0), where (epsilon) is the
               machine precision, then the value (epsilon) is used in place
               of TOL. For most problems this is unreasonably small.

           7:  SVD -- LOGICAL                                        Output
               On exit: SVD is returned as .FALSE. if the least-squares
               solution has been obtained from the QU factorization of A.
               In this case A is of full rank. SVD is returned as .TRUE. if
               the least-squares solution has been obtained from the
               singular value decomposition of A.

           8:  SIGMA -- DOUBLE PRECISION                             Output
                                                               

                                                              / T
               On exit: the standard error, i.e., the value \/ r r/(m-k)
               when m>k, and the value zero when m=k. Here r is the
               residual vector b-Ax and k is the rank of A.

           9:  IRANK -- INTEGER                                      Output
               On exit: k, the rank of the matrix A. It should be noted
               that it is possible for IRANK to be returned as n and SVD to
               be returned as .TRUE.. This means that the matrix U only
               just failed the test for non-singularity.

          10:  WORK(LWORK) -- DOUBLE PRECISION array                 Output
               On exit: if SVD is returned as .FALSE., then the first n
               elements of WORK contain information on the QU factorization
               of A (see parameter A above and F02WDF(*)), and WORK(n+1)
                                                      -1
               contains the condition number ||U|| ||U  ||  of the
                                                  E       E
               upper triangular matrix U.

               If SVD is returned as .TRUE., then the first n elements of
               WORK contain the singular values of A arranged in descending
               order and WORK(n+1) contains the total number of iterations
               taken by the QR algorithm. The rest of WORK is used as
               workspace.

          11:  LWORK -- INTEGER                                       Input
               On entry:
               the dimension of the array WORK as declared in the
               (sub)program from which F04JGF is called.
               Constraint: LWORK >= 4*N.

          12:  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
               On entry N < 1,

               or       M < N,

               or       NRA < M,

               or       LWORK < 4*N.

          IFAIL= 2
               The QR algorithm has failed to converge to the singular
               values in 50*N iterations. This failure can only happen when
               the singular value decomposition is employed, but even then
               it is not likely to occur.

          7. Accuracy

                                               T
          The computed factors Q, U, R, D and P  satisfy the relations

                              (U)        (R 0)(D) T
                             Q(0)=A+E , Q(0 I)(0)P =A+F,

          where

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


                           ||F|| <=c (epsilon)||A|| ,
                                2   2              2

          (epsilon) being the machine precision, and c  and c  being modest
                                                      1      2
          functions of m and n. Note that ||A|| =(sigma) .
                                               2        1

          For a fuller discussion, covering the accuracy of the solution x
          see Lawson and Hanson [1], especially pp 50 and 95.

          8. Further Comments

          If the least-squares solution is obtained from the QU
          factorization then the time taken by the routine is approximately
                           2
          proportional to n (3m-n). If the least-squares solution is
          obtained from the singular value decomposition then the time
                                                  2
          taken is approximately proportional to n (3m+19n). The
          approximate proportionality factor is the same in each case.

          This routine is column biased and so is suitable for use in paged
          environments.

          Following the QU factorization of A the condition number

                                             -1
                               c(U)=||U|| ||U  ||
                                         E       E

          is determined and if c(U) is such that

                                    c(U)*TOL>1.0

          then U is regarded as singular and the singular values of A are
          computed. If this test is not satisfied, U is regarded as non-
          singular and the rank of A is set to n. When the singular values
          are computed the rank of A, say k, is returned as the largest
          integer such that

                               (sigma) >TOL*(sigma) ,
                                      k            1

          unless (sigma) =0 in which case k is returned as zero. That is,
                        1
          singular values which satisfy (sigma) <=TOL*(sigma)  are regarded
                                               i             1
          as negligible because relative perturbations of order TOL can
          make such singular values zero.

          9. Example

          To obtain a least-squares solution for r=b-Ax, where

                           (0.05  0.05 0.25 -0.25)      (1)
                           (0.25  0.25 0.05 -0.05)      (2)
                           (0.35  0.35 1.75 -1.75)      (3)
                         A=(1.75  1.75 0.35 -0.35),   B=(4)
                           (0.30 -0.30 0.30  0.30)      (5)
                           (0.40 -0.40 0.40  0.40)      (6)

                                                  -4
          and the value TOL is to be taken as 5*10  .

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04maf}{NAG On-line Documentation: f04maf}
\beginscroll
\begin{verbatim}



     F04MAF(3NAG)      Foundation Library (12/10/92)      F04MAF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04MAF
                  F04MAF -- 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 solve a sparse symmetric positive-definite system of linear
          equations, Ax=b, using a pre-conditioned conjugate gradient
          method, where A has been factorized by F01MAF.

          2. Specification

                 SUBROUTINE F04MAF (N, NZ, A, LICN, IRN, LIRN, ICN, B, ACC,
                1                   NOITS, WKEEP, WORK, IKEEP, INFORM,
                2                   IFAIL)
                 INTEGER          N, NZ, LICN, IRN(LIRN), LIRN, ICN(LICN),
                1                 NOITS(2), IKEEP(2*N), INFORM(4), IFAIL
                 DOUBLE PRECISION A(LICN), B(N), ACC(2), WKEEP(3*N), WORK
                1                 (3*N)

          3. Description

          F04MAF solves the n linear equations

                                     Ax=b,                              (1)

          where A is a sparse symmetric positive-definite matrix, following
          the incomplete Cholesky factorization by F01MAF, given by

                                      T T
                                C=PLDL P  , WAW=C+E,

          where P is a permutation matrix, L is a unit lower triangular
          matrix, D is a diagonal matrix with positive diagonal elements, E
          is an error matrix representing elements dropped during the
          factorization and diagonal elements that have been modified to
          ensure that C is positive-definite, and W is a diagonal matrix,
          chosen to make the diagonal elements of WAW unity.

          Equation (1) is solved by applying a pre-conditioned conjugate
          gradient method to the equations

                                       -1
                                (WAW)(W  x)=Wb,                         (2)

          using C as the pre-conditioning matrix. Details of the conjugate
          gradient method are given in Munksgaard [1].

          The iterative procedure is terminated if

                                ||Wr|| <=(eta),                         (3)
                                      2

          where r is the residual vector r=b-Ax, ||r||  denotes the
                                                      2
          Euclidean length of r, (eta) is a user-supplied tolerance and x
          is the current approximation to the solution. Notice that

                                               -1
                                  Wr=Wb-(WAW)(W  x)

          so that Wr is the residual of the normalised equations (2).

          F04MAF is based on the Harwell Library routine MA31B.

          4. References

          [1]   Munksgaard N (1980) Solving Sparse Symmetric Sets of Linear
                Equations by Pre-conditioned Conjugate Gradients. ACM Trans.
                Math. Softw. 6 206--219.

          5. Parameters

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

           2:  NZ -- INTEGER                                          Input
               On entry: the number of non-zero elements in the upper
               triangular part of the matrix A, including the number of
               elements on the leading diagonal. Constraint: NZ >= N.

           3:  A(LICN) -- DOUBLE PRECISION array                      Input
               On entry: the first LROW elements, where LROW is the value
               supplied in INFORM(1), must contain details of the
               factorization, as returned by F01MAF.

           4:  LICN -- INTEGER                                        Input
               On entry: the length of the array A, as declared in the
               (sub)program from which F04MAF is called. It need never be
               larger than the value of LICN supplied to F01MAF.
               Constraint: LICN >= INFORM(1).

           5:  IRN(LIRN) -- INTEGER array                             Input
               On entry: the first LCOL elements, where LCOL is the value
               supplied in INFORM(2), must contain details of the
               factorization, as returned by F01MAF.

           6:  LIRN -- INTEGER                                        Input
               On entry: the length of the array IRN, as declared in the
               (sub)program from which F04MAF is called. It need never be
               larger than the value of LIRN supplied to F01MAF.
               Constraint: LIRN >= INFORM(2).

           7:  ICN(LICN) -- INTEGER array                             Input
               On entry: the first LROW elements, where LROW is the value
               supplied in INFORM(1), must contain details of the
               factorization, as returned by F01MAF.

           8:  B(N) -- DOUBLE PRECISION array                  Input/Output
               On entry: the right-hand side vector b. On exit: B is
               overwritten by the solution vector x.

           9:  ACC(2) -- DOUBLE PRECISION array                Input/Output
               On entry: ACC(1) specifies the tolerance for convergence,
               (eta), in equation (3) of Section 3. If ACC(1) is outside
               the range [(epsilon),1], where (epsilon) is the machine
               precision, then the value (epsilon) is used in place of ACC
               (1). ACC(2) need not be set. On exit: ACC(2) contains the
               actual value of ||Wr||  at the final point. ACC(1) is
                                     2
               unchanged.

          10:  NOITS(2) -- INTEGER array                       Input/Output
               On entry: NOITS(1) specifies the maximum permitted number of
               iterations. If NOITS(1) < 1, then the value 100 is used in
               its place. NOITS(2) need not be set. On exit: NOITS(2)
               contains the number of iterations taken to converge. NOITS
               (1) is unchanged.

          11:  WKEEP(3*N) -- DOUBLE PRECISION array                   Input
               On entry: WKEEP must be unchanged from the previous call of
               F01MAF.

          12:  WORK(3*N) -- DOUBLE PRECISION array                   Output
               On exit: WORK(1) contains a lower bound for the condition
               number of A. The rest of the array is used for workspace.

          13:  IKEEP(2*N) -- INTEGER array                            Input
               On entry: IKEEP must be unchanged from the previous call of
               F01MAF.

          14:  INFORM(4) -- INTEGER array                             Input
               On entry: INFORM must be unchanged from the previous call of
               F01MAF.

          15:  IFAIL -- INTEGER                                Input/Output
               For this routine, the normal use of IFAIL is extended to
               control the printing of error and warning messages as well
               as specifying hard or soft failure (see the Essential
               Introduction).

               Before entry, IFAIL must be set to a value with the decimal
               expansion cba, where each of the decimal digits c, b and a
               must have a value of 0 or 1.
               a=0   specifies hard failure, otherwise soft failure;

               b=0   suppresses error messages, otherwise error messages
                     will be printed (see Section 6);

               c=0   suppresses warning messages, otherwise warning
                     messages will be printed (see Section 6).
               The recommended value for inexperienced users is 110 (i.e.,
               hard failure with all messages printed).

               Unless the routine detects an error (see Section 6), IFAIL
               contains 0 on exit.

          6. Error Indicators and Warnings

          Errors detected by the routine:

          For each error, an explanatory error message is output on the
          current error message unit (as defined by X04AAF), unless
          suppressed by the value of IFAIL on entry.

          IFAIL= 1
               On entry N < 1,

               or       NZ < N,

               or       LICN < INFORM(1),

               or       LIRN < INFORM(2).

          IFAIL= 2
               Convergence has not taken place within the requested NOITS
               (1) number of iterations. ACC(2) gives the value ||Wr|| ,
                                                                      2
               for the final point. Either too few iterations have been
               allowed, or the requested convergence criterion cannot be
               met.

          IFAIL= 3
               The matrix A is singular, or nearly singular. Singularity
               has been detected during the conjugate gradient iterations,
               so that the computations are not complete.

          IFAIL= 4
               The matrix A is singular, or nearly singular. The message
               output on the current error message channel will include an
               estimate of the condition number of A. In the case of soft
               failure an approximate solution is returned such that the
               value ||Wr||  is given by ACC(2) and the estimate (a lower
                           2
               bound) of the condition number is returned in WORK(1).

          7. Accuracy

          On successful return, or on return with IFAIL = 2 or IFAIL = 4
          the computed solution will satisfy equation (3) of Section 3,
          with (eta) = ACC(2).

          8. Further Comments

          The time taken by the routine will depend upon the sparsity of
          the factorization and the number of iterations required. The
          number of iterations will be affected by the nature of the
          factorization supplied by F01MAF. The more incomplete the
          factorization, the higher the number of iterations required by
          F04MAF.

          When the solution of several systems of equations, all with the
          same matrix of coefficients, A, is required, then F01MAF need be
          called only once to factorize A. This is illustrated in the
          context of an eigenvalue problem in the example program for
          F02FJF.

          9. Example

          The example program illustrates the use of F01MAF in conjunction
          with F04MAF to solve the 16 linear equations Ax=b, where

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

                    1
          where a=- -.
                    4

                   T (  1  1  1  1  1      1  1      1  1  1  1  1)
                  b =(  -  -  -  -  - 0 0  -  - 0 0  -  -  -  -  -)
                     (  2  4  4  2  4      4  4      4  2  4  4  2)

          The n by n matrix A arises in the solution of Laplace's equation
          in a unit-square, using a five-point formula with a 6 by 6
          discretisation, with unity on the boundaries.

          The drop tolerance, DROPTL, is taken as 0.1 and the density
          factor, DENSW, is taken as 0.8. The value IFAIL = 111 is used so
          that advisory and error messages will be printed, but soft
          failure would occur if IFAIL were returned as non-zero.

          A relative accuracy of about 0.0001 is requested in the solution
          from F04MAF, with a maximum of 50 iterations.

          The example program for F02FJF illustrates the use of routines
          F01MAF and F04MAF in solving an eigenvalue problem.

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04mbf}{NAG On-line Documentation: f04mbf}
\beginscroll
\begin{verbatim}



     F04MBF(3NAG)      Foundation Library (12/10/92)      F04MBF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04MBF
                  F04MBF -- 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

          F04MBF solves a system of real sparse symmetric linear equations
          using a Lanczos algorithm.

          2. Specification

                 SUBROUTINE F04MBF (N, B, X, APROD, MSOLVE, PRECON, SHIFT,
                1                   RTOL, ITNLIM, MSGLVL, ITN, ANORM,
                2                   ACOND, RNORM, XNORM, WORK, RWORK,
                3                   LRWORK, IWORK, LIWORK, INFORM, IFAIL)
                 INTEGER          N, ITNLIM, MSGLVL, ITN, LRWORK, IWORK
                1                 (LIWORK), LIWORK, INFORM, IFAIL
                 DOUBLE PRECISION B(N), X(N), SHIFT, RTOL, ANORM, ACOND,
                1                 RNORM, XNORM, WORK(N,5), RWORK(LRWORK)
                 LOGICAL          PRECON
                 EXTERNAL         APROD, MSOLVE

          3. Description

          F04MBF solves the system of linear equations

                               (A-(lambda)I)x=b                       (3.1)

          where A is an n by n sparse symmetric matrix and (lambda) is a
          scalar, which is of course zero if the solution of the equations

                                        Ax=b

          is required. It should be noted that neither A nor (A-(lambda)I)
          need be positive-definite.

          (lambda) is supplied as the parameter SHIFT, and allows F04MBF to
          be used for finding eigenvectors of A in methods such as Rayleigh
          quotient iteration (see for example Lewis [1]), in which case
          (lambda) will be an approximation to an eigenvalue of A and b an
          approximation to an eigenvector of A.

          The routine also provides an option to allow pre-conditioning and
          this will often reduce the number of iterations required by
          F04MBF.

          F04MBF is based upon algorithm SYMMLQ (see Paige and Saunders
          [2]) and solves the equations by an algorithm based upon the

          Lanczos process. Details of the method are given in Paige and
          Saunders [2]. The routine does not require A explicitly, but A is
          specified via a user-supplied routine APROD which, given an n
          element vector c, must return the vector z given by

                                        z=Ac.

          The pre-conditioning option is based on the following reasoning.
          If A can be expressed in the form

                                        A=I+B

          where B is of rank (rho), then the Lanczos process converges (in
          exact arithmetic) in at most (rho) iterations. If more generally
          A can be expressed in the form

                                        A=M+C

          where M is symmetric positive-definite and C has rank (rho), then

                           -(1/2)  -(1/2)    -(1/2)  -(1/2)
                          M      AM      =I+M      CM

               -(1/2)  -(1/2)
          and M      AM       also has rank (rho), and the Lanczos process
                      -(1/2)  -(1/2)
          applied to M      AM       would again converge in at most (rho)
          iterations. On a computer, the number of iterations may be
          greater than (rho), but the Lanczos process may still be expected
                                                        -(1/2)  -(1/2)
          to converge rapidly. F04MBF does not require M      AM       to
          be formed explicitly, but implicitly solves the equations

                -(1/2)              -(1/2)   -(1/2)       1/2
               M      (A-(lambda)I)M      y=M      b , y=M   x        (3.2)

          with the user being required to supply a routine MSOLVE to solve
          the equations

                                    Mz=c.                             (3.3)

          For the pre-conditioning option to be effective, it is desirable
          that equations (3.3) can be solved efficiently. The example
          program in Section 9 illustrates the use of this option.

          If we let r denote the residual vector

                                 r=b-(A-(lambda)I)x

          corresponding to an iterate x, then, when pre-conditioning has
          not been requested, the iterative procedure is terminated if it
          is estimated that

                      ||r||<=tol.||A-(lambda)I||.||x||,               (3.4)

          where tol is a user-supplied tolerance, ||r|| denotes the
          Euclidean length of the vector r and ||A|| denotes the Frobenius
          (Euclidean) norm of the matrix A. When pre-conditioning has been
          requested, the iterative procedure is terminated if it is
          estimated that

             -(1/2)            -(1/2)             -(1/2)      1/2
          ||M      r||<=tol.||M      (A-(lambda)I)M     ||.||M   x||. (3.5)

          Note that

                -(1/2)    -(1/2)    -(1/2)              -(1/2)  1/2
               M      r=(M      b)-M      (A-(lambda)I)M      (M   x)

                   -(1/2)
          so that M      r is the residual vector corresponding to equation
          (3.2). The routine will also terminate if it is estimated that

                   ||A-(lambda)I||.||x||>=||b||/(epsilon),            (3.6)

          where (epsilon) is the machine precision, when pre-conditioning
          has not been requested; or if it is estimated that


             -(1/2)              -(1/2)      1/2        -(1/2)
          ||M      (A-(lambda)I)M      ||.||M   x||>=||M      b||/(epsilon)

                                                                      (3.7)

          when pre-conditioning has been requested. If (3.6) is satisfied
          then x is almost certainly an eigenvector of A corresponding to
          the eigenvalue (lambda). If (lambda) was set to 0 (for the
          solution of Ax=b), then this condition simply means that A is
          effectively singular.

          4. References

          [1]   Lewis J G (1977) Algorithms for sparse matrix eigenvalue
                problems. Technical Report STAN-CS-77-595. Computer Science
                Department, Stanford University.

          [2]   Paige C C and Saunders M A (1975) Solution of Sparse
                Indefinite Systems of Linear Equations. SIAM J. Numer. Anal.
                12 617--629.

          5. Parameters

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

           2:  B(N) -- DOUBLE PRECISION array                         Input
               On entry: the right-hand side vector b.

           3:  X(N) -- DOUBLE PRECISION array                        Output
               On exit: the solution vector x.

           4:  APROD -- SUBROUTINE, supplied by the user.
                                                         External Procedure
               APROD must return the vector y=Ax for a given vector x.

               Its specification is:

                      SUBROUTINE APROD (IFLAG, N, X, Y, RWORK, LRWORK,
                     1                  IWORK,LIWORK)
                      INTEGER          IFLAG, N, LRWORK, LIWORK, IWORK
                     1                 (LIWORK)
                      DOUBLE PRECISION X(N), Y(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  Ax.   If IFLAG is negative on exit from
                    APROD, F04MBF will exit immediately with IFAIL set to
                    IFLAG.

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

                3:  X(N) -- DOUBLE PRECISION array                    Input
                    On entry: the vector x for which Ax is required.

                4:  Y(N) -- DOUBLE PRECISION array                   Output
                    On exit: the vector y=Ax.

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

                6:  LRWORK -- INTEGER                                 Input

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

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

           5:  MSOLVE -- SUBROUTINE, supplied by the user.
                                                         External Procedure
               MSOLVE is only referenced when PRECON is supplied as .TRUE..
               When PRECON is supplied as .FALSE., then F04MBF may be
               called with APROD as the actual argument for MSOLVE. When
               PRECON is supplied as .TRUE., then MSOLVE must return the
               solution y of the equations My=x for a given vector x, where
               M must be symmetric positive-definite.

               Its specification is:

                      SUBROUTINE MSOLVE (IFLAG, N, X, Y, RWORK,
                     1                   LRWORK, IWORK,LIWORK)
                      INTEGER          IFLAG, N, LRWORK, LIWORK, IWORK
                     1                 (LIWORK)
                      DOUBLE PRECISION X(N), Y(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
                    solution of My=x.

                    If IFLAG is negative on exit from MSOLVE, F04MBF will
                    exit immediately with IFAIL set to IFLAG.

                2:  N -- INTEGER                                      Input
                    On entry: n, the order of the matrix M.

                3:  X(N) -- DOUBLE PRECISION array                    Input
                    On entry: the vector x for which the equations My=x are
                    to be solved.

                4:  Y(N) -- DOUBLE PRECISION array                   Output
                    On exit: the solution to the equations My=x.

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

                6:  LRWORK -- INTEGER                                 Input

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

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

           6:  PRECON -- LOGICAL                                      Input
               On entry: PRECON specifies whether or not pre-conditioning
               is required. If PRECON = .TRUE., then pre-conditioning will
               be invoked and MSOLVE will be referenced by F04MBF; if
               PRECON = .FALSE., then MSOLVE is not referenced.

           7:  SHIFT -- DOUBLE PRECISION                              Input
               On entry: the value of (lambda). If the equations Ax=b are
               to be solved, then SHIFT must be supplied as zero.

           8:  RTOL -- DOUBLE PRECISION                               Input
               On entry: the tolerance for convergence, tol, of equation
               (3.4). RTOL should not normally be less than (epsilon),
               where (epsilon) is the machine precision.

           9:  ITNLIM -- INTEGER                                      Input
               On entry: an upper limit on the number of iterations. If
               ITNLIM <= 0, then the value N is used in place of ITNLIM.

          10:  MSGLVL -- INTEGER                                      Input
               On entry: the level of printing from F04MBF. If MSGLVL <= 0,
               then no printing occurs, but otherwise messages will be
               output on the advisory message channel (see X04ABF). A
               description of the printed output is given in Section 5.1
               below. The level of printing is determined as follows:
               MSGLVL <= 0
                     No printing.

               MSGLVL = 1
                     A brief summary is printed just prior to return from
                     F04MBF.

               MSGLVL >= 2
                     A summary line is printed periodically to monitor the
                     progress of F04MBF, together with a brief summary just
                     prior to return from F04MBF.

          11:  ITN -- INTEGER                                        Output
               On exit: the number of iterations performed.

          12:  ANORM -- DOUBLE PRECISION                             Output
               On exit: an estimate of ||A-(lambda)I|| when PRECON =
                              -(1/2)              -(1/2)
               .FALSE., and ||M      (A-(lambda)I)M      || when PRECON =
               .TRUE..

          13:  ACOND -- DOUBLE PRECISION                             Output
               On exit: an estimate of the condition number of (A-
               (lambda)I) when PRECON = .FALSE., and of
                -(1/2)              -(1/2)
               M      (A-(lambda)I)M       when PRECON = .TRUE.. This will
               usually be a substantial under-estimate.

          14:  RNORM -- DOUBLE PRECISION                             Output
               On exit: ||r||, where r=b-(A-(lambda)I)x and x is the
               solution returned in X.

          15:  XNORM -- DOUBLE PRECISION                             Output
               On exit: ||x||, where x is the solution returned in X.

          16:  WORK(5*N) -- DOUBLE PRECISION array                Workspace

          17:  RWORK(LRWORK) -- DOUBLE PRECISION array       User Workspace
               RWORK is not used by F04MBF, but is passed directly to
               routines APROD and MSOLVE and may be used to pass
               information to these routines.

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

          19:  IWORK(LIWORK) -- INTEGER array                User Workspace
               IWORK is not used by F04MBF, but is passed directly to
               routines APROD and MSOLVE and may be used to pass
               information to these routines.

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

          21:  INFORM -- INTEGER                                     Output
               On exit: the reason for termination of F04MBF as follows:
               INFORM = 0
                     The right-hand side vector b=0 so that the exact
                     solution is x=0. No iterations are performed in this
                     case.

               INFORM = 1
                     The termination criterion of equation (3.4) has been
                     satisfied with tol as the value supplied in RTOL.

               INFORM = 2
                     The termination criterion of equation (3.4) has been
                     satisfied with tol equal to (epsilon), where (epsilon)
                     is the machine precision. The value supplied in RTOL
                     must have been less than (epsilon) and was too small
                     for the machine.

               INFORM = 3
                     The termination criterion of equation (3.5) has been
                     satisfied so that X is almost certainly an eigenvector
                     of A corresponding to the eigenvalue SHIFT.
               The values INFORM = 4 and INFORM = 5 correspond to failure
               with IFAIL = 3 or IFAIL = 2 respectively (see Section 6) and
               when IFAIL is negative, INFORM will be set to the same
               negative value.

          22:  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).

          5.1. Description of the Printed Output

          When MSGLVL > 0, then F04MBF will produce output (except in the
          case where the routine fails with IFAIL = 1) on the advisory
          message channel (see X04ABF ).

          The following notation is used in the output.

             Output     Meaning

                         -(1/2)                   
             RBAR       M      (b-(A-(lambda)I)x)=r

                         -(1/2)              -(1/2) 
             ABAR       M      (A-(lambda)I)M      =A

                         1/2
             Y          M   x

             R          b-(A-(lambda)I)x

             NORM(A)    ||A||

          Of course, when pre-conditioning has not been requested then the
          first three reduce to (b-(A-(lambda)I)x), (A-(lambda)I) and x
          respectively. When MSGLVL >= 2 then some initial information is
          printed and the following notation is used.

             Output     Meaning

                          T -1  1/2
             BETA1      (b M  b)   ==(beta)
                                           1

                                   2  -(1/2)  T  -(1/2)  -(1/2)   -(1/2)
             ALFA1      (1/(beta) ) (M      b) (M      AM      )(M      b)
                                 1
                        ==(alpha)
                                 1
          and a summary line is printed periodically giving the following
          information:

             Output     Meaning

             ITN        Iteration number, k.

                                                         L         L
             X1(LQ)     The first element of the vector x , where x  is the
                                                         k         k
                        current iterate. See Paige and Saunders [2] for
                        details.

                                                         C         C
             X1(CG)     The first element of the vector x , where x  is the
                                                         k         k
                        vector that would be obtained by conjugate
                        gradients. See Paige and Saunders [2] for details.

                                     

             NORM(RBAR) ||r||, where r is as defined above and x is either
                         L     C
                        x  or x  depending upon which is the best current
                         k     k
                        approximation to the solution. (See LQ/CG below).

             NORM(T)    The value ||T ||, where T  is the tridiagonal
                                     k           k
                        matrix of the Lanczos process. This increases
                                                                

                        monotonically and is a lower bound on ||A||.

             COND(L)    A monotonically increasing lower bound on the
                                                         -1
                        condition number of A, ||A||||(A)  ||.

                                         L
             LQ/CG      L is printed if x  is the best current
                                         k
                        approximation to the solution and C is printed
                        otherwise.

          6. Error Indicators and Warnings

          Errors detected by the routine:

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

          IFAIL= 1
               On entry N < 1,

               or       LRWORK < 1,

               or       LIWORK < 1.

          IFAIL= 2
               The pre-conditioning matrix M does not appear to be
               positive-definite. The user should check that MSOLVE is
               working correctly.

          IFAIL= 3
               The limit on the number of iterations has been reached. If
               IFAIL = 1 on entry then the latest approximation to the
               solution is returned in X and the values ANORM, ACOND, RNORM
               and XNORM are also returned.

          The value of INFORM contains additional information about the
          termination of the routine and users must examine INFORM to judge
          whether the routine has performed successfully for the problem in
          hand. In particular INFORM = 3 denotes that the matrix A-
          (lambda)I is effectively singular: if the purpose of calling
          F04MBF is to solve a system of equations Ax=b, then this
          condition must be regarded as a failure, but if the purpose is to
          compute an eigenvector, this result would be very satisfactory.

          7. Accuracy

          The computed solution x will satisfy the equation

                                 r=b-(A-(lambda)I)x

          where the value ||r|| is as returned in the parameter RNORM.

          8. Further Comments

          The time taken by the routine is likely to be principally
          determined by the time taken in APROD and, when pre-conditioning
          has been requested, in MSOLVE. Each of these routines is called
          once every iteration.

          The time taken by the remaining operations in F04MBF is
          approximately proportional to n.

          9. Example

          To solve the 10 equations Ax=b given by

                            (2 1 0 0 0 0 0 0 0 3)      (6)
                            (1 2 1 0 0 0 0 0 0 0)      (4)
                            (0 1 2 1 0 0 0 0 0 0)      (4)
                            (0 0 1 2 1 0 0 0 0 0)      (4)
                            (0 0 0 1 2 1 0 0 0 0)      (4)
                          A=(0 0 0 0 1 2 1 0 0 0),   b=(4).
                            (0 0 0 0 0 1 2 1 0 0)      (4)
                            (0 0 0 0 0 0 1 2 1 0)      (4)
                            (0 0 0 0 0 0 0 1 2 1)      (4)
                            (3 0 0 0 0 0 0 0 1 2)      (6)

          The tridiagonal part of A is positive-definite and such
          tridiagonal equations can be solved efficiently by F04FAF. The
          form of A suggests that this tridiagonal part is a good candidate
          for the pre-conditioning matrix M and so we illustrate the use of
          F04MBF by pre-conditioning with the 10 by 10 matrix

                                    (2 1 0 ... 0)
                                    (1 2 1 ... 0)
                                    (0 1 2 ... 0)
                                  M=(. . .   .  ).
                                    (. . .   .  )
                                    (. . .   .  )
                                    (0 0 0 ... 2)

          Since A-M has only 2 non-zero elements and is obviously of rank
          2, we can expect F04MBF to converge very quickly in this example.
          Of course, in practical problems we shall not usually be able to
          make such a good choice of M.

                                                  -5
          The example sets the tolerance RTOL = 10  .


          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04mcf}{NAG On-line Documentation: f04mcf}
\beginscroll
\begin{verbatim}



     F04MCF(3NAG)      Foundation Library (12/10/92)      F04MCF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04MCF
                  F04MCF -- 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

          F04MCF computes the approximate solution of a system of real
          linear equations with multiple right-hand sides,  AX=B,  where A
          is a symmetric positive-definite variable-bandwidth matrix, which
          has previously been factorized by F01MCF. Related systems may
          also be solved.

          2. Specification

                 SUBROUTINE F04MCF (N, AL, LAL, D, NROW, IR, B, NRB,
                1                   ISELCT, X, NRX, IFAIL)
                 INTEGER          N, LAL, NROW(N), IR, NRB, ISELCT, NRX,
                1                 IFAIL
                 DOUBLE PRECISION AL(LAL), D(N), B(NRB,IR), X(NRX,IR)

          3. Description

          The normal use of this routine is the solution of the systems
          AX=B, following a call of F01MCF to determine the Cholesky
                             T
          factorization A=LDL  of the symmetric positive-definite variable-
          bandwidth matrix A.

          However, the routine may be used to solve any one of the
          following systems of linear algebraic equations:

                  T
          (1)  LDL X = B (usual system),

          (2)  LDX   = B (lower triangular system),

                 T
          (3)  DL X  = B (upper triangular system),

                 T
          (4)  LL X  = B

          (5)  LX    = B (unit lower triangular system),

                T
          (6)  L X   = B (unit upper triangular system).

          L denotes a unit lower triangular variable-bandwidth matrix of
          order n, D a diagonal matrix of order n, and B a set of right-
          hand sides.

          The matrix L is represented by the elements lying within its
          envelope i.e., between the first non-zero of each row and the
          diagonal (see Section 9 for an example). The width NROW(i) of the
          ith row is the number of elements between the first non-zero
          element and the element on the diagonal inclusive.

          4. References

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

          5. Parameters

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

           2:  AL(LAL) -- DOUBLE PRECISION array                      Input
               On entry: the elements within the envelope of the lower
               triangular matrix L, taken in row by row order, as returned
               by F01MCF. The unit diagonal elements of L must be stored
               explicitly.

           3:  LAL -- INTEGER                                         Input
               On entry:
               the dimension of the array AL as declared in the
               (sub)program from which F04MCF is called.
               Constraint: LAL >= NROW(1) + NROW(2) +... + NROW(n).

           4:  D(N) -- DOUBLE PRECISION array                         Input
               On entry: the diagonal elements of the diagonal matrix D. D
               is not referenced if ISELCT >= 4.

           5:  NROW(N) -- INTEGER array                               Input
               On entry: NROW(i) must contain the width of row i of L,
               i.e.,the number of elements between the first (leftmost)
               non-zero element and the element on the diagonal, inclusive.
               Constraint: 1 <= NROW(i)<=i.

           6:  IR -- INTEGER                                          Input
               On entry: r, the number of right-hand sides. Constraint: IR
               >= 1.

           7:  B(NRB,IR) -- DOUBLE PRECISION array                    Input
               On entry: the n by r right-hand side matrix B. See also
               Section 8.

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

           9:  ISELCT -- INTEGER                                      Input
               On entry: ISELCT must specify the type of system to be
               solved, as follows:

                                     T
               ISELCT = 1:  solve LDL X = B,

               ISELCT = 2:  solve LDX = B,

                                    T
               ISELCT = 3:  solve DL X = B,

                                    T
               ISELCT = 4:  solve LL X = B,

               ISELCT = 5:  solve LX = B,

                                   T
               ISELCT = 6:  solve L X = B.

          10:  X(NRX,IR) -- DOUBLE PRECISION array                   Output
               On exit: the n by r solution matrix X. See also Section 8.

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

          12:  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
               On entry N < 1,

               or       for some i, NROW(i)<1 or NROW(i) > i,

               or       LAL < NROW(1) + NROW(2) +... + NROW(N).

          IFAIL= 2

               On entry IR < 1,

               or       NRB < N,

               or       NRX < N.

          IFAIL= 3
               On entry ISELCT < 1,

               or       ISELCT > 6.

          IFAIL= 4
               The diagonal matrix D is singular, i.e., at least one of the
               elements of D is zero. This can only occur if ISELCT <= 3.

          IFAIL= 5
               At least one of the diagonal elements of L is not equal to
               unity.

          7. Accuracy

          The usual backward error analysis of the solution of triangular
          system applies: each computed solution vector is exact for
          slightly perturbed matrices L and D, as appropriate (cf.
          Wilkinson and Reinsch [1] pp 25--27, 54--55).

          8. Further Comments

          The time taken by the routine is approximately proportional to
          pr, where

                           p=NROW(1)+NROW(2)+...+NROW(n).

          Unless otherwise stated in the Users' Note for your
          implementation, the routine may be called with the same actual
          array supplied for the parameters B and X, in which case the
          solution matrix will overwrite the right-hand side matrix.
          However this is not standard Fortran 77 and may not work in all
          implementations.

          9. Example

          To solve the system of equations AX=B, where

                                  (1  2  0  0  5  0)
                                  (2  5  3  0 14  0)
                                  (0  3 13  0 18  0)
                                A=(0  0  0 16  8 24)
                                  (5 14 18  8 55 17)
                                  (0  0  0 24 17 77)

          and

                                       ( 6 -10)
                                       (15 -21)
                                       (11  -3)
                                     B=( 0  24)
                                       (51 -39)
                                       (46  67)

          Here A is symmetric and positive-definite and must first be
          factorized by F01MCF.

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf04qaf}{NAG On-line Documentation: f04qaf}
\beginscroll
\begin{verbatim}



     F04QAF(3NAG)      Foundation Library (12/10/92)      F04QAF(3NAG)



          F04 -- Simultaneous Linear Equations                       F04QAF
                  F04QAF -- 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

          F04QAF solves sparse unsymmetric equations, sparse linear least-
          squares problems and sparse damped linear least-squares problems,
          using a Lanczos algorithm.

          2. Specification

                 SUBROUTINE F04QAF (M, N, B, X, SE, APROD, DAMP, ATOL,
                1                   BTOL, CONLIM, ITNLIM, MSGLVL, ITN,
                2                   ANORM, ACOND, RNORM, ARNORM, XNORM,
                3                   WORK, RWORK, LRWORK, IWORK, LIWORK,
                4                   INFORM, IFAIL)
                 INTEGER          M, N, ITNLIM, MSGLVL, ITN, LRWORK, IWORK
                1                 (LIWORK), LIWORK, INFORM, IFAIL
                 DOUBLE PRECISION B(M), X(N), SE(N), DAMP, ATOL, BTOL,
                1                 CONLIM, ANORM, ACOND, RNORM, ARNORM,
                2                 XNORM, WORK(N,2), RWORK(LRWORK)
                 EXTERNAL         APROD

          3. Description

          F04QAF can be used to solve a system of linear equations

                                     Ax=b                             (3.1)

          where A is an n by n sparse unsymmetric matrix, or can be used to
          solve linear least-squares problems, so that F04QAF minimizes the
          value (rho) given by

                             (rho)=||r||,  r=b-Ax                     (3.2)

          where A is an m by n sparse matrix and ||r|| denotes the
                                             2  T
          Euclidean length of r so that ||r|| =r r. A damping parameter,
          (lambda), may be included in the least-squares problem in which
          case F04QAF minimizes the value (rho) given by

                             2      2         2     2
                        (rho) =||r|| +(lambda) ||x||                  (3.3)

          (lambda) is supplied as the parameter DAMP and should of course
          be zero if the solution to problems (3.1) or (3.2) is required.
          Minimizing (rho) in (3.3) is often called ridge regression.

          F04QAF is based upon algorithm LSQR (see Paige and Saunders [1]
          and [2]) and solves the problems by an algorithm based upon the
          Lanczos process. Details of the method are given in [1]. The
          routine does not require A explicitly, but A is specified via a
          user-supplied routine APROD which must perform the operations (
                        T
          y+Ax) and (x+A y) for a given n element vector x and m element
          vector y. A parameter to APROD specifies which of the two
          operations is required on a given entry.

          The routine also returns estimates of the standard errors of the
          sample regression coefficients (x , for i=1,2,...,n) given by the
                                           i
          diagonal elements of the estimated variance-covariance matrix V.
          When problem (3.2) is being solved and A is of full rank, then V
          is given by

                            2  T  -1    2      2
                         V=s (A A)  ,  s =(rho) /(m-n),  m>n

          and when problem (3.3) is being solved then V is given by

                    2  T          2  -1    2      2
                 V=s (A A+(lambda) I)  ,  s =(rho) /m,  (lambda)/=0.

              

          Let A denote the matrix

                                    (A        )
               A=A,  (lambda)=0 ; A=((lambda)I),  (lambda)/=0,        (3.4)

              

          let r denote the residual vector

                                       (b) 
                  r=r,  (lambda)=0 ; r=(0)-Ax,  (lambda)/=0           (3.5)

                                                         

          corresponding to an iterate x, so that (rho)=||r|| is the
          function being minimized, and let ||A|| denote the Frobenius
          (Euclidean) norm of A. Then the routine accepts x as a solution
          if it is estimated that one of the following two conditions is
          satisfied:

                                    

                       (rho)<=tol ||A||.||x||+tol ||b||               (3.6)
                                 1               2

                              T           
                           ||A r||<=tol ||A||(rho)                    (3.7)
                                       1

          where tol  and tol  are user-supplied tolerances which estimate
                   1        2
          the relative errors in A and b respectively. Condition (3.6) is
          appropriate for compatible problems where, in theory, we expect
          the residual to be zero and will be satisfied by an acceptable
          solution x to a compatible problem. Condition (3.7) is
          appropriate for incompatible systems where we do not expect the
          residual to be zero and is based upon the observation that, in
          theory,

                                         T
                                        A r=0

          when x is a solution to the least-squares problem, and so (3.7)
          will be satisfied by an acceptable solution x to a linear least-
          squares problem.

          The routine also includes a test to prevent convergence to
          solutions, x, with unacceptably large elements. This can happen
          if A is nearly singular or is nearly rank deficient. If we let
                                 

          the singular values of A be

                        (sigma) >=(sigma) >=...>=(sigma) >=0
                               1         2              n

                                       

          then the condition number of A is defined as

                                   

                              cond(A)=(sigma) /(sigma)
                                             1        k

                                                                    

          where (sigma)  is the smallest non-zero singular value of A and
                       k
                                                   

          hence k is the rank of A. When k<n, then A is rank deficient, the
          least-squares solution is not unique and F04QAF will normally
                                                               

          converge to the minimal length solution. In practice A will not
          have exactly zero singular values, but may instead have small
          singular values that we wish to regard as zero.

          The routine provides for this possibility by terminating if

                                     

                                cond(A)>=c                            (3.8)
                                          lim

                                                                         

          where c    is a user-supplied limit on the condition number of A.
                 lim
          For problem (3.1) termination with this condition indicates that
          A is nearly singular and for problem (3.2) indicates that A is
          nearly rank deficient and so has near linear dependencies in its
                                                        T
          columns. In this case inspection of ||r||, ||A r|| and ||x||,
          which are all returned by the routine, will indicate whether or
          not an acceptable solution has been found. Condition (3.8),
          perhaps in conjunction with (lambda)/=0, can be used to try and '
          regularise' least-squares solutions. A full discussion of the
          stopping criteria is given in Section 6 of reference Paige and
          Saunders [1].

          Introduction of a non-zero damping parameter (lambda) tends to
          reduce the size of the computed solution and to make its
          components less sensitive to changes in the data, and F04QAF is
          applicable when a value of (lambda) is known a priori. To have an
                                                         

          effect, (lambda) should normally be at least \/(epsilon)||A||
          where (epsilon) is the machine precision. For further discussion
          see Paige and Saunders [2] and the references given there.

          Whenever possible the matrix A should be scaled so that the
          relative errors in the elements of A are all of comparable size.
          Such a scaling helps to prevent the least-squares problem from
          being unnecessarily sensitive to data errors and will normally
          reduce the number of iterations required. At the very least, in
          the absence of better information, the columns of A should be
          scaled to have roughly equal column length.

          4. References

          [1]   Paige C C and Saunders M A (1982) LSQR: An Algorithm for
                Sparse Linear Equations and Sparse Least-squares. ACM Trans.
                Math. Softw. 8 43--71.

          [2]   Paige C C and Saunders M A (1982) ALGORITHM 583 LSQR: Sparse
                Linear Equations and Least-squares Problems. ACM Trans.
                Math. Softw. 8 195--209.

          5. Parameters

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

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

           3:  B(M) -- DOUBLE PRECISION array                  Input/Output
               On entry: the right-hand side vector b. On exit: the array
               is overwritten.

           4:  X(N) -- DOUBLE PRECISION array                        Output
               On exit: the solution vector x.

           5:  SE(N) -- DOUBLE PRECISION array                       Output
               On exit: the estimates of the standard errors of the
               components of x. Thus SE(i) contains an estimate of the
               element v   of the estimated variance-covariance matrix V.
                        ii
               The estimates returned in SE will be the lower bounds on the
               actual estimated standard errors, but will usually have at
               least one correct figure.

           6:  APROD -- SUBROUTINE, supplied by the user.
                                                         External Procedure
                                                                   T
               APROD must perform the operations y:=y+Ax and x:=x+A y for
               given vectors x and y.

               Its specification is:

                      SUBROUTINE APROD (MODE, M, N, X, Y, RWORK,
                     1                  LRWORK, IWORK, LIWORK)
                      INTEGER          MODE, M, N, LRWORK, LIWORK,
                     1                 IWORK(LIWORK)
                      DOUBLE PRECISION X(N), Y(M), RWORK(LRWORK)

                1:  MODE -- INTEGER                            Input/Output
                    On entry: MODE specifies which operation is to be
                    performed:
                         If MODE = 1, then APROD must compute y+Ax.

                                                                 T
                         If MODE = 2, then APROD must compute x+A y.
                    On exit: MODE may be used as a flag to indicate a
                                                             T
                    failure in the computation of y+Ax or x+A y. If MODE is
                    negative on exit from APROD, F04QAF will exit
                    immediately with IFAIL set to MODE.

                2:  M -- INTEGER                                      Input
                    On entry: m, the number of rows of A.

                3:  N -- INTEGER                                      Input
                    On entry: n, the number of columns of A.

                4:  X(N) -- DOUBLE PRECISION array             Input/Output
                    On entry: the vector x. On exit: if MODE = 1, X must be
                    unchanged;

                                                   T
                    If MODE = 2, X must contain x+A y.

                5:  Y(M) -- DOUBLE PRECISION array             Input/Output
                    On entry: the vector y. On exit: if MODE = 1, Y must
                    contain y+Ax;

                    If MODE = 2, Y must be unchanged.

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

                7:  LRWORK -- INTEGER                                 Input

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

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

           7:  DAMP -- DOUBLE PRECISION                               Input
               On entry: the value (lambda). If either problem (3.1) or
               problem (3.2) is to be solved, then DAMP must be supplied as
               zero.

           8:  ATOL -- DOUBLE PRECISION                               Input
               On entry: the tolerance, tol , of the convergence criteria
                                           1
               (3.6) and (3.7); it should be an estimate of the largest
               relative error in the elements of A. For example, if the
               elements of A are correct to about 4 significant figures,
                                                    -4
               then ATOL should be set to about 5*10  . If ATOL is supplied
               as less than (epsilon), where (epsilon) is the machine
               precision, then the value (epsilon) is used in place of
               ATOL.

           9:  BTOL -- DOUBLE PRECISION                               Input
               On entry: the tolerance, tol , of the convergence criterion
                                           2
               (3.6);  it should be an estimate of the largest relative
               error in the elements of B. For example, if the elements of
               B are correct to about 4 significant figures, then BTOL
                                          -4
               should be set to about 5*10  . If BTOL is supplied as less
               than (epsilon), where (epsilon) is the machine precision,
               then the value (epsilon) is used in place of BTOL.

          10:  CONLIM -- DOUBLE PRECISION                             Input
               On entry: the value c    of equation  (3.8); it should be an
                                    lim
                                                      

               upper limit on the condition number of A. CONLIM should not
               normally be chosen much larger than 1.0/ATOL. If CONLIM is
               supplied as zero then the value 1.0/(epsilon), where
               (epsilon) is the machine precision, is used in place of
               CONLIM.

          11:  ITNLIM -- INTEGER                                      Input
               On entry: an upper limit on the number of iterations. If
               ITNLIM <= 0, then the value N is used in place of ITNLIM,
               but for ill-conditioned problems a higher value of ITNLIM is
               likely to be necessary.

          12:  MSGLVL -- INTEGER                                      Input
               On entry: the level of printing from F04QAF. If MSGLVL <= 0,
               then no printing occurs, but otherwise messages will be
               output on the advisory message channel (see X04ABF). A
               description of the printed output is given in Section 5.2
               below. The level of printing is determined as follows:
               MSGLVL <= 0
                     No printing.

               MSGLVL = 1
                     A brief summary is printed just prior to return from
                     F04QAF.

               MSGLVL >= 2
                     A summary line is printed periodically to monitor the
                     progress of F04QAF, together with a brief summary just
                     prior to return from F04QAF.

          13:  ITN -- INTEGER                                        Output
               On exit: the number of iterations performed.

          14:  ANORM -- DOUBLE PRECISION                             Output
                                                            

               On exit: an estimate of ||A|| for the matrix A of equation
               (3.4).

          15:  ACOND -- DOUBLE PRECISION                             Output
                                            

               On exit: an estimate of cond(A) which is a lower bound.

          16:  RNORM -- DOUBLE PRECISION                             Output
                                                                

               On exit: an estimate of ||r|| for the residual,  r, of
               equation (3.5) corresponding to the solution x returned in
                              

               X. Note that ||r|| is the function being minimized.

          17:  ARNORM -- DOUBLE PRECISION                            Output
                                              T
               On exit: an estimate of the ||A r|| corresponding to the
               solution x returned in X.

          18:  XNORM -- DOUBLE PRECISION                             Output
               On exit: an estimate of ||x|| for the solution x returned in
               X.

          19:  WORK(2*N) -- DOUBLE PRECISION array                Workspace

          20:  RWORK(LRWORK) -- DOUBLE PRECISION array       User Workspace
               RWORK is not used by F04QAF, but is passed directly to
               routine APROD and may be used to pass information to that
               routine.

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

          22:  IWORK(LIWORK) -- INTEGER array                User Workspace
               IWORK is not used by F04QAF, but is passed directly to
               routine APROD and may be used to pass information to that
               routine.

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

          24:  INFORM -- INTEGER                                     Output
               On exit: the reason for termination of F04QAF as follows:
               INFORM = 0
                     The exact solution is x=0. No iterations are performed
                     in this case.

               INFORM = 1
                     The termination criterion of equation (3.6) has been
                     satisfied with tol  and tol  as the values supplied in
                                       1        2
                     ATOL and BTOL respectively.

               INFORM = 2
                     The termination criterion of equation (3.7) has been
                     satisfied with tol  as the value supplied in ATOL.
                                       1

               INFORM = 3
                     The termination criterion of equation (3.6) has been
                     satisfied with tol  and/or tol  as the value (epsilon)
                                       1           2
                     , where (epsilon) is the machine precision. One or
                     both of the values supplied in ATOL and BTOL must have
                     been less than (epsilon) and was too small for this
                     machine.

               INFORM = 4
                     The termination criterion of equation (3.7) has been
                     satisfied with tol  as the value (epsilon), where
                                       1
                     (epsilon) is the machine precision. The value supplied
                     in ATOL must have been less than (epsilon) and was too
                     small for this machine.
               The values INFORM = 5, INFORM = 6 and INFORM = 7 correspond
               to failure with IFAIL = 2, IFAIL = 3 and IFAIL = 4
               respectively (see Section 6) and when IFAIL is negative
               INFORM will be set to the same negative value.

          25:  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).

          5.1. Description of the printed output

          When MSGLVL > 0, then F04QAF will produce output (except in the
          case where the routine fails with IFAIL = 1) on the advisory
          message channel (see X04ABF ).

          When MSGLVL >= 2 then a summary line is printed periodically
          giving the following information:

             Output       Meaning

             ITN          Iteration number, k.

             X(1)         The first element of the current iterate x .
                                                                    k

             FUNCTION     The current value of the function, (rho), being
                          minimized.

                                                             

             COMPAT       An estimate of ||r ||/||b||, where r  is the
                                            k                 k
                          residual corresponding to x . This value should
                                                     k
                          converge to zero (in theory) if and only if the
                          problem is compatible. COMPAT decreases
                          monotonically.

                                            T             
             INCOMPAT     An estimate of ||A r ||/(||A||||r ||) which
                                              k            k
                          should converge to zero if and only if at the
                          solution (rho) is non-zero. INCOMPAT is not
                          usually monotonic.

                                                                   

             NRM(ABAR)    A monotonically increasing estimate of ||A||.

             COND(ABAR)   A monotonically increasing estimate of the
                                                

                          condition number cond(A).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL< 0
               A negative value of IFAIL indicates an exit from F04QAF
               because the user has set MODE negative in APROD. The value
               of IFAIL will be the same as the user's setting of MODE.

          IFAIL= 1
               On entry M < 1,

               or       N < 1,

               or       LRWORK < 1,

               or       LIWORK < 1.

          IFAIL= 2
               The condition of equation (3.8) has been satisfied for the
               value of c    supplied in CONLIM. If this failure is
                         lim
               unexpected the user should check that APROD is working
               correctly. Although conditions (3.6) or (3.7) have not been
               satisfied, the values returned in RNORM, ARNORM and XNORM
               may nevertheless indicate that an acceptable solution has
               been reached.

          IFAIL= 3
               The conditions of equation (3.8) has been satisified for the
               value c   =1.0/(epsilon), where (epsilon) is the machine
                      lim
                                     

               precision. The matrix A is nearly singular or rank deficient
               and the problem is too ill-conditioned for this machine. If
               this failure is unexpected, the user should check that APROD
               is working correctly.

          IFAIL= 4
               The limit on the number of iterations has been reached. The
               number of iterations required by F04QAF and the condition of
                          

               the matrix A can depend strongly on the scaling of the
               problem. Poor scaling of the rows and columns of A should be
               avoided whenever possible.

          7. Accuracy

          When the problem is compatible, the computed solution x will
          satisfy the equation

                                       r=b-Ax,

          where an estimate of ||r|| is returned in the parameter RNORM.
          When the problem is incompatible, the computed solution x will
          satisfy the equation

                                        T
                                       A r=e,

          where an estimate of ||e|| is returned in the parameter ARNORM.
          See also Section 6.2 of Paige and Saunders [1].

          8. Further Comments

          The time taken by the routine is likely to be principally
          determined by the time taken in APROD, which is called twice on
          each iteration, once with MODE = 1 and once with MODE = 2. The
          time taken per iteration by the remaining operations in F04QAF is
          approximately proportional to max(m,n).

          The Lanczos process will usually converge more quickly if A is
          pre-conditioned by a non-singular matrix M that approximates A in
          some sense and is also chosen so that equations of the form My=c
          can efficiently be solved for y. Some discussion of pre-
          conditioning in the context of symmetric matrices is given in
          Section 3 of the document for F04MBF. In the context of F04QAF,
          problem (3.1) is equivalent to

                                     -1
                                  (AM  )y=b,  Mx=y

          and problem (3.2) is equivalent to minimizing

                                               -1
                          (rho)=||r||,  r=b-(AM  )y,  Mx=y.

                                         -1 T   -1   -T  T   -1
          Note that the normal matrix (AM  ) (AM  )=M  (A A)M   so that the
                             -1
          pre-conditioning AM   is equivalent to the pre-conditioning
           -T  T   -1                       T
          M  (A A)M   of the normal matrix A A.

          Pre-conditioning can be incorporated into F04QAF simply by coding
                                           -1         -T T
          the routine APROD to compute y+AM  x and x+M  A y in place of
                      T
          y+Ax and x+A y respectively, and then solving the equations Mx=y
                                           -1
          for x on return from F04QAF. y+AM  x should be computed by
                                                             -T T
          solving Mz=x for z and then computing y+Az, and x+M  A y should
                                  T   T
          be computed by solving M z=A y for z and then forming x+z.

          9. Example

          To solve the linear least-squares problem

                            minimize (rho)=||r||,  r=b-Ax

          where A is the 13 by 12 matrix and b is the 13 element vector
          given by

                        ( 1  0  0 -1  0  0  0  0  0  0  0  0)
                        ( 0  1  0  0 -1  0  0  0  0  0  0  0)
                        ( 0  0  1 -1  0  0  0  0  0  0  0  0)
                        (-1  0 -1  4 -1  0  0 -1  0  0  0  0)
                        ( 0 -1  0 -1  4 -1  0  0 -1  0  0  0)
                        ( 0  0  0  0 -1  1  0  0  0  0  0  0)
                      A=( 0  0  0  0  0  0  1 -1  0  0  0  0),
                        ( 0  0  0 -1  0  0 -1  4 -1  0 -1  0)
                        ( 0  0  0  0 -1  0  0 -1  4 -1  0 -1)
                        ( 0  0  0  0  0  0  0  0 -1  1  0  0)
                        ( 0  0  0  0  0  0  0 -1  0  0  1  0)
                        ( 0  0  0  0  0  0  0  0 -1  0  0  1)
                        ( 1  1  1  0  0  1  1  0  0  1  1  1)

                                          ( 0  )
                                          ( 0  )
                                          ( 0  )
                                          ( 1  )
                                          ( 1  )
                                         2( 0  )
                                     b=-h ( 0  )
                                          ( 1  )
                                          ( 1  )
                                          ( 0  )
                                          ( 0  )
                                          ( 0  )
                                          (  -3)
                                          (-h  )

          with h=0.1.

          Such a problem can arise by considering the Neumann problem on a
          rectangle

                              (delta)u
                              --------=0
                              (delta)n

               (delta)u            2           (delta)u      /
               --------=0   (nabla) u=g(x,y)   --------=0    |u=1
               (delta)n                        (delta)n      /
                                                             c

                              (delta)u
                              --------=0
                              (delta)n

          where C is the boundary of the rectangle, and discretising as
          illustrated below with the square mesh



                   Please see figure in printed Reference Manual

          The 12 by 12 symmetric part of A represents the difference
          equations and the final row comes from the normalising condition.
          The example program has g(x,y)=1 at all the internal mesh points,
          but apart from this is written in a general manner so that the
          number of rows (NROWS) and columns (NCOLS) in the grid can
          readily be altered.

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf06}{NAG On-line Documentation: f06}
\beginscroll
\begin{verbatim}



     F06(3NAG)         Foundation Library (12/10/92)         F06(3NAG)



          F06 -- Linear Algebra Support Routines        Introduction -- F06
                                    Chapter F06
                          Linear Algebra Support Routines

          Contents of this Introduction:

          1.     Scope of the Chapter

          2.     Background to the Problems

          2.1.   The Use of BLAS Names

          2.2.   Background Information

          2.2.1. Real plane rotations

          2.3.   References

          3.     Recommendations on Choice and Use of Routines

          3.1.   The Level-0 Scalar Routines

          3.2.   The Level-1 Vector Routines

          3.3.   The Level-2 Matrix-vector Routines

          3.4.   The Level-3 Matrix-matrix Routines

          4.     Description of the F06 Routines

          4.1.   The Level-0 Scalar Routines

          4.2.   The Level-1 Vector Routines

          4.3.   The Level-2 Matrix-vector Routines

          4.4.   The Level-3 Matrix-matrix Routines



          1. Scope of the Chapter

          This Chapter is concerned with basic linear algebra routines
          which perform elementary algebraic operations involving scalars,
          vectors and matrices.

          2. Background to the Problems

          All the routines in this Chapter meet the specification of the
          Basic Linear Algebra Subprograms (BLAS) as described in Lawson
          et al [6], Dongarra et al [3] and [4]. The first reference
          describes a set of routines concerned with operations on scalars
          and vectors: these will be referred to here as the Level-0 and
          the Level-1 BLAS; the second reference describes a set of
          routines concerned with matrix-vector operations: these will be
          referred to here as the Level-2 BLAS; and the third reference
          describes a set of routines concerned with matrix-matrix
          operations: these will be referred to here as the Level-3 BLAS.
          The terminology reflects the number of operations involved. For
                                                 2
          example, a Level-2 routine involves 0(n ) operations for an n by
          n matrix.

          Table 1.1 indicates the naming scheme for the routines in this
          Chapter. The heading 'mixed type' is for routines where a mixture
          of data types is involved, such as a routine that returns the
          real Euclidean length of a complex vector.


                                       Level-0  Level-1  Level-2  Level-3
                'real'   BLAS routine  F06A F   F06E F   F06P F   F06Y F
             'complex'   BLAS routine  -        F06G F   F06S F   F06Z F

                                     Table 1.1



          The routines in this chapter do not have full routine documents,
          but instead are covered by some relevant background material, in
          Section 2.2, together with general descriptions, in Section 4,
          sufficient to enable their use. As this chapter is concerned only
          with basic linear algebra operations, the routines will not
          normally be required by the general user. The functionality of
          each routine is indicated in Section 3 so that those users
          requiring these routines to build specialist linear algebra
          modules can determine which routines are of interest.

          2.1. The Use of BLAS Names

          Many of the routines in other chapters of the Library call the
          BLAS in this chapter. These routines are usually called by the
          BLAS name and so, for correct operation of the Library, it is
          essential that users do not attempt to link their own versions of
          these routines. If users are in any doubt about how to avoid
          this, please consult your local support staff or the NAG Response
          Centre.

          The BLAS names are used in order to make use of efficient
          implementations of the routines when these exist. Such
          implementations are stringently tested before being used, to
          ensure that they correctly meet the specification of the BLAS,
          and that they return the desired accuracy (see, for example,
          Dongarra et al. [3] and [4]).

          2.2. Background Information

          Most of the routines in this chapter implement straightforward
          scalar, vector and matrix operations that need no further
          explanation beyond a statement of the purpose of the routine. In
          this section we give some additional background information for
          those few cases where additional explanation may be necessary.

          2.2.1.  Real plane rotations

          Two routines in the chapter are concerned with setting up and
          applying plane rotations. For further background information see
          Golub and Van Loan [5].

          A plane rotation matrix for the (i,j) plane, R  , is an
                                                        ij
          orthogonal matrix that is different from the unit matrix only in
          the elements r  , r  , r   and r  . If we put
                        ii   jj   ij      ji


                                      (r   r  )
                                      ( ii  ij)
                                    R=(r   r  ),
                                      ( ji  jj)

          then, in the real case, it is usual to choose R   so that
                                                         ij

                     ( c s)
                   R=(-s c),  c=cos(theta),  s=sin(theta).            (2.1)

          The application of plane rotations is straightforward and needs
          no further elaboration, so further comment is made only on the
          construction of plane rotations.

          The most common use of plane rotations is to choose c and s so
          that for given a and b,


                                ( c s)(a) (d)
                                (-s c)(b)=(0)                         (2.2)

          In such an application the matrix R is often termed a Givens
          rotation matrix.

          The BLAS routine F06AAF(*) (DROTG), see Lawson et al [6] and
          Dodson and Grimes [1, 2], computes c, s and d as


                                           2  2 1/2
                                d=(sigma)(a +b )   ,
                          {a/d, d/=0      {b/d, d/=0
                        c={1,   d=0 ,   s={0,   d=0                   (2.3)

                        {sign a,|a|>|b|
          where (sigma)={sign b,|a|<=|b|.

          The value z defined as

                               {s,   |s|<c or c=0
                             z={1/c, 0<|c|<=s                         (2.4)

          is also computed and this enables c and s to be reconstructed
          from the single value z as


                         {0,          z=1
                         {    2 1/2             {1,       z=1
                       c={(1-z )   , |z|<1    s={z,      |z|<1
                         {1/z,       |z|>1,     {    2
                                                {(1-c ), |z|>1.

          2.3. References

          [1]   Dodson D S and Grimes R G (1982) Remark on Algorithm 539.
                ACM Trans Math Softw. 8 403--404.

          [2]   Dodson D S and Grimes R G (1982) Remark on Algorithm 539.
                ACM Trans. Math. Softw. 9 140.

          [3]   Dongarra J J, Du Croz J J, Hammarling S and Hanson R J
                (1988) An Extended Set of FORTRAN Basic Linear Algebra
                Subprograms. ACM Trans. Math. Softw. 14 1--32.

          [4]   Dongarra J J, Du Croz J J, Duff I S and Hammarling S (1990)
                A Set of Level 3 Basic Linear Algebra Subprograms. ACM
                Trans. Math. Softw. 16 1--28.

          [5]   Golub G H and Van Loan C F (1989) Matrix Computations (2nd
                Edition). Johns Hopkins University Press, Baltimore,
                Maryland.

          [6]   Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979)
                Basic Linear Algebra Subprograms for Fortran Usage. ACM
                Trans. Math. Softw. 5 308--325.

          3. Recommendations on Choice and Use of Routines

          This section lists the routines in each of the categories Level-0
          (scalar), Level-1 (vector), Level-2 (matrix-vector and matrix)
          and Level-3 (matrix-matrix). The corresponding double precision
          BLAS name is indicated in brackets.

          Within each section routines are listed in alphabetic order of
          the fifth character in the routine name, so that corresponding
          real and complex routines may have adjacent entries.

          3.1. The Level-0 Scalar Routine

          The Level-0 routine performs the scalar operation of generating a
          plane rotation.

          F06AAF (DROTG)  generates a real plane rotation.

          3.2. The Level-1 Vector Routines

          The Level-1 routines perform operations on or between vectors,
          such as computing dot products and Euclidean lengths.

          F06EAF (DDOT)   computes the dot product of two real vectors

          F06GAF (ZDOTU)  computes the dot product of two complex vectors
                          (unconjugated)

          F06GBF (ZDOTC)  computes the dot product of two complex vectors
                          (conjugated)

          F06ECF (DAXPY)  adds a scalar times a vector to another real
                          vector

          F06GCF (ZAXPY)  adds a scalar times a vector to another complex
                          vector

          F06EDF (DSCAL)  multiplies a real vector by a scalar

          F06GDF (ZSCAL)  multiplies a complex vector by a scalar

          F06JDF (ZDSCAL) multiplies a complex vector by a real scalar

          F06EFF (DCOPY)  copies a real vector

          F06GFF (ZCOPY)  copies a complex vector

          F06EGF (DSWAP)  swaps two real vectors

          F06GGF (ZSWAP)  swaps two complex vectors

          F06EJF (DNRM2)  computes the Euclidean length of a real vector

          F06JJF (DZNRM2) computes the Euclidean length of a complex vector

          F06EKF (DASUM)  sums the absolute values of the elements of a
                          real vector

          F06JKF (DZASUM) sums the absolute values of the elements of a
                          complex vector

          F06JLF (IDAMAX) finds the index of the element of largest
                          absolute value of a real vector

          F06JMF (IZAMAX) finds the index of the element of largest
                          absolute value of a complex vector

          F06EPF (DROT)   applies a real plane rotation

          3.3. The Level-2 Matrix-vector Routines

          The Level-2 routines perform matrix-vector operations, such as
          forming the product between a matrix and a vector.

          F06PAF (DGEMV)  computes a matrix-vector product;
                          real general matrix

          F06SAF (ZGEMV)  computes a matrix-vector product;
                          complex general matrix

          F06PBF (DGBMV)  computes a matrix-vector product;
                          real general band matrix

          F06SBF (ZGBMV)  computes a matrix-vector product;
                          complex general band matrix

          F06PCF (DSYMV)  computes a matrix-vector product;
                          real symmetric matrix

          F06SCF (ZHEMV)  computes a matrix-vector product;
                          complex Hermitian matrix

          F06PDF (DSBMV)  computes a matrix-vector product;
                          real symmetric band matrix

          F06SDF (ZHBMV)  computes a matrix-vector product;
                          complex Hermitian band matrix

          F06PEF (DSPMV)  computes a matrix-vector product;
                          real symmetric packed matrix

          F06SEF (ZHPMV)  computes a matrix-vector product;
                          complex Hermitian packed matrix

          F06PFF (DTRMV)  computes a matrix-vector product;
                          real triangular matrix

          F06SFF (ZTRMV)  computes a matrix-vector product;
                          complex triangular matrix

          F06PGF (DTBMV)  computes a matrix-vector product;
                          real triangular band matrix

          F06SGF (ZTBMV)  computes a matrix-vector product;
                          complex triangular band matrix

          F06PHF (DTPMV)  computes a matrix-vector product;
                          real triangular packed matrix

          F06SHF (ZTPMV)  computes a matrix-vector product;
                          complex triangular packed matrix

          F06PJF (DTRSV)  solves a system of equations;
                          real triangular coefficient matrix

          F06SJF (ZTRSV)  solves a system of equations;
                          complex triangular coefficient matrix

          F06PKF (DTBSV)  solves a system of equations;
                          real triangular band coefficient matrix

          F06SKF (ZTBSV)  solves a system of equations;
                          complex triangular band coefficient matrix

          F06PLF (DTPSV)  solves a system of equations;
                          real triangular packed coefficient matrix

          F06SLF (ZTPSV)  solves a system of equations;
                          complex triangular packed coefficient matrix

          F06PMF (DGER)   performs a rank-one update;
                          real general matrix

          F06SMF (ZGERU)  performs a rank-one update;
                          complex general matrix (unconjugated vector)

          F06SNF (ZGERC)  performs a rank-one update;
                          complex general matrix (conjugated vector)

          F06PPF (DSYR)   performs a rank-one update;
                          real symmetric matrix

          F06SPF (ZHER)   performs a rank-one update;
                          complex Hermitian matrix

          F06PQF (DSPR)   performs a rank-one update;
                          real symmetric packed matrix

          F06SQF (ZHPR)   performs a rank-one update;
                          complex Hermitian packed matrix

          F06PRF (DSYR2)  performs a rank-two update;
                          real symmetric matrix

          F06SRF (ZHER2)  performs a rank-two update;
                          complex Hermitian matrix

          F06PSF (DSPR2)  performs a rank-two update;
                          real symmetric packed matrix

          F06SSF (ZHPR2)  performs a rank-two update;
                          complex Hermitian packed matrix

          3.4. The Level-3 Matrix-matrix Routines

          The Level-3 routines perform matrix-matrix operations, such as
          forming the product of two matrices.

          F06YAF (DGEMM)  computes a matrix-matrix product; two real
                          rectangular matrices

          F06ZAF (ZGEMM)  computes a matrix-matrix product; two complex
                          rectangular matrices

          F06YCF (DSYMM)  computes a matrix-matrix product; one real
                          symmetric matrix, one real rectangular matrix

          F06ZCF (ZHEMM)  computes a matrix-matrix product; one complex
                          Hermitian matrix, one complex rectangular matrix

          F06YFF (DTRMM)  computes a matrix-matrix product; one real
                          triangular matrix, one real rectangular matrix

          F06ZFF (ZTRMM)  computes a matrix-matrix product; one complex
                          triangular matrix, one complex rectangular matrix

          F06YJF (DTRSM)  solves a system of equations with multiple right-
                          hand sides, real triangular coefficient matrix

          F06ZJF (ZTRSM)  solves a system of equations with multiple right-
                          hand sides, complex triangular coefficient matrix

          F06YPF (DSYRK)  performs a rank-k update of a real symmetric
                          matrix

          F06ZPF (ZHERK)  performs a rank-k update of a complex hermitian
                          matrix

          F06YRF (DSYR2K) performs a rank-2k update of a real symmetric
                          matrix

          F06ZRF (ZHER2K) performs a rank-2k update of a complex Hermitian
                          matrix

          F06ZTF (ZSYMM)  computes a matrix-matrix product: one complex
                          symmetric matrix, one complex rectangular matrix

          F06ZUF (ZSYRK)  performs a rank-k update of a complex symmetric
                          matrix

          F06ZWF (ZSYR2K) performs a rank-2k update of a complex symmetric
                          matrix

          4. Description of the F06 Routines

          In this section we describe the purpose of each routine and give
          information on the parameter lists, where appropriate indicating
          their general nature. Usually the association between the routine
          arguments and the mathematical variables is obvious and in such
          cases a description of the argument is omitted.

          Within each section, the parameter lists for all routines are
          presented, followed by the purpose of the routines and
          information on the parameter lists. The double precision BLAS
          names are given in ENTRY statements.

          Within each section routines are listed in alphabetic order of
          the fifth character in the routine name, so that corresponding
          real and complex routines may have adjacent entries.

          4.1. The Level-0 Scalar Routines

          The scalar routines have no array arguments.


          SUBROUTINE   F06AAF( A,B,C,S )
          ENTRY        DROTG ( A,B,C,S )
          DOUBLE PRECISION     A,B,C,S

          F06AAF(*) generates the parameters c and s of a Givens rotation
          as defined by equations (2.3) and (2.4), from given a and b. On
          exit, A is overwritten by d and B is overwritten by z.

          4.2. The Level-1 Vector Routines

          The vector routines all have one or more one-dimensional arrays
          as arguments, each representing a vector.

          The length of each vector, n, is represented by the argument N,
          and the routines may be called with non-positive values of N, in
          which case the routine returns immediately except for the
          functions, which set the function value to zero before returning.

          In addition to the argument N, each array argument is also
          associated with an increment argument that immediately follows
          the array argument, and whose name consists of the three
          characters INC, followed by the name of the array. For example, a
          vector x will be represented by the two arguments X, INCX. The
          increment argument is the spacing (stride) in the array for which
          the elements of the vector occur. For instance, if INCX = 2, then
          the elements of x are in locations X(1),X(3),...,X(2*N-1) of the
          array X and the intermediate locations X(2),X(4),...,X(2*N-2) are
          not referenced.

          Thus when INCX > 0, the vector element x  is in the array element
                                                  i
          X(1+(i-1)*INCX). When INCX <= 0 the elements are stored in the
          reverse order so that the vector element x  is in the array
                                                    i
          element X(1-(n-i)*INCX) and hence, in particular, the element x
                                                                         n
          is in X(1). The declared length of the array X in the calling
          (sub)program must be at least (1+(N-1)*|INCX|).

          Non-positive increments are permitted only for those routines
          that have more than one array argument. While zero increments are
          formally permitted for such routines, their use in Chapter F06 is
          strongly discouraged since the effect may be implementation
          dependent.



          DOUBLE PRECISION FUNCTION F06EAF ( N,      X,INCX,Y,INCY )
          DOUBLE PRECISION          DDOT
          ENTRY                     DDOT   ( N,      X,INCX,Y,INCY )
          INTEGER                            N,        INCX,  INCY
          DOUBLE PRECISION                           X(*),  Y(*)

          COMPLEX(KIND(1.0D0)) FUNCTION F06GAF ( N,      X,INCX,Y,INCY )
          COMPLEX(KIND(1.0D0))          ZDOTU
          ENTRY                         ZDOTU  ( N,      X,INCX,Y,INCY )
          INTEGER                                N,        INCX,  INCY
          COMPLEX(KIND(1.0D0))                           X(*),  Y(*)

          COMPLEX(KIND(1.0D0)) FUNCTION F06GBF ( N,      X,INCX,Y,INCY )
          COMPLEX(KIND(1.0D0))          ZDOTC
          ENTRY                         ZDOTC  ( N,      X,INCX,Y,INCY )
          INTEGER                                N,        INCX,  INCY
          COMPLEX(KIND(1.0D0))                           X(*),  Y(*)

          SUBROUTINE                F06ECF ( N,ALPHA,X,INCX,Y,INCY )
          ENTRY                     DAXPY  ( N,ALPHA,X,INCX,Y,INCY )
          INTEGER                            N,        INCX,  INCY
          DOUBLE PRECISION                     ALPHA,X(*),  Y(*)

          SUBROUTINE                F06GCF ( N,ALPHA,X,INCX,Y,INCY )
          ENTRY                     ZAXPY  ( N,ALPHA,X,INCX,Y,INCY )
          INTEGER                            N,        INCX,  INCY
          COMPLEX(KIND(1.0D0))                 ALPHA,X(*),  Y(*)

          SUBROUTINE                F06EDF ( N,ALPHA,X,INCX )
          ENTRY                     DSCAL  ( N,ALPHA,X,INCX )
          INTEGER                            N,        INCX
          DOUBLE PRECISION                     ALPHA,X(*)

          SUBROUTINE                F06GDF ( N,ALPHA,X,INCX )
          ENTRY                     ZSCAL  ( N,ALPHA,X,INCX )
          INTEGER                            N,        INCX
          COMPLEX(KIND(1.0D0))                 ALPHA,X(*)

          SUBROUTINE                F06JDF ( N,ALPHA,X,INCX )
          ENTRY                     ZDSCAL ( N,ALPHA,X,INCX )
          INTEGER                            N,        INCX
          DOUBLE PRECISION          ALPHA
          COMPLEX(KIND(1.0D0))                       X(*)

          SUBROUTINE                F06EFF ( N,      X,INCX,Y,INCY )
          ENTRY                     DCOPY  ( N,      X,INCX,Y,INCY )
          INTEGER                            N,        INCX,  INCY
          DOUBLE PRECISION                           X(*),  Y(*)

          SUBROUTINE                F06GFF ( N,      X,INCX,Y,INCY )
          ENTRY                     ZCOPY  ( N,      X,INCX,Y,INCY )
          INTEGER                            N,        INCX,  INCY
          COMPLEX(KIND(1.0D0))                       X(*),  Y(*)

          SUBROUTINE                F06EGF ( N,      X,INCX,Y,INCY )
          ENTRY                     DSWAP  ( N,      X,INCX,Y,INCY )
          INTEGER                            N,        INCX,  INCY
          DOUBLE PRECISION                           X(*),  Y(*)

          SUBROUTINE                F06GGF ( N,      X,INCX,Y,INCY )
          ENTRY                     ZSWAP  ( N,      X,INCX,Y,INCY )
          INTEGER                            N,        INCX,  INCY
          COMPLEX(KIND(1.0D0))                       X(*),  Y(*)

          DOUBLE PRECISION FUNCTION F06EJF ( N,      X,INCX )
          DOUBLE PRECISION          DNRM2
          ENTRY                     DNRM2  ( N,      X,INCX )
          INTEGER                            N,        INCX
          DOUBLE PRECISION                           X(*)

          DOUBLE PRECISION FUNCTION F06JJF ( N,      X,INCX )
          DOUBLE PRECISION          DZNRM2
          ENTRY                     DZNRM2 ( N,      X,INCX )
          INTEGER                            N,        INCX
          COMPLEX(KIND(1.0D0))                       X(*)

          DOUBLE PRECISION FUNCTION F06EKF ( N,      X,INCX )
          DOUBLE PRECISION          DASUM
          ENTRY                     DASUM  ( N,      X,INCX )
          INTEGER                            N,        INCX
          DOUBLE PRECISION                           X(*)

          DOUBLE PRECISION FUNCTION F06JKF ( N,      X,INCX )
          DOUBLE PRECISION          DZASUM
          ENTRY                     DZASUM ( N,      X,INCX )
          INTEGER                            N,        INCX
          COMPLEX(KIND(1.0D0))                       X(*)

          INTEGER FUNCTION          F06JLF ( N,      X,INCX )
          INTEGER                   IDAMAX
          ENTRY                     IDAMAX ( N,      X,INCX )
          INTEGER                            N,        INCX
          DOUBLE PRECISION                            X(*)

          INTEGER FUNCTION          F06JMF ( N,      X,INCX )
          INTEGER                   IZAMAX
          ENTRY                     IZAMAX ( N,      X,INCX )
          INTEGER                            N,        INCX
          COMPLEX(KIND(1.0D0))                       X(*)

          SUBROUTINE                F06EPF ( N,      X,INCX,Y,INCY,C,S )
          ENTRY                     DROT   ( N,      X,INCX,Y,INCY,C,S )
          INTEGER                            N,        INCX,  INCY
          DOUBLE PRECISION                           X(*),  Y(*),  C,S

          F06EAF(*) and F06GAF(*)

                                  T
          return the dot product x y.

          F06GBF(*)

                                   H          H
          returns the dot product x y, where x  denotes the complex
                        T
          conjugate of x .

          F06ECF(*) and F06GCF(*)

          perform the operation y<-(alpha)x+y, often called an axpy
          operation.

          F06EDF(*), F06GDF(*) and F06JDF(*)

          perform the operation x<-(alpha)x.

          F06EFF(*) and F06GFF(*)

          perform the operation y<-x.

          F06EGF(*) and F06GGF(*)

          perform the operation x<=>y, that is x and y are swapped.

          F06EJF(*) and F06JJF(*)

                                                     ( n       )1/2
                                                     ( --     2)
          return the value ||x||  defined by ||x|| = ( >  |x | )   .
                                2                 2  ( --   i  )
                                                     ( i=1     )

          F06EKF(*)

                                                      n
                                                      --
          returns the value ||x||  defined by ||x|| = >  |x |.
                                 1                 1  --   i
                                                      i=1

          F06JKF(*)

                                                  n
                                                  --
          returns the value asum defined by asum= >  (|(Re(x )|+|Im(x )|).
                                                  --        i        i
                                                  i=1

          F06JLF(*)

          returns the first index j such that |x |=max |x |.
                                                j     i  i

          F06JMF(*)

          returns the first index j such that
          |Re(x )|+|Im(x )|=max (|(Re(x )|+|Im(x )|).
               j        j      i       i        i

          F06EPF(*)

                                      ( T)          ( T)
                                      (x )          (x )
                                      ( T)    ( c s)( T)
          performs the plane rotation (y ) <- (-s c)(y ).

          4.3. The Level-2 Matrix-vector Routines

          The matrix-vector routines all have one array argument
          representing a matrix; usually this is a two-dimensional array
          but in some cases the matrix is represented by a one-dimensional
          array.

          The size of the matrix is determined by the arguments M and N for
          an m by n rectangular matrix; and by the argument N for an n by n
          symmetric, Hermitian, or triangular matrix. Note that it is
          permissible to call the routines with M or N = 0, in which case
          the routines exit immediately without referencing their array
          arguments. For band matrices, the bandwidth is determined by the
          arguments KL and KU for a rectangular matrix with kl sub-
          diagonals and ku super-diagonals; and by the argument K for a
          symmetric, Hermitian, or triangular matrix with k sub-diagonals
          and/or super-diagonals.

          The description of the matrix consists either of the array name
          (A) followed by the first dimension of the array as declared in
          the calling (sub)program (LDA), when the matrix is being stored
          in a two-dimensional array; or the array name (AP) alone when the
          matrix is being stored as a (packed) vector. In the former case
          the actual array must contain at least ((n-1)d+l) elements, where
          d is the first dimension of the array, d>=l , and l=m for arrays
          representing general matrices, l=n for arrays representing
          symmetric, Hermitian and triangular matrices, l=kl+ku+1 for
          arrays representing general band matrices and l=k+1 for
          symmetric, Hermitian and triangular band matrices. For one-
          dimensional arrays representing matrices (packed storage) the
                                             1
          actual array must contain at least -n(n+1) elements.
                                             2

          As with the vector routines, vectors are represented by one-
          dimensional arrays together with a corresponding increment
          argument (see Section 4.2). The only difference is that for these
          routines a zero increment is not permitted.

          When the vector x consists of k elements then the declared length
          of the array X in the calling (sub)program must be at least
          (1+(k-1)|INCX|).

          The arguments that specify options are character arguments with
          the names TRANS, UPLO and DIAG. TRANS is used by the matrix-
          vector product routines as follows:

              Value      Meaning

              'N' or 'n' Operate with the matrix

              'T' or 't' Operate with the transpose of the matrix

              'C' or 'c' Operate with the conjugate transpose of the matrix

          In the real case the values 'T', 't', 'C' and 'c' have the same
          meaning.

          UPLO is used by the Hermitian, symmetric, and triangular matrix
          routines to specify whether the upper or lower triangle is being
          referenced as follows:


              Value      Meaning

              'U' or 'u' Upper triangle

              'L' or 'l' Lower triangle

          DIAG is used by the triangular matrix routines to specify whether
          or not the matrix is unit triangular, as follows:

              Value      Meaning

              'U' or 'u' Unit triangular

              'N' or 'n' Non-unit triangular

          When DIAG is supplied as 'U' or 'u' the diagonal elements are not
          referenced.

          It is worth noting that actual character arguments in Fortran may
          be longer than the corresponding dummy arguments. So that, for
          example, the value 'T' for TRANS may be passed as 'TRANSPOSE'.

          The routines for real symmetric and complex Hermitian matrices
          allow for the matrix to be stored in either the upper (UPLO = 'U
          to be packed in a one-dimensional array. In the latter case the
          upper triangle may be packed sequentially column by column (UPLO
          = 'U'), or the lower triangle may be packed sequentially column
          by column (UPLO = 'L'). Note that for real symmetric matrices
          packing the upper triangle by column is equivalent to packing the
          lower triangle by rows, and packing the lower triangle by columns
          is equivalent to packing the upper triangle by rows. (For complex
          Hermitian matrices the only difference is that the off-diagonal
          elements are conjugated.)

          For triangular matrices the argument UPLO serves to define
          whether the matrix is upper (UPLO = 'U') or lower (UPLO = 'L')
          triangular. In packed storage the triangle has to be packed by
          column.

          The band matrix routines allow storage so that the jth column of
          the matrix is stored in the jth column of the Fortran array. For
          a general band matrix the diagonal of the matrix is stored in the
          (ku+1)th row of the array. For a Hermitian or symmetric matrix
          either the upper triangle (UPLO = 'U') may be stored in which
          case the leading diagonal is in the (k+1)th row of the array, or
          the lower triangle (UPLO = 'L') may be stored in which case the
          leading diagonal is in the first row of the array. For an upper
          triangular band matrix (UPLO = 'U') the leading diagonal is in
          the (k+1)th row of the array and for a lower triangular band
          matrix (UPLO = 'L') the leading diagonal is in the first row.

          For a Hermitian matrix the imaginary parts of the diagonal
          elements are of course zero and thus the imaginary parts of the
          corresponding Fortran array elements need not be set, but are
          assumed to be zero.

          For packed triangular matrices the same storage layout is used
          whether or not DIAG = 'U', i.e., space is left for the diagonal
          elements even if those array elements are not referenced.

                                             H
          Throughout the following sections A  denotes the complex
                        T
          conjugate of A .


          SUBROUTINE F06PAF( TRANS,M,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          ENTRY DGEMV      ( TRANS,M,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          CHARACTER*1        TRANS
          INTEGER            M,N,LDA,INCX,INCY
          DOUBLE PRECISION   ALPHA,A(LDA,*),X(*),BETA,Y(*)

          SUBROUTINE F06SAF( TRANS,M,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          ENTRY ZGEMV      ( TRANS,M,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          CHARACTER*1          TRANS
          INTEGER              M,N,LDA,INCX,INCY
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),X(*),BETA,Y(*)

          SUBROUTINE F06PBF( TRANS,M,N,KL,KU,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          ENTRY DGBMV      ( TRANS,M,N,KL,KU,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          CHARACTER*1        TRANS
          INTEGER            M,N,KL,KU,LDA,INCX,INCY
          DOUBLE PRECISION   ALPHA,A(LDA,*),X(*),BETA,Y(*)

          SUBROUTINE F06SBF( TRANS,M,N,KL,KU,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          ENTRY ZGBMV      ( TRANS,M,N,KL,KU,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          CHARACTER*1          TRANS
          INTEGER              M,N,KL,KU,LDA,INCX,INCY
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),X(*),BETA,Y(*)

          SUBROUTINE F06PCF( UPLO,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          ENTRY DSYMV      ( UPLO,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          CHARACTER*1        UPLO
          INTEGER            N,LDA,INCX,INCY
          DOUBLE PRECISION   ALPHA,A(LDA,*),X(*),BETA,Y(*)

          SUBROUTINE F06SCF( UPLO,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          ENTRY ZHEMV      ( UPLO,N,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          CHARACTER*1          UPLO
          INTEGER              N,LDA,INCX,INCY
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),X(*),BETA,Y(*)

          SUBROUTINE F06PDF( UPLO,N,K,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          ENTRY DSBMV      ( UPLO,N,K,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          CHARACTER*1        UPLO
          INTEGER            N,K,LDA,INCX,INCY
          DOUBLE PRECISION   ALPHA,A(LDA,*),X(*),BETA,Y(*)

          SUBROUTINE F06SDF( UPLO,N,K,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          ENTRY ZHBMV      ( UPLO,N,K,ALPHA,A,LDA,X,INCX,BETA,Y,INCY )
          CHARACTER*1          UPLO
          INTEGER              N,K,LDA,INCX,INCY
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),X(*),BETA,Y(*)

          SUBROUTINE F06PEF( UPLO,N,ALPHA,AP,X,INCX,BETA,Y,INCY )
          ENTRY DSPMV      ( UPLO,N,ALPHA,AP,X,INCX,BETA,Y,INCY )
          CHARACTER*1        UPLO
          INTEGER            N,INCX,INCY
          DOUBLE PRECISION   ALPHA,AP(*),X(*),BETA,Y(*)

          SUBROUTINE F06SEF( UPLO,N,ALPHA,AP,X,INCX,BETA,Y,INCY )
          ENTRY ZHPMV      ( UPLO,N,ALPHA,AP,X,INCX,BETA,Y,INCY )
          CHARACTER*1          UPLO
          INTEGER              N,INCX,INCY
          COMPLEX(KIND(1.0D0)) ALPHA,AP(*),X(*),BETA,Y(*)

          SUBROUTINE F06PFF( UPLO,TRANS,DIAG,N,A,LDA,X,INCX )
          ENTRY DTRMV      ( UPLO,TRANS,DIAG,N,A,LDA,X,INCX )
          CHARACTER*1        UPLO,TRANS,DIAG
          INTEGER            N,LDA,INCX
          DOUBLE PRECISION   A(LDA,*),X(*)

          SUBROUTINE F06SFF( UPLO,TRANS,DIAG,N,A,LDA,X,INCX )
          ENTRY ZTRMV      ( UPLO,TRANS,DIAG,N,A,LDA,X,INCX )
          CHARACTER*1          UPLO,TRANS,DIAG
          INTEGER              N,LDA,INCX
          COMPLEX(KIND(1.0D0)) A(LDA,*),X(*)

          SUBROUTINE F06PGF( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX )
          ENTRY DTBMV      ( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX )
          CHARACTER*1        UPLO,TRANS,DIAG
          INTEGER            N,K,LDA,INCX
          DOUBLE PRECISION   A(LDA,*),X(*)

          SUBROUTINE F06SGF( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX )
          ENTRY ZTBMV      ( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX )
          CHARACTER*1          UPLO,TRANS,DIAG
          INTEGER              N,K,LDA,INCX
          COMPLEX(KIND(1.0D0)) A(LDA,*),X(*)

          SUBROUTINE F06PHF( UPLO,TRANS,DIAG,N,AP,X,INCX )
          ENTRY DTPMV      ( UPLO,TRANS,DIAG,N,AP,X,INCX )
          CHARACTER*1        UPLO,TRANS,DIAG
          INTEGER            N,INCX
          DOUBLE PRECISION   AP(*),X(*)

          SUBROUTINE F06SHF( UPLO,TRANS,DIAG,N,AP,X,INCX )
          ENTRY ZTPMV      ( UPLO,TRANS,DIAG,N,AP,X,INCX )
          CHARACTER*1          UPLO,TRANS,DIAG
          INTEGER              N,INCX
          COMPLEX(KIND(1.0D0)) AP(*),X(*)

          SUBROUTINE F06PJF( UPLO,TRANS,DIAG,N,A,LDA,X,INCX )
          ENTRY DTRSV      ( UPLO,TRANS,DIAG,N,A,LDA,X,INCX )
          CHARACTER*1        UPLO,TRANS,DIAG
          INTEGER            N,LDA,INCX
          DOUBLE PRECISION   A(LDA,*),X(*)

          SUBROUTINE F06SJF( UPLO,TRANS,DIAG,N,A,LDA,X,INCX )
          ENTRY ZTRSV      ( UPLO,TRANS,DIAG,N,A,LDA,X,INCX )
          CHARACTER*1          UPLO,TRANS,DIAG
          INTEGER              N,LDA,INCX
          COMPLEX(KIND(1.0D0)) A(LDA,*),X(*)

          SUBROUTINE F06PKF( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX )
          ENTRY DTBSV      ( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX )
          CHARACTER*1        UPLO,TRANS,DIAG
          INTEGER            N,K,LDA,INCX
          DOUBLE PRECISION   A(LDA,*),X(*)

          SUBROUTINE F06SKF( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX )
          ENTRY ZTBSV      ( UPLO,TRANS,DIAG,N,K,A,LDA,X,INCX )
          CHARACTER*1          UPLO,TRANS,DIAG
          INTEGER              N,K,LDA,INCX
          COMPLEX(KIND(1.0D0)) A(LDA,*),X(*)

          SUBROUTINE F06PLF( UPLO,TRANS,DIAG,N,AP,X,INCX )
          ENTRY DTPSV      ( UPLO,TRANS,DIAG,N,AP,X,INCX )
          CHARACTER*1        UPLO,TRANS,DIAG
          INTEGER            N,INCX
          DOUBLE PRECISION   AP(*),X(*)

          SUBROUTINE F06SLF( UPLO,TRANS,DIAG,N,AP,X,INCX )
          ENTRY ZTPSV      ( UPLO,TRANS,DIAG,N,AP,X,INCX )
          CHARACTER*1          UPLO,TRANS,DIAG
          INTEGER              N,INCX
          COMPLEX(KIND(1.0D0)) AP(*),X(*)

          SUBROUTINE F06PMF( M,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          ENTRY DGER       ( M,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          INTEGER            M,N,INCX,INCY,LDA
          DOUBLE PRECISION   ALPHA,X(*),Y(*),A(LDA,*)

          SUBROUTINE F06SMF( M,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          ENTRY ZGERU      ( M,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          INTEGER              M,N,INCX,INCY,LDA
          COMPLEX(KIND(1.0D0)) ALPHA,X(*),Y(*),A(LDA,*)

          SUBROUTINE F06SNF( M,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          ENTRY ZGERC      ( M,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          INTEGER              M,N,INCX,INCY,LDA
          COMPLEX(KIND(1.0D0)) ALPHA,X(*),Y(*),A(LDA,*)

          SUBROUTINE F06PPF( UPLO,N,ALPHA,X,INCX,A,LDA )
          ENTRY DSYR       ( UPLO,N,ALPHA,X,INCX,A,LDA )
          CHARACTER*1        UPLO
          INTEGER            N,INCX,LDA
          DOUBLE PRECISION   ALPHA,X(*),A(LDA,*)

          SUBROUTINE F06SPF( UPLO,N,ALPHA,X,INCX,A,LDA )
          ENTRY ZHER       ( UPLO,N,ALPHA,X,INCX,A,LDA )
          CHARACTER*1          UPLO
          INTEGER              N,INCX,LDA
          DOUBLE PRECISION     ALPHA
          COMPLEX(KIND(1.0D0)) X(*),A(LDA,*)

          SUBROUTINE F06PQF( UPLO,N,ALPHA,X,INCX,AP )
          ENTRY DSPR       ( UPLO,N,ALPHA,X,INCX,AP )
          CHARACTER*1        UPLO
          INTEGER                   N,INCX
          DOUBLE PRECISION            ALPHA,X(*),AP(*)

          SUBROUTINE F06SQF( UPLO,N,ALPHA,X,INCX,AP )
          ENTRY ZHPR       ( UPLO,N,ALPHA,X,INCX,AP )
          CHARACTER*1          UPLO
          INTEGER              N,INCX
          DOUBLE PRECISION     ALPHA
          COMPLEX(KIND(1.0D0)) X(*),AP(*)

          SUBROUTINE F06PRF( UPLO,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          ENTRY DSYR2      ( UPLO,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          CHARACTER*1        UPLO
          INTEGER            N,INCX,INCY,LDA
          DOUBLE PRECISION   ALPHA,X(*),Y(*),A(LDA,*)

          SUBROUTINE F06SRF( UPLO,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          ENTRY ZHER2      ( UPLO,N,ALPHA,X,INCX,Y,INCY,A,LDA )
          CHARACTER*1          UPLO
          INTEGER              N,INCX,INCY,LDA
          COMPLEX(KIND(1.0D0)) ALPHA,X(*),Y(*),A(LDA,*)

          SUBROUTINE F06PSF( UPLO,N,ALPHA,X,INCX,Y,INCY,AP )
          ENTRY DSPR2      ( UPLO,N,ALPHA,X,INCX,Y,INCY,AP )
          CHARACTER*1        UPLO
          INTEGER            N,INCX,INCY
          DOUBLE PRECISION  ALPHA,X(*),Y(*),AP(*)

          SUBROUTINE F06SSF( UPLO,N,ALPHA,X,INCX,Y,INCY,AP )
          ENTRY ZHPR2      ( UPLO,N,ALPHA,X,INCX,Y,INCY,AP )
          CHARACTER*1          UPLO
          INTEGER              N,INCX,INCY
          COMPLEX(KIND(1.0D0)) ALPHA,X(*),Y(*),AP(*)

          F06PAF(*), F06SAF(*), F06PBF(*) and F06SBF(*)

          perform the operation

              y<-(alpha)Ax+(beta)y, when TRANS = 'N',

                         T
              y<-(alpha)A x+(beta)y, when TRANS = 'T',

                         H
              y<-(alpha)A x+(beta)y, when TRANS = 'C',

          where A is a general matrix for F06PAF(*) and F06SAF(*), and is a
          general band matrix for F06PBF(*) and F06SBF(*).

          F06PCF(*), F06SCF(*), F06PEF(*), F06SEF(*), F06PDF(*) and
          F06SDF(*)

          perform the operation

          y<-(alpha)Ax+(beta)y

          where A is symmetric and Hermitian for F06PCF(*) and F06SCF(*)
          respectively, is symmetric and Hermitian stored in packed form
          for F06PEF(*) and F06SEF(*) respectively, and is symmetric and
          Hermitian band for F06PDF(*) and F06SDF(*).

          F06PFF(*), F06SFF(*), F06PHF(*), F06SHF(*), F06PGF(*) and
          F06SGF(*)

          perform the operation

              x<-Ax,       when TRANS = 'N',

                  T
              x<-A x,      when TRANS = 'T',

                  H
              x<-A x,      when TRANS = 'C',

          where A is a triangular matrix for F06PFF(*) and F06SFF(*), is a
          triangular matrix stored in packed form for F06PHF(*) and
          F06SHF(*), and is a triangular band matrix for F06PGF(*) and
          F06SGF(*).

          F06PJF(*), F06SJF(*), F06PLF(*), F06SLF(*), F06PKF(*) and
          F06SKF(*)

          solve the equations

              Ax=b,        when TRANS = 'N',

               T
              A x=b,       when TRANS = 'T',

               H
              A x=b,       when TRANS = 'C',

          where A is a triangular matrix for F06PJF(*) and F06SJF(*), is a
          triangular matrix stored in packed form for F06PLF(*) and
          F06SLF(*), and is a triangular band matrix for F06PKF(*) and
          F06SKF(*). The vector b must be supplied in the array X and is
          overwritten by the solution. It is important to note that no test
          for singularity is included in these routines.

          F06PMF(*) and F06SMF(*)

                                            T
          perform the operation A<-(alpha)xy +A, where A is a general
          matrix.

          F06SNF(*)

                                             H
          performs the operation A<-(alpha)xy +A, where A is a general
          complex matrix.

          F06PPF(*) and F06PQF(*)

                                            T
          perform the operation A<-(alpha)xx +A, where A is a symmetric
          matrix for F06PPF(*) and is a symmetric matrix stored in packed
          form for F06PQF(*).

          F06SPF(*) and F06SQF(*)

                                            H
          perform the operation A<-(alpha)xx +A, where A is an Hermitian
          matrix for F06SPF(*) and is an Hermitian matrix stored in packed
          form for F06SQF(*).

          F06PRF(*) and F06PSF(*)

                                            T          T
          perform the operation A<-(alpha)xy +(alpha)yx +A, where A is a
          symmetric matrix for F06PRF(*) and is a symmetric matrix stored
          in packed form for F06PSF(*).

          F06SRF(*) and F06SSF(*)

                                            H          H
          perform the operation A<-(alpha)xy +(alpha)yx +A, where A is an
          Hermitian matrix for F06SRF(*) and is an Hermitian matrix stored
          in packed form for F06SSF(*).

          The following argument values are invalid:

               Any value of the character arguments DIAG, TRANS, or UPLO
               whose meaning is not specified.

               M < 0

               N < 0

               KL < 0

               KU < 0

               K < 0

               LDA < M

               LDA < KL + KU + 1

               LDA < N for the routines involving full Hermitian,
               symmetric or triangular matrices

               LDA < K + 1 for the routines involving band Hermitian,
               symmetric or triangular matrices

               INCX = 0

               INCY = 0

          If a routine is called with an invalid value then an error
          message is output, on the error message unit (see X04AAF), giving
          the name of the routine and the number of the first invalid
          argument, and execution is terminated.

          4.4. The Level-3 Matrix-matrix Routines

          The matrix-matrix routines all have either two or three arguments
          representing a matrix, one of which is an input-output argument,
          and in each case the arguments are two-dimensional arrays.

          The sizes of the matrices are determined by one or more of the
          arguments M, N and K. The size of the input-output array is
          always determined by the arguments M and N for a rectangular m by
          n matrix, and by the argument N for a square n by n matrix. It is
          permissible to call the routines with M or N = 0, in which case
          the routines exit immediately without referencing their array
          arguments.

          Many of the routines perform an operation of the form

                                    C<-P+(beta)C,

          where P is the product of two matrices, or the sum of two such
          products. When the inner dimension of the matrix product is
          different from m or n it is denoted by K. Again it is permissible
          to call the routines with K = 0 and if M > 0, but K = 0, then the
          routines perform the operation


                                     C<-(beta)C.

          As with the Level-2 routines (see Section 4.3) the description of
          the matrix consists of the array name (A or B or C) followed by
          the first dimension (LDA or LDB or LDC).

          The arguments that specify options are character arguments with
          the names SIDE, TRANSA, TRANSB, TRANS, UPLO and DIAG. UPLO and
          DIAG have the same values and meanings as for the Level-2
          routines (see Section 4.3); TRANSA, TRANSB and TRANS have the
          same values and meanings as TRANS in the Level-2 routines, where
          TRANSA and TRANSB apply to the matrices A and B respectively.
          SIDE is used by the routines as follows:

              Value   Meaning

              'L'     Multiply general matrix by symmetric, Hermitian or
                      triangular matrix on the left

              'R'     Multiply general matrix by symmetric, Hermitian or
                      triangular matrix on the right

          The storage conventions for matrices are as for the Level-2
          routines (see Section 4.3).

          SUBROUTINE F06YAF( TRANSA,TRANSB,M,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          ENTRY      DGEMM ( TRANSA,TRANSB,M,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          CHARACTER          TRANSA,TRANSB
          INTEGER            M,N,K,LDA,LDB,LDC
          DOUBLE PRECISION   ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*)

          SUBROUTINE F06ZAF( TRANSA,TRANSB,M,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          ENTRY      ZGEMM ( TRANSA,TRANSB,M,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          CHARACTER            TRANSA,TRANSB
          INTEGER              M,N,K,LDA,LDB,LDC
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*)

          SUBROUTINE F06YCF( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          ENTRY      DSYMM ( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          CHARACTER          SIDE,UPLO
          INTEGER            M,N,LDA,LDB,LDC
          DOUBLE PRECISION   ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*)

          SUBROUTINE F06ZCF( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          ENTRY      ZHEMM ( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          CHARACTER            SIDE,UPLO
          INTEGER              M,N,LDA,LDB,LDC
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*)

          SUBROUTINE F06ZTF( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          ENTRY      ZSYMM ( SIDE,UPLO,M,N,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          CHARACTER            SIDE,UPLO
          INTEGER              M,N,LDA,LDB,LDC
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*)

          SUBROUTINE F06YFF( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB )
          ENTRY      DTRMM ( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB )
          CHARACTER          SIDE,UPLO,TRANSA,DIAG
          INTEGER            M,N,LDA,LDB
          DOUBLE PRECISION   ALPHA,A(LDA,*),B(LDB,*)

          SUBROUTINE F06ZFF( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB )
          ENTRY      ZTRMM ( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB )
          CHARACTER            SIDE,UPLO,TRANSA,DIAG
          INTEGER              M,N,LDA,LDB
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*)

          SUBROUTINE F06YJF( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB )
          ENTRY      DTRSM ( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB )
          CHARACTER          SIDE,UPLO,TRANSA,DIAG
          INTEGER            M,N,LDA,LDB
          DOUBLE PRECISION   ALPHA,A(LDA,*),B(LDB,*)

          SUBROUTINE F06ZJF( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB )
          ENTRY      ZTRSM ( SIDE,UPLO,TRANSA,DIAG,M,N,ALPHA,A,LDA,B,LDB )
          CHARACTER            SIDE,UPLO,TRANSA,DIAG
          INTEGER              M,N,LDA,LDB
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*)

          SUBROUTINE F06YPF( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC )
          ENTRY      DSYRK ( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC )
          CHARACTER          UPLO,TRANS
          INTEGER            N,K,LDA,LDC
          DOUBLE PRECISION   ALPHA,A(LDA,*),BETA,C(LDC,*)

          SUBROUTINE F06ZPF( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC )
          ENTRY      ZHERK ( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC )
          CHARACTER            UPLO,TRANS
          INTEGER              N,K,LDA,LDC
          DOUBLE PRECISION     ALPHA,BETA
          COMPLEX(KIND(1.0D0)) A(LDA,*),C(LDC,*)

          SUBROUTINE F06ZUF( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC )
          ENTRY      ZSYRK ( UPLO,TRANS,N,K,ALPHA,A,LDA,BETA,C,LDC )
          CHARACTER            UPLO,TRANS
          INTEGER              N,K,LDA,LDC
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),BETA,C(LDC,*)

          SUBROUTINE F06YRF( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          ENTRY      DSYR2K( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          CHARACTER          UPLO,TRANS
          INTEGER            N,K,LDA,LDB,LDC
          DOUBLE PRECISION   ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*)

          SUBROUTINE F06ZRF( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          ENTRY      ZHER2K( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          CHARACTER            UPLO,TRANS
          INTEGER              N,K,LDA,LDB,LDC
          DOUBLE PRECISION     BETA
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),C(LDC,*)

          SUBROUTINE F06ZWF( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          ENTRY      ZSYR2K( UPLO,TRANS,N,K,ALPHA,A,LDA,B,LDB,BETA,C,LDC )
          CHARACTER            UPLO,TRANS
          INTEGER              N,K,LDA,LDB,LDC
          COMPLEX(KIND(1.0D0)) ALPHA,A(LDA,*),B(LDB,*),BETA,C(LDC,*)


          F06YAF(*) and F06ZAF(*)

          perform the operation indicated in the following table:

                        TRANSA = 'N'    TRANSA = 'T'      TRANSA = 'C'

                                                     T               H
          TRANSB='N'   C <- (alpha)AB   C <- (alpha)A B   C <- (alpha)A B
                            +(beta)C        +(beta)C          +(beta)C
                       A is m*k,        A is k*m,         A is k*m,
                       B is k*n         B is k*n          B is k*n

                                     T               T T               H T
          TRANSB='T'   C <- (alpha)AB   C <- (alpha)A B   C <- (alpha)A B
                           +(beta)C         +(beta)C          +(beta)C
                       A is m*k,        A is k*m,         A is k*m,
                       B is n*k         B is n*k          B is n*k

                                     H               T H               H H
          TRANSB='C'   C <- (alpha)AB   C <- (alpha)A B   C <- (alpha)A B
                           +(beta)C         +(beta)C          +(beta)C
                       A is m*k,        A is k*m,         A is k*m,
                       B is n*k         B is n*k          B is n*k


          where A and B are general matrices and C is a general m by n
          matrix.

          F06YCF(*), F06ZCF(*) and F06ZTF(*) perform the operation

          indicated in the following table:

              SIDE = 'L'               SIDE = 'R'

              C<-(alpha)AB+(beta)C     C<-(alpha)BA+(beta)C

              A is m*m                 B is m*n

              B is m*n                 A is n*n

          where A is symmetric for F06YCF(*) and F06ZTF(*) and is Hermitian
          for F06ZCF(*), B is a general matrix and C is a general m by n
          matrix.

          F06YFF(*) and F06ZFF(*) perform the operation indicated in the
          following table:

                    TRANSA = 'N'       TRANSA = 'T'        TRANSA = 'C'

                                                    T                   H
          SIDE='L'  B <- (alpha)AB     B <- (alpha)A B     B <- (alpha)A B

                    A is               A is                A is
                    triangular         triangular          triangular
                    m*m                m*m                 m*m

                                                     T                   H
          SIDE='R'  B <- (alpha)BA     B <- (alpha)BA      B <- (alpha)BA

                    A is               A is                A is
                    triangular         triangular          triangular
                    n*n                n*n                 n*n

          where B is a general m by n matrix.

          F06YJF(*) and F06ZJF(*) solve the equations, indicated in the
          following table, for X:

                    TRANSA = 'N'       TRANSA = 'T'       TRANSA = 'C'

                                        T                  H
          SIDE='L'  AX=(alpha)B        A X=(alpha)B       A X=(alpha)B

                    A is               A is               A is
                    triangular         triangular         triangular
                    m*m                m*m                m*m

                                         T                  H
          SIDE='R'  XA=(alpha)B        XA =(alpha)B       XA =(alpha)B

                    A is               A is               A is
                    triangular         triangular         triangular
                    n*n                n*n                n*n

          where B is a general m by n matrix. The m by n solution matrix X
          is overwritten on the array B. It is important to note that no
          test for singularity is included in these routines.

          F06YPF(*), F06ZPF(*) and F06ZUF(*) perform the operation
          indicated in the following table:

                    TRANS = 'N'        TRANS = 'T'        TRANS = 'C'

                                  T                 T                  T
          F06YPF    C <- (alpha)AA     C <- (alpha)A A    C <- (alpha)A A
                        +(beta)C           +(beta)C           +(beta)C
                                  T                 T
          F06ZUF    C <- (alpha)AA     C <- (alpha)A A         --
                        +(beta)C           +(beta)C
                                  H                                    H
          F06ZPF    C <- (alpha)AA          --            C <- (alpha)A A
                        +(beta)C                              +(beta)C

                    A is n*k           A is k*n           A is k*n

          where A is a general matrix and C is an n by n symmetric matrix
          for F06YPF(*) and F06ZUF(*), and is an n by n Hermitian matrix
          for F06ZPF(*).

          F06YRF(*), F06ZRF(*) and F06ZWF(*) perform the operation
          indicated in the following table:


                    TRANS = 'N'        TRANS = 'T'        TRANS = 'C'

                                  T                 T                  T
          F06YRF    C <- (alpha)AB     C <- (alpha)A B    C <- (alpha)A B
                                  T                 T                  T
                        +(alpha)BA         +(alpha)B A        +(alpha)B A
                        +(beta)C           +(beta)C           +(beta)C
                                  T                 T
          F06ZWF    C <- (alpha)AB     C <- (alpha)A B           --
                                  T                 T
                        +(alpha)BA         +(alpha)B A
                        +(beta)C           +(beta)C
                                  H                                    H
          F06ZRF    C <- (alpha)AB           --           C <- (alpha)A B
                                  H                                    H
                        +(alpha)BA                            +(alpha)B A
                        +(beta)C                              +(beta)C

                    A and B are n*k    A and B are k*n    A and B are k*n

          where A and B are general matrices and C is an n by n symmetric
          matrix for F06YRF(*) and F06ZWF(*), and is an n by n Hermitian
          matrix for F06ZPF(*).

          The following values of arguments are invalid:

               Any value of the character arguments SIDE, TRANSA, TRANSB,
               TRANS, UPLO or DIAG, whose meaning is not specified.

               M < 0

               N < 0

               K < 0

               LDA < the number of rows in the matrix A.

               LDB < the number of rows in the matrix B.

               LDC < the number of rows in the matrix C.

          If a routine is called with an invalid value then an error
          message is output, on the error message unit (see X04AAF), giving
          the name of the routine and the number of the first invalid
          argument, and execution is terminated.


          F06 -- Linear Algebra Support Routines            Contents -- F06
          Chapter F06

          Linear Algebra Support Routines

          F06AAF  (DROTG) Generate real plane rotation

          F06EAF  (DDOT) Dot product of two real vectors

          F06ECF  (DAXPY) Add scalar times real vector to real vector

          F06EDF  (DSCAL) Multiply real vector by scalar

          F06EFF  (DCOPY) Copy real vector

          F06EGF  (DSWAP) Swap two real vectors

          F06EJF  (DNRM2) Compute Euclidean norm of real vector

          F06EKF  (DASUM) Sum the absolute values of real vector elements

          F06EPF  (DROT) Apply real plane rotation

          F06GAF  (ZDOTU) Dot product of two complex vectors, unconjugated

          F06GBF  (ZDOTC) Dot product of two complex vectors, conjugated

          F06GCF  (ZAXPY) Add scalar times complex vector to complex vector

          F06GDF  (ZSCAL) Multiply complex vector by complex scalar

          F06GFF  (ZCOPY) Copy complex vector

          F06GGF  (ZSWAP) Swap two complex vectors

          F06JDF  (ZDSCAL) Multiply complex vector by real scalar

          F06JJF  (DZNRM2) Compute Euclidean norm of complex vector

          F06JKF  (DZASUM) Sum the absolute values of complex vector
                  elements

          F06JLF  (IDAMAX) Index, real vector element with largest absolute
                  value

          F06JMF  (IZAMAX) Index, complex vector element with largest
                  absolute value

          F06PAF  (DGEMV) Matrix-vector product, real rectangular matrix

          F06PBF  (DGBMV) Matrix-vector product, real rectangular band
                  matrix

          F06PCF  (DSYMV) Matrix-vector product, real symmetric matrix

          F06PDF  (DSBMV) Matrix-vector product, real symmetric band matrix

          F06PEF  (DSPMV) Matrix-vector product, real symmetric packed
                  matrix

          F06PFF  (DTRMV) Matrix-vector product, real triangular matrix

          F06PGF  (DTBMV) Matrix-vector product, real triangular band
                  matrix

          F06PHF  (DTPMV) Matrix-vector product, real triangular packed
                  matrix

          F06PJF  (DTRSV) System of equations, real triangular matrix

          F06PKF  (DTBSV) System of equations, real triangular band matrix

          F06PLF  (DTPSV) System of equations, real triangular packed
                  matrix

          F06PMF  (DGER) Rank-1 update, real rectangular matrix

          F06PPF  (DSYR) Rank-1 update, real symmetric matrix

          F06PQF  (DSPR) Rank-1 update, real symmetric packed matrix

          F06PRF  (DSYR2) Rank-2 update, real symmetric matrix

          F06PSF  (DSPR2) Rank-2 update, real symmetric packed matrix

          F06SAF  (ZGEMV) Matrix-vector product, complex rectangular matrix

          F06SBF  (ZGBMV) Matrix-vector product, complex rectangular band
                  matrix

          F06SCF  (ZHEMV) Matrix-vector product, complex Hermitian matrix

          F06SDF  (ZHBMV) Matrix-vector product, complex Hermitian band
                  matrix

          F06SEF  (ZHPMV) Matrix-vector product, complex Hermitian packed
                  matrix

          F06SFF  (ZTRMV) Matrix-vector product, complex triangular matrix

          F06SGF  (ZTBMV) Matrix-vector product, complex triangular band
                  matrix

          F06SHF  (ZTPMV) Matrix-vector product, complex triangular packed
                  matrix

          F06SJF  (ZTRSV) System of equations, complex triangular matrix

          F06SKF  (ZTBSV) System of equations, complex triangular band
                  matrix

          F06SLF  (ZTPSV) System of equations, complex triangular packed
                  matrix

          F06SMF  (ZGERU) Rank-1 update, complex rectangular matrix,
                  unconjugated vector

          F06SNF  (ZGERC) Rank-1 update, complex rectangular matrix,
                  conjugated vector

          F06SPF  (ZHER) Rank-1 update, complex Hermitian matrix

          F06SQF  (ZHPR) Rank-1 update, complex Hermitian packed matrix

          F06SRF  (ZHER2) Rank-2 update, complex Hermitian matrix

          F06SSF  (ZHPR2) Rank-2 update, complex Hermitian packed matrix

          F06YAF  (DGEMM) Matrix-matrix product, two real rectangular
                  matrices

          F06YCF  (DSYMM) Matrix-matrix product, one real symmetric matrix,
                  one real rectangular matrix

          F06YFF  (DTRMM) Matrix-matrix product, one real triangular
                  matrix, one real rectangular matrix

          F06YJF  (DTRSM) Solves a system of equations with multiple right-
                  hand sides, real triangular coefficient matrix

          F06YPF  (DSYRK) Rank-k update of a real symmetric matrix

          F06YRF  (DSYR2K) Rank-2k update of a real symmetric matrix

          F06ZAF  (ZGEMM) Matrix-matrix product, two complex rectangular
                  matrices

          F06ZCF  (ZHEMM) Matrix-matrix product, one complex Hermitian
                  matrix, one complex rectangular matrix

          F06ZFF  (ZTRMM) Matrix-matrix product, one complex triangular
                  matrix, one complex rectangular matrix

          F06ZJF  (ZTRSM) Solves system of equations with multiple right-
                  hand sides, complex triangular coefficient matrix

          F06ZPF  (ZHERK) Rank-k update of a complex Hermitian matrix

          F06ZRF  (ZHER2K) Rank-2k update of a complex Hermitian matrix

          F06ZTF  (ZSYMM) Matrix-matrix product, one complex symmetric
                  matrix, one complex rectangular matrix

          F06ZUF  (ZSYRK) Rank-k update of a complex symmetric matrix

          F06ZWF  (ZSYR2K) Rank-2k update of a complex symmetric matrix

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf07}{NAG On-line Documentation: f07}
\beginscroll
\begin{verbatim}



     F07(3NAG)         Foundation Library (12/10/92)         F07(3NAG)



          F07 -- Linear Equations (LAPACK)              Introduction -- F07
                                    Chapter F07
                             Linear Equations (LAPACK)

          1. Scope of the Chapter

          This chapter provides four routines concerned with matrix
          factorization, and the solution of systems of linear equations
          following the matrix factorizations.

          2. Background to the Problems

          Background material, together with pointers to the routines in
          this chapter, are to be found in the F01 and F04 Chapter
          Introductions.

          3. Recommendations on Choice and Use of Routines

          The routines in this chapter are derived from the LAPACK project
          and may also be called using the LAPACK name, which is given in
          brackets following the F07 name in the following descriptions.

          Routine F07ADF (DGETRF) performs an LU factorization of a real m
          by n matrix A. Following the use of this routine, F07AEF (DGETRS)
          may be used to solve a system of n non-singular linear equations,
          with one or more right-hand sides.

          Routine F07FDF (DPOTRF) performs the Cholesky factorization of a
          real symmetric positive-definite matrix A. Following the use of
          this routine, F07FEF (DPOTRS) may be used to solve a system of
          symmetric positive-definite linear equations, with one or more
          right-hand sides.


          F07 -- Linear Equations (LAPACK)                  Contents -- F07
          Chapter F07

          Linear Equations (LAPACK)

          F07ADF  (DGETRF) LU factorization of real m by n matrix

          F07AEF  (DGETRS) Solution of real system of linear equations,
                  multiple right-hand sides, matrix already factorized by
                  F07ADF

          F07FDF  (DPOTRF) Cholesky factorization of real symmetric
                  positive-definite matrix

          F07FEF  (DPOTRS) Solution of real symmetric positive-definite
                  system of linear equations, multiple right-hand sides,
                  matrix already factorized by F07FDF

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf07adf}{NAG On-line Documentation: f07adf}
\beginscroll
\begin{verbatim}



     F07ADF(3NAG)      Foundation Library (12/10/92)      F07ADF(3NAG)



          F07 -- Linear Equations (LAPACK)                           F07ADF
                  F07ADF -- 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

          F07ADF (DGETRF) computes the LU factorization of a real m by n
          matrix.

          2. Specification

                 SUBROUTINE F07ADF (M, N, A, LDA, IPIV, INFO)
                 ENTRY            M, N, A, LDA, IPIV, INFO
                 INTEGER          M, N, LDA, IPIV(*), INFO
                 DOUBLE PRECISION A(LDA,*)

          The ENTRY statement enables the routine to be called by its
          LAPACK name.

          3. Description

          This routine forms the LU factorization of a real m by n matrix A
          as A=PLU, where P is a permutation matrix, L is lower triangular
          with unit diagonal elements (lower trapezoidal if m>n) and U is
          upper triangular (upper trapezoidal if m<n). Usually A is square
          (m=n), and both L and U are triangular. The routine uses partial
          pivoting, with row interchanges.

          4. References

          [1]   Golub G H and Van Loan C F (1989) Matrix Computations (2nd
                Edition). Johns Hopkins University Press, Baltimore,
                Maryland.

          5. Parameters

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

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

           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 m by n matrix A. On exit: A is overwritten by
               the factors L and U; the unit diagonal elements of L are not
               stored.

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

           5:  IPIV(*) -- INTEGER array                              Output
               Note: the dimension of the array IPIV must be at least
               max(1,min(M,N)).
               On exit: the pivot indices. Row i of the matrix A was
               interchanged with row IPIV(i) for i=1,2,...,min(m,n).

           6:  INFO -- INTEGER                                       Output
               On exit: INFO = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          INFO < 0
               If INFO = -i, the ith parameter has an illegal value. An
               explanatory message is output, and execution of the program
               is terminated.

          INFO > 0
               If INFO = i, u   is exactly zero. The factorization has been
                             ii
               completed but the factor U is exactly singular, and division
               by zero will occur if it is subsequently used to solve a
                                                         -1
               system of linear equations or to compute A  .

          7. Accuracy

          The computed factors L and U are the exact factors of a perturbed
          matrix A+E, where

                          |E|<=c(min(m,n))(epsilon)P|L||U|,

          c(n) is a modest linear function of n, and (epsilon) is the
          machine precision.

          8. Further Comments

          The total number of floating-point operations is approximately
           2 3                           1 2                   1 2
           -n  if m=n (the usual case),  -n (3m-n) if m>n and  -m (3n-m) if
           3                             3                     3
          m<n.

          A call to this routine with m=n may be followed by calls to the
          routines:

                                                 T
               F07AEF (DGETRS) to solve AX=B or A X=B;

               F07AGF (DGECON)(*) to estimate the condition number of A;

               F07AJF (DGETRI)(*) to compute the inverse of A.

          The complex analogue of this routine is F07ARF (ZGETRF)(*).

          9. Example

          To compute the LU factorization of the matrix A, where

                              ( 1.80  2.88  2.05 -0.89)
                              ( 5.25 -2.95 -0.95 -3.80)
                            A=( 1.58 -2.69 -2.90 -1.04).
                              (-1.11 -0.66 -0.59  0.80)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf07aef}{NAG On-line Documentation: f07aef}
\beginscroll
\begin{verbatim}



     F07AEF(3NAG)      Foundation Library (12/10/92)      F07AEF(3NAG)



          F07 -- Linear Equations (LAPACK)                           F07AEF
                  F07AEF -- 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

          F07AEF (DGETRS) solves a real system of linear equations with
                                              T
          multiple right-hand sides, AX=B or A X=B, where A has been
          factorized by F07ADF (DGETRF).

          2. Specification

                 SUBROUTINE F07AEF (TRANS, N, NRHS, A, LDA, IPIV, B, LDB,
                1                   INFO)
                 ENTRY            TRANS, N, NRHS, A, LDA, IPIV, B, LDB, INFO
                 INTEGER          N, NRHS, LDA, IPIV(*), LDB, INFO
                 DOUBLE PRECISION A(LDA,*), B(LDB,*)
                 CHARACTER*1      TRANS

          The ENTRY statement enables the routine to be called by its
          LAPACK name.

          3. Description

                                                              T
          To solve a real system of linear equations AX=B or A X=B, this
          routine must be preceded by a call to F07ADF (DGETRF)which
          computes the LU factorization of A as A=PLU. The solution is
          computed by forward and backward substitution.

          If TRANS = 'N', the solution is computed by solving PLY=B and
          then UX=Y.

                                                                      T
          If TRANS = 'T' or 'C', the solution is computed by solving U Y=B
                    T T
          and then L P X=Y.

          4. References

          [1]   Golub G H and Van Loan C F (1989) Matrix Computations (2nd
                Edition). Johns Hopkins University Press, Baltimore,
                Maryland.

          5. Parameters

           1:  TRANS -- CHARACTER*1                                   Input
               On entry: indicates the form of the equations as follows:
                    if TRANS = 'N', then AX=B is solved for X;

                                                 T
                    if TRANS = 'T' or 'C', then A X=B is solved for X.
                Constraint: TRANS = 'N', 'T' or 'C'.

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

           3:  NRHS -- INTEGER                                        Input
               On entry: r, the number of right-hand sides. Constraint:
               NRHS >= 0.

           4:  A(LDA,*) -- DOUBLE PRECISION array                     Input
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the LU factorization of A, as returned by F07ADF
               (DGETRF).

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

           6:  IPIV(*) -- INTEGER array                               Input
               Note: the dimension of the array IPIV must be at least
               max(1,N).
               On entry: the pivot indices, as returned by F07ADF (DGETRF).

           7:  B(LDB,*) -- DOUBLE PRECISION array              Input/Output
               Note: the second dimension of the array B must be at least
               max(1,NRHS).
               On entry: the n by r right-hand side matrix B. On exit: the
               n by r solution matrix X.

           8:  LDB -- INTEGER                                         Input
               On entry:
               the first dimension of the array B as declared in the
               (sub)program from which F07AEF is called.
               Constraint: LDB >= max(1,N).

           9:  INFO -- INTEGER                                       Output
               On exit: INFO = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          INFO < 0
               If INFO = -i, the ith parameter has an illegal value. An
               explanatory message is output, and execution of the program
               is terminated.

          7. Accuracy

          For each right-hand side vector b, the computed solution x is the
          exact solution of a perturbed system of equations (A+E)x=b, where

                             |E|<=c(n)(epsilon)P|L||U|,

          c(n) is a modest linear function of n, and (epsilon) is the
          machine precision.

             ^
          If x is the true solution, then the computed solution x satisfies
          a forward error bound of the form

                             ^
                        ||x-x||
                               infty
                        ------------ <= c(n)cond(A,x)(epsilon)
                         ||x||
                              infty

                              -1
          where cond(A,x)=|||A  ||A||x|||     /||x||      <=
                                         infty      infty
                      -1
          cond(A)=|||A  ||A|||     <=(kappa)     (A). Note that cond(A,x)
                              infty         infty
                                                      T
          can be much smaller than cond(A), and cond(A ) can be much larger
          (or smaller) than cond(A).

          Forward and backward error bounds can be computed by calling
          F07AHF (DGERFS)(*), and an estimate for (kappa)     (A) can be
                                                         infty
          obtained by calling F07AGF (DGECON)(*) with NORM ='I'.

          8. Further Comments

          The total number of floating-point operations is approximately
            2
          2n r.

          This routine may be followed by a call to F07AHF (DGERFS)(*) to
          refine the solution and return an error estimate.

          The complex analogue of this routine is F07ASF (ZGETRS)(*).

          9. Example

          To solve the system of equations AX=B, where

                               ( 1.80  2.88  2.05 -0.89)
                               ( 5.25 -2.95 -0.95 -3.80)
                             A=( 1.58 -2.69 -2.90 -1.04)
                               (-1.11 -0.66 -0.59  0.80)

          and


                                    ( 9.52  18.47)
                                    (24.35   2.25)
                                  B=( 0.77 -13.28).
                                    (-6.22  -6.21)

          Here A is unsymmetric and must first be factorized by F07ADF
          (DGETRF)).

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf07fdf}{NAG On-line Documentation: f07fdf}
\beginscroll
\begin{verbatim}



     F07FDF(3NAG)      Foundation Library (12/10/92)      F07FDF(3NAG)



          F07 -- Linear Equations (LAPACK)                           F07FDF
                  F07FDF -- 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

          F07FDF (DPOTRF) computes the Cholesky factorization of a real
          symmetric positive-definite matrix.

          2. Specification

                 SUBROUTINE F07FDF (UPLO, N, A, LDA, INFO)
                 ENTRY            UPLO, N, A, LDA, INFO
                 INTEGER          N, LDA, INFO
                 DOUBLE PRECISION A(LDA,*)
                 CHARACTER*1      UPLO

          The ENTRY statement enables the routine to be called by its
          LAPACK name.

          3. Description

          This routine forms the Cholesky factorization of a real symmetric
                                                  T                       T
          positive-definite matrix A either as A=U U if UPLO = 'U' or A=LL
          if UPLO = 'L', where U is an upper triangular matrix and L is
          lower triangular.

          4. References

          [1]   Demmel J W (1989) On Floating-point Errors in Cholesky.
                LAPACK Working Note No. 14. University of Tennessee,
                Knoxville.

          [2]   Golub G H and Van Loan C F (1989) Matrix Computations (2nd
                Edition). Johns Hopkins University Press, Baltimore,
                Maryland.

          5. Parameters

           1:  UPLO -- CHARACTER*1                                    Input
               On entry: indicates whether the upper or lower triangular
               part of A is stored and how A is factorized, as follows:
                    if UPLO = 'U', then the upper triangular part of A is
                                                   T
                    stored and A is factorized as U U, where U is upper
                    triangular;

                    if UPLO = 'L', then the lower triangular part of A is
                                                    T
                    stored and A is factorized as LL , where L is lower
                    triangular.
                Constraint: UPLO = 'U' or 'L'.

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

           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 n by n symmetric positive-definite matrix A.
               If UPLO = 'U', the upper triangle of A must be stored and
               the elements of the array below the diagonal are not
               referenced; if UPLO = 'L', the lower triangle of A must be
               stored and the elements of the array above the diagonal are
               not referenced. On exit: the upper or lower triangle of A is
               overwritten by the Cholesky factor U or L as specified by
               UPLO.

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

           5:  INFO -- INTEGER                                       Output
               On exit: INFO = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          INFO < 0
               If INFO = -i, the ith parameter has an illegal value. An
               explanatory message is output, and execution of the program
               is terminated.

          INFO > 0
               If INFO = i, the leading minor of order i is not positive-
               definite and the factorization could not be completed. Hence
               A itself is not positive-definite. This may indicate an
               error in forming the matrix A. To factorize a symmetric
               matrix which is not positive-definite, call F07MDF
               (DSYTRF)(*) instead.

          7. Accuracy

          If UPLO = 'U', the computed factor U is the exact factor of a
          perturbed matrix A+E, where

                                                 T
                             |E|<=c(n)(epsilon)|U ||U|,

          c(n) is a modest linear function of n, and (epsilon) is the
          machine precision. If UPLO = 'L', a similar statement holds for
          the computed factor L. It follows that
                                 

          |e  |<=c(n)(epsilon)  /a  a  .
            ij                \/  ii jj

          8. Further Comments

          The total number of floating-point operations is approximately
           1 3
           -n .
           3

          A call to this routine may be followed by calls to the routines:

               F07FEF (DPOTRS) to solve AX=B;

               F07FGF (DPOCON)(*) to estimate the condition number of A;

               F07FJF (DPOTRI)(*) to compute the inverse of A.

          The complex analogue of this routine is F07FRF (ZPOTRF)(*).

          9. Example

          To compute the Cholesky factorization of the matrix A, where

                              ( 4.16 -3.12  0.56 -0.10)
                              (-3.12  5.03 -0.83  1.18)
                            A=( 0.56 -0.83  0.76  0.34).
                              (-0.10  1.18  0.34  1.18)

          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.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXf07fef}{NAG On-line Documentation: f07fef}
\beginscroll
\begin{verbatim}



     F07FEF(3NAG)      Foundation Library (12/10/92)      F07FEF(3NAG)



          F07 -- Linear Equations (LAPACK)                           F07FEF
                  F07FEF -- 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

          F07FEF (DPOTRS) solves a real symmetric positive-definite system
          of linear equations with multiple right-hand sides, AX=B, where A
          has been factorized by F07FDF (DPOTRF).

          2. Specification

                 SUBROUTINE F07FEF (UPLO, N, NRHS, A, LDA, B, LDB, INFO)
                 ENTRY            UPLO, N, NRHS, A, LDA, B, LDB, INFO
                 INTEGER          N, NRHS, LDA, LDB, INFO
                 DOUBLE PRECISION A(LDA,*), B(LDB,*)
                 CHARACTER*1      UPLO

          The ENTRY statement enables the routine to be called by its
          LAPACK name.

          3. Description

          To solve a real symmetric positive-definite system of linear
          equations AX=B, this routine must be preceded by a call to
          F07FDF (DPOTRF) which computes the Cholesky factorization of A.
          The solution X is computed by forward and backward substitution.

                            T
          If UPLO = 'U', A=U U, where U is upper triangular; the solution X
                                  T
          is computed by solving U Y=B and then UX=Y.

                             T
          If UPLO = 'L', A=LL , where L is lower triangular; the solution X
                                                T
          is computed by solving LY=B and then L X=Y.

          4. References

          [1]   Golub G H and Van Loan C F (1989) Matrix Computations (2nd
                Edition). Johns Hopkins University Press, Baltimore,
                Maryland.

          5. Parameters

           1:  UPLO -- CHARACTER*1                                    Input
               On entry: indicates whether the upper or lower triangular
               part of A is stored and how A is factorized, as follows:
                                           T
                    if UPLO = 'U', then A=U U where U is upper triangular;

                                            T
                    if UPLO = 'L', then A=LL  where L is lower triangular.
                Constraint: UPLO = 'U' or 'L'.

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

           3:  NRHS -- INTEGER                                        Input
               On entry: r, the number of right-hand sides. Constraint:
               NRHS >= 0.

           4:  A(LDA,*) -- DOUBLE PRECISION array                     Input
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the Cholesky factor of A, as returned by F07FDF
               (DPOTRF).

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

           6:  B(LDB,*) -- DOUBLE PRECISION array              Input/Output
               Note: the second dimension of the array B must be at least
               max(1,NRHS).
               On entry: the n by r right-hand side matrix B.

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

           8:  INFO -- INTEGER                                       Output
               On exit: INFO = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          INFO < 0
               If INFO = -i, the ith parameter has an illegal value. An
               explanatory message is output, and execution of the program
               is terminated.

          7. Accuracy

          For each right-hand side vector b, the computed solution x is the
          exact solution of a perturbed system of equations (A+E)x=b, where

                                   T
               |E|<=c(n)(epsilon)|U ||U| if UPLO = 'U',

                                      T
               |E|<=c(n)(epsilon)|L||L | if UPLO = 'L',

          c(n) is a modest linear function of n, and (epsilon) is the
          machine precision.

             ^
          If x is the true solution, then the computed solution x satisfies
          a forward bound of the form

                             ^
                        ||x-x||
                               infty
                        ------------<=c(n)cond(A,x)(epsilon)
                         ||x||
                              infty

                              -1
          where cond(A,x)=|||A  ||A||x|||     /||x||      <=
                                         infty      infty
                      -1
          cond(A)=|||A  ||A|||     <=(kappa)     (A). Note that cond(A,x)
                              infty         infty
          can be much smaller than cond(A).

          Forward and backward error bounds can be computed by calling
          F07FHF (DPORFS)(*), and an estimate for (kappa)     (A) (
                                                         infty
          =(kappa) (A)) can be obtained by calling F07FGF (DPOCON)(*).
                  1

          8. Further Comments

          The total number of floating-point operations is approximately
            2
          2n r.

          This routine may be followed by a call to F07FHF (DPORFS)(*) to
          refine the solution and return an error estimate.

          The complex analogue of this routine is F07FSF (ZPOTRS)(*).

          9. Example

          To compute the Cholesky factorization of the matrix A, where

                              ( 4.16 -3.12  0.56 -0.10)
                              (-3.12  5.03 -0.83  1.18)
                            A=( 0.56 -0.83  0.76  0.34).
                              (-0.10  1.18  0.34  1.18)

          and

                                    (  8.70 8.30)
                                    (-13.35 2.13)
                                  B=(  1.89 1.61).
                                    ( -4.14 5.00)

          Here A is symmetric positive-definite and must first be
          factorized by F07FDF (DPOTRF).

          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.

\end{verbatim}
\endscroll
\end{page}