CGTSVX(l)		LAPACK routine (version	1.1)		    CGTSVX(l)

NAME
  CGTSVX - use the LU factorization to compute the solution to a complex sys-
  tem of linear	equations A * X	= B, A**T * X =	B, or A**H * X = B,

SYNOPSIS

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

      CHARACTER	     FACT, TRANS

      INTEGER	     INFO, LDB,	LDX, N,	NRHS

      REAL	     RCOND

      INTEGER	     IPIV( * )

      REAL	     BERR( * ),	FERR( *	), RWORK( * )

      COMPLEX	     B(	LDB, * ), D( * ), DF( *	), DL( * ), DLF( * ), DU( *
		     ),	DU2( * ), DUF( * ), WORK( * ), X( LDX, * )

PURPOSE
  CGTSVX uses the LU factorization to compute the solution to a	complex	sys-
  tem 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.

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. 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, steps	3 and 4	are skipped.

  3. The system	of equations is	solved for X using the factored	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
	  modified.  = '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)

  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) COMPLEX array, dimension (N-1)
	  The (n-1) subdiagonal	elements of A.

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

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

  DLF	  (input or output) COMPLEX 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 factori-
	  zation of A as computed by CGTTRF.

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

  DF	  (input or output) COMPLEX 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 factorization 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 factorization of A.

  DUF	  (input or output) COMPLEX 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) COMPLEX 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) 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
	  CGTTRF.

	  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 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.

  B	  (input) COMPLEX 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).

  X	  (output) COMPLEX array, dimension (LDX,NRHS)
	  If INFO = 0, the N-by-NRHS solution matrix X.

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

  RCOND	  (output) REAL
	  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 con-
	  dition is indicated by a return code of INFO > 0, and	the solution
	  and error bounds are not computed.

  FERR	  (output) REAL	array, dimension (NRHS)
	  The estimated	forward	error bounds for each solution vector X(j)
	  (the j-th column of the solution matrix X).  If XTRUE	is the true
	  solution, FERR(j) bounds the magnitude of the	largest	entry in
	  (X(j)	- XTRUE) divided by the	magnitude of the largest entry in
	  X(j).	 The quality of	the error bound	depends	on the quality of the
	  estimate of norm(inv(A)) computed in the code; if the	estimate of
	  norm(inv(A)) is accurate, the	error bound is guaranteed.

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

  WORK	  (workspace) COMPLEX array, dimension (2*N)

  RWORK	  (workspace) REAL array, dimension (N)

  INFO	  (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)	is exactly zero.  The factorization has	not been com-
	  pleted unless	i = N, but the factor U	is exactly singular, so	the
	  solution and error bounds could not be computed.  = N+1:  RCOND is
	  less than machine precision.	The factorization has been completed,
	  but the matrix is singular to	working	precision, and the solution
	  and error bounds have	not been computed.


Back to the listing of expert driver routines