.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 boolean\&. Trust the answer if the !> reciprocal condition number is less than the threshold !> sqrt(n) * slamch('Epsilon')\&. !> !> err = 2 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 \&. 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 boolean\&. Trust the answer if the !> reciprocal condition number is less than the threshold !> sqrt(n) * slamch('Epsilon')\&. !> !> err = 2 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 \&. 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\&.