DGTSVX  - use the LU factorization to compute the solution
       to a real system of linear equations A * X = B or A**T * X
       = B,


SYNOPSIS

       SUBROUTINE DGTSVX( FACT,  TRANS,  N, NRHS, DL, D, DU, DLF,
                          DF, DUF, DU2, IPIV,  B,  LDB,  X,  LDX,
                          RCOND, FERR, BERR, WORK, IWORK, INFO )

           CHARACTER      FACT, TRANS

           INTEGER        INFO, LDB, LDX, N, NRHS

           DOUBLE         PRECISION RCOND

           INTEGER        IPIV( * ), IWORK( * )

           DOUBLE         PRECISION  B( LDB, * ), BERR( * ), D( *
                          ), DF( * ), DL( * ), DLF( * ), DU( * ),
                          DU2(  * ), DUF( * ), FERR( * ), WORK( *
                          ), X( LDX, * )


PURPOSE

       DGTSVX uses the LU factorization to compute  the  solution
       to a real system of linear equations A * X = B or A**T * X
       = B, where A is a tridiagonal matrix of order N and X  and
       B are N-by-NRHS matrices.

       Error  bounds on the solution and a condition estimate are
       also provided.


DESCRIPTION

       The following steps are performed:

       1. If FACT = 'N', the LU decomposition is used  to  factor
       the matrix A
          as  A  = L * U, where L is a product of permutation and
       unit lower
          bidiagonal matrices and  U  is  upper  triangular  with
       nonzeros in
          only the main diagonal and first two superdiagonals.

       2.  If  some U(i,i)=0, so that U is exactly singular, then
       the routine
          returns with INFO = i. Otherwise, the factored form  of
       A is used
          to  estimate  the condition number of the matrix A.  If
       the
          reciprocal of the condition number is less than machine
       precision,
          INFO  =  N+1  is returned as a warning, but the routine
       still goes on

       below.

       3.  The system of equations is solved for X using the fac­
       tored form
          of A.

       4. Iterative refinement is applied to improve the computed
       solution
          matrix  and  calculate  error bounds and backward error
       estimates
          for it.


ARGUMENTS

       FACT    (input) CHARACTER*1
               Specifies whether or not the factored  form  of  A
               has been supplied on entry.  = 'F':  DLF, DF, DUF,
               DU2, and IPIV contain the factored form of A;  DL,
               D, DU, DLF, DF, DUF, DU2 and IPIV will not be mod­
               ified.  = 'N':  The matrix will be copied to  DLF,
               DF, and DUF and factored.

       TRANS   (input) CHARACTER*1
               Specifies the form of the system of equations:
               = 'N':  A * X = B     (No transpose)
               = 'T':  A**T * X = B  (Transpose)
               =  'C':   A**H  *  X  =  B  (Conjugate transpose =
               Transpose)

       N       (input) INTEGER
               The order of the matrix A.  N >= 0.

       NRHS    (input) INTEGER
               The number of right hand sides, i.e.,  the  number
               of columns of the matrix B.  NRHS >= 0.

       DL      (input) DOUBLE PRECISION array, dimension (N-1)
               The (n-1) subdiagonal elements of A.

       D       (input) DOUBLE PRECISION array, dimension (N)
               The n diagonal elements of A.

       DU      (input) DOUBLE PRECISION array, dimension (N-1)
               The (n-1) superdiagonal elements of A.

       DLF     (input or output) DOUBLE PRECISION array,
               dimension (N-1)
               If  FACT  = 'F', then DLF is an input argument and
               on  entry  contains  the  (n-1)  multipliers  that
               define the matrix L from the LU factorization of A
               as computed by DGTTRF.

               If FACT = 'N', then DLF is an output argument  and

               the matrix L from the LU factorization of A.

       DF      (input or output) DOUBLE PRECISION array,
               dimension (N)
               If FACT = 'F', then DF is an input argument and on
               entry contains the  n  diagonal  elements  of  the
               upper  triangular  matrix U from the LU factoriza­
               tion of A.

               If FACT = 'N', then DF is an output  argument  and
               on  exit  contains  the n diagonal elements of the
               upper triangular matrix U from the  LU  factoriza­
               tion of A.

       DUF     (input or output) DOUBLE PRECISION array,
               dimension (N-1)
               If  FACT  = 'F', then DUF is an input argument and
               on entry contains the (n-1) elements of the  first
               superdiagonal of U.

               If  FACT = 'N', then DUF is an output argument and
               on exit contains the (n-1) elements of  the  first
               superdiagonal of U.

       DU2     (input or output) DOUBLE PRECISION array,
               dimension (N-2)
               If  FACT  = 'F', then DU2 is an input argument and
               on entry contains the (n-2) elements of the second
               superdiagonal of U.

               If  FACT = 'N', then DU2 is an output argument and
               on exit contains the (n-2) elements of the  second
               superdiagonal of U.

       IPIV    (input or output) INTEGER array, dimension (N)
               If  FACT = 'F', then IPIV is an input argument and
               on entry contains the pivot indices  from  the  LU
               factorization of A as computed by DGTTRF.

               If FACT = 'N', then IPIV is an output argument and
               on exit contains the pivot  indices  from  the  LU
               factorization of A; row i of the matrix was inter­
               changed with row IPIV(i).  IPIV(i) will always  be
               either  i  or  i+1;  IPIV(i)  =  i indicates a row
               interchange was not required.

       B       (input) DOUBLE PRECISION array, dimension
               (LDB,NRHS)
               The N-by-NRHS right hand side matrix B.

       LDB     (input) INTEGER
               The  leading  dimension  of  the  array B.  LDB >=
               max(1,N).

               (LDX,NRHS)
               If  INFO = 0 or INFO = N+1, the N-by-NRHS solution
               matrix X.

       LDX     (input) INTEGER
               The leading dimension of  the  array  X.   LDX  >=
               max(1,N).

       RCOND   (output) DOUBLE PRECISION
               The estimate of the reciprocal condition number of
               the matrix A.  If RCOND is less than  the  machine
               precision  (in  particular,  if  RCOND  =  0), the
               matrix is singular  to  working  precision.   This
               condition  is indicated by a return code of INFO >
               0.

       FERR    (output) DOUBLE PRECISION array, dimension (NRHS)
               The estimated forward error bound for  each  solu­
               tion  vector X(j) (the j-th column of the solution
               matrix X).  If XTRUE is the true  solution  corre­
               sponding  to  X(j),  FERR(j) is an estimated upper
               bound for the magnitude of the largest element  in
               (X(j)  -  XTRUE)  divided  by the magnitude of the
               largest element in X(j).  The estimate is as reli­
               able  as  the  estimate  for  RCOND, and is almost
               always a slight overestimate of the true error.

       BERR    (output) DOUBLE PRECISION array, dimension (NRHS)
               The componentwise relative backward error of  each
               solution  vector X(j) (i.e., the smallest relative
               change in any element of A or B that makes X(j) an
               exact solution).

       WORK    (workspace) DOUBLE PRECISION array, dimension
               (3*N)

       IWORK   (workspace) INTEGER array, dimension (N)

       INFO    (output) INTEGER
               = 0:  successful exit
               < 0:  if INFO = -i, the i-th argument had an ille­
               gal value
               > 0:  if INFO = i, and i is
               <=  N:  U(i,i) is exactly zero.  The factorization
               has not been completed unless i = N, but the  fac­
               tor  U  is  exactly  singular, so the solution and
               error bounds could not be computed.  RCOND = 0  is
               returned.   =  N+1: U is nonsingular, but RCOND is
               less than  machine  precision,  meaning  that  the
               matrix  is  singular to working precision.  Never­
               theless, the solution and error  bounds  are  com­
               puted  because  there  are  a number of situations
               where the computed solution can be  more  accurate



Man(1) output converted with man2html