
          F07 -- Linear Equations (LAPACK)              Introduction -- F07
                                    Chapter F07
                             Linear Equations (LAPACK)

          1. Scope of the Chapter

          This chapter provides four routines concerned with matrix
          factorization, and the solution of systems of linear equations
          following the matrix factorizations.

          2. Background to the Problems

          Background material, together with pointers to the routines in
          this chapter, are to be found in the F01 and F04 Chapter
          Introductions.

          3. Recommendations on Choice and Use of Routines

          The routines in this chapter are derived from the LAPACK project
          and may also be called using the LAPACK name, which is given in
          brackets following the F07 name in the following descriptions.

          Routine F07ADF (DGETRF) performs an LU factorization of a real m
          by n matrix A. Following the use of this routine, F07AEF (DGETRS)
          may be used to solve a system of n non-singular linear equations,
          with one or more right-hand sides.

          Routine F07FDF (DPOTRF) performs the Cholesky factorization of a
          real symmetric positive-definite matrix A. Following the use of
          this routine, F07FEF (DPOTRS) may be used to solve a system of
          symmetric positive-definite linear equations, with one or more
          right-hand sides.


          F07 -- Linear Equations (LAPACK)                  Contents -- F07
          Chapter F07

          Linear Equations (LAPACK)

          F07ADF  (DGETRF) LU factorization of real m by n matrix

          F07AEF  (DGETRS) Solution of real system of linear equations,
                  multiple right-hand sides, matrix already factorized by
                  F07ADF

          F07FDF  (DPOTRF) Cholesky factorization of real symmetric
                  positive-definite matrix

          F07FEF  (DPOTRS) Solution of real symmetric positive-definite
                  system of linear equations, multiple right-hand sides,
                  matrix already factorized by F07FDF

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

          F07 -- Linear Equations (LAPACK)                           F07ADF
                  F07ADF -- NAG Foundation Library Routine Document

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

          1. Purpose

          F07ADF (DGETRF) computes the LU factorization of a real m by n
          matrix.

          2. Specification

                 SUBROUTINE F07ADF (M, N, A, LDA, IPIV, INFO)
                 ENTRY            M, N, A, LDA, IPIV, INFO
                 INTEGER          M, N, LDA, IPIV(*), INFO
                 DOUBLE PRECISION A(LDA,*)

          The ENTRY statement enables the routine to be called by its
          LAPACK name.

          3. Description

          This routine forms the LU factorization of a real m by n matrix A
          as A=PLU, where P is a permutation matrix, L is lower triangular
          with unit diagonal elements (lower trapezoidal if m>n) and U is
          upper triangular (upper trapezoidal if m<n). Usually A is square
          (m=n), and both L and U are triangular. The routine uses partial
          pivoting, with row interchanges.

          4. References

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

          5. Parameters

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

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

           3:  A(LDA,*) -- DOUBLE PRECISION array              Input/Output
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the m by n matrix A. On exit: A is overwritten by
               the factors L and U; the unit diagonal elements of L are not
               stored.

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

           5:  IPIV(*) -- INTEGER array                              Output
               Note: the dimension of the array IPIV must be at least
               max(1,min(M,N)).
               On exit: the pivot indices. Row i of the matrix A was
               interchanged with row IPIV(i) for i=1,2,...,min(m,n).

           6:  INFO -- INTEGER                                       Output
               On exit: INFO = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          INFO < 0
               If INFO = -i, the ith parameter has an illegal value. An
               explanatory message is output, and execution of the program
               is terminated.

          INFO > 0
               If INFO = i, u   is exactly zero. The factorization has been
                             ii
               completed but the factor U is exactly singular, and division
               by zero will occur if it is subsequently used to solve a
                                                         -1
               system of linear equations or to compute A  .

          7. Accuracy

          The computed factors L and U are the exact factors of a perturbed
          matrix A+E, where

                          |E|<=c(min(m,n))(epsilon)P|L||U|,

          c(n) is a modest linear function of n, and (epsilon) is the
          machine precision.

          8. Further Comments

          The total number of floating-point operations is approximately
           2 3                           1 2                   1 2
           -n  if m=n (the usual case),  -n (3m-n) if m>n and  -m (3n-m) if
           3                             3                     3
          m<n.

          A call to this routine with m=n may be followed by calls to the
          routines:

                                                 T
               F07AEF (DGETRS) to solve AX=B or A X=B;

               F07AGF (DGECON)(*) to estimate the condition number of A;

               F07AJF (DGETRI)(*) to compute the inverse of A.

          The complex analogue of this routine is F07ARF (ZGETRF)(*).

          9. Example

          To compute the LU factorization of the matrix A, where

                              ( 1.80  2.88  2.05 -0.89)
                              ( 5.25 -2.95 -0.95 -3.80)
                            A=( 1.58 -2.69 -2.90 -1.04).
                              (-1.11 -0.66 -0.59  0.80)

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

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

          F07 -- Linear Equations (LAPACK)                           F07AEF
                  F07AEF -- NAG Foundation Library Routine Document

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

          1. Purpose

          F07AEF (DGETRS) solves a real system of linear equations with
                                              T
          multiple right-hand sides, AX=B or A X=B, where A has been
          factorized by F07ADF (DGETRF).

          2. Specification

                 SUBROUTINE F07AEF (TRANS, N, NRHS, A, LDA, IPIV, B, LDB,
                1                   INFO)
                 ENTRY            TRANS, N, NRHS, A, LDA, IPIV, B, LDB, INFO
                 INTEGER          N, NRHS, LDA, IPIV(*), LDB, INFO
                 DOUBLE PRECISION A(LDA,*), B(LDB,*)
                 CHARACTER*1      TRANS

          The ENTRY statement enables the routine to be called by its
          LAPACK name.

          3. Description

                                                              T
          To solve a real system of linear equations AX=B or A X=B, this
          routine must be preceded by a call to F07ADF (DGETRF)which
          computes the LU factorization of A as A=PLU. The solution is
          computed by forward and backward substitution.

          If TRANS = 'N', the solution is computed by solving PLY=B and
          then UX=Y.

                                                                      T
          If TRANS = 'T' or 'C', the solution is computed by solving U Y=B
                    T T
          and then L P X=Y.

          4. References

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

          5. Parameters

           1:  TRANS -- CHARACTER*1                                   Input
               On entry: indicates the form of the equations as follows:
                    if TRANS = 'N', then AX=B is solved for X;

                                                 T
                    if TRANS = 'T' or 'C', then A X=B is solved for X.
                Constraint: TRANS = 'N', 'T' or 'C'.

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

           3:  NRHS -- INTEGER                                        Input
               On entry: r, the number of right-hand sides. Constraint:
               NRHS >= 0.

           4:  A(LDA,*) -- DOUBLE PRECISION array                     Input
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the LU factorization of A, as returned by F07ADF
               (DGETRF).

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

           6:  IPIV(*) -- INTEGER array                               Input
               Note: the dimension of the array IPIV must be at least
               max(1,N).
               On entry: the pivot indices, as returned by F07ADF (DGETRF).

           7:  B(LDB,*) -- DOUBLE PRECISION array              Input/Output
               Note: the second dimension of the array B must be at least
               max(1,NRHS).
               On entry: the n by r right-hand side matrix B. On exit: the
               n by r solution matrix X.

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

           9:  INFO -- INTEGER                                       Output
               On exit: INFO = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          INFO < 0
               If INFO = -i, the ith parameter has an illegal value. An
               explanatory message is output, and execution of the program
               is terminated.

          7. Accuracy

          For each right-hand side vector b, the computed solution x is the
          exact solution of a perturbed system of equations (A+E)x=b, where

                             |E|<=c(n)(epsilon)P|L||U|,

          c(n) is a modest linear function of n, and (epsilon) is the
          machine precision.

             ^
          If x is the true solution, then the computed solution x satisfies
          a forward error bound of the form

                             ^
                        ||x-x||
                               infty
                        ------------ <= c(n)cond(A,x)(epsilon)
                         ||x||
                              infty

                              -1
          where cond(A,x)=|||A  ||A||x|||     /||x||      <=
                                         infty      infty
                      -1
          cond(A)=|||A  ||A|||     <=(kappa)     (A). Note that cond(A,x)
                              infty         infty
                                                      T
          can be much smaller than cond(A), and cond(A ) can be much larger
          (or smaller) than cond(A).

          Forward and backward error bounds can be computed by calling
          F07AHF (DGERFS)(*), and an estimate for (kappa)     (A) can be
                                                         infty
          obtained by calling F07AGF (DGECON)(*) with NORM ='I'.

          8. Further Comments

          The total number of floating-point operations is approximately
            2
          2n r.

          This routine may be followed by a call to F07AHF (DGERFS)(*) to
          refine the solution and return an error estimate.

          The complex analogue of this routine is F07ASF (ZGETRS)(*).

          9. Example

          To solve the system of equations AX=B, where

                               ( 1.80  2.88  2.05 -0.89)
                               ( 5.25 -2.95 -0.95 -3.80)
                             A=( 1.58 -2.69 -2.90 -1.04)
                               (-1.11 -0.66 -0.59  0.80)

          and


                                    ( 9.52  18.47)
                                    (24.35   2.25)
                                  B=( 0.77 -13.28).
                                    (-6.22  -6.21)

          Here A is unsymmetric and must first be factorized by F07ADF
          (DGETRF)).

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

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

          F07 -- Linear Equations (LAPACK)                           F07FDF
                  F07FDF -- NAG Foundation Library Routine Document

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

          1. Purpose

          F07FDF (DPOTRF) computes the Cholesky factorization of a real
          symmetric positive-definite matrix.

          2. Specification

                 SUBROUTINE F07FDF (UPLO, N, A, LDA, INFO)
                 ENTRY            UPLO, N, A, LDA, INFO
                 INTEGER          N, LDA, INFO
                 DOUBLE PRECISION A(LDA,*)
                 CHARACTER*1      UPLO

          The ENTRY statement enables the routine to be called by its
          LAPACK name.

          3. Description

          This routine forms the Cholesky factorization of a real symmetric
                                                  T                       T
          positive-definite matrix A either as A=U U if UPLO = 'U' or A=LL
          if UPLO = 'L', where U is an upper triangular matrix and L is
          lower triangular.

          4. References

          [1]   Demmel J W (1989) On Floating-point Errors in Cholesky.
                LAPACK Working Note No. 14. University of Tennessee,
                Knoxville.

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

          5. Parameters

           1:  UPLO -- CHARACTER*1                                    Input
               On entry: indicates whether the upper or lower triangular
               part of A is stored and how A is factorized, as follows:
                    if UPLO = 'U', then the upper triangular part of A is
                                                   T
                    stored and A is factorized as U U, where U is upper
                    triangular;

                    if UPLO = 'L', then the lower triangular part of A is
                                                    T
                    stored and A is factorized as LL , where L is lower
                    triangular.
                Constraint: UPLO = 'U' or 'L'.

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

           3:  A(LDA,*) -- DOUBLE PRECISION array              Input/Output
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the n by n symmetric positive-definite matrix A.
               If UPLO = 'U', the upper triangle of A must be stored and
               the elements of the array below the diagonal are not
               referenced; if UPLO = 'L', the lower triangle of A must be
               stored and the elements of the array above the diagonal are
               not referenced. On exit: the upper or lower triangle of A is
               overwritten by the Cholesky factor U or L as specified by
               UPLO.

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

           5:  INFO -- INTEGER                                       Output
               On exit: INFO = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          INFO < 0
               If INFO = -i, the ith parameter has an illegal value. An
               explanatory message is output, and execution of the program
               is terminated.

          INFO > 0
               If INFO = i, the leading minor of order i is not positive-
               definite and the factorization could not be completed. Hence
               A itself is not positive-definite. This may indicate an
               error in forming the matrix A. To factorize a symmetric
               matrix which is not positive-definite, call F07MDF
               (DSYTRF)(*) instead.

          7. Accuracy

          If UPLO = 'U', the computed factor U is the exact factor of a
          perturbed matrix A+E, where

                                                 T
                             |E|<=c(n)(epsilon)|U ||U|,

          c(n) is a modest linear function of n, and (epsilon) is the
          machine precision. If UPLO = 'L', a similar statement holds for
          the computed factor L. It follows that
                                 

          |e  |<=c(n)(epsilon)  /a  a  .
            ij                \/  ii jj

          8. Further Comments

          The total number of floating-point operations is approximately
           1 3
           -n .
           3

          A call to this routine may be followed by calls to the routines:

               F07FEF (DPOTRS) to solve AX=B;

               F07FGF (DPOCON)(*) to estimate the condition number of A;

               F07FJF (DPOTRI)(*) to compute the inverse of A.

          The complex analogue of this routine is F07FRF (ZPOTRF)(*).

          9. Example

          To compute the Cholesky factorization of the matrix A, where

                              ( 4.16 -3.12  0.56 -0.10)
                              (-3.12  5.03 -0.83  1.18)
                            A=( 0.56 -0.83  0.76  0.34).
                              (-0.10  1.18  0.34  1.18)

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

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

          F07 -- Linear Equations (LAPACK)                           F07FEF
                  F07FEF -- NAG Foundation Library Routine Document

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

          1. Purpose

          F07FEF (DPOTRS) solves a real symmetric positive-definite system
          of linear equations with multiple right-hand sides, AX=B, where A
          has been factorized by F07FDF (DPOTRF).

          2. Specification

                 SUBROUTINE F07FEF (UPLO, N, NRHS, A, LDA, B, LDB, INFO)
                 ENTRY            UPLO, N, NRHS, A, LDA, B, LDB, INFO
                 INTEGER          N, NRHS, LDA, LDB, INFO
                 DOUBLE PRECISION A(LDA,*), B(LDB,*)
                 CHARACTER*1      UPLO

          The ENTRY statement enables the routine to be called by its
          LAPACK name.

          3. Description

          To solve a real symmetric positive-definite system of linear
          equations AX=B, this routine must be preceded by a call to
          F07FDF (DPOTRF) which computes the Cholesky factorization of A.
          The solution X is computed by forward and backward substitution.

                            T
          If UPLO = 'U', A=U U, where U is upper triangular; the solution X
                                  T
          is computed by solving U Y=B and then UX=Y.

                             T
          If UPLO = 'L', A=LL , where L is lower triangular; the solution X
                                                T
          is computed by solving LY=B and then L X=Y.

          4. References

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

          5. Parameters

           1:  UPLO -- CHARACTER*1                                    Input
               On entry: indicates whether the upper or lower triangular
               part of A is stored and how A is factorized, as follows:
                                           T
                    if UPLO = 'U', then A=U U where U is upper triangular;

                                            T
                    if UPLO = 'L', then A=LL  where L is lower triangular.
                Constraint: UPLO = 'U' or 'L'.

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

           3:  NRHS -- INTEGER                                        Input
               On entry: r, the number of right-hand sides. Constraint:
               NRHS >= 0.

           4:  A(LDA,*) -- DOUBLE PRECISION array                     Input
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the Cholesky factor of A, as returned by F07FDF
               (DPOTRF).

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

           6:  B(LDB,*) -- DOUBLE PRECISION array              Input/Output
               Note: the second dimension of the array B must be at least
               max(1,NRHS).
               On entry: the n by r right-hand side matrix B.

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

           8:  INFO -- INTEGER                                       Output
               On exit: INFO = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          INFO < 0
               If INFO = -i, the ith parameter has an illegal value. An
               explanatory message is output, and execution of the program
               is terminated.

          7. Accuracy

          For each right-hand side vector b, the computed solution x is the
          exact solution of a perturbed system of equations (A+E)x=b, where

                                   T
               |E|<=c(n)(epsilon)|U ||U| if UPLO = 'U',

                                      T
               |E|<=c(n)(epsilon)|L||L | if UPLO = 'L',

          c(n) is a modest linear function of n, and (epsilon) is the
          machine precision.

             ^
          If x is the true solution, then the computed solution x satisfies
          a forward bound of the form

                             ^
                        ||x-x||
                               infty
                        ------------<=c(n)cond(A,x)(epsilon)
                         ||x||
                              infty

                              -1
          where cond(A,x)=|||A  ||A||x|||     /||x||      <=
                                         infty      infty
                      -1
          cond(A)=|||A  ||A|||     <=(kappa)     (A). Note that cond(A,x)
                              infty         infty
          can be much smaller than cond(A).

          Forward and backward error bounds can be computed by calling
          F07FHF (DPORFS)(*), and an estimate for (kappa)     (A) (
                                                         infty
          =(kappa) (A)) can be obtained by calling F07FGF (DPOCON)(*).
                  1

          8. Further Comments

          The total number of floating-point operations is approximately
            2
          2n r.

          This routine may be followed by a call to F07FHF (DPORFS)(*) to
          refine the solution and return an error estimate.

          The complex analogue of this routine is F07FSF (ZPOTRS)(*).

          9. Example

          To compute the Cholesky factorization of the matrix A, where

                              ( 4.16 -3.12  0.56 -0.10)
                              (-3.12  5.03 -0.83  1.18)
                            A=( 0.56 -0.83  0.76  0.34).
                              (-0.10  1.18  0.34  1.18)

          and

                                    (  8.70 8.30)
                                    (-13.35 2.13)
                                  B=(  1.89 1.61).
                                    ( -4.14 5.00)

          Here A is symmetric positive-definite and must first be
          factorized by F07FDF (DPOTRF).

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

