Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

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

pardiso

Calculates the solution of a set of sparse linear equations with single or multiple right-hand sides.

Syntax

void
pardiso
(
_MKL_DSS_HANDLE_t
pt
,
const
MKL_INT
*
maxfct
,
const
MKL_INT
*
mnum
,
const
MKL_INT
*
mtype
,
const
MKL_INT
*
phase
,
const
MKL_INT
*
n
,
const
void
*
a
,
const
MKL_INT
*
ia
,
const
MKL_INT
*
ja
,
MKL_INT
*
perm
,
const
MKL_INT
*
nrhs
,
MKL_INT
*
iparm
,
const
MKL_INT
*
msglvl
,
void
*
b
,
void
*
x
,
MKL_INT
*
error
);
Include Files
  • mkl.h
Description
The routine
pardiso
 calculates the solution of a set of sparse linear equations 
A*X = B
with single or multiple right-hand sides, using a parallel
LU
,
LDL
, or
LL
T
 factorization, where
A
 is an
n
-by-
n
 matrix, and
X
 and
B
 are
n
-by-
nrhs
 vectors or matrices.
This routine supports the Progress Routine feature. See Progress Function for details. The case of
iparm
[23]
=10 does not support this feature.
Optimization Notice
Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.
Notice revision #20110804
This notice covers the following instruction sets: SSE2, SSE4.2, AVX2, AVX-512.
Input Parameters
pt
Array with size of 64.
Handle to internal data structure. The entries must be set to zero prior to the first call to
pardiso
. Unique for factorization.
After the first call to
pardiso
 do not directly modify
pt
, as that could cause a serious memory leak.
Use the pardiso_handle_store or
pardiso_handle_store_64
 routine to store the content of
pt
 to a file. Restore the contents of
pt
 from the file using pardiso_handle_restore or
pardiso_handle_restore_64
. Use
pardiso_handle_store
 and
pardiso_handle_restore
 with
pardiso
, and
pardiso_handle_store_64
 and
pardiso_handle_restore_64
 with
pardiso_64
.
maxfct
Maximum number of factors with identical sparsity structure that must be kept in memory at the same time. In most applications this value is equal to 1. It is possible to store several different factorizations with the same nonzero structure at the same time in the internal data structure management of the solver.
pardiso
 can process several matrices with an identical matrix sparsity pattern and it can store the factors of these matrices at the same time. Matrices with a different sparsity structure can be kept in memory with different memory address pointers
pt
.
mnum
Indicates the actual matrix for the solution phase. With this scalar you can define which matrix to factorize. The value must be:
1
≤
mnum
≤
maxfct
.
In most applications this value is 1.
mtype
Defines the matrix type, which influences the pivoting method. The
Intel® oneAPI Math Kernel Library
 PARDISO solver supports the following matrices:
1
real and structurally symmetric
2
real and symmetric positive definite
-2
real and symmetric indefinite
3
complex and structurally symmetric
4
complex and Hermitian positive definite
-4
complex and Hermitian indefinite
6
complex and symmetric
11
real and nonsymmetric
13
complex and nonsymmetric
phase
Controls the execution of the solver. Usually it is a two- or three-digit integer. The first digit indicates the starting phase of execution and the second digit indicates the ending phase.
Intel® oneAPI Math Kernel Library
 PARDISO has the following phases of execution:
  • Phase 1: Fill-reduction analysis and symbolic factorization
  • Phase 2: Numerical factorization
  • Phase 3: Forward and Backward solve including optional iterative refinement
    This phase can be divided into two or three separate substitutions: forward, backward, and diagonal (see Separate Forward and Backward Substitution).
  • Memory release phase (
    phase
    = 0 or
    phase
    = -1)
If a previous call to the routine has computed information from previous phases, execution may start at any phase. The
phase
 parameter can have the following values:
phase
Solver Execution Steps
11
Analysis
12
Analysis, numerical factorization
13
Analysis, numerical factorization, solve, iterative refinement
22
Numerical factorization
23
Numerical factorization, solve, iterative refinement
33
Solve, iterative refinement
331
like
phase
=33, but only forward substitution
332
like
phase
=33, but only diagonal substitution (if available)
333
like
phase
=33, but only backward substitution
0
Release internal memory for
L
 and
U
 matrix number
mnum
-1
Release all internal memory for all matrices
If
iparm
[35]
= 0
, phases 331, 332, and 333 perform this decomposition:
If
iparm
[35]
= 2
, phases 331, 332, and 333 perform a different decomposition:
You can supply a custom implementation for phase 332 instead of calling
pardiso
. For example, it can be implemented with dense LAPACK functionality. Custom implementation also allows you to substitute the matrix
S
 with your own.
For very large Schur complement matrices use LAPACK functionality to compute the Schur complement vector instead of the
Intel® oneAPI Math Kernel Library
 PARDISO phase 332 implementation.
n
Number of equations in the sparse linear systems of equations
A
*
X
 =
B
. Constraint:
n
 > 0
.
a
Array. Contains the non-zero elements of the coefficient matrix
A
 corresponding to the indices in
ja
. The coefficient matrix can be either real or complex. The matrix must be stored in the three-array variant of the compressed sparse row (CSR3) or in the three-array variant of the block compressed sparse row (BSR3) format, and the matrix must be stored with increasing values of
ja
 for each row.
For CSR3 format, the size of
a
 is the same as that of
ja
. Refer to the
values
 array description in Three Array Variation of CSR Format for more details.
For BSR3 format the size of
a
 is the size of
ja
 multiplied by the square of the block size. Refer to the
values
 array description in Three Array Variation of BSR Format for more details.
If you set
iparm
[36]
to a negative value,
Intel® oneAPI Math Kernel Library
 PARDISO converts the data from CSR3 format to an internal variable BSR (VBSR) format. SeeSparse Data Storage.
ia
Array, size
(
n
+1)
.
For CSR3 format,
ia
[
i
]
 (
i
<
n
) points to the first column index of row
i
 in the array
ja
. That is,
ia
[
i
]
 gives the index of the element in array
a
 that contains the first non-zero element from row
i
 of
A
. The last element
ia
[
n
]
 is taken to be equal to the number of non-zero elements in
A
, plus one. Refer to
rowIndex
 array description in Three Array Variation of CSR Format for more details.
For BSR3 format,
ia
[
i
]
 (
i
<
n
) points to the first column index of row
i
 in the array
ja
. That is,
ia
[
i
]
 gives the index of the element in array
a
 that contains the first non-zero block from row
i
 of
A
. The last element
ia
[
n
]
 is taken to be equal to the number of non-zero blcoks in
A
, plus one. Refer to
rowIndex
 array description in Three Array Variation of BSR Format for more details.
The array
ia
 is accessed in all phases of the solution process.
Indexing of
ia
 is one-based by default, but it can be changed to zero-based by setting the appropriate value to the parameter
iparm
[34]
.
ja
For CSR3 format, array
ja
 contains column indices of the sparse matrix
A
. It is important that the indices are in increasing order per row. For structurally symmetric matrices it is assumed that all diagonal elements are stored (even if they are zeros) in the list of non-zero elements in
a
 and
ja
. For symmetric matrices, the solver needs only the upper triangular part of the system as is shown for
columns
 array in Three Array Variation of CSR Format.
For BSR3 format, array
ja
 contains column indices of the sparse matrix
A
. It is important that the indices are in increasing order per row. For structurally symmetric matrices it is assumed that all diagonal blocks are stored (even if they are zeros) in the list of non-zero blocks in
a
 and
ja
. For symmetric matrices, the solver needs only the upper triangular part of the system as is shown for
columns
 array in Three Array Variation of BSR Format.
The array
ja
 is accessed in all phases of the solution process.
Indexing of
ja
 is one-based by default, but it can be changed to zero-based by setting the appropriate value to the parameter
iparm
[34]
.
perm
Array, size (
n
). Depending on the value of
iparm
[4]
 and
iparm
[30]
, holds the permutation vector of size
n
, specifies elements used for computing a partial solution, or specifies differing values of the input matrices for low rank update.
  • If
    iparm
    [4]
     = 1,
    iparm
    [30]
     = 0, and
    iparm
    [35]
     = 0
    ,
    perm
     specifies the fill-in reducing ordering to the solver. Let
    A
     be the original matrix and
    C
     =
    P
    *
    A
    *
    P
    T
     be the permuted matrix. Row (column)
    i
     of
    C
     is the
    perm
    [
    i
    ]
     row (column) of
    A
    . The array
    perm
     is also used to return the permutation vector calculated during fill-in reducing ordering stage.
    Be aware that setting
    iparm
    [4]
     = 1 prevents use of a parallel algorithm for the solve step.
  • If
    iparm
    [4]
     = 2,
    iparm
    [30]
     = 0, and
    iparm
    [35]
     = 0, the permutation vector computed in phase 11 is returned in the
    perm
     array.
  • If
    iparm
    [4]
     = 0,
    iparm
    [30]
     > 0, and
    iparm
    [35]
     = 0,
    perm
     specifies elements of the right-hand side to use or of the solution to compute for a partial solution.
  • If
    iparm
    [4]
     = 0,
    iparm
    [30]
     = 0, and
    iparm
    [35]
     > 0,
    perm
     specifies elements for a Schur complement.
  • If
    iparm
    [38]
     = 1,
    perm
     specifies values that differ in
    A
     for low rank update (see Low Rank Update). The size of the array must be at least 2*
    ndiff
     + 1, where
    ndiff
     is the number of values of
    A
     that are different. The values of
    perm
     should be:
    perm
     = {
    ndiff
    ,
    row_index1
    ,
    column_index1
    ,
    row_index2
    ,
    column_index2
    , ....,
    row_index_ndiff
    ,
    column_index_ndiff
    }
    where
    row_index_m
     and
    column_index_m
     are the row and column indices of the
    m
    -th differing non-zero value in matrix
    A
    . The row and column index pairs can be in any order, but must use zero-based indexing regardless of the value of
    iparm
    [34]
    .
See
iparm
[4]
,
iparm
[30]
, and
iparm
[38]
 for more details.
Indexing of
perm
 is one-based by default, but unless
iparm
[38]
 = 1 it can be changed to zero-based by setting the appropriate value to the parameter
iparm
[34]
.
nrhs
Number of right-hand sides that need to be solved for.
iparm
Array, size (
64
). This array is used to pass various parameters to
Intel® oneAPI Math Kernel Library
 PARDISO and to return some useful information after execution of the solver.
See pardiso iparm Parameter for more details about the
iparm
 parameters.
msglvl
Message level information. If
msglvl
 = 0
 then
pardiso
 generates no output, if
msglvl
 = 1
 the solver prints statistical information to the screen.
b
Array, size (
n
*
nrhs
). On entry, contains the right-hand side vector/matrix
B
, which is placed in memory contiguously. The
b
[
+
k
*
nrhs
]
 element must hold the
i
-th component of
k
-th right-hand side vector. Note that
b
 is only accessed in the solution phase.
Output Parameters
pt
Handle to internal data structure.
perm
See the Input Parameter description of the
perm
 array.
iparm
On output, some
iparm
 values report information such as the numbers of non-zero elements in the factors.
See pardiso iparm Parameter for more details about the
iparm
 parameters.
b
On output, the array is replaced with the solution if
iparm
[5]
 = 1.
x
Array, size (
n
*
nrhs
). If
iparm
[5]
=0 it contains solution vector/matrix
X
, which is placed contiguously in memory. The
x
[
i
 +
k
*
n
]
 element must hold the
i
-th component of the
k
-th solution vector. Note that
x
 is only accessed in the solution phase.
error
The error indicator according to the below table:
error
Information
0
no error
-1
input inconsistent
-2
not enough memory
-3
reordering problem
-4
Zero pivot, numerical factorization or iterative refinement problem. If the error appears during the solution phase, try to change the pivoting perturbation (
iparm
[9]
) and also increase the number of iterative refinement steps. If it does not help, consider changing the scaling, matching and pivoting options (
iparm
[10]
,
iparm
[12]
,
iparm
[20]
)
-5