Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

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

?gesvxx

Uses extra precise iterative refinement to compute the solution to the system of linear equations with a square coefficient matrix A and multiple right-hand sides

Syntax

lapack_int LAPACKE_sgesvxx
(
int
matrix_layout
,
char
fact
,
char
trans
,
lapack_int
n
,
lapack_int
nrhs
,
float*
a
,
lapack_int
lda
,
float*
af
,
lapack_int
ldaf
,
lapack_int*
ipiv
,
char*
equed
,
float*
r
,
float*
c
,
float*
b
,
lapack_int
ldb
,
float*
x
,
lapack_int
ldx
,
float*
rcond
,
float*
rpvgrw
,
float*
berr
,
lapack_int
n_err_bnds
,
float*
err_bnds_norm
,
float*
err_bnds_comp
,
lapack_int
nparams
,
const float*
params
);
lapack_int LAPACKE_dgesvxx
(
int
matrix_layout
,
char
fact
,
char
trans
,
lapack_int
n
,
lapack_int
nrhs
,
double*
a
,
lapack_int
lda
,
double*
af
,
lapack_int
ldaf
,
lapack_int*
ipiv
,
char*
equed
,
double*
r
,
double*
c
,
double*
b
,
lapack_int
ldb
,
double*
x
,
lapack_int
ldx
,
double*
rcond
,
double*
rpvgrw
,
double*
berr
,
lapack_int
n_err_bnds
,
double*
err_bnds_norm
,
double*
err_bnds_comp
,
lapack_int
nparams
,
const double*
params
);
lapack_int LAPACKE_cgesvxx
(
int
matrix_layout
,
char
fact
,
char
trans
,
lapack_int
n
,
lapack_int
nrhs
,
lapack_complex_float*
a
,
lapack_int
lda
,
lapack_complex_float*
af
,
lapack_int
ldaf
,
lapack_int*
ipiv
,
char*
equed
,
float*
r
,
float*
c
,
lapack_complex_float*
b
,
lapack_int
ldb
,
lapack_complex_float*
x
,
lapack_int
ldx
,
float*
rcond
,
float*
rpvgrw
,
float*
berr
,
lapack_int
n_err_bnds
,
float*
err_bnds_norm
,
float*
err_bnds_comp
,
lapack_int
nparams
,
const float*
params
);
lapack_int LAPACKE_zgesvxx
(
int
matrix_layout
,
char
fact
,
char
trans
,
lapack_int
n
,
lapack_int
nrhs
,
lapack_complex_double*
a
,
lapack_int
lda
,
lapack_complex_double*
af
,
lapack_int
ldaf
,
lapack_int*
ipiv
,
char*
equed
,
double*
r
,
double*
c
,
lapack_complex_double*
b
,
lapack_int
ldb
,
lapack_complex_double*
x
,
lapack_int
ldx
,
double*
rcond
,
double*
rpvgrw
,
double*
berr
,
lapack_int
n_err_bnds
,
double*
err_bnds_norm
,
double*
err_bnds_comp
,
lapack_int
nparams
,
const double*
params
);
Include Files
  • mkl.h
Description
The routine uses the LU factorization to compute the solution to a real or complex system of linear equations
A*X
 =
B
, where
A
 is an
n
-by-
n
 matrix, the columns of the matrix
B
 are individual right-hand sides, and the columns of
X
 are the corresponding solutions.
Both normwise and maximum componentwise error bounds are also provided on request. The routine returns a solution with a small guaranteed error (
O(eps)
, where
eps
 is the working machine precision) unless the matrix is very ill-conditioned, in which case a warning is returned. Relevant condition numbers are also calculated and returned.
The routine accepts user-provided factorizations and equilibration factors; see definitions of the
fact
 and
equed
 options. Solving with refinement and using a factorization from a previous call of the routine also produces a solution with
O(eps)
 errors or warnings but that may not be true for general user-provided factorizations and equilibration factors if they differ from what the routine would itself produce.
The routine
?gesvxx
 performs the following steps:
  1. If
    fact
     =
    'E'
    , scaling factors
    r
     and
    c
     are computed to equilibrate the system:
    trans
     =
    'N'
    :
    diag
    (
    r
    )*
    A
    *
    diag
    (
    c
    )*inv(
    diag
    (
    c
    ))*
    X
     =
    diag
    (
    r
    )*
    B
    trans
     =
    'T'
    :
    (
    diag
    (
    r
    )*
    A
    *
    diag
    (
    c
    ))
    T
    *inv(
    diag
    (
    r
    ))*
    X
     =
    diag
    (
    c
    )*
    B
    trans
     =
    'C'
    :
    (
    diag
    (
    r
    )*
    A
    *
    diag
    (
    c
    ))
    H
    *inv(
    diag
    (
    r
    ))*
    X
     =
    diag
    (
    c
    )*
    B
    Whether or not the system will be equilibrated depends on the scaling of the matrix
    A
    , but if equilibration is used,
    A
     is overwritten by
    diag
    (
    r
    )*
    A
    *
    diag
    (
    c
    )
     and
    B
     by
    diag
    (
    r
    )*
    B
     (if
    trans
    =
    'N'
    )
     or
    diag
    (
    c
    )*
    B
     (if
    trans
     =
    'T'
     or
    'C'
    ).
  2. If
    fact
     =
    'N'
     or
    'E'
    , the
    LU
     decomposition is used to factor the matrix
    A
     (after equilibration if
    fact
     =
    'E'
    ) as
    A
     =
    P*L*U
    , where
    P
     is a permutation matrix,
    L
     is a unit lower triangular matrix, and
    U
     is upper triangular.
  3. If some
    U
    i
    ,
    i
    = 0, so that
    U
     is exactly singular, then the routine returns with
    info
     =
    i
    . Otherwise, the factored form of
    A
     is used to estimate the condition number of the matrix
    A
     (see the
    rcond
     parameter). If the reciprocal of the condition number is less than machine precision, the routine still goes on to solve for
    X
     and compute error bounds.
  4. The system of equations is solved for
    X
     using the factored form of
    A
    .
  5. By default, unless is set to zero, the routine applies iterative refinement to improve the computed solution matrix and calculate error bounds. Refinement calculates the residual to at least twice the working precision.
  6. If equilibration was used, the matrix
    X
     is premultiplied by
    diag
    (
    c
    )
     (if
    trans
     =
    'N'
    ) or
    diag
    (
    r
    )
     (if
    trans
     =
    'T'
     or
    'C'
    ) so that it solves the original system before equilibration.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
fact
Must be
'F'
,
'N'
, or
'E'
.
Specifies whether or not the factored form of the matrix
A
 is supplied on entry, and if not, whether the matrix
A
 should be equilibrated before it is factored.
If
fact
 =
'F'
, on entry,
af
 and
ipiv
 contain the factored form of
A
. If
equed
 is not
'N'
, the matrix
A
 has been equilibrated with scaling factors given by
r
 and
c
. Parameters
a
,
af
, and
ipiv
 are not modified.
If
fact
 =
'N'
, the matrix
A
 will be copied to
af
 and factored.
If
fact
 =
'E'
, the matrix
A
 will be equilibrated, if necessary, copied to
af
 and factored.
trans
Must be
'N'
,
'T'
, or
'C'
.
Specifies the form of the system of equations:
If
trans
 =
'N'
, the system has the form
A
*
X
 =
B
 (No transpose).
If
trans
 =
'T'
, the system has the form
A
T
*
X
 =
B
 (Transpose).
If
trans
 =
'C'
, the system has the form
A
H
*
X
 =
B
 (Conjugate Transpose = Transpose for real flavors, Conjugate Transpose for complex flavors).
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
Arrays:
a
(size max(
lda
*
n
))
,
af
(size max(
ldaf
*
n
))
,
b
(size max(1,
ldb
*
nrhs
) for column major layout and max(1,
ldb
*
n
) for row major layout)
.
The array
a
 contains the matrix
A
. If
fact
 =
'F'
 and
equed
 is not
'N'
, then
A
 must have been equilibrated by the scaling factors in
r
 and/or
c
. .
The array
af
 is an input argument if
fact
 =
'F'
. It contains the factored form of the matrix
A
, that is, the factors
L
 and
U
 from the factorization
A
 =
P*L*U
 as computed by
?getrf
. If
equed
 is not
'N'
, then
af
 is the factored form of the equilibrated matrix
A
.
The array
b
 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
)
. The array
ipiv
 is an input argument if
fact
 =
'F'
. It 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
-1]
.
equed
Must be
'N'
,
'R'
,
'C'
, or
'B'
.
equed
 is an input argument if
fact
 =
'F'
. It specifies the form of equilibration that was done:
If
equed
 =
'N'
, no equilibration was done (always true if
fact
 =
'N'
).
If
equed
 =
'R'
, row equilibration was done, that is,
A
 has been premultiplied by
diag
(
r
).
If
equed
 =
'C'
, column equilibration was done, that is,
A
 has been postmultiplied by
diag
(
c
).
If
equed
 =
'B'
, both row and column equilibration was done, that is,
A
 has been replaced by
diag
(
r
)*
A
*
diag
(
c
)
.
r
,
c
Arrays:
r
 (size
n
),
c
 (size
n
)
. The array
r
 contains the row scale factors for
A
, and the array
c
 contains the column scale factors for
A
. These arrays are input arguments if
fact
 =
'F'
 only; otherwise they are output arguments.
If
equed
 =
'R'
 or
'B'
,
A
 is multiplied on the left by
diag
(
r
); if
equed
 =
'N'
 or
'C'
,
r
 is not accessed.
If
fact
 =
'F'
 and
equed
 =
'R'
or
'B'
, each element of
r
 must be positive.
If
equed
 =
'C'
 or
'B'
,
A
 is multiplied on the right by
diag
(
c
); if
equed
 =
'N'
 or
'R'
,
c
 is not accessed.
If
fact
 =
'F'
 and
equed
 =
'C'
 or
'B'
, each element of
c
 must be positive.
Each element of
r
 or
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.
ldb
The leading dimension of the array
b
;
ldb
≥
 max(1,
n
) for column major layout and
ldb
≥
nrhs
 for row major layout
.
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 max(1,
nparams
). Specifies algorithm parameters. If an entry is less than 0.0, that entry is 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.