Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 0.9
  • 09/09/2020
  • Public Content
Contents

Interface Consideration

One-Based and Zero-Based Indexing

The
Intel® oneAPI Math Kernel Library
 Sparse BLAS Level 2 and Level 3 routines support one-based and zero-based indexing of data arrays.
Routines with typical interfaces support zero-based indexing for the following sparse data storage formats: CSR, CSC, BSR, and COO. Routines with simplified interfaces support zero based indexing for the following sparse data storage formats: CSR, BSR, and COO. See the complete list of Sparse BLAS Level 2 and Level 3 Routines.
The one-based indexing uses the convention of starting array indices at 1. The zero-based indexing uses the convention of starting array indices at 0. For example, indices of the 5-element array
x
 can be presented in case of one-based indexing as follows:
Element index:
1 2 3 4 5
Element value:
1.0 5.0 7.0 8.0 9.0
and in case of zero-based indexing as follows:
Element index:
0 1 2 3 4
Element value:
1.0 5.0 7.0 8.0 9.0
The detailed descriptions of the one-based and zero-based variants of the sparse data storage formats are given in the "Sparse Matrix Storage Formats" in
the
Appendix
"Linear Solvers Basics"
.
Most parameters of the routines are identical for both one-based and zero-based indexing, but some of them have certain differences. The following table lists all these differences.
Parameter
One-based Indexing
Zero-based Indexing
val
Array containing non-zero elements of the matrix
A
, its length is .
pntre
[m] -
pntrb
[1]
Array containing non-zero elements of the matrix
A
, its length is .
pntre
[m—1] -
pntrb
[0]
pntrb
Array of length
m
. This array contains row indices, such that
pntrb
[
i
] -
pntrb
[1]+1
 is the first index of row
i
 in the arrays
val
 and
indx
Array of length
m
. This array contains row indices, such that
pntrb
[
i
] -
pntrb
[0]
 is the first index of row
i
 in the arrays
val
 and
indx
.
pntre
Array of length
m
. This array contains row indices, such that
pntre
[
I
] -
pntrb
[1]
 is the last index of row
i
 in the arrays
val
 and
indx
.
Array of length
m
. This array contains row indices, such that
pntre
[
i
] -
pntrb
[0]-1
 is the last index of row
i
 in the arrays
val
 and
indx
.
ia
Array of length
m
 + 1
, containing indices of elements in the array
a
, such that
ia
[
i
]
 is the index in the array
a
 of the first non-zero element from the row
i
. The value of the last element
ia
[
m
 + 1]
 is equal to the number of non-zeros plus one.
Array of length
m
+1
, containing indices of elements in the array
a
, such that
ia
[
i
]
 is the index in the array
a
 of the first non-zero element from the row
i
. The value of the last element
ia
[
m
]
 is equal to the number of non-zeros.
ldb
Specifies the leading dimension of
b
 as declared in the calling (sub)program.
Specifies the second dimension of
b
 as declared in the calling (sub)program.
ldc
Specifies the leading dimension of
c
 as declared in the calling (sub)program.
Specifies the second dimension of
c
 as declared in the calling (sub)program.

Differences Between Intel MKL and NIST* Interfaces

The
Intel® oneAPI Math Kernel Library
 Sparse BLAS Level 3 routines have the following conventional interfaces:
mkl_xyyymm(
transa
,
m
,
n
,
k
,
alpha
,
matdescra
, arg(
A
),
b
,
ldb
,
beta
,
c
,
ldc
)
, for matrix-matrix product;
mkl_xyyysm(
transa
,
m
,
n
,
alpha
,
matdescra
, arg(
A
),
b
,
ldb
,
c
,
ldc
)
, for triangular solvers with multiple right-hand sides.
Here
x
 denotes data type, and
yyy
 - sparse matrix data structure (storage format).
The analogous NIST* Sparse BLAS (NSB) library routines have the following interfaces:
xyyymm(
transa
,
m
,
n
,
k
,
alpha
,
descra
, arg(
A
),
b
,
ldb
,
beta
,
c
,
ldc
,
work
,
lwork
)
, for matrix-matrix product;
xyyysm(
transa
,
m
,
n
,
unitd
,
dv
,
alpha
,
descra
, arg(
A
),
b
,
ldb
,
beta
,
c
,
ldc
,
work
,
lwork
)
, for triangular solvers with multiple right-hand sides.
Some similar arguments are used in both libraries. The argument
transa
 indicates what operation is performed and is slightly different in the NSB library (see Table
“Parameter
transa
”
). The arguments
m
 and
k
 are the number of rows and column in the matrix
A
, respectively,
n
 is the number of columns in the matrix
C
. The arguments
alpha
 and
beta
 are scalar
alpha
 and
beta
 respectively (
beta
is not used in the
Intel® oneAPI Math Kernel Library
 triangular solvers.) The arguments
b
 and
c
 are rectangular arrays with the leading dimension
ldb
 and
ldc
, respectively.
arg(
A
)
 denotes the list of arguments that describe the sparse representation of
A
.
Parameter
transa
 
MKL interface
NSB interface
Operation
data type
char *
INTEGER
 
value
N or n
0
op(
A
) =
A
 
T or t
1
op(
A
) =
A
T
 
C or c
2
op(
A
) =
A
T
 or
op(
A
) =
A
H

Parameter matdescra

The parameter
matdescra
 describes the relevant characteristic of the matrix
A
. This manual describes
matdescra
as an array of six elements in line with the NIST* implementation. However, only the first four elements of the array are used in the current versions of the
Intel® oneAPI Math Kernel Library
 Sparse BLAS routines. Elements
matdescra
[4]
 and
matdescra
[5]
 are reserved for future use. Note that whether
matdescra
is described in your application as an array of length 6 or 4 is of no importance because the array is declared as a pointer in the
Intel® oneAPI Math Kernel Library
 routines. To learn more about declaration of the
matdescra
array, see the Sparse BLAS examples located in the
Intel® oneAPI Math Kernel Library
 installation directory:
examples/spblasc/
for C
. The table below lists elements of the parameter
matdescra
, their Fortran values, and their meanings. The parameter
matdescra
 corresponds to the argument
descra
 from NSB library.
Possible Values of the Parameter
matdescra
[
descra
 - 1]
 
MKL interface
NSB interface
Matrix characteristics
one-based indexing
zero-based indexing
data type
char *
char *
int *
 
1st element
matdescra
[1]
matdescra
[0]
descra
[0]
matrix structure
value
G
G
0
general
 
S
S
1
symmetric
(
A
 =
A
T
)
 
H
H
2
Hermitian
(
A
 = (
A
H
)
)
 
T
T
3
triangular
 
A
A
4
skew(anti)-symmetric
(
A
 = -
A
T
)
 
D
D
5
diagonal
2nd element
matdescra
[2]
matdescra
[1]
descra
[1]
upper/lower triangular indicator
value
L
L
1
lower
 
U
U
2
upper
3rd element
matdescra
[3]
matdescra
[2]
descra
[2]
main diagonal type
value
N
N
0
non-unit
 
U
U
1
unit
4th element
matdescra
[4]
matdescra
[3]
descra
[3]
type of indexing
value
F
1
one-based indexing
C
0
zero-based indexing
In some cases possible element values of the parameter matdescra depend on the values of other elements. The Table "Possible Combinations of Element Values of the Parameter
matdescra
" lists all possible combinations of element values for both multiplication routines and triangular solvers.
Possible Combinations of Element Values of the Parameter
matdescra
Routines
matdescra[0]
matdescra[1]
matdescra[2]
matdescra[3]
Multiplication Routines
G
ignored
ignored
F
 (default) or C
S or H
L
 (default)
N
 (default)
F
 (default) or C
S or H
L
 (default)
U
F
 (default) or C
S or H
U
N
 (default)
F
 (default) or C
S or H
U
U
F
 (default) or C
A
L
 (default)
ignored
F
 (default) or C
A
U
ignored
F
 (default) or C
Multiplication Routines and Triangular Solvers
T
L
U
F
 (default) or C