
          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

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

          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.

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

          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.

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

          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.

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

          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.

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

          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.

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

          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.

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

          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.

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

          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.

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

          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.

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

          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.

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

          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.

