Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

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

?gesvx

Computes the solution to the system of linear equations with a square coefficient matrix A and multiple right-hand sides, and provides error bounds on the solution.

Syntax

lapack_int LAPACKE_sgesvx
(
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*
ferr
,
float*
berr
,
float*
rpivot
);
lapack_int LAPACKE_dgesvx
(
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*
ferr
,
double*
berr
,
double*
rpivot
);
lapack_int LAPACKE_cgesvx
(
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*
ferr
,
float*
berr
,
float*
rpivot
);
lapack_int LAPACKE_zgesvx
(
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*
ferr
,
double*
berr
,
double*
rpivot
);
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 matrix
B
 are individual right-hand sides, and the columns of
X
 are the corresponding solutions.
Error bounds on the solution and a condition estimate are also provided.
The routine
?gesvx
 performs the following steps:
  1. If
    fact
     =
    'E'
    , real 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
    . If the reciprocal of the condition number is less than machine precision,
    info
     =
    n
     + 1
     is returned as a warning, but the routine still goes on to solve for
    X
     and compute error bounds as described below.
  4. The system of equations is solved for
    X
     using the factored form of
    A
    .
  5. Iterative refinement is applied to improve the computed solution matrix and calculate error bounds and backward error estimates for it.
  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
.
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, then 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
 (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
The array
a
(size max(1,
lda
*
n
))
 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
.
af
The array
af
af
(size max(1,
ldaf
*
n
))
 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
.
b
The array
b
b
of 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
)
.
ldb
The leading dimension of
b
;
ldb
≥
 max(1,
n
) for column major layout and
ldb
≥
nrhs
 for row major layout
.
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.
ldx
The leading dimension of the output array
x
;
ldx
≥
 max(1,
n
) for column major layout and
ldx
≥
nrhs
 for row major layout
.
Output Parameters
x
Array, size
max(1,
ldx
*
nrhs
) for column major layout and max(1,
ldx
*
n
) for row major layout
.
If
info
 = 0
 or
info
 =
n
+1
, the array
x
 contains the solution matrix
X
 to the
original
 system of equations. Note that
A
 and
B
 are modified on exit if
equed
≠
'N'
, and the solution to the equilibrated system is:
diag
(
C
)
-1
*
X
, if
trans
 =
'N'
 and
equed
 =
'C'
 or
'B'
;
diag
(
R
)
-1
*
X
, if
trans
 =
'T'
 or
'C'
 and
equed
 =
'R'
 or
'B'
. The second dimension of
x
 must be at least
max(1,
nrhs
)
.
a
Array
a
 is not modified on exit if
fact
 =
'F'
 or
'N'
, or if
fact
 =
'E'
 and
equed
 =
'N'
. If
equed
≠
'N'
,
A
 is scaled on exit as follows:
equed
 =
'R'
:
A
 =
diag
(
R
)*
A
equed
 =
'C'
:
A
 =
A
*