Purpose
=======
LA_GESVX computes the solution to a real or complex linear system of
equations of the form A*X = B, A^T*X = B or A^H*X = B, where A is a
square matrix and X and B are rectangular matrices or vectors.
LA_GESVX can also optionally equilibrate the system if A is poorly
scaled, estimate the condition number of (the equilibrated) A, return
the pivot growth factor, and compute error bounds.
=========
SUBROUTINE LA_GESVX ( A, B, X, AF=af, IPIV=ipiv, FACT=fact, &
TRANS=trans, EQUED=equed, R=r, C=c, FERR=ferr, &
BERR=berr, RCOND=rcond, RPVGRW=rpvgrw, &
INFO=info )
(), INTENT(INOUT) :: A(:,:),
(), INTENT(OUT) ::
(), INTENT(INOUT), OPTIONAL :: AF(:,:)
INTEGER, INTENT(INOUT), OPTIONAL :: IPIV(:)
CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: FACT, &
TRANS
CHARACTER(LEN=1), INTENT(INOUT), OPTIONAL :: EQUED
REAL(), INTENT(INOUT), OPTIONAL :: R(:), C(:)
REAL(), INTENT(OUT), OPTIONAL :: , RCOND, RPVGRW
INTEGER, INTENT(OUT), OPTIONAL :: INFO
where
::= REAL | COMPLEX
::= KIND(1.0) | KIND(1.0D0)
::= B(:,:) | B(:)
::= X(:,:) | X(:)
::= FERR(:), BERR(:) | FERR, BERR
Arguments
=========
A (input/output) REAL or COMPLEX square array, shape (:,:).
On entry, the matrix A or its equilibration:
If FACT = 'F' and EQUED /= 'N' then A has been equilibrated
by the scaling factors in R and/or C during a previous call
to LA_GESVX.
On exit, if FACT = 'E', then the equilibrated version of A
is stored in A; otherwise, A is unchanged.
B (input/output) REAL or COMPLEX array, shape (:,:) with
size(B,1) = size(A,1) or shape (:) with size(B) = size(A,1).
On entry, the matrix B.
On exit, the scaled version of B if the system has been
equilibrated; otherwise, B is unchanged.
X (output) REAL or COMPLEX array, shape (:,:) with size(X,1) =
size(A,1) and size(X,2) = size(B,2), or shape (:) with
size(X) = size(A,1).
The solution matrix X .
AF Optional (input or output) REAL or COMPLEX square array,
shape (:,:) with the same size as A.
If FACT = 'F' then AF is an input argument that contains the
factors L and U of (the equilibrated) A returned by a
previous call to LA_GESVX.
If FACT /= 'F' then AF is an output argument that contains
the factors L and U of (the equilibrated) A.
IPIV Optional (input or output) INTEGER array, shape (:) with
size(IPIV) = size(A,1).
If FACT = 'F' then IPIV is an input argument that contains
the pivot indices from the factorization of (the
equilibrated) A, returned by a previous call to LA_GESVX.
If FACT /= 'F' then IPIV is an output argument that contains
the pivot indices from the factorization of (the
equilibrated) A.
FACT Optional (input) CHARACTER(LEN=1).
Specifies whether 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.
= 'N': The matrix A will be copied to AF and factored (no
equilibration).
= 'E': The matrix A will be equilibrated, then copied to AF
and factored.
= 'F': AF and IPIV contain the factored form of (the
equilibrated) A.
Default value: 'N'.
TRANS Optional (input) CHARACTER(LEN=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)
EQUED Optional (input or output) CHARACTER(LEN=1).
Specifies the form of equilibration that was done.
EQUED is an input argument if FACT = 'F', otherwise it is an
output argument:
= 'N': No equilibration (always true if FACT = 'N').
= 'R': Row equilibration, i.e., A has been premultiplied by
diag(R).
= 'C': Column equilibration, i.e., A has been postmultiplied
by diag(C).
= 'B': Both row and column equilibration.
Default value: 'N'.
R Optional (input or output) REAL array, shape (:) with size(R)
= size(A,1). The row scale factors for A.
R is an input argument if FACT = 'F' and EQUED = 'R' or 'B'.
R is an output argument if FACT = 'E' and EQUED = 'R' or 'B'.
C Optional (input or output) REAL array, shape (:) with size(C)
= size(A,1). The column scale factors for A.
C is an input argument if FACT = 'F' and EQUED = 'C' or 'B'.
C is an output argument if FACT = 'E' and EQUED = 'C' or 'B'.
FERR Optional (output) REAL array of shape (:), with size(FERR) =
size(X,2), or REAL scalar.
The estimated forward error bound for each solution vector
X(j) (the j-th column of the solution matrix X). If XTRUE is
the true solution corresponding 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 reliable as the
estimate for RCOND and is almost always a slight
overestimate of the true error.
BERR Optional (output) REAL array of shape (:), with size(BERR) =
size(X,2), or REAL scalar.
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).
RCOND Optional (output) REAL.
The estimate of the reciprocal condition number of (the
equilibrated) A. If RCOND is less than the machine precision,
the matrix is singular to working precision. This condition
is indicated by a return code of INFO > 0.
RPVGRW Optional (output) REAL.
The reciprocal pivot growth factor ||A||inf = ||U||inf. If
RPVGRW 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
the factorization fails with 0 < INFO <= size(A,1), then
RPVGRW contains the reciprocal pivot growth factor for the
leading INFO columns of A.
INFO Optional (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) = 0. The factorization has been completed,
but the factor U is singular, so the solution could
not be computed.
= n+1: U is nonsingular, but RCOND is less than machine
precision, so the matrix is singular to working
precision. Nevertheless, the solution and error
bounds are computed because the computed solution
can be more accurate than the value of RCOND would
suggest.
If INFO is not present and an error occurs, then the program
is terminated with an error message.