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

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.