Previous: cgesvd Up: ../lapack-c.html Next: cgetf2


cgesvx


 NAME
      CGESVX - use the LU factorization to compute the solution to
      a complex system of linear equations  A * X = B,

 SYNOPSIS
      SUBROUTINE CGESVX( FACT, TRANS, N, NRHS, A, LDA, AF, LDAF,
                         IPIV, EQUED, R, C, B, LDB, X, LDX, RCOND,
                         FERR, BERR, WORK, RWORK, INFO )

          CHARACTER      EQUED, FACT, TRANS

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

          REAL           RCOND

          INTEGER        IPIV( * )

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

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

 PURPOSE
      CGESVX uses the LU factorization to compute the solution to
      a complex system of linear equations
         A * X = B, where A is an N-by-N 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 = 'E', real scaling factors are computed to
      equilibrate
         the system:
            TRANS = 'N':  diag(R)*A*diag(C)     *inv(diag(C))*X =
      diag(R)*B
            TRANS = 'T': (diag(R)*A*diag(C))**T *inv(diag(R))*X =
      diag(C)*B
            TRANS = 'C': (diag(R)*A*diag(C))**H *inv(diag(R))*X =
      diag(C)*B
         Whether or not the system will be equilibrated depends on
      the
         scaling of the matrix A, but if equilibration is used, A
      is
         overwritten by diag(R)*A*diag(C) and B by diag(R)*B (if
      TRANS='N')
         or diag(C)*B (if TRANS = 'T' or 'C').

      2. If FACT = 'N' or 'E', the LU decomposition is used to
      factor the
         matrix A (after equilibration if FACT = 'E') as
            A = P * L * U,
         where P is a permutation matrix, L is a unit lower tri-
      angular
         matrix, and U is upper triangular.

      3. 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 4-6 are skipped.

      4. The system of equations is solved for X using the fac-
      tored form
         of A.

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

      6. If FACT = 'E' and equilibration was used, the matrix X is
         premultiplied by diag(C) (if TRANS = 'N') or diag(R) (if
         TRANS = 'T' or 'C') so that it solves the original system
      before
         equilibration.

 ARGUMENTS
      FACT    (input) CHARACTER*1
              Specifies whether or not the factored form of the
              matrix A is supplied on entry, and if not, whether
              the matrix A should be equilibrated before it is
              factored.  = 'F':  On entry, AF and IPIV contain the
              factored form of A.  If EQUED is not 'N', the matrix
              A has been equilibrated with scaling factors given
              by R and C.  A, AF, and IPIV are not modified.  =
              'N':  The matrix A will be copied to AF and fac-
              tored.
              = 'E':  The matrix A will be equilibrated if neces-
              sary, then copied to AF 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 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/output) COMPLEX array, dimension (LDA,N)
              On entry, the N-by-N matrix A.  If FACT = 'F' and
              EQUED is not 'N', then A must have been equilibrated
              by the scaling factors in R and/or C.  A is not
              modified if FACT = 'F' or 'N', or if FACT = 'E' and
              EQUED = 'N' on exit.

              On exit, if EQUED .ne. 'N', A is scaled as follows:
              EQUED = 'R':  A := diag(R) * A
              EQUED = 'C':  A := A * diag(C)
              EQUED = 'B':  A := diag(R) * A * diag(C).

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

      AF      (input or output) COMPLEX array, dimension (LDAF,N)
              If FACT = 'F', then AF is an input argument and on
              entry contains the factors L and U from the factori-
              zation A = P*L*U as computed by CGETRF.  If EQUED
              .ne. 'N', then AF is the factored form of the
              equilibrated matrix A.

              If FACT = 'N', then AF is an output argument and on
              exit returns the factors L and U from the factoriza-
              tion A = P*L*U of the original matrix A.

              If FACT = 'E', then AF is an output argument and on
              exit returns the factors L and U from the factoriza-
              tion A = P*L*U of the equilibrated matrix A (see the
              description of A for the form of the equilibrated
              matrix).

      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 the pivot indices from the factoriza-
              tion A = P*L*U as computed by CGETRF; row i of the
              matrix was interchanged with row IPIV(i).

              If FACT = 'N', then IPIV is an output argument and
              on exit contains the pivot indices from the

              factorization A = P*L*U of the original matrix A.

              If FACT = 'E', then IPIV is an output argument and
              on exit contains the pivot indices from the factori-
              zation A = P*L*U of the equilibrated matrix A.

      EQUED   (input/output) CHARACTER*1
              Specifies the form of equilibration that was done.
              = 'N':  No equilibration (always true if FACT =
              'N').
              = 'R':  Row equilibration, i.e., A has been premul-
              tiplied by diag(R).  = 'C':  Column equilibration,
              i.e., A has been postmultiplied by diag(C).  = 'B':
              Both row and column equilibration, i.e., A has been
              replaced by diag(R) * A * diag(C).  EQUED is an
              input variable if FACT = 'F'; otherwise, it is an
              output variable.

      R       (input/output) REAL array, dimension (N)
              The row scale factors for A.  If EQUED = 'R' or 'B',
              A is multiplied on the left by diag(R); if EQUED =
              'N' or 'C', R is not accessed.  R is an input vari-
              able if FACT = 'F'; otherwise, R is an output vari-
              able.  If FACT = 'F' and EQUED = 'R' or 'B', each
              element of R must be positive.

      C       (input/output) REAL array, dimension (N)
              The column scale factors for A.  If EQUED = 'C' or
              'B', A is multiplied on the right by diag(C); if
              EQUED = 'N' or 'R', C is not accessed.  C is an
              input variable if FACT = 'F'; otherwise, C is an
              output variable.  If FACT = 'F' and EQUED = 'C' or
              'B', each element of C must be positive.

      B       (input/output) COMPLEX array, dimension (LDB,NRHS)
              On entry, the N-by-NRHS right hand side matrix B.
              On exit, if EQUED = 'N', B is not modified; if TRANS
              = 'N' and EQUED = 'R' or 'B', B is overwritten by
              diag(R)*B; if TRANS = 'T' or 'C' and EQUED = 'C' or
              'B', B is overwritten by diag(C)*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 to the
              original system of equations.  Note that A and B are
              modified on exit if EQUED .ne. 'N', and the solution
              to the equilibrated system is inv(diag(C))*X if
              TRANS = 'N' and EQUED = 'C' or 'B', or
              inv(diag(R))*X if TRANS = 'T' or 'C' and EQUED = 'R'

              or 'B'.

      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 after equilibration (if done).  If
              RCOND is less than the machine precision (in partic-
              ular, if RCOND = 0), the matrix is singular to work-
              ing precision.  This condition 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 accu-
              rate, 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 (2*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 been completed, but the factor U is exactly
              singular, so the solution and error bounds could not
              be computed.  = N+1: RCOND is less than machine pre-
              cision.  The factorization has been completed, but
              the matrix is singular to working precision, and the
              solution and error bounds have not been computed.