.TH "SRC/zla_gbrfsx_extended.f" 3 "Version 3.12.0" "LAPACK" \" -*- nroff -*- .ad l .nh .SH NAME SRC/zla_gbrfsx_extended.f .SH SYNOPSIS .br .PP .SS "Functions/Subroutines" .in +1c .ti -1c .RI "subroutine \fBzla_gbrfsx_extended\fP (prec_type, trans_type, n, kl, ku, nrhs, ab, ldab, afb, ldafb, ipiv, colequ, c, b, ldb, y, ldy, berr_out, n_norms, err_bnds_norm, err_bnds_comp, res, ayb, dy, y_tail, rcond, ithresh, rthresh, dz_ub, ignore_cwise, info)" .br .RI "\fBZLA_GBRFSX_EXTENDED\fP improves the computed solution to a system of linear equations for general banded matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution\&. " .in -1c .SH "Function/Subroutine Documentation" .PP .SS "subroutine zla_gbrfsx_extended (integer prec_type, integer trans_type, integer n, integer kl, integer ku, integer nrhs, complex*16, dimension( ldab, * ) ab, integer ldab, complex*16, dimension( ldafb, * ) afb, integer ldafb, integer, dimension( * ) ipiv, logical colequ, double precision, dimension( * ) c, complex*16, dimension( ldb, * ) b, integer ldb, complex*16, dimension( ldy, * ) y, integer ldy, double precision, dimension( * ) berr_out, integer n_norms, double precision, dimension( nrhs, * ) err_bnds_norm, double precision, dimension( nrhs, * ) err_bnds_comp, complex*16, dimension( * ) res, double precision, dimension(*) ayb, complex*16, dimension( * ) dy, complex*16, dimension( * ) y_tail, double precision rcond, integer ithresh, double precision rthresh, double precision dz_ub, logical ignore_cwise, integer info)" .PP \fBZLA_GBRFSX_EXTENDED\fP improves the computed solution to a system of linear equations for general banded matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution\&. .PP \fBPurpose:\fP .RS 4 .PP .nf ZLA_GBRFSX_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 ZGBRFSX to perform iterative refinement\&. In addition to normwise error bound, the code provides maximum componentwise error bound if possible\&. See comments for ERR_BNDS_NORM and ERR_BNDS_COMP for details of the error bounds\&. Note that this subroutine is only responsible for setting the second fields of ERR_BNDS_NORM and ERR_BNDS_COMP\&. .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 \fIKL\fP .PP .nf KL is INTEGER The number of subdiagonals within the band of A\&. KL >= 0\&. .fi .PP .br \fIKU\fP .PP .nf KU is INTEGER The number of superdiagonals within the band of A\&. KU >= 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 \fIAB\fP .PP .nf AB is COMPLEX*16 array, dimension (LDAB,N) On entry, the N-by-N matrix A\&. .fi .PP .br \fILDAB\fP .PP .nf LDAB is INTEGER The leading dimension of the array A\&. LDAB >= max(1,N)\&. .fi .PP .br \fIAFB\fP .PP .nf AFB is COMPLEX*16 array, dimension (LDAF,N) The factors L and U from the factorization A = P*L*U as computed by ZGBTRF\&. .fi .PP .br \fILDAFB\fP .PP .nf LDAFB 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 ZGBTRF; 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 DOUBLE PRECISION 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*16 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*16 array, dimension (LDY,NRHS) On entry, the solution matrix X, as computed by ZGBTRS\&. 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 DOUBLE PRECISION 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 ZLA_LIN_BERR\&. .fi .PP .br \fIN_NORMS\fP .PP .nf N_NORMS is INTEGER Determines which error bounds to return (see ERR_BNDS_NORM and ERR_BNDS_COMP)\&. If N_NORMS >= 1 return normwise error bounds\&. If N_NORMS >= 2 return componentwise error bounds\&. .fi .PP .br \fIERR_BNDS_NORM\fP .PP .nf ERR_BNDS_NORM is DOUBLE PRECISION 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 ERR_BNDS_NORM(i,:) corresponds to the ith right-hand side\&. The second index in ERR_BNDS_NORM(:,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 \fIERR_BNDS_COMP\fP .PP .nf ERR_BNDS_COMP is DOUBLE PRECISION 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 ERR_BNDS_COMP is not accessed\&. If N_ERR_BNDS < 3, then at most the first (:,N_ERR_BNDS) entries are returned\&. The first index in ERR_BNDS_COMP(i,:) corresponds to the ith right-hand side\&. The second index in ERR_BNDS_COMP(:,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*16 array, dimension (N) Workspace to hold the intermediate residual\&. .fi .PP .br \fIAYB\fP .PP .nf AYB is DOUBLE PRECISION array, dimension (N) Workspace\&. .fi .PP .br \fIDY\fP .PP .nf DY is COMPLEX*16 array, dimension (N) Workspace to hold the intermediate solution\&. .fi .PP .br \fIY_TAIL\fP .PP .nf Y_TAIL is COMPLEX*16 array, dimension (N) Workspace to hold the trailing bits of the intermediate solution\&. .fi .PP .br \fIRCOND\fP .PP .nf RCOND is DOUBLE PRECISION 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 ERR_BNDS_NORM and ERR_BNDS_COMP may no longer be trustworthy\&. .fi .PP .br \fIRTHRESH\fP .PP .nf RTHRESH is DOUBLE PRECISION 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 DOUBLE PRECISION 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 ZGBTRS 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 \fB403\fP of file \fBzla_gbrfsx_extended\&.f\fP\&. .SH "Author" .PP Generated automatically by Doxygen for LAPACK from the source code\&.