Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

?syrfsx

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_ssyrfsx
(
int
matrix_layout
,
char
uplo
,
char
equed
,
lapack_int
n
,
lapack_int
nrhs
,
const float*
a
,
lapack_int
lda
,
const float*
af
,
lapack_int
ldaf
,
const lapack_int*
ipiv
,
const float*
s
,
const float*
b
,
lapack_int
ldb
,
float*
x
,
lapack_int
ldx
,
float*
rcond
,
float*
berr
,
lapack_int
n_err_bnds
,
float*
err_bnds_norm
,
float*
err_bnds_comp
,
lapack_int
nparams
,
float*
params
);
lapack_int LAPACKE_dsyrfsx
(
int
matrix_layout
,
char
uplo
,
char
equed
,
lapack_int
n
,
lapack_int
nrhs
,
const double*
a
,
lapack_int
lda
,
const double*
af
,
lapack_int
ldaf
,
const lapack_int*
ipiv
,
const double*
s
,
const double*
b
,
lapack_int
ldb
,
double*
x
,
lapack_int
ldx
,
double*
rcond
,
double*
berr
,
lapack_int
n_err_bnds
,
double*
err_bnds_norm
,
double*
err_bnds_comp
,
lapack_int
nparams
,
double*
params
);
lapack_int LAPACKE_csyrfsx
(
int
matrix_layout
,
char
uplo
,
char
equed
,
lapack_int
n
,
lapack_int
nrhs
,
const lapack_complex_float*
a
,
lapack_int
lda
,
const lapack_complex_float*
af
,
lapack_int
ldaf
,
const lapack_int*
ipiv
,
const float*
s
,
const lapack_complex_float*
b
,
lapack_int
ldb
,
lapack_complex_float*
x
,
lapack_int
ldx
,
float*
rcond
,
float*
berr
,
lapack_int
n_err_bnds
,
float*
err_bnds_norm
,
float*
err_bnds_comp
,
lapack_int
nparams
,
float*
params
);
lapack_int LAPACKE_zsyrfsx
(
int
matrix_layout
,
char
uplo
,
char
equed
,
lapack_int
n
,
lapack_int
nrhs
,
const lapack_complex_double*
a
,
lapack_int
lda
,
const lapack_complex_double*
af
,
lapack_int
ldaf
,
const lapack_int*
ipiv
,
const double*
s
,
const lapack_complex_double*
b
,
lapack_int
ldb
,
lapack_complex_double*
x
,
lapack_int
ldx
,
double*
rcond
,
double*
berr
,
lapack_int
n_err_bnds
,
double*
err_bnds_norm
,
double*
err_bnds_comp
,
lapack_int
nparams
,
double*
params
);
Include Files
  • mkl.h
Description
The routine improves the computed solution to a system of linear equations when the coefficient matrix is symmetric 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
The array
a
(size max(1,
lda
*
n
))
 contains the symmetric/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
(size max(1,
ldaf
*
n
))
 contains the triangular factor
L
 or
U
 from the Cholesky factorization
A
 =
U
T
*
U
 or
A
 =
L
*
L
T
 as computed by
ssytrf
 for real flavors or
dsytrf
 for complex flavors.
The array
b
(size max(1,
ldb
*
nrhs
) for column major layout and max(1,
ldb
*
n
) for row major layout)
 contains the matrix
B
 whose columns are the right-hand sides for the systems of equations.
lda
The leading dimension of
a
;
lda
≥
 max(1,
n
)
.
ldaf
The leading dimension of
af
;
ldaf
≥
 max(1,
n
)
.
ipiv
Array, size at least
max(1,
n
)
. Contains details of the interchanges and the block structure of
D
 as determined by
ssytrf
 for real flavors or
dsytrf
 for complex flavors.
s
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
) for column major layout and
ldb
≥
nrhs
 for row major layout
.
x
Array,
of size max(1,
ldx
*
nrhs
) for column major layout and max(1,
ldx
*
n
) for row major layout
.
The solution matrix
X
 as computed by
?sytrs
ldx
The leading dimension of the output array
x
;
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
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
[0]
 : Whether to perform iterative refinement or not. Default: 1.0 (for single precision flavors), 1.0D+0 (for double precision flavors).
=0.0
No refinement is performed and no error bounds are computed.
=1.0
Use the double-precision refinement algorithm, possibly with doubled-single computations if the compilation environment does not support double precision.
(Other values are reserved for future use.)
params
[1]
 : Maximum number of residual computations allowed for refinement.
Default
10.0
Aggressive
Set to 100.0 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.
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).
Output Parameters
x
The improved solution matrix
X
.
rcond
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
Array, size at least
max(1,
nrhs
)
. Contains the componentwise relative backward error for each solution vector
x
j
, that is, the smallest relative change in any element of
A
 or
B
 that makes
x
j
 an exact solution.
err_bnds_norm
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
The array is indexed by the type of error information as described below. There are currently up to three pieces of information returned.
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 for some appropriately scaled matrix
Z
 are:
The information for right-hand side
i
, where 1
≤
i
≤
nrhs
, and type of error
err
 is stored in:
  • Column major layout:
    err_bnds_norm
    [(
    err
     - 1)*
    nrhs
     +
    i
     - 1]
    .
  • Row major layout:
    err_bnds_norm
    [
    err
     - 1 + (
    i
     - 1)*
    n_err_bnds
    ]
err_bnds_comp
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:
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.
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 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 for some appropriately scaled matrix
Z
 are:
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.
The information for right-hand side
i
, where 1
≤
i
≤
nrhs
, and type of error
err
 is stored in:
  • Column major layout:
    err_bnds_comp
    [(
    err
     - 1)*
    nrhs
     +
    i
     - 1]
    .
  • Row major layout:
    err_bnds_comp
    [
    err
     - 1 + (
    i
     - 1)*
    n_err_bnds
    ]
params
Output parameter only if the input contains erroneous values, namely, in