CHESVX  -  use the diagonal pivoting factorization to com­
       pute the solution to a complex system of linear  equations
       A * X = B,


SYNOPSIS

       SUBROUTINE CHESVX( FACT,  UPLO, N, NRHS, A, LDA, AF, LDAF,
                          IPIV, B,  LDB,  X,  LDX,  RCOND,  FERR,
                          BERR, WORK, LWORK, RWORK, INFO )

           CHARACTER      FACT, UPLO

           INTEGER        INFO,  LDA,  LDAF,  LDB, LDX, LWORK, N,
                          NRHS

           REAL           RCOND

           INTEGER        IPIV( * )

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

           COMPLEX        A( LDA, * ), AF( LDAF, * ), B(  LDB,  *
                          ), WORK( * ), X( LDX, * )


PURPOSE

       CHESVX uses the diagonal pivoting factorization to compute
       the solution to a complex system of linear equations A * X
       = B, where A is an N-by-N Hermitian matrix 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 diagonal pivoting method is used to
       factor A.
          The form of the factorization is
             A = U * D * U**H,  if UPLO = 'U', or
             A = L * D * L**H,  if UPLO = 'L',
          where U (or L) is a product  of  permutation  and  unit
       upper (lower)
          triangular matrices, and D is Hermitian and block diag­
       onal with
          1-by-1 and 2-by-2 diagonal blocks.

       2. If some D(i,i)=0, so that D 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

       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) CHARACTER*1
               Specifies  whether  or  not the factored form of A
               has been supplied on entry.  = 'F':  On entry,  AF
               and  IPIV  contain  the factored form of A.  A, AF
               and IPIV will not be modified.  = 'N':  The matrix
               A will be copied to AF and factored.

       UPLO    (input) CHARACTER*1
               = 'U':  Upper triangle of A is stored;
               = 'L':  Lower triangle of A is stored.

       N       (input) INTEGER
               The number of linear equations, i.e., 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 matrices B and X.  NRHS >= 0.

       A       (input) COMPLEX array, dimension (LDA,N)
               The  Hermitian matrix A.  If UPLO = 'U', the lead­
               ing N-by-N upper triangular part of A contains the
               upper  triangular  part  of  the matrix A, and the
               strictly lower triangular part of A is not  refer­
               enced.   If  UPLO  = 'L', the leading N-by-N lower
               triangular part of A contains the lower triangular
               part  of the matrix A, and the strictly upper tri­
               angular part of A is not referenced.

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

       AF      (input or output) COMPLEX array, dimension
               (LDAF,N)

               entry contains the block diagonal matrix D and the
               multipliers used to obtain the factor U or L  from
               the  factorization A = U*D*U**H or A = L*D*L**H as
               computed by CHETRF.

               If FACT = 'N', then AF is an output  argument  and
               on  exit  returns  the block diagonal matrix D and
               the multipliers used to obtain the factor U  or  L
               from  the  factorization  A  =  U*D*U**H  or  A  =
               L*D*L**H.

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

       IPIV    (input or output) INTEGER array, dimension (N)
               If  FACT = 'F', then IPIV is an input argument and
               on entry contains details of the interchanges  and
               the block structure of D, as determined by CHETRF.
               If IPIV(k) >  0,  then  rows  and  columns  k  and
               IPIV(k)  were  interchanged and D(k,k) is a 1-by-1
               diagonal block.  If  UPLO  =  'U'  and  IPIV(k)  =
               IPIV(k-1)  <  0,  then  rows  and  columns k-1 and
               -IPIV(k) were interchanged and D(k-1:k,k-1:k) is a
               2-by-2  diagonal block.  If UPLO = 'L' and IPIV(k)
               = IPIV(k+1) < 0, then rows  and  columns  k+1  and
               -IPIV(k) were interchanged and D(k:k+1,k:k+1) is a
               2-by-2 diagonal block.

               If FACT = 'N', then IPIV is an output argument and
               on  exit  contains details of the interchanges and
               the block structure of D, as determined by CHETRF.

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

               0.

       FERR    (output) REAL 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) REAL 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/output) COMPLEX array, dimension
               (LWORK)
               On  exit, if INFO = 0, WORK(1) returns the optimal
               LWORK.

       LWORK   (input) INTEGER
               The length of WORK.  LWORK >= 2*N,  and  for  best
               performance LWORK >= N*NB, where NB is the optimal
               blocksize for CHETRF.

               If LWORK = -1, then a workspace query is  assumed;
               the  routine  only  calculates the optimal size of
               the WORK array, returns this value  as  the  first
               entry  of  the  WORK  array,  and no error message
               related to LWORK is issued by XERBLA.

       RWORK   (workspace) REAL 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:  D(i,i) is exactly zero.  The factorization
               has been completed but the  factor  D  is  exactly
               singular,  so  the solution and error bounds could
               not be computed. RCOND = 0 is returned.  = N+1:  D
               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 num­
               ber  of situations where the computed solution can
               be more accurate than the  value  of  RCOND  would
               suggest.


Man(1) output converted with man2html