Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

Contents

p?heev

Computes all eigenvalues and, optionally, eigenvectors of a complex Hermitian matrix.

Syntax

void
pcheev
(
char
*jobz
,
char
*uplo
,
MKL_INT
*n
,
MKL_Complex8
*a
,
MKL_INT
*ia
,
MKL_INT
*ja
,
MKL_INT
*desca
,
float
*w
,
MKL_Complex8
*z
,
MKL_INT
*iz
,
MKL_INT
*jz
,
MKL_INT
*descz
,
MKL_Complex8
*work
,
MKL_INT
*lwork
,
float
*rwork
,
MKL_INT
*lrwork
,
MKL_INT
*info
);
void
pzheev
(
char
*jobz
,
char
*uplo
,
MKL_INT
*n
,
MKL_Complex16
*a
,
MKL_INT
*ia
,
MKL_INT
*ja
,
MKL_INT
*desca
,
double
*w
,
MKL_Complex16
*z
,
MKL_INT
*iz
,
MKL_INT
*jz
,
MKL_INT
*descz
,
MKL_Complex16
*work
,
MKL_INT
*lwork
,
double
*rwork
,
MKL_INT
*lrwork
,
MKL_INT
*info
);
Include Files
  • mkl_scalapack.h
Description
The
p?heev
function
computes all eigenvalues and, optionally, eigenvectors of a complex Hermitian matrix
A
 by calling the recommended sequence of ScaLAPACK
functions
. The
function
assumes a homogeneous system and makes spot checks of the consistency of the eigenvalues across the different processes. A heterogeneous system may return incorrect results without any error messages.
Input Parameters
np
 = the number of rows local to a given process.
nq
 = the number of columns local to a given process.
jobz
(global) Must be
'N'
 or
'V'
.
Specifies if it is necessary to compute the eigenvectors:
If
jobz
 =
'N'
, then only eigenvalues are computed.
If
jobz
 =
'V'
, then eigenvalues and eigenvectors are computed.
uplo
(global) Must be
'U'
 or
'L'
.
Specifies whether the upper or lower triangular part of the Hermitian matrix
A
 is stored:
If
uplo
 =
'U'
,
a
 stores the upper triangular part of
A
.
If
uplo
 =
'L'
,
a
 stores the lower triangular part of
A
.
n
(global) The number of rows and columns of the matrix
A
(
n
≥
 0)
.
a
(local).
Block cyclic array of global size
n
*
n
 and local size
lld_a
*
LOC
c
(
ja
+
n
-1)
. On entry, the Hermitian matrix
A
.
If
uplo
 =
'U'
, only the upper triangular part of
A
 is used to define the elements of the Hermitian matrix.
If
uplo
 =
'L'
, only the lower triangular part of
A
 is used to define the elements of the Hermitian matrix.
ia
,
ja
(global) The row and column indices in the global matrix
A
 indicating the first row and the first column of the submatrix
A
, respectively.
desca
(global and local) array of size
dlen_
. The array descriptor for the distributed matrix
A
. If
desca
[
ctxt_
 - 1]
 is incorrect,
p?heev
 cannot guarantee correct error reporting.
iz
,
jz
(global) The row and column indices in the global matrix
Z
 indicating the first row and the first column of the submatrix
Z
, respectively.
descz
(global and local) array of size
dlen_
. The array descriptor for the distributed matrix
Z
.
descz
[
ctxt_
 - 1]
 must equal
desca
[
ctxt_
 - 1]
.
work
(local).
Array of size
lwork
.
lwork
(local) The size of the array
work
.
If only eigenvalues are requested (
jobz
 =
'N'
):
lwork
≥
max
(
nb
*(
np
0 + 1), 3) + 3*
n
If eigenvectors are requested (
jobz
 =
'V'
), then the amount of workspace required:
lwork
≥
 (
np
0+
nq
0+
nb
)*
nb
 + 3*
n
 +
n
2
with
nb
 =
desca
[
mb
_ - 1] =
desca
[
nb
_ - 1] =
nb
 =
descz
[
mb
_ - 1] =
descz
[
nb
_ - 1]
np
0 =
numroc
(
nn
,
nb
, 0, 0,
NPROW
)
.
nq
0 =
numroc
( max(
n
,
nb
, 2 ),
nb
, 0, 0,
NPCOL
)
.
If
lwork
 = -1
, then
lwork
 is global input and a workspace query is assumed; the
function
only calculates the size required for optimal performance for all work arrays. The required workspace is returned as the first element of the corresponding work arrays, and no error message is issued by
pxerbla
.
(local).
Workspace array of size
lrwork
.
lrwork
(local) The size of the array
rwork
.
See below for definitions of variables used to define
lrwork
.
If no eigenvectors are requested (
jobz
 =
'N'
), then
lrwork
≥
 2*
n
.
If eigenvectors are requested (
jobz
 =
'V'
), then
lrwork
≥
 2*
n
 + 2*
n
-2
.
If
lrwork
 = -1
, then
lrwork
 is global input and a workspace query is assumed; the
function
only calculates the minimum size required for the
rwork
 array. The required workspace is returned as the first element of
rwork
, and no error message is issued by
pxerbla
.
Output Parameters
a
On exit, the lower triangle (if
uplo
 =
'L'
), or the upper triangle (if
uplo
 =
'U'
) of
A
, including the diagonal, is overwritten.
w
(global).
Array of size
n
. The first
m
 elements contain the selected eigenvalues in ascending order.
z
(local).
Array, global size
n
*
n
, local size
lld_z
*
LOCc
(
jz
+
n
-1)
.
If
jobz
 =
'V'
, then on normal exit the first
m
 columns of
z
 contain the orthonormal eigenvectors of the matrix corresponding to the selected eigenvalues. If an eigenvector fails to converge, then that column of
z
 contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in
ifail
.
If
jobz
 =
'N'
, then
z
 is not referenced.
work
[0]
On exit, returns adequate workspace to allow optimal performance.
If
jobz
 =
'N'
, then
work
[0]
 = minimal workspace only for eigenvalues.
If
jobz
 =
'V'
, then
work
[0]
 = minimal workspace required to generate all the eigenvectors.
rwork
[0]
(local)
On output,
rwork
[0]
 returns workspace required to guarantee completion.
info
(global)
If
info
 = 0
, the execution is successful.
If
info
 < 0
:
If the
i
-th argument is an array and the
j
-entry had an illegal value, then
info
 = -(
i
*100+
j
)
. If the
i
-th argument is a scalar and had an illegal value, then
info
 = -
i
.
If
info
>
 0
:
If
info
 = 1 through
n
, the
i
-th eigenvalue did not converge in
?steqr2
 after a total of 30*
n
 iterations.
If
info
 =
n
+1, then
p?heev
 detected heterogeneity, and the accuracy of the results cannot be guaranteed.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.