next up previous contents index
Next: Example (from Program LA_GESVX_EXAMPLE) Up: General Linear Systems Previous: Description   Contents   Index

Arguments

A
(input/output) REAL or COMPLEX square array, shape $(:,:)$.
On entry, the matrix $A$ or its equilibration:
If ${\bf FACT} = $ 'F' and ${\bf EQUED} \neq$ 'N' then $A$ has been equilibrated by the scaling factors in ${\bf R}$ and/or ${\bf C}$ during a previous call to LA_GESVX.
On exit, if ${\bf FACT} = $ 'E', then the equilibrated version of $A$ is stored in A; otherwise, ${\bf A}$ is unchanged.

B
(input/output) REAL or COMPLEX array, shape $(:,:)$ with $size({\bf B},1) = size({\bf A},1)$ or shape $(:)$ with $size({\bf B})=size({\bf A},1)$.
On entry, the matrix $B$.
On exit, the scaled version of $B$ if the system has been equilibrated; otherwise, ${\bf B}$ is unchanged.

X
(output) REAL or COMPLEX array, shape $(:,:)$ with $size({\bf X},1) = size({\bf A},1)$ and $size({\bf X},2) =
size({\bf B},2)$, or shape $(:)$ with $size({\bf X}) = size({\bf A},1)$.
The solution matrix $X$.

AF
Optional (input or output) REAL or COMPLEX square array, shape $(:,:)$ with the same size as ${\bf A}$.
If ${\bf 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 ${\bf FACT} \neq$ 'F' then ${\bf 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({\bf IPIV})=size({\bf A},1)$.
If ${\bf FACT}$ = 'F' then ${\bf 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 ${\bf FACT} \neq$ 'F' then ${\bf 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.

\begin{optionarg}
\item[{= 'N':}] The matrix $A$\ will be copied to {\bf AF} an...
...{\bf IPIV} contain the
factored form of (the equilibrated) $A$.
\end{optionarg}
Default value: 'N'.

TRANS
Optional (input) CHARACTER(LEN=1).
Specifies the form of the system of equations:

\begin{optionarg}
\item[{= 'N':}] $AX=B$\ (No transpose)
\item[{= 'T':}] $A^TX=B$\ (Transpose)
\item[{= 'C':}] $A^HX=B$\ (Conjugate transpose)
\end{optionarg}
Default value: 'N'.

EQUED
Optional (input or output) CHARACTER(LEN=1).
Specifies the form of equilibration that was done.
${\bf EQUED}$ is an input argument if ${\bf FACT} = $ 'F', otherwise it is an output argument:

\begin{optionarg}
\item[{= 'N':}] No equilibration (always true if {\bf FACT} =...
...({\bf C})$.
\item[{= 'B':}] Both row and column equilibration.
\end{optionarg}
Default value: 'N'.

R
Optional (input or output) REAL array, shape $(:)$ with $size({\bf R})=size({\bf A},1)$.
The row scale factors for $A$.
R is an input argument if FACT = 'F' and ${\bf EQUED}=$ 'R' or 'B'.
R is an output argument if FACT = 'E' and ${\bf EQUED}=$ 'R' or 'B'.

C
Optional (input or output) REAL array, shape $(:)$ with $size({\bf C})=size({\bf A},1)$.
The column scale factors for $A$.
C is an input argument if FACT = 'F' and ${\bf EQUED}=$ 'C' or 'B'.
C is an output argument if FACT = 'E' and ${\bf EQUED}=$ 'C' or 'B'.

FERR
Optional (output) REAL array of shape $(:)$, with $size({\bf FERR})=size({\bf 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 $\mathit{XTRUE}$ is the true solution corresponding to $X_j$, ${\bf FERR}_j$ is an estimated upper bound for the magnitude of the largest element in $(X_j - \mathit{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({\bf BERR})=size({\bf 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 $\Vert A\Vert _{\infty}/\Vert U\Vert _{\infty}$. 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 ${\bf FERR}$ could be unreliable. If the factorization fails with $0<{\bf INFO}\leq size({\bf A},1)$, then RPVGRW contains the reciprocal pivot growth factor for the leading INFO columns of $A$.

INFO
Optional (output) INTEGER

\begin{infoarg}
\item[{$=$\ 0:}] successful exit.
\item[{$<$\ 0:}] if ${\bf IN...
...urate than the
value of {\bf RCOND} would suggest.
\end{infoarg} \end{infoarg}
If ${\bf INFO}$ is not present and an error occurs, then the program is terminated with an error message.
References: [1] and [17,9,20,21].
next up previous contents index
Next: Example (from Program LA_GESVX_EXAMPLE) Up: General Linear Systems Previous: Description   Contents   Index
Susan Blackford 2001-08-19