Contents


NAME

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

SYNOPSIS

     SUBROUTINE ZGTSVX(FACT, TRANSA, N, NRHS, LOW, DIAG, UP, LOWF, DIAGF,
           UPF1, UPF2, IPIVOT, B, LDB, X, LDX, RCOND, FERR, BERR, WORK,
           WORK2, INFO)

     CHARACTER * 1 FACT, TRANSA
     DOUBLE COMPLEX LOW(*), DIAG(*),  UP(*),  LOWF(*),  DIAGF(*),
     UPF1(*), UPF2(*), B(LDB,*), X(LDX,*), WORK(*)
     INTEGER N, NRHS, LDB, LDX, INFO
     INTEGER IPIVOT(*)
     DOUBLE PRECISION RCOND
     DOUBLE PRECISION FERR(*), BERR(*), WORK2(*)

     SUBROUTINE ZGTSVX_64(FACT, TRANSA, N, NRHS, LOW, DIAG, UP, LOWF,
           DIAGF, UPF1, UPF2, IPIVOT, B, LDB, X, LDX, RCOND, FERR, BERR,
           WORK, WORK2, INFO)

     CHARACTER * 1 FACT, TRANSA
     DOUBLE COMPLEX LOW(*), DIAG(*),  UP(*),  LOWF(*),  DIAGF(*),
     UPF1(*), UPF2(*), B(LDB,*), X(LDX,*), WORK(*)
     INTEGER*8 N, NRHS, LDB, LDX, INFO
     INTEGER*8 IPIVOT(*)
     DOUBLE PRECISION RCOND
     DOUBLE PRECISION FERR(*), BERR(*), WORK2(*)

  F95 INTERFACE
     SUBROUTINE GTSVX(FACT, [TRANSA], [N], [NRHS], LOW, DIAG, UP, LOWF,
            DIAGF, UPF1, UPF2, IPIVOT, B, [LDB], X, [LDX], RCOND, FERR, BERR,
            [WORK], [WORK2], [INFO])

     CHARACTER(LEN=1) :: FACT, TRANSA
     COMPLEX(8), DIMENSION(:) ::  LOW,  DIAG,  UP,  LOWF,  DIAGF,
     UPF1, UPF2, WORK
     COMPLEX(8), DIMENSION(:,:) :: B, X
     INTEGER :: N, NRHS, LDB, LDX, INFO
     INTEGER, DIMENSION(:) :: IPIVOT
     REAL(8) :: RCOND
     REAL(8), DIMENSION(:) :: FERR, BERR, WORK2

     SUBROUTINE GTSVX_64(FACT, [TRANSA], [N], [NRHS], LOW, DIAG, UP, LOWF,
            DIAGF, UPF1, UPF2, IPIVOT, B, [LDB], X, [LDX], RCOND, FERR, BERR,
            [WORK], [WORK2], [INFO])

     CHARACTER(LEN=1) :: FACT, TRANSA
     COMPLEX(8), DIMENSION(:) ::  LOW,  DIAG,  UP,  LOWF,  DIAGF,
     UPF1, UPF2, WORK
     COMPLEX(8), DIMENSION(:,:) :: B, X
     INTEGER(8) :: N, NRHS, LDB, LDX, INFO
     INTEGER(8), DIMENSION(:) :: IPIVOT
     REAL(8) :: RCOND
     REAL(8), DIMENSION(:) :: FERR, BERR, WORK2

  C INTERFACE
     #include <sunperf.h>

     void zgtsvx(char fact, char transa, int n, int  nrhs,  doub-
               lecomplex *low, doublecomplex *diag, doublecomplex
               *up, doublecomplex  *lowf,  doublecomplex  *diagf,
               doublecomplex   *upf1,  doublecomplex  *upf2,  int
               *ipivot, doublecomplex *b, int ldb,  doublecomplex
               *x,  int  ldx, double *rcond, double *ferr, double
               *berr, int *info);

     void zgtsvx_64(char fact, char transa, long  n,  long  nrhs,
               doublecomplex  *low,  doublecomplex  *diag,  doub-
               lecomplex *up, doublecomplex *lowf,  doublecomplex
               *diagf,  doublecomplex *upf1, doublecomplex *upf2,
               long *ipivot, doublecomplex *b,  long  ldb,  doub-
               lecomplex  *x,  long  ldx,  double  *rcond, double
               *ferr, double *berr, long *info);

PURPOSE

     zgtsvx uses the LU factorization to compute the solution  to
     a  complex  system of linear equations A * X = B, A**T * X =
     B, or A**H * 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.

     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
        to solve for X and  compute  error  bounds  as  described
     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)
               Specifies whether or not the factored  form  of  A
               has  been supplied on entry.  = 'F':  LOWF, DIAGF,
               UPF1, UPF2, and IPIVOT contain the  factored  form
               of  A;  LOW, DIAG, UP, LOWF, DIAGF, UPF1, UPF2 and
               IPIVOT will not be modified.  = 'N':   The  matrix
               will  be  copied to LOWF, DIAGF, and UPF1 and fac-
               tored.

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

               TRANSA is defaulted to 'N' for F95 INTERFACE.

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

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

     LOW (input)
               The (n-1) subdiagonal elements of A.
     DIAG (input)
               The n diagonal elements of A.

     UP (input/output)
               The (n-1) superdiagonal elements of A.

     LOWF (input or output)
               If FACT = 'F', then LOWF 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 CGTTRF.

               If FACT = 'N', then LOWF is an output argument and
               on exit contains the (n-1) multipliers that define
               the matrix L from the LU factorization of A.

     DIAGF (input or output)
               If FACT = 'F', then DIAGF 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 DIAGF is  an  output  argument
               and  on  exit  contains the n diagonal elements of
               the upper triangular matrix U from the LU factori-
               zation of A.

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

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

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

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

     IPIVOT (input/output)
               If FACT = 'F', then IPIVOT is  an  input  argument
               and  on  entry contains the pivot indices from the
               LU factorization of A as computed by CGTTRF.

               If FACT = 'N', then IPIVOT 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 IPIVOT(i).  IPIVOT(i) will always
               be either i or i+1; IPIVOT(i) = i indicates a  row
               interchange was not required.

     B (input) The N-by-NRHS right hand side matrix B.

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

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

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

     RCOND (output)
               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)
               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
               corresponding  to  X(j),  FERR(j)  is an estimated
               upper bound for the magnitude of the largest  ele-
               ment 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 (output)
               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)
               dimension(2*N)

     WORK2 (workspace)
               dimension(N)

     INFO (output)
               = 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.
               Nevertheless,  the  solution  and error bounds are
               computed because there are a number of  situations
               where  the  computed solution can be more accurate
               than the value of RCOND would suggest.