
 
 Purpose
 =======
 
     LA_GTSVX computes the solution to a real or complex linear system 
 of equations of the form A*X = B, A^T*X = B or A^H*X = B, where A is a
 square tridiagonal matrix and X and B are rectangular matrices or
 vectors.
     LA_GTSVX can also optionally estimate the condition number of A and 
 compute error bounds.
 
 =========
 
       SUBROUTINE LA_GTSVX( DL, D, DU, B, X, DLF=dlf, DF=df, DUF=duf, &
               DU2=du2, IPIV=ipiv, FACT=fact, TRANS=trans, FERR=ferr, &
               BERR=berr, RCOND=rcond, INFO=info )
           <type>(<wp>), INTENT(IN) :: DL(:), D(:), DU(:), <rhs>
           <type>(<wp>), INTENT(OUT) :: <sol>
           <type>(<wp>), INTENT(INOUT), OPTIONAL :: DLF(:), DF(:), &
                                                   DUF(:), DU2(:)
           INTEGER, INTENT(INOUT), OPTIONAL :: IPIV(:)
           CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: FACT, TRANS
           REAL(<wp>), INTENT(OUT), OPTIONAL :: <err>
           REAL(<wp>), INTENT(OUT), OPTIONAL :: RCOND
           INTEGER, INTENT(OUT), OPTIONAL :: INFO
       where
           <type> ::= REAL | COMPLEX
           <wp>   ::= KIND(1.0) | KIND(1.0D0)
           <rhs>  ::= B(:,:) | B(:)
           <sol>  ::= X(:,:) | X(:)
           <err>  ::= FERR(:), BERR(:) | FERR, BERR
 
 Arguments
 =========
 
 DL     (input) REAL or COMPLEX array, shape (:) with size(DL) = n-1.
        The subdiagonal of A.
 D      (input) REAL or COMPLEX array, shape (:) with size(D) = n.
        The diagonal of A.
 DU     (input) REAL or COMPLEX array, shape (:) with size(DU) = n-1.
        The superdiagonal of A.
 B      (input/output) REAL or COMPLEX array, shape (:,:) with 
        size(B,1) = n or shape (:) with size(B) = n.
        The matrix B.
 X      (output) REAL or COMPLEX array, shape (:,:) with size(X,1) = n
        and size(X,2) = size(B,2), or shape (:) with size(X) = n.
        The solution matrix X .
 DLF    Optional (input or output) REAL or COMPLEX array, shape (:) with
        size(DLF)= n-1.
        If FACT = 'F' then DLF is an input argument that contains the 
        multipliers that define the matrix L from the LU factorization
        of A.
        If FACT = 'N' then DLF is an output argument that contains the 
        multipliers that define the matrix L from the LU factorization
        of A.
 DF     Optional (input or output) REAL or COMPLEX array, shape (:) with
        size(DF)= n.
        If FACT = 'F' then DF is an input argument that contains the 
        diagonal of the matrix U .
        If FACT = 'N' then DF is an output argument that contains the 
        diagonal of the matrix U .
 DUF    Optional (input or output) REAL or COMPLEX array, shape (:) with
        size(DUF) = n-1.
        If FACT = 'F' then DUF is an input argument that contains the
        first superdiagonal of U.
        If FACT = 'N' then DUF is an output argument that contains the
        first superdiagonal of U.
 DU2    Optional (input or output) REAL or COMPLEX array, shape (:) with
        size(DU2) = n-2.
        If FACT = 'F', then DU2 is an input argument that contains the 
        second superdiagonal of U.
        If FACT = 'N', then DU2 is an output argument that contains the
        second superdiagonal of U.
 IPIV   Optional (input or output) INTEGER array, shape (:) with 
        size(IPIV) = n.
        If FACT = 'F' then IPIV is an input argument that contains the
        pivot indices from the LU factorization of A.
        If FACT = 'N', then IPIV is an output argument that contains the
        pivot indices from the LU factorization of A; row i of the 
        matrix was interchanged with row IPIV(i). IPIV(i) will always
        be either i or i+1; IPIV(i) = i indicates a row interchange was
        not required.
 FACT   Optional (input) CHARACTER(LEN=1).
        Specifies whether the factored form of A is supplied on entry.
            = 'N': The matrix will be copied to DLF, DF and DUF and
 	          factored.
            = 'F': DLF, DF, DUF, DU2 and IPIV contain the factored form
 	          of A.
        Default value: 'N'.
 TRANS  Optional (input) CHARACTER(LEN=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)
        Default value: 'N'.
 FERR   Optional (output) REAL array of shape (:), with size(FERR) =
        size(X,2), or REAL scalar.
        The estimated forward error bound for each solution vector X(j)
        (the j-th column of the solution matrix X). If XTRUE is the true
        solution corresponding 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 reliable as the estimate for RCOND and is almost
        always a slight overestimate of the true error.
 BERR   Optional (output) REAL array of shape (:), with size(BERR) = 
        size(X,2), or REAL scalar.
        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).
 RCOND  Optional (output) REAL.
        The estimate of the reciprocal condition number of the matrix A.
        If RCOND is less than the machine precision, the matrix is 
        singular to working precision. This condition is indicated by
        a return code of INFO > 0.
 INFO   Optional (output) INTEGER
        = 0: successful exit.
        < 0: if INFO = -i, the i-th argument had an illegal value.
        > 0: if INFO = i, and i is 
           <= n: U(i,i) = 0. The factorization has not been completed 
 	        unless i = n. The factor U is singular, so the solution
 		could not be computed.
           = n+1: U is nonsingular, but RCOND is less than machine 
 	        precision, meaning that the matrix is singular to 
 		working precision. Nevertheless, the solution and
                 error bounds are computed because the computed solution
 		can be more accurate than the value of RCOND would 
 		suggest.
        If INFO is not present and an error occurs, then the program is
        terminated with an error message.

