Interface Consideration
One-Based and Zero-Based Indexing
The Sparse BLAS Level 2 and Level 3 routines support one-based and zero-based indexing of data arrays.
Intel® oneAPI Math Kernel Library
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]+1i in the arrays
val and
indx | Array of length
m . This array contains row
indices, such that
pntrb [i ] -
pntrb [0]i in the arrays
val and
indx .
|
pntre | Array of length
m . This array contains row
indices, such that
pntre [I ] -
pntrb [1]i in the arrays
val and
indx .
| Array of length
m . This array contains row
indices, such that
pntre [i ] -
pntrb [0]-1i in the arrays
val and
indx .
|
ia | Array of length
m + 1a , such that
ia [i ]a
of the first non-zero element from the row
i . The value of the last element
ia [ is equal to
the number of non-zeros plus one.
m + 1] | Array of length
m +1a , such that
ia [i ]a
of the first non-zero element from the row
i . The value of the last element
ia [ is equal to the
number of non-zeros.
m ] |
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 Sparse BLAS Level 3 routines have the following conventional interfaces:
Intel® oneAPI Math Kernel Library
mkl_xyyymm(
, for
matrix-matrix product;
transa
,
m
,
n
,
k
,
alpha
,
matdescra
,
arg(A
),
b
,
ldb
,
beta
,
c
,
ldc
)mkl_xyyysm(
, for triangular
solvers with multiple right-hand sides.
transa
,
m
,
n
,
alpha
,
matdescra
,
arg(A
),
b
,
ldb
,
c
,
ldc
)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(
, for
matrix-matrix product;
transa
,
m
,
n
,
k
,
alpha
,
descra
,
arg(A
),
b
,
ldb
,
beta
,
c
,
ldc
,
work
,
lwork
)xyyysm(
, for
triangular solvers with multiple right-hand sides.
transa
,
m
,
n
,
unitd
,
dv
,
alpha
,
descra
,
arg(A
),
b
,
ldb
,
beta
,
c
,
ldc
,
work
,
lwork
)Some similar arguments are used in both libraries.
The argument
triangular solvers.) The arguments
transa
indicates what operation is performed and is slightly different in the NSB
library (see
Table
“Parameter
). The
arguments
transa
”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
b
and
c
are
rectangular arrays with the leading dimension
ldb
and
ldc
,
respectively.
arg(
denotes the list of
arguments that describe the sparse representation of
A
)A
.
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( or
A ) =
A T op( A ) =
A H |
Parameter matdescra
The parameter
Sparse BLAS routines. Elements and
are
reserved for future use. Note that whether
routines. To learn more about declaration of the installation directory:. The table below lists
elements of 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
matdescra
[4]matdescra
[5]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
matdescra
array, see the Sparse BLAS examples located in the Intel® oneAPI Math Kernel Library
examples/spblasc/
for C
matdescra
,
their Fortran values, and their meanings. The parameter
matdescra
corresponds to the argument
descra
from
NSB library.
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.
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
|
T
| L
| N
| F (default) or C
| |
T
| U
| U
| F (default) or C
| |
T
| U
| N
| F (default) or C
| |
D
| ignored
| N (default)
| F (default) or C
| |
D
| ignored
| U
| F (default) or C
|
For a matrix in the skyline format with the main
diagonal declared to be a unit, diagonal elements must be stored in the sparse
representation even if they are zero. In all other formats, diagonal elements
can be stored (if needed) in the sparse representation if they are not zero.
Operations with Partial Matrices
One of the distinctive feature of the Sparse BLAS routines is a possibility to perform operations only on partial matrices composed of certain parts (triangles and the main diagonal) of the input sparse matrix. It can be done by setting properly first three elements of the parameter
Intel® oneAPI Math Kernel Library
matdescra
.
An arbitrary sparse matrix
A
can be
decomposed as
A = L + D + U
where
L
is the
strict lower triangle of
A
,
U
is the
strict upper triangle of
A
,
D
is the main
diagonal.
Table
"Output Matrices for Multiplication
Routines"
shows correspondence between the output matrices and
values of the parameter
matdescra
for the sparse matrix
A
for
multiplication routines.