.TH "SRC/cla_gerfsx_extended.f" 3 "Version 3.12.0" "LAPACK" \" -*- nroff -*- .ad l .nh .SH NAME SRC/cla_gerfsx_extended.f .SH SYNOPSIS .br .PP .SS "Functions/Subroutines" .in +1c .ti -1c .RI "subroutine \fBcla_gerfsx_extended\fP (prec_type, trans_type, n, nrhs, a, lda, af, ldaf, ipiv, colequ, c, b, ldb, y, ldy, berr_out, n_norms, errs_n, errs_c, res, ayb, dy, y_tail, rcond, ithresh, rthresh, dz_ub, ignore_cwise, info)" .br .RI "\fBCLA_GERFSX_EXTENDED\fP " .in -1c .SH "Function/Subroutine Documentation" .PP .SS "subroutine cla_gerfsx_extended (integer prec_type, integer trans_type, integer n, integer nrhs, complex, dimension( lda, * ) a, integer lda, complex, dimension( ldaf, * ) af, integer ldaf, integer, dimension( * ) ipiv, logical colequ, real, dimension( * ) c, complex, dimension( ldb, * ) b, integer ldb, complex, dimension( ldy, * ) y, integer ldy, real, dimension( * ) berr_out, integer n_norms, real, dimension( nrhs, * ) errs_n, real, dimension( nrhs, * ) errs_c, complex, dimension( * ) res, real, dimension( * ) ayb, complex, dimension( * ) dy, complex, dimension( * ) y_tail, real rcond, integer ithresh, real rthresh, real dz_ub, logical ignore_cwise, integer info)" .PP \fBCLA_GERFSX_EXTENDED\fP .PP \fBPurpose:\fP .RS 4 .PP .nf CLA_GERFSX_EXTENDED improves the computed solution to a system of linear equations by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution\&. This subroutine is called by CGERFSX to perform iterative refinement\&. In addition to normwise error bound, the code provides maximum componentwise error bound if possible\&. See comments for ERRS_N and ERRS_C for details of the error bounds\&. Note that this subroutine is only responsible for setting the second fields of ERRS_N and ERRS_C\&. .fi .PP .RE .PP \fBParameters\fP .RS 4 \fIPREC_TYPE\fP .PP .nf PREC_TYPE is INTEGER Specifies the intermediate precision to be used in refinement\&. The value is defined by ILAPREC(P) where P is a CHARACTER and P = 'S': Single = 'D': Double = 'I': Indigenous = 'X' or 'E': Extra .fi .PP .br \fITRANS_TYPE\fP .PP .nf TRANS_TYPE is INTEGER Specifies the transposition operation on A\&. The value is defined by ILATRANS(T) where T is a CHARACTER and T = 'N': No transpose = 'T': Transpose = 'C': Conjugate transpose .fi .PP .br \fIN\fP .PP .nf N is INTEGER The number of linear equations, i\&.e\&., the order of the matrix A\&. N >= 0\&. .fi .PP .br \fINRHS\fP .PP .nf NRHS is INTEGER The number of right-hand-sides, i\&.e\&., the number of columns of the matrix B\&. .fi .PP .br \fIA\fP .PP .nf A is COMPLEX array, dimension (LDA,N) On entry, the N-by-N matrix A\&. .fi .PP .br \fILDA\fP .PP .nf LDA is INTEGER The leading dimension of the array A\&. LDA >= max(1,N)\&. .fi .PP .br \fIAF\fP .PP .nf AF is COMPLEX array, dimension (LDAF,N) The factors L and U from the factorization A = P*L*U as computed by CGETRF\&. .fi .PP .br \fILDAF\fP .PP .nf LDAF is INTEGER The leading dimension of the array AF\&. LDAF >= max(1,N)\&. .fi .PP .br \fIIPIV\fP .PP .nf IPIV is INTEGER array, dimension (N) The pivot indices from the factorization A = P*L*U as computed by CGETRF; row i of the matrix was interchanged with row IPIV(i)\&. .fi .PP .br \fICOLEQU\fP .PP .nf COLEQU is LOGICAL If \&.TRUE\&. then column equilibration was done to A before calling this routine\&. This is needed to compute the solution and error bounds correctly\&. .fi .PP .br \fIC\fP .PP .nf C is REAL array, dimension (N) The column scale factors for A\&. If COLEQU = \&.FALSE\&., C is not accessed\&. If C is input, each element of C should be a power of the radix to ensure a reliable solution and error estimates\&. Scaling by powers of the radix does not cause rounding errors unless the result underflows or overflows\&. Rounding errors during scaling lead to refining with a matrix that is not equivalent to the input matrix, producing error estimates that may not be reliable\&. .fi .PP .br \fIB\fP .PP .nf B is COMPLEX array, dimension (LDB,NRHS) The right-hand-side matrix B\&. .fi .PP .br \fILDB\fP .PP .nf LDB is INTEGER The leading dimension of the array B\&. LDB >= max(1,N)\&. .fi .PP .br \fIY\fP .PP .nf Y is COMPLEX array, dimension (LDY,NRHS) On entry, the solution matrix X, as computed by CGETRS\&. On exit, the improved solution matrix Y\&. .fi .PP .br \fILDY\fP .PP .nf LDY is INTEGER The leading dimension of the array Y\&. LDY >= max(1,N)\&. .fi .PP .br \fIBERR_OUT\fP .PP .nf BERR_OUT is REAL array, dimension (NRHS) On exit, BERR_OUT(j) contains the componentwise relative backward error for right-hand-side j from the formula max(i) ( abs(RES(i)) / ( abs(op(A_s))*abs(Y) + abs(B_s) )(i) ) where abs(Z) is the componentwise absolute value of the matrix or vector Z\&. This is computed by CLA_LIN_BERR\&. .fi .PP .br \fIN_NORMS\fP .PP .nf N_NORMS is INTEGER Determines which error bounds to return (see ERRS_N and ERRS_C)\&. If N_NORMS >= 1 return normwise error bounds\&. If N_NORMS >= 2 return componentwise error bounds\&. .fi .PP .br \fIERRS_N\fP .PP .nf ERRS_N is REAL array, dimension (NRHS, N_ERR_BNDS) For each right-hand side, this array contains information about various error bounds and condition numbers corresponding to the normwise relative error, which is defined as follows: Normwise relative error in the ith solution vector: max_j (abs(XTRUE(j,i) - X(j,i))) ------------------------------ max_j abs(X(j,i)) The array is indexed by the type of error information as described below\&. There currently are up to three pieces of information returned\&. The first index in ERRS_N(i,:) corresponds to the ith right-hand side\&. The second index in ERRS_N(:,err) contains the following three fields: err = 1 'Trust/don't trust' boolean\&. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon')\&. err = 2 'Guaranteed' error bound: The estimated forward error, almost certainly within a factor of 10 of the true error so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon')\&. This error bound should only be trusted if the previous boolean is true\&. err = 3 Reciprocal condition number: Estimated normwise reciprocal condition number\&. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is 'guaranteed'\&. These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z\&. Let Z = S*A, where S scales each row by a power of the radix so all absolute row sums of Z are approximately 1\&. This subroutine is only responsible for setting the second field above\&. See Lapack Working Note 165 for further details and extra cautions\&. .fi .PP .br \fIERRS_C\fP .PP .nf ERRS_C is REAL array, dimension (NRHS, N_ERR_BNDS) For each right-hand side, this array contains information about various error bounds and condition numbers corresponding to the componentwise relative error, which is defined as follows: Componentwise relative error in the ith solution vector: abs(XTRUE(j,i) - X(j,i)) max_j ---------------------- abs(X(j,i)) The array is indexed by the right-hand side i (on which the componentwise relative error depends), and the type of error information as described below\&. There currently are up to three pieces of information returned for each right-hand side\&. If componentwise accuracy is not requested (PARAMS(3) = 0\&.0), then ERRS_C is not accessed\&. If N_ERR_BNDS < 3, then at most the first (:,N_ERR_BNDS) entries are returned\&. The first index in ERRS_C(i,:) corresponds to the ith right-hand side\&. The second index in ERRS_C(:,err) contains the following three fields: err = 1 'Trust/don't trust' boolean\&. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon')\&. err = 2 'Guaranteed' error bound: The estimated forward error, almost certainly within a factor of 10 of the true error so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon')\&. This error bound should only be trusted if the previous boolean is true\&. err = 3 Reciprocal condition number: Estimated componentwise reciprocal condition number\&. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is 'guaranteed'\&. These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z\&. Let Z = S*(A*diag(x)), where x is the solution for the current right-hand side and S scales each row of A*diag(x) by a power of the radix so all absolute row sums of Z are approximately 1\&. This subroutine is only responsible for setting the second field above\&. See Lapack Working Note 165 for further details and extra cautions\&. .fi .PP .br \fIRES\fP .PP .nf RES is COMPLEX array, dimension (N) Workspace to hold the intermediate residual\&. .fi .PP .br \fIAYB\fP .PP .nf AYB is REAL array, dimension (N) Workspace\&. .fi .PP .br \fIDY\fP .PP .nf DY is COMPLEX array, dimension (N) Workspace to hold the intermediate solution\&. .fi .PP .br \fIY_TAIL\fP .PP .nf Y_TAIL is COMPLEX array, dimension (N) Workspace to hold the trailing bits of the intermediate solution\&. .fi .PP .br \fIRCOND\fP .PP .nf RCOND is REAL Reciprocal scaled condition number\&. This is an estimate of the reciprocal Skeel condition number of the matrix A after equilibration (if done)\&. If this is less than the machine precision (in particular, if it is zero), the matrix is singular to working precision\&. Note that the error may still be small even if this number is very small and the matrix appears ill- conditioned\&. .fi .PP .br \fIITHRESH\fP .PP .nf ITHRESH is INTEGER The maximum number of residual computations allowed for refinement\&. The default is 10\&. For 'aggressive' set to 100 to permit convergence using approximate factorizations or factorizations other than LU\&. If the factorization uses a technique other than Gaussian elimination, the guarantees in ERRS_N and ERRS_C may no longer be trustworthy\&. .fi .PP .br \fIRTHRESH\fP .PP .nf RTHRESH is REAL Determines when to stop refinement if the error estimate stops decreasing\&. Refinement will stop when the next solution no longer satisfies norm(dx_{i+1}) < RTHRESH * norm(dx_i) where norm(Z) is the infinity norm of Z\&. RTHRESH satisfies 0 < RTHRESH <= 1\&. The default value is 0\&.5\&. For 'aggressive' set to 0\&.9 to permit convergence on extremely ill-conditioned matrices\&. See LAWN 165 for more details\&. .fi .PP .br \fIDZ_UB\fP .PP .nf DZ_UB is REAL Determines when to start considering componentwise convergence\&. Componentwise convergence is only considered after each component of the solution Y is stable, which we define as the relative change in each component being less than DZ_UB\&. The default value is 0\&.25, requiring the first bit to be stable\&. See LAWN 165 for more details\&. .fi .PP .br \fIIGNORE_CWISE\fP .PP .nf IGNORE_CWISE is LOGICAL If \&.TRUE\&. then ignore componentwise convergence\&. Default value is \&.FALSE\&.\&. .fi .PP .br \fIINFO\fP .PP .nf INFO is INTEGER = 0: Successful exit\&. < 0: if INFO = -i, the ith argument to CGETRS had an illegal value .fi .PP .RE .PP \fBAuthor\fP .RS 4 Univ\&. of Tennessee .PP Univ\&. of California Berkeley .PP Univ\&. of Colorado Denver .PP NAG Ltd\&. .RE .PP .PP Definition at line \fB391\fP of file \fBcla_gerfsx_extended\&.f\fP\&. .SH "Author" .PP Generated automatically by Doxygen for LAPACK from the source code\&.