?la_gerfsx_extended

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

Date 11/07/2023

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-D4109582-C8AC-43C1-9FE7-5EF4803AE5D9

View Details

?la_gerfsx_extended

Improves the computed solution to a system of linear equations for general matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution.

Syntax

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

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

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

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

Include Files

mkl.fi

Description

The ?la_gerfsx_extended subroutine improves the computed solution to a system of linear equations for general matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution. The ?gerfsx routine calls ?la_gerfsx_extended 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.

Use ?la_gerfsx_extended to set only the second fields of errs_n and errs_c.

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.

nrhs

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

a, af, b, y

REAL for sla_gerfsx_extended

DOUBLE PRECISION for dla_gerfsx_extended

COMPLEX for cla_gerfsx_extended

DOUBLE COMPLEX for zla_gerfsx_extended.

Arrays: a(lda,*), af(ldaf,*), b(ldb,*), y(ldy,*).

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

The array af contains the factors L and U from the factorization A = P*L*U) as computed by ?getrf. The second dimension of af 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 ?getrs. The second dimension of y must be at least max(1,nrhs).

lda

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

ldaf

INTEGER. The leading dimension of the array af; ldaf≥ 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 ?getrf; 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 (sla_gerfsx_extended, cla_gerfsx_extended)

DOUBLE PRECISION for double precision flavors (dla_gerfsx_extended, zla_gerfsx_extended).

c contains the column scale factors for A. If colequ = .FALSE., c is not used.

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 errs_n and errs_c descriptions in Output Arguments section below.

If n_norms≥ 1, returns normwise error bounds.

If n_norms≥ 2, returns componentwise error bounds.

errs_n

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 errs_n(i,:) corresponds to the i-th 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(ε) 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.

errs_c

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 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 i-th right-hand side.

The second index in errs_c(:,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_gerfsx_extended

DOUBLE PRECISION for dla_gerfsx_extended

COMPLEX for cla_gerfsx_extended

DOUBLE COMPLEX for zla_gerfsx_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 errs_n and errs_c 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_gerfsx_extended

DOUBLE PRECISION for dla_gerfsx_extended

COMPLEX for cla_gerfsx_extended

DOUBLE COMPLEX for zla_gerfsx_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.

errs_n, errs_c

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_gerfsx_extended

Syntax

Include Files

Description

Input Parameters

Output Parameters

See Also