Developer Reference for Intel® oneAPI Math Kernel Library for C
?herfsx
Uses extra precise iterative refinement to improve the solution to the system of linear equations with a symmetric indefinite coefficient matrix A and provides error bounds and backward error estimates.
Syntax
lapack_int LAPACKE_cherfsx ( intmatrix_layout , charuplo , charequed , lapack_intn , lapack_intnrhs , const lapack_complex_float*a , lapack_intlda , const lapack_complex_float*af , lapack_intldaf , const lapack_int*ipiv , const float*s , const lapack_complex_float*b , lapack_intldb , lapack_complex_float*x , lapack_intldx , float*rcond , float*berr , lapack_intn_err_bnds , float*err_bnds_norm , float*err_bnds_comp , lapack_intnparams , float*params );
lapack_int LAPACKE_zherfsx ( intmatrix_layout , charuplo , charequed , lapack_intn , lapack_intnrhs , const lapack_complex_double*a , lapack_intlda , const lapack_complex_double*af , lapack_intldaf , const lapack_int*ipiv , const double*s , const lapack_complex_double*b , lapack_intldb , lapack_complex_double*x , lapack_intldx , double*rcond , double*berr , lapack_intn_err_bnds , double*err_bnds_norm , double*err_bnds_comp , lapack_intnparams , double*params );
Include Files
mkl.h
Description
cherfsx zherfsx
The routine improves the computed solution to a system of linear equations when the coefficient matrix is Hermitian indefinite, and provides error bounds and backward error estimates for the solution. In addition to a normwise error bound, the code provides a maximum componentwise error bound, if possible. See comments for err_bnds_norm and err_bnds_comp for details of the error bounds.
The original system of linear equations may have been equilibrated before calling this routine, as described by the parameters equed and s below. In this case, the solution and error bounds returned are for the original unequilibrated system.
Input Parameters
- matrix_layout
-
Specifies whether two-dimensional array storage is row major ( LAPACK_ROW_MAJOR ) or column major ( LAPACK_COL_MAJOR ).
uplo
Must be ‘U’ or ‘L’ .
Indicates whether the upper or lower triangular part of A is stored: If uplo = 'U' , the upper triangle of A is stored. If uplo = 'L' , the lower triangle of A is stored.
equed
Must be ‘N’ or ‘Y’ .
Specifies the form of equilibration that was done to A before calling this routine. If equed = 'N' , no equilibration was done. If equed = 'Y' , both row and column equilibration was done, that is, A has been replaced by diag(s)*A*diag(s) . The right-hand side B has been changed accordingly.
n
The number of linear equations; the order of the matrix A ; n ≥ 0.
nrhs
The number of right-hand sides; the number of columns of the matrices B and X ; nrhs ≥ 0.
- a , af , b , work
-
COMPLEX for cherfsx DOUBLE COMPLEX for zherfsx . Arrays: a(lda,*) , af(ldaf,*) , b(ldb,*) , work(*) .
The array a of size max(1, lda * n ) contains the Hermitian matrix A as specified by uplo . If uplo = ‘U’ , the leading n -by- n upper triangular part of a contains the upper triangular part of the matrix A and the strictly lower triangular part of a is not referenced. If uplo = ‘L’ , the leading n -by- n lower triangular part of a contains the lower triangular part of the matrix A and the strictly upper triangular part of a is not referenced.
The array af of size max(1, ldaf * n ) contains the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization A = U*D*U^{T} or A = L*D*L^{T} as computed by GUID-E63FFF60-72A7-44E2-8DEE-4331872FF8D5.xml#GUID-E63FFF60-72A7-44E2-8DEE-4331872FF8D5 for cherfsx or GUID-E63FFF60-72A7-44E2-8DEE-4331872FF8D5.xml#GUID-E63FFF60-72A7-44E2-8DEE-4331872FF8D5 for zherfsx .
The array b of size max(1, ldb * nrhs ) for row major layout and max(1, ldb * n ) for column major layout contains the matrix B whose columns are the right-hand sides for the systems of equations.
work(*) is a workspace array. The dimension of work must be at least max(1,2*n) .
lda
The leading dimension of a ; lda≥ max(1, n) .
ldaf
The leading dimension of af ; ldaf≥ max(1, n) .
- ipiv
-
INTEGER . Array, size at least max(1, n) . Contains details of the interchanges and the block structure of D as determined by ssytrf (Computes the Bunch-Kaufman factorization of a symmetric matrix.) for real flavors or dsytrf (Computes the Bunch-Kaufman factorization of a symmetric matrix.) for complex flavors.
- s
-
REAL for single precision flavors DOUBLE PRECISION for double precision flavors. Array, size ( n ). The array s contains the scale factors for A . If equed = 'N' , s is not accessed. If equed = ‘Y’ , each element of s must be positive. Each element of s 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.
ldb
The leading dimension of the array b ; ldb≥ max(1, n)ldb ≥ max(1, n ) for column major layout and ldb ≥ nrhs for row major layout .
- x
-
COMPLEX for cherfsx DOUBLE COMPLEX for zherfsx .
Array, size (ldx,*) max(1, ldx * nrhs ) for column major layout and max(1, ldx * n ) for row major layout .
The solution matrix X as computed by ?hetrs (Solves a system of linear equations with a UDUT- or LDLT-factored Hermitian coefficient matrix.)
ldx
The leading dimension of the output array x ; ldx≥ max(1, n)ldx ≥ max(1, n ) for column major layout and ldx ≥ nrhs for row major layout .
n_err_bnds
Number of error bounds to return for each right hand side and each type (normwise or componentwise). See err_bnds_norm and err_bnds_comp descriptions in Output Arguments section below.
nparams
Specifies the number of parameters set in params . If ≤ 0, the params array is never referenced and default values are used.
- params
-
REAL for single precision flavors DOUBLE PRECISION for double precision flavors. Array, size nparams . Specifies algorithm parameters. If an entry is less than 0.0, that entry will be filled with the default value used for that parameter. Only positions up to nparams are accessed; defaults are used for higher-numbered parameters. If defaults are acceptable, you can pass nparams = 0, which prevents the source code from accessing the params argument. params(1)params[0] : Whether to perform iterative refinement or not. Default: 1.0 (for cherfsx ), 1.0D+0 (for zherfsx ). (Other values are reserved for future use.) params(2)params[1] : Maximum number of residual computations allowed for refinement. params(3)params[2] : Flag determining if the code will attempt to find a solution with a small componentwise relative error in the double-precision algorithm. Positive is true, 0.0 is false. Default: 1.0 (attempt componentwise convergence).
- rwork
-
REAL for cherfsx DOUBLE PRECISION for zherfsx . Workspace array, size at least max(1, 3*n) .
Output Parameters
- x
-
COMPLEX for cherfsx DOUBLE COMPLEX for zherfsx . The improved solution matrix X .
- rcond
-
REAL for cherfsx DOUBLE PRECISION for zherfsx . 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.
- berr
-
REAL for cherfsx DOUBLE PRECISION for zherfsx .
Array, size at least max(1, nrhs) . Contains the componentwise relative backward error for each solution vector x(j)xj , that is, the smallest relative change in any element of A or B that makes x(j)xj an exact solution.
- err_bnds_norm
-
REAL for cherfsx DOUBLE PRECISION for zherfsx .
Array of size 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
\[\frac{\max_j |Xtrue_{j,i} - X_{j,i}|}{\max_j |X_{j,i}|}\]
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: The information for right-hand side i , where 1 ≤ i ≤ nrhs , and type of error err is stored in:
- err_bnds_comp
-
REAL for cherfsx DOUBLE PRECISION for zherfsx .
Array of size 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:
\[\max_j \frac{|Xtrue_{j,i} - X_{j,i}|}{|X_{j,i}|}\]
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 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 array is indexed 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 not requested ( params[2] = 0.0), then err_bnds_comp is not accessed. 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 following three fields: The information for right-hand side i , where 1 ≤ i ≤ nrhs , and type of error err is stored in:
- params
-
REAL for single precision flavors DOUBLE PRECISION for double precision flavors.
Output parameter only if the input contains erroneous values, namely, in params[0] , params[1] , params[2] . In such a case, the corresponding elements of params are filled with default values on output.
Return Values
This function returns a value info .
If info = 0 , the execution is successful. The solution to every right-hand side is guaranteed.
If info = -i , parameter i had an illegal value.
If 0 < info ≤ n : Uinfo,info is exactly zero. The factorization has been completed, but the factor D is exactly singular, so the solution and error bounds could not be computed; rcond = 0 is returned.
If info = n+j : The solution corresponding to the j -th right-hand side is not guaranteed. The solutions corresponding to other right-hand sides k with k > j may not be guaranteed as well, but only the first such right-hand side is reported. If a small componentwise error is not requested params[2] = 0.0 , then the j -th right-hand side is the first with a normwise error bound that is not guaranteed (the smallest j such that for column major layout err_bnds_norm[j - 1] = 0.0 or err_bnds_comp[j - 1] = 0.0 ; or for row major layout err_bnds_norm[(j - 1)*n_err_bnds] = 0.0 or err_bnds_comp[(j - 1)*n_err_bnds] = 0.0 ). See the definition of err_bnds_norm and err_bnds_comp for err = 1. To get information about all of the right-hand sides, check err_bnds_norm or err_bnds_comp .