?la_gbrfsx_extended

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

Date 6/24/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-2DE4E58F-7A08-4321-B58A-AC6239DB5B1E

View Details

?la_gbrfsx_extended

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.

Syntax

call sla_gbrfsx_extended( 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 )

call dla_gbrfsx_extended( 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 )

call cla_gbrfsx_extended( 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 )

call zla_gbrfsx_extended( 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 )

Include Files

mkl.fi

Description

The ?la_gbrfsx_extended subroutine 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. The ?gbrfsx routine calls ?la_gbrfsx_extended 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.

Use ?la_gbrfsx_extended to set only the second fields of err_bnds_norm and err_bnds_comp.

Input Parameters

prec_type

INTEGER.

Specifies the intermediate precision to be used in refinement. The value is defined by ilaprec(p), where p is a CHARACTER and:

If p = 'S': Single.

If p = 'D': Double.

If p = 'I': Indigenous.

If p = 'X', 'E': Extra.

trans_type

INTEGER.

Specifies the transposition operation on A. The value is defined by ilatrans(t), where t is a CHARACTER and:

If t = 'N': No transpose.

If t = 'T': Transpose.

If t = 'C': Conjugate Transpose.

n

INTEGER. The number of linear equations; the order of the matrix A; n≥ 0.

kl

INTEGER. The number of subdiagonals within the band of A; kl≥ 0.

ku

INTEGER. The number of superdiagonals within the band of A; ku≥ 0.

nrhs

INTEGER. The number of right-hand sides; the number of columns of the matrix B.

ab, afb, b, y

REAL for sla_gbrfsx_extended

DOUBLE PRECISION for dla_gbrfsx_extended

COMPLEX for cla_gbrfsx_extended

DOUBLE COMPLEX for zla_gbrfsx_extended.

Arrays: ab(ldab,*), afb(ldafb,*), b(ldb,*), y(ldy,*).

The array ab contains the original n-by-n matrix A. The second dimension of ab must be at least max(1,n).

The array afb contains the factors L and U from the factorization A = P*L*U) as computed by ?gbtrf. The second dimension of afb must be at least max(1,n).

The array b contains the matrix B whose columns are the right-hand sides for the systems of equations. The second dimension of b must be at least max(1,nrhs).

The array y on entry contains the solution matrix X as computed by ?gbtrs. The second dimension of y must be at least max(1,nrhs).

ldab

INTEGER. The leading dimension of the array ab; ldab≥ max(1,n).

ldafb

INTEGER. The leading dimension of the array afb; ldafb≥ max(1,n).

ipiv

INTEGER.

Array, DIMENSION at least max(1, n). Contains the pivot indices from the factorization A = P*L*U) as computed by ?gbtrf; row i of the matrix was interchanged with row ipiv(i).

colequ

LOGICAL. If colequ = .TRUE., column equilibration was done to A before calling this routine. This is needed to compute the solution and error bounds correctly.

c

REAL for single precision flavors

DOUBLE PRECISION for double precision flavors.

c contains 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 power 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.

ldb

INTEGER. The leading dimension of the array b; ldb≥ max(1, n).

ldy

INTEGER. The leading dimension of the array y; ldy≥ max(1, n).

n_norms

INTEGER. Determines which error bounds to return. See err_bnds_norm and err_bnds_comp descriptions in Output Arguments section below.

If n_norms≥ 1, returns normwise error bounds.

If n_norms≥ 2, returns componentwise error bounds.

err_bnds_norm

REAL for single precision flavors

DOUBLE PRECISION for double precision flavors.

Array, DIMENSION(nrhs,n_err_bnds). For each right-hand side, 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 i-th solution vector

The array is indexed by the type of error information as described below. There are currently up to three pieces of information returned.

The first index in err_bnds_norm(i,:) corresponds to the i-th 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(ε) for single precision flavors and sqrt(n)*dlamch(ε) for double precision flavors.

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(ε) for single precision flavors and sqrt(n)*dlamch(ε) for double precision flavors. 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(ε) for single precision flavors and sqrt(n)*dlamch(ε) for double precision flavors to determine if the error estimate is "guaranteed". These reciprocal condition numbers are 1/(norm(1/z,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.

Use this subroutine to set only the second field above.

err_bnds_comp

REAL for single precision flavors

DOUBLE PRECISION for double precision flavors.

Array, DIMENSION(nrhs,n_err_bnds). For each right-hand side, 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 i-th solution vector:

The array is indexed by the right-hand side i, on which the componentwise relative error depends, and by the type of error information as described below. There are currently up to three pieces of information returned for each right-hand side. If componentwise accuracy is nit 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 i-th right-hand side.

The second index in err_bnds_comp(:,err) contains the follwoing three fields:

err=1

err=2

"Guaranteed" error bpound. 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(ε) for single precision flavors and sqrt(n)*dlamch(ε) for double precision flavors. 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(ε) for single precision flavors and sqrt(n)*dlamch(ε) for double precision flavors to determine if the error estimate is "guaranteed". These reciprocal condition numbers are 1/(norm(1/z,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.

Use this subroutine to set only the second field above.

res, dy, y_tail

REAL for sla_gbrfsx_extended

DOUBLE PRECISION for dla_gbrfsx_extended

COMPLEX for cla_gbrfsx_extended

DOUBLE COMPLEX for zla_gbrfsx_extended.

Workspace arrays of DIMENSIONn.

res holds the intermediate residual.

dy holds the intermediate solution.

y_tail holds the trailing bits of the intermediate solution.

ayb

REAL for single precision flavors

DOUBLE PRECISION for double precision flavors.

Workspace array, DIMENSIONn.

rcond

REAL for single precision flavors

DOUBLE PRECISION for double precision flavors.

Reciprocal scaled condition number. An estimate of the reciprocal Skeel condition number of the matrix A after equilibration (if done). If rcond is less than the machine precision, in particular, if rcond = 0, 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

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

REAL for single precision flavors

DOUBLE PRECISION for double precision flavors.

Determines when to stop refinement if the error estimate stops decreasing. Refinement stops 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.

dz_ub

REAL for single precision flavors

DOUBLE PRECISION for double precision flavors.

Determines when to start considering componentwise convergence. Componentwise dz_ub convergence is only considered after each component of the solution y is stable, that is, the relative change in each component is less than dz_ub. The default value is 0.25, requiring the first bit to be stable.

ignore_cwise

LOGICAL

If .TRUE., the function ignores componentwise convergence. Default value is .FALSE.

Output Parameters

y

REAL for sla_gbrfsx_extended

DOUBLE PRECISION for dla_gbrfsx_extended

COMPLEX for cla_gbrfsx_extended

DOUBLE COMPLEX for zla_gbrfsx_extended.

The improved solution matrix Y.

berr_out

REAL for single precision flavors

DOUBLE PRECISION for double precision flavors.

Array, DIMENSION at least max(1, nrhs). Contains the componentwise relative backward error for right-hand-side j from the formula

max(i) ( abs(res(i)) / ( abs(op(A))*abs(y) + abs(B) )(i) )

where abs(z) is the componentwise absolute value of the matrix or vector Z. This is computed by ?la_lin_berr.

err_bnds_norm, err_bnds_comp

Values of the corresponding input parameters improved after iterative refinement and stored in the second column of the array ( 1:nrhs, 2 ). The other elements are kept unchanged.

info

INTEGER. If info = 0, the execution is successful. The solution to every right-hand side is guaranteed.

If info = -i, the i-th parameter had an illegal value.

Parent topic: LAPACK Auxiliary Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

?la_gbrfsx_extended

Syntax

Include Files

Description

Input Parameters

Output Parameters

See Also