--- name: "cla_porfsx_extended.f" section: "3" platform: "linux" package: "lapack-doc" version: "3.12.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/cla_porfsx_extended.f" --- # cla\_porfsx\_extended.f(3) ## NAME SRC/cla\_porfsx\_extended.f ## SYNOPSIS ### Functions/Subroutines subroutine **cla\_porfsx\_extended** (prec\_type, uplo, n, nrhs, a, lda, af, ldaf, 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)\ **CLA\_PORFSX\_EXTENDED** improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution. ## Function/Subroutine Documentation ### subroutine cla\_porfsx\_extended (integer prec\_type, character uplo, integer n, integer nrhs, complex, dimension( lda, \* ) a, integer lda, complex, dimension( ldaf, \* ) af, integer ldaf, 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, \* ) err\_bnds\_norm, real, dimension( nrhs, \* ) err\_bnds\_comp, 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) **CLA\_PORFSX\_EXTENDED** improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution. **Purpose:** ``` !> !> CLA_PORFSX_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 CPORFSX 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. !> ``` **Parameters** *PREC\_TYPE* ``` !> 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 !> ``` *UPLO* ``` !> UPLO is CHARACTER*1 !> = 'U': Upper triangle of A is stored; !> = 'L': Lower triangle of A is stored. !> ``` *N* ``` !> N is INTEGER !> The number of linear equations, i.e., the order of the !> matrix A. N >= 0. !> ``` *NRHS* ``` !> NRHS is INTEGER !> The number of right-hand-sides, i.e., the number of columns of the !> matrix B. !> ``` *A* ``` !> A is COMPLEX array, dimension (LDA,N) !> On entry, the N-by-N matrix A. !> ``` *LDA* ``` !> LDA is INTEGER !> The leading dimension of the array A. LDA >= max(1,N). !> ``` *AF* ``` !> AF is COMPLEX array, dimension (LDAF,N) !> The triangular factor U or L from the Cholesky factorization !> A = U**T*U or A = L*L**T, as computed by CPOTRF. !> ``` *LDAF* ``` !> LDAF is INTEGER !> The leading dimension of the array AF. LDAF >= max(1,N). !> ``` *COLEQU* ``` !> 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. !> ``` *C* ``` !> 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. !> ``` *B* ``` !> B is COMPLEX array, dimension (LDB,NRHS) !> The right-hand-side matrix B. !> ``` *LDB* ``` !> LDB is INTEGER !> The leading dimension of the array B. LDB >= max(1,N). !> ``` *Y* ``` !> Y is COMPLEX array, dimension (LDY,NRHS) !> On entry, the solution matrix X, as computed by CPOTRS. !> On exit, the improved solution matrix Y. !> ``` *LDY* ``` !> LDY is INTEGER !> The leading dimension of the array Y. LDY >= max(1,N). !> ``` *BERR\_OUT* ``` !> 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. !> ``` *N\_NORMS* ``` !> 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. !> ``` *ERR\_BNDS\_NORM* ``` !> ERR_BNDS_NORM 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 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. !> ``` *ERR\_BNDS\_COMP* ``` !> ERR_BNDS_COMP 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 !> 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. !> ``` *RES* ``` !> RES is COMPLEX array, dimension (N) !> Workspace to hold the intermediate residual. !> ``` *AYB* ``` !> AYB is REAL array, dimension (N) !> Workspace. !> ``` *DY* ``` !> DY is COMPLEX array, dimension (N) !> Workspace to hold the intermediate solution. !> ``` *Y\_TAIL* ``` !> Y_TAIL is COMPLEX array, dimension (N) !> Workspace to hold the trailing bits of the intermediate solution. !> ``` *RCOND* ``` !> 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. !> ``` *ITHRESH* ``` !> 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. !> ``` *RTHRESH* ``` !> 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. !> ``` *DZ\_UB* ``` !> 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. !> ``` *IGNORE\_CWISE* ``` !> IGNORE_CWISE is LOGICAL !> If .TRUE. then ignore componentwise convergence. Default value !> is .FALSE.. !> ``` *INFO* ``` !> INFO is INTEGER !> = 0: Successful exit. !> < 0: if INFO = -i, the ith argument to CPOTRS had an illegal !> value !> ``` **Author** Univ. of Tennessee Univ. of California Berkeley Univ. of Colorado Denver NAG Ltd. Definition at line **380** of file **cla\_porfsx\_extended.f**. ## Author Generated automatically by Doxygen for LAPACK from the source code.