NAG Library Routine Document

F07APF (ZGESVX)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

1 Purpose

F07APF (ZGESVX) uses the LU factorization to compute the solution to a complex system of linear equations

AX=B or ATX=B or AHX=B ,

where A is an n by n matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.

2 Specification

SUBROUTINE F07APF (	FACT, TRANS, N, NRHS, A, LDA, AF, LDAF, IPIV, EQUED, R, C, B, LDB, X, LDX, RCOND, FERR, BERR, WORK, RWORK, INFO)
INTEGER	N, NRHS, LDA, LDAF, IPIV(*), LDB, LDX, INFO
*double precision*	R(), C(), RCOND, FERR(NRHS), BERR(NRHS), RWORK(max(1,2*N))
**complex16***	A(LDA,), AF(LDAF,), B(LDB,), X(LDX,), WORK(2*N)
CHARACTER*1	FACT, TRANS, EQUED

The routine may be called by its LAPACK name zgesvx.

3 Description

F07APF (ZGESVX) performs the following steps:

Equilibration
The linear system to be solved may be badly scaled. However, the system can be equilibrated as a first stage by setting FACT='E'. In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated. Equilibrated forms of the systems AX=B and ATX=B are
DR A DC DC-1X = DR B
and
DR A DC T DR-1 X = DC B ,
respectively, where DR and DC are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors.

When equilibration is used, A will be overwritten by DR A DC and B will be overwritten by DR B (or DC B when the solution of ATX=B or AHX=B is sought).
Factorization
The matrix A, or its scaled form, is copied and factored using the LU decomposition
A=PLU ,
where P is a permutation matrix, L is a unit lower triangular matrix, and U is upper triangular.

This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to F07APF (ZGESVX) with the same matrix A.
Condition Number Estimation
The LU factorization of A determines whether a solution to the linear system exists. If some diagonal element of U is zero, then U is exactly singular, no solution exists and the routine returns with a failure. Otherwise the factorized 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 then a warning code is returned on final exit.
Solution
The (equilibrated) system is solved for X ( DC-1X or DR-1X ) using the factored form of A ( DRADC ).
Iterative Refinement
Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution.
Construct Solution Matrix X
If equilibration was used, the matrix X is premultiplied by DC (if TRANS='N') or DR (if TRANS='T' or 'C') so that it solves the original system before equilibration.

4 References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Higham N J (2002) Accuracy and Stability of Numerical Algorithms (2nd Edition) SIAM, Philadelphia

5 Parameters

1: FACT – CHARACTER*1Input

On entry: specifies whether or not the factorized form of the matrix A is supplied on entry, and if not, whether the matrix A should be equilibrated before it is factorized.

FACT='F'

Constraint: FACT='F', 'N' or 'E'.

2: TRANS – CHARACTER*1Input

On entry: specifies the form of the system of equations.

TRANS='N': AX=B (No transpose).
TRANS='T': ATX=B (Transpose).
TRANS='C': AHX=B (Conjugate transpose).

Constraint: TRANS='N', 'T' or 'C'.

3: N – INTEGERInput

On entry: n, the number of linear equations, i.e., the order of the matrix A.

Constraint: N≥0.

4: NRHS – INTEGERInput

On entry: r, the number of right-hand sides, i.e., the number of columns of the matrix B.

Constraint: NRHS≥0.

5: A(LDA,*) – complex*16 arrayInput/Output

Note: the second dimension of the array A must be at least max1,N.

On entry: the n by n matrix A.

If FACT='F' and EQUED≠'N', A must have been equilibrated by the scaling factors in R and/or C.

On exit: if FACT='F' or 'N', or if FACT='E' and EQUED='N', A is not modified.

If FACT='E' or EQUED≠'N', A is scaled as follows:

if EQUED='R', A=DRA;
if EQUED='C', A=ADC;
if EQUED='B', A=DRADC.

6: LDA – INTEGERInput

On entry: the first dimension of the array A as declared in the (sub)program from which F07APF (ZGESVX) is called.

Constraint: LDA≥max1,N.

7: AF(LDAF,*) – complex*16 arrayInput/Output

Note: the second dimension of the array AF must be at least max1,N.

On entry: if FACT='F', AF contains the factors L and U from the factorization A=PLU as computed by F07ARF (ZGETRF). If EQUED≠'N', AF is the factorized form of the equilibrated matrix A.

If FACT='N' or 'E', AF need not be set.

On exit: if FACT='N', AF returns the factors L and U from the factorization A=PLU of the original matrix A.

If FACT='E', AF returns the factors L and U from the factorization A=PLU of the equilibrated matrix A (see the description of A for the form of the equilibrated matrix).

If FACT='F', AF is unchanged from entry.

8: LDAF – INTEGERInput

On entry: the first dimension of the array AF as declared in the (sub)program from which F07APF (ZGESVX) is called.

Constraint: LDAF≥max1,N.

9: IPIV(*) – INTEGER arrayInput/Output

Note: the dimension of the array IPIV must be at least max1,N.

On entry: if FACT='F', IPIV contains the pivot indices from the factorization A=PLU as computed by F07ARF (ZGETRF); at the ith step row i of the matrix was interchanged with row IPIVi.

If FACT='N' or 'E', IPIV need not be set. IPIVi=i indicates a row interchange was not required.

On exit: if FACT='N', IPIV contains the pivot indices from the factorization A=PLU of the original matrix A.

If FACT='E', IPIV contains the pivot indices from the factorization A=PLU of the equilibrated matrix A.

If FACT='F', IPIV is unchanged from entry.

10: EQUED – CHARACTER*1Input/Output

On entry: if FACT='N' or 'E', EQUED need not be set.

If FACT='F', EQUED must specify the form of the equilibration that was performed as follows:

if EQUED='N', no equilibration;
if EQUED='R', row equilibration, i.e., A has been premultiplied by DR;
if EQUED='C', column equilibration, i.e., A has been postmultiplied by DC;
if EQUED='B', both row and column equilibration, i.e., A has been replaced by DRADC.

On exit: if FACT='F', EQUED is unchanged from entry.

Otherwise, if no constraints are violated, EQUED specifies the form of equilibration that was performed as specified above.

Constraint: if FACT='F', EQUED='N', 'R', 'C' or 'B'.

11: R(*) – double precision arrayInput/Output

Note: the dimension of the array R must be at least max1,N.

On entry: if FACT='N' or 'E', R need not be set.

If FACT='F' and EQUED='R' or 'B', R must contain the row scale factors for A, DR; each element of R must be positive.

On exit: if FACT='F', R is unchanged from entry.

Otherwise, if no constraints are violated and EQUED='R' or 'B', R contains the row scale factors for A, DR, such that A is multiplied on the left by DR; each element of R is positive.

12: C(*) – double precision arrayInput/Output

Note: the dimension of the array C must be at least max1,N.

On entry: if FACT='N' or 'E', C need not be set.

If FACT='F' or EQUED='C' or 'B', C must contain the column scale factors for A, DC; each element of C must be positive.

On exit: if FACT='F', C is unchanged from entry.

Otherwise, if no constraints are violated and EQUED='C' or 'B', C contains the row scale factors for A, DC; each element of C is positive.

13: B(LDB,*) – complex*16 arrayInput/Output

Note: the second dimension of the array B must be at least max1,NRHS.

On entry: the n by r 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 DRB.

If TRANS='T' or 'C' and EQUED='C' or 'B', B is overwritten by DCB.

14: LDB – INTEGERInput

On entry: the first dimension of the array B as declared in the (sub)program from which F07APF (ZGESVX) is called.

Constraint: LDB≥max1,N.

15: X(LDX,*) – complex*16 arrayOutput

Note: the second dimension of the array X must be at least max1,NRHS.

On exit: if INFO=0 or N+1, the n by r solution matrix X to the original system of equations. Note that the arrays A and B are modified on exit if EQUED≠'N', and the solution to the equilibrated system is DC-1X if TRANS='N' and EQUED='C' or 'B', or DR-1X if TRANS='T' or 'C' and EQUED='R' or 'B'.

16: LDX – INTEGERInput

On entry: the first dimension of the array X as declared in the (sub)program from which F07APF (ZGESVX) is called.

Constraint: LDX≥max1,N.

17: RCOND – double precisionOutput

On exit: if no constraints are violated, an estimate of the reciprocal condition number of the matrix A (after equilibration if that is performed), computed as RCOND=1/A1 A-11 .

18: FERR(NRHS) – double precision arrayOutput

On exit: if INFO=0 or N+1, an estimate of the forward error bound for each computed solution vector, such that x^j-xj∞/xj∞≤FERRj where x^j is the jth column of the computed solution returned in the array X and xj is the corresponding column of the exact solution X. The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.

19: BERR(NRHS) – double precision arrayOutput

On exit: if INFO=0 or N+1, an estimate of the component-wise relative backward error of each computed solution vector x^j (i.e., the smallest relative change in any element of A or B that makes x^j an exact solution).

20: WORK(2×N) – complex*16 arrayWorkspace

21: RWORK(max1,2×N) – double precision arrayOutput

On exit: RWORK1 contains the reciprocal pivot growth factor A/U. The ‘max absolute element’ norm is used. If RWORK1 is much less than 1, then the stability of the LU factorization of the (equilibrated) matrix A could be poor. This also means that the solution X, condition estimator RCOND, and forward error bound FERR could be unreliable. If factorization fails with INFO>0 and INFO≤N, then RWORK1 contains the reciprocal pivot growth factor for the leading INFO columns of A.

22: INFO – INTEGEROutput

On exit: INFO=0 unless the routine detects an error (see Section 6).

6 Error Indicators and Warnings

Errors or warnings detected by the routine:

INFO<0: If INFO=-i, the ith argument had an illegal value. An explanatory message is output, and execution of the program is terminated.

INFO>0 and INFO≤N: If INFO=i, uii 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. RCOND=0 is returned.

INFO=N+1: The triangular matrix 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.

7 Accuracy

For each right-hand side vector b, the computed solution x^ is the exact solution of a perturbed system of equations A+Ex^=b, where

E≤cnεPLU ,

cn is a modest linear function of n, and ε is the machine precision. See Section 9.3 of Higham (2002) for further details.

If x is the true solution, then the computed solution x^ satisfies a forward error bound of the form

x-x^∞ x^∞ ≤ wc condA,x^,b

where condA,x^,b = A-1 A x^ + b ∞/ x^∞ ≤ condA = A-1 A ∞≤κ∞ A. If x^ is the j th column of X , then wc is returned in BERRj and a bound on x - x^ ∞ / x^ ∞ is returned in FERRj . See Section 4.4 of Anderson et al. (1999) for further details.