Parallel Engineering and Scientific Subroutine Library for AIX Version 2 Release 3: Guide and Reference
These subroutines compute selected eigenvalues and, optionally, the
eigenvectors of a real symmetric or complex Hermitian matrix A,
where A represents the global real symmetric or complex Hermitian
submatrix Aia:ia+n-1,
ja:ja+n-1. Eigenvalues and
eigenvectors can be selected by specifying a range of values or a range of
indices for the eigenvalues.
If n = 0, no computation is performed and the subroutine
returns after doing some parameter checking.
See references [13], [24], [25], and [26].
Table 102. Data Types
| vl, vu, abstol, orfac, w,
rwork, gap
| A, Z, work
| iwork, ifail, iclustr
| Subroutine
|
| Long-precision real
| Long-precision real
| Integer
| PDSYEVX
|
| Long-precision real
| Long-precision complex
| Integer
| PZHEEVX
|
| Fortran
| CALL PDSYEVX (jobz, range, uplo, n,
a, ia, ja, desc_a, vl,
vu, il, iu, abstol, m,
nz, w, orfac, z, iz, jz,
desc_z, work, lwork, iwork,
liwork, ifail, iclustr, gap,
info)
|
| CALL PZHEEVX (jobz, range, uplo, n,
a, ia, ja, desc_a, vl,
vu, il, iu, abstol, m,
nz, w, orfac, z, iz, jz,
desc_z, work, lwork, rwork,
lrwork, iwork, liwork, ifail,
iclustr, gap, info)
|
| C and C++
| pdsyevx (jobz, range, uplo, n,
a, ia, ja, desc_a, vl,
vu, il, iu, abstol, m,
nz, w, orfac, z, iz, jz,
desc_z, work, lwork, iwork,
liwork, ifail, iclustr, gap,
info);
|
| pzheevx (jobz, range, uplo, n,
a, ia, ja, desc_a, vl,
vu, il, iu, abstol, m,
nz, w, orfac, z, iz, jz,
desc_z, work, lwork, rwork,
lrwork, iwork, liwork, ifail,
iclustr, gap, info);
|
- jobz
- indicates the type of computation to be performed, where:
If jobz = 'N', eigenvalues only are
computed.
If jobz = 'V', eigenvalues and eigenvectors are
computed.
Scope: global
Specified as: a single character;
jobz = 'N' or 'V'.
- range
- indicates which eigenvalues to compute, where:
If range = 'A', all eigenvalues are to be
found.
If range = 'V', all eigenvalues in the interval
[vl, vu] are to be found.
If range = 'I', the il-th through
iu-th eigenvalues are to be found.
Scope: global
Specified as: a single character;
range = 'A', 'V', or 'I'.
- uplo
- indicates whether the upper or lower triangular part of the global
submatrix A is referenced, where:
If uplo = 'U', the upper triangular part is
referenced.
If uplo = 'L', the lower triangular part is
referenced.
Scope: global
Specified as: a single character;
uplo = 'U' or 'L'.
- n
- is the order of submatrix A used in the computation.
Scope: global
Specified as: a fullword integer;
n >= 0.
- a
- is the local part of the global real symmetric or complex Hermitian matrix
A. This identifies the first element of the local
array A. This subroutine computes the location of the first
element of the local subarray used, based on ia, ja,
desc_a, p, q, myrow, and
mycol; therefore, the leading
LOCp(ia+n-1) by LOCq(ja+n-1)
part of the local array A must contain the local pieces of the
leading ia+n-1 by ja+n-1 part
of the global matrix, and:
- If uplo = 'U', the leading
n × n upper triangular part of the global
submatrix Aia:ia+n-1,
ja:ja+n-1 must contain the upper
triangular part of the matrix, and the strictly lower triangular part is not
referenced.
- If uplo = 'L', the leading
n × n lower triangular part of the global
submatrix Aia:ia+n-1,
ja:ja+n-1 must contain the lower
triangular part of the matrix, and the strictly upper triangular part is not
referenced.
Scope: local
Specified as: an LLD_A by (at least) LOCq(N_A) array, containing
numbers of the data type indicated in Table 102. Details about the square block-cyclic data
distribution of global matrix A are stored in
desc_a.
- ia
- is the row index of the global matrix A, identifying the first
row of the submatrix A.
Scope: global
Specified as: a fullword integer;
1 <= ia <= M_A and
ia+n-1 <= M_A.
- ja
- is the column index of the global matrix A, identifying the
first column of the submatrix A.
Scope: global
Specified as: a fullword integer;
1 <= ja <= N_A and
ja+n-1 <= N_A.
- desc_a
- is the array descriptor for global matrix A, described in the
following table:
| desc_a
| Name
| Description
| Limits
| Scope
|
| 1
| DTYPE_A
| Descriptor type
| DTYPE_A=1
| Global
|
| 2
| CTXT_A
| BLACS context
| Valid value, as returned by BLACS_GRIDINIT or BLACS_GRIDMAP
| Global
|
| 3
| M_A
| Number of rows in the global matrix
| If n = 0: M_A >= 0
Otherwise: M_A >= 1
| Global
|
| 4
| N_A
| Number of columns in the global matrix
| If n = 0: N_A >= 0
Otherwise: N_A >= 1
| Global
|
| 5
| MB_A
| Row block size
| MB_A >= 1
| Global
|
| 6
| NB_A
| Column block size
| NB_A >= 1
| Global
|
| 7
| RSRC_A
| The process row of the p × q grid over
which the first row of the global matrix is distributed
| 0 <= RSRC_A < p
| Global
|
| 8
| CSRC_A
| The process column of the p × q grid over
which the first column of the global matrix is distributed
| 0 <= CSRC_A < q
| Global
|
| 9
| LLD_A
| The leading dimension of the local array
| LLD_A >= max(1,LOCp(M_A))
| Local
|
Specified as: an array of (at least) length 9, containing fullword
integers.
- vl
- has the following meaning:
If range = 'V', it is the lower bound of the
interval to be searched for eigenvalues.
If range <> 'V', this argument is
ignored.
Scope: global
Specified as: a number of the data type indicated in Table 102. If range = 'V',
vl < vu.
- vu
- has the following meaning:
If range = 'V', it is the upper bound of the
interval to be searched for eigenvalues.
If range <> 'V', this argument is
ignored.
Scope: global
Specified as: a number of the data type indicated in Table 102. If range = 'V',
vl < vu.
- il
- has the following meaning:
If range = 'I', it is the index (from smallest to
largest) of the smallest eigenvalue to be returned.
If range <> 'I', this argument is
ignored.
Scope: global
Specified as: a fullword integer;
il >= 1.
- iu
- has the following meaning:
If range = 'I', it is the index (from smallest to
largest) of the largest eigenvalue to be returned.
If range <> 'I', this argument is
ignored.
Scope: global
Specified as: a fullword integer; min(il,
n) <= iu <= n.
- abstol
- is the absolute tolerance for the eigenvalues. An approximate
eigenvalue is accepted as converged when it is determined to lie in an
interval [a, b] of width less than or equal
to:
- abstol+epsilon(max(|a|, |b|))
where epsilon is the machine precision. If abstol is less
than or equal to zero, then epsilon(norm(T)) is used in its place,
where norm(T) is the 1-norm of the tridiagonal matrix obtained by
reducing A to tridiagonal form. For most problems, this is
the appropriate level of accuracy to request.
For certain strongly graded matrices, greater accuracy can be obtained in
very small eigenvalues by setting abstol to a very small positive
number. However, if abstol is less than:
where unfl is the underflow threshold, then:
is used in its place.
Eigenvalues are computed most accurately when abstol is set to
twice the underflow threshold--that is, (2)(unfl).
If jobz = 'V', then setting abstol to
unfl, the underflow threshold, yields the most orthogonal
eigenvectors.
Scope: global
Specified as: a number of the data type indicated in Table 102.
- m
- See On Return.
- nz
- See On Return.
- w
- See On Return.
- orfac
- specifies which eigenvectors should be reorthogonalized.
Eigenvectors that correspond to eigenvalues which are within:
- ortol = (orfac)(norm(A))
of each other (where norm(A) is the 1-norm of A) are
to be reorthogonalized.
However, if the workspace is insufficient (see lwork and |lrwork), ortol may be decreased until all eigenvectors to be
reorthogonalized can be stored in one process.
If orfac is zero, no reorthogonalization is done.
If orfac is less than zero, a default value of
10-3 is used.
Scope: global
Specified as: a number of the data type indicated in Table 102.
- z
- See On Return.
- iz
- is the row index of the global matrix Z, identifying the first
row of the submatrix Z.
Scope: global
Specified as: a fullword integer;
1 <= iz <= M_Z and
iz+n-1 <= M_Z.
- jz
- is the column index of the global matrix Z, identifying the
first column of the submatrix Z.
Scope: global
Specified as: a fullword integer;
1 <= jz <= N_Z and
jz+n-1 <= N_Z.
- desc_z
- is the array descriptor for global matrix Z, described in the
following table:
| desc_z
| Name
| Description
| Limits
| Scope
|
| 1
| DTYPE_Z
| Descriptor type
| DTYPE_Z=1
| Global
|
| 2
| CTXT_Z
| BLACS context
| Valid value, as returned by BLACS_GRIDINIT or BLACS_GRIDMAP
| Global
|
| 3
| M_Z
| Number of rows in the global matrix
| If n = 0: M_Z >= 0
Otherwise: M_Z >= 1
| Global
|
| 4
| N_Z
| Number of columns in the global matrix
| If n = 0: N_Z >= 0
Otherwise: N_Z >= 1
| Global
|
| 5
| MB_Z
| Row block size
| MB_Z >= 1
| Global
|
| 6
| NB_Z
| Column block size
| NB_Z >= 1
| Global
|
| 7
| RSRC_Z
| The process row of the p × q grid over
which the first row of the global matrix is distributed
| 0 <= RSRC_Z < p
| Global
|
| 8
| CSRC_Z
| The process column of the p × q grid over
which the first column of the global matrix is distributed
| 0 <= CSRC_Z < q
| Global
|
| 9
| LLD_Z
| The leading dimension of the local array
| LLD_Z >= max(1,LOCp(M_Z))
| Local
|
Specified as: an array of (at least) length 9, containing fullword
integers.
- work
- has the following meaning:
If lwork = 0, work is ignored.
If lwork <> 0, work is a work area used by this
subroutine, where:
- If lwork <> -1, then its size is (at least) of length
lwork.
- If lwork = -1, then its size is (at least) of length
1.
Scope: local
Specified as: an area of storage containing numbers of data type
indicated in Table 102.
- lwork
- is the number of elements in array WORK.
Scope:
- If lwork >= 0, lwork is
local.
- If lwork = -1, lwork is
global.
Specified as: a fullword integer; where:
- If lwork = 0, PDSYEVX and PZHEEVX dynamically allocate
the work area used by the subroutine. The work area is deallocated
before control is returned to the calling program. This option is an
extension to the ScaLAPACK standard.
- If lwork = -1, PDSYEVX and PZHEEVX perform a work area
query and return the minimum required size of work in
work1. No computation is performed and the
subroutine returns after error checking is complete.
- Otherwise, use the following rules to determine the value to
specify:
- If jobz = 'N', it must have the following
value:
For PDSYEVX, lwork >=
3(n+ja-1)+2n +max(5nn,
(nb)(np+1))
For PZHEEVX, lwork >= n+ja-1
+max(3nb, nb(np+1))
- If jobz = 'V', then the amount of workspace
required to guarantee that all eigenvectors are computed is:
For PDSYEVX, lwork >=
3(n+ja-1)+2n +max(5nn,
(np0)(mq0)+2(nb)(nb)) +
iceil(neig, (nprow)(npcol))(nn)
For PZHEEVX, lwork >= n+ja-1
+(np0+mq0+nb)(nb)
where:
- nn = max(n, nb, 2)
- neig is the number of eigenvectors requested
- nb = MB_A = NB_A = MB_Z = NB_Z
- np = NUMROC(nn, nb, myrow,
iarow, nprow)
- np0 = NUMROC(nn+iroffz, nb,
izrow, izrow, nprow)
- mq0 = NUMROC(max(neig, nb,
2)+icoffz, nb, izcol, izcol,
npcol)
- iarow = mod(RSRC_A +
(ia-1)/nb, nprow)
- izrow = mod(RSRC_Z +
(iz-1)/nb, nprow)
- izcol = mod(CSRC_Z +
(jz-1)/nb, npcol)
- iroffz = mod(iz-1, MB_Z)
- icoffz = mod(jz-1, NB_Z)
For PDSYEVX, the computed eigenvectors may not be orthogonal if the minimum
workspace is supplied and ortol is too small; therefore, if you
want to guarantee orthogonality (at the cost of potentially compromising
performance), you should add the following to lwork:
(clustersize-1)(n)
where clustersize is the number of eigenvalues in the largest
cluster, where a cluster is defined as a set of close eigenvalues:
- {wk, ...,
wk+iclustrsz-1 |
wj+1 <=
wj+orfac(2)(norm(A))}
- Note:
- PDSYEVX does not add this amount when dynamically allocating this
workspace. You must use static allocation if you want to guarantee
orthogonality.
When lwork is too small:
- For PDSYEVX, if lwork is too small to guarantee orthogonality,
this subroutine attempts to maintain orthogonality in the clusters with the
smallest spacing between the eigenvalues.
- If lwork is too small to compute all the eigenvectors requested,
no computation is performed, except that if
range = 'V', this subroutine does not know how many
eigenvectors are requested until the eigenvalues are computed.
Therefore, if range = 'V' and lwork is large
enough to allow this subroutine to compute the eigenvalues, this subroutine
computes the eigenvalues and as many eigenvectors as it can.
For the relationship between workspace, orthogonality, and performance, see
Notes and Coding Rules 14.
- rwork
- has the following meaning:
If lrwork = 0, rwork is ignored.
If lrwork <> 0, rwork is a work area used by
this subroutine, where:
- If lrwork <> -1, then its size is (at least) of
length lrwork.
- If lrwork = -1, then its size is (at least) of length
1.
Scope: local
Specified as: an area of storage containing numbers of data type
indicated in Table 102.
- lrwork
- is the number of elements in array RWORK.
Scope:
- If lrwork >= 0, lrwork is
local.
- If lrwork = -1, lrwork is
global.
Specified as: a fullword integer; where:
- If lrwork = 0, PZHEEVX dynamically allocates the work
area used by this subroutine. The work area is deallocated before
control is returned to the calling program. This option is an extension
to the ScaLAPACK standard.
- If lrwork = -1, PZHEEVX performs a work area query and
return the minimum required size of rwork in
rwork1. No computation is performed and the
subroutine returns after error checking is complete.
- Otherwise, use the following rules to determine the value to
specify:
- If jobz = 'N', it must have the following
value:
lrwork >= 2(n+ja-1)
+2n +5nn
- If jobz = 'V', then the amount of workspace
required to guarantee that all eigenvectors are computed is:
lrwork >= 2(n+ja-1)
+2n +max(5nn, (np0)(mq0)) +
iceil(neig, (nprow)(npcol))(nn)
where:
- nn = max(n, nb, 2)
- neig is the number of eigenvectors requested
- nb = MB_A = NB_A = MB_Z = NB_Z
- np0 = NUMROC(nn+iroffz, nb,
izrow, izrow, nprow)
- mq0 = NUMROC(max(neig, nb,
2)+icoffz, nb, izcol, izcol,
npcol)
- izrow = mod(RSRC_Z +
(iz-1)/nb, nprow)
- izcol = mod(CSRC_Z +
(jz-1)/nb, npcol)
- iroffz = mod(iz-1, MB_Z)
- icoffz = mod(jz-1, NB_Z)
For PZHEEVX, the computed eigenvectors may not be orthogonal if the minimum
workspace is supplied and ortol is too small; therefore, if you
want to guarantee orthogonality (at the cost of potentially compromising
performance), you should add the following to lrwork:
(clustersize-1)(n)
where clustersize is the number of eigenvalues in the largest
cluster, where a cluster is defined as a set of close eigenvalues:
- {wk, ...,
wk+iclustrsz-1 |
wj+1 <=
wj+orfac(2)(norm(A))}
- Note:
- PZHEEVX does not add this amount when dynamically allocating this
workspace. You must use static allocation if you want to guarantee
orthogonality.
When lrwork is too small:
- If lrwork is too small to guarantee orthogonality, this
subroutine attempts to maintain orthogonality in the clusters with the
smallest spacing between the eigenvalues.
- If lrwork is too small to compute all the eigenvectors requested,
no computation is performed, except that if
range = 'V', this subroutine does not know how many
eigenvectors are requested until the eigenvalues are computed.
Therefore, if range = 'V' and lrwork is
large enough to allow this subroutine to compute the eigenvalues, this
subroutine computes the eigenvalues and as many eigenvectors as it can.
For the relationship between workspace, orthogonality, and performance, see
Notes and Coding Rules 14.
- iwork
- has the following meaning:
If liwork = 0, iwork is ignored.
If liwork <> 0, iwork is a work area used by
this subroutine, where:
- If liwork <> -1, then its size is (at least) of
length liwork.
- If liwork = -1, then its size is (at least) of length
1.
Scope: local
Specified as: an area of storage containing fullword integers.
- liwork
- is the number of elements in array IWORK.
Scope:
- If liwork >= 0, liwork is
local.
- If liwork = -1, liwork is
global.
Specified as: a fullword integer; where:
- ifail
- See On Return.
- iclustr
- See On Return.
- gap
- See On Return.
- info
- See On Return.
- a
- a is the local part of the global matrix A,
where:
If uplo = 'U', the upper triangle and diagonal of
submatrix Aia:ia+n-1,
ja:ja+n-1 are overwritten;
that is, the original input is not preserved.
If uplo = 'L', the lower triangle and diagonal of
submatrix Aia:ia+n-1,
ja:ja+n-1 are overwritten;
that is, the original input is not preserved.
Scope: local
Returned as: an LLD_A by (at least) LOCq(N_A) array, containing
numbers of the data type indicated in Table 102.
- m
- is the number of eigenvalues found.
Scope: global
Returned as: a fullword integer;
0 <= m <= n.
- nz
- has the following meaning:
If jobz <> 'V', then nz is
ignored.
If jobz = 'V', then nz is the number of
eigenvectors computed--that is, the number of columns of Z
used in the computation. On output, nz = m
unless you provide insufficient space. To get all the eigenvectors
requested, you must supply both sufficient space to hold the eigenvectors in
Z and sufficient workspace to compute them (see lwork and
lrwork).
If range = 'A' or 'I', this subroutine
does not perform any computations if the work space supplied is
insufficient. In this case, an input-argument error is issued and your
job is terminated. For range = 'V', the number
of requested eigenvectors is unknown until the eigenvalues are found.
In this case, the subroutine computes as many eigenvectors as space
allows. Then, if nz <> m, a computational
error message is issued.
Scope: global
Returned as: a fullword integer;
0 <= nz <= m.
- w
- On normal exit (see info), it is the vector w,
containing the selected eigenvalues in ascending order in the first m
elements of w.
Scope: global
Returned as: a one-dimensional array of (at least) length n,
containing numbers of the data type indicated in Table 102.
- z
- has the following meaning:
If jobz = 'N', then z is ignored.
If jobz = 'V' and there is a normal exit (see
info), then this is the updated local part of the global matrix
Z, where columns jz to jz+m-1 of
the global matrix Z contain the orthonormal eigenvectors of the
global matrix A, corresponding to the selected eigenvalues.
If an eigenvector fails to converge, then the corresponding column of the
global matrix Z contains the last approximation to the eigenvector,
and the index of the eigenvector is returned in ifail.
This identifies the first element of the local array
Z. This subroutine computes the location of the first
element of the local subarray used, based on iz, jz,
desc_z, p, q, myrow, and
mycol; therefore, the leading
LOCp(iz+n-1) by LOCq(jz+n-1)
part of the local array Z must contain the local pieces of the
leading iz+n-1 by jz+n-1 part
of the global matrix Z.
Scope: local
Returned as: an LLD_Z by (at least) LOCq(N_Z) array, containing
numbers of the data type indicated in Table 102.
- work
- is the work area used by this subroutine if lwork <>
0,where:
If lwork <> 0 and lwork <> -1,
its size is (at least) of length lwork.
If lwork = -1, its size is (at least) of length
1.
Scope: local
Returned as: an area of storage, containing numbers of the data type
indicated in Table 102, where:
If lwork >= 1 or lwork = -1,
then:
- If jobz = 'N', then work1 is
set to the minimum lwork needed.
- If jobz = 'V', then:
For PDSYEVX, work1 is set to the minimum lwork
needed to compute all eigenvectors, but not necessarily sufficient to
guarantee orthogonality of the eigenvectors.
For PZHEEVX, work1 is set to the minimum lwork
needed to compute all eigenvectors.
- Except for work1, the contents of work are
overwritten on return.
- rwork
- is the work area used by this subroutine if lrwork <>
0,where:
If lrwork <> 0 and lrwork <> -1,
its size is (at least) of length lrwork.
If lrwork = -1, its size is (at least) of length
1.
Scope: local
Returned as: an area of storage, containing numbers of the data type
indicated in Table 102, where:
If lrwork >= 1 or lrwork = -1,
then:
- If jobz = 'N', then rwork1 is
set to the minimum lrwork value needed.
- If jobz = 'V', then rwork1 is
set to the minimum lrwork value needed to compute all eigenvectors,
but not necessarily sufficient to guarantee orthogonality of the
eigenvectors.
- Except for rwork1, the contents of rwork are
overwritten on return.
- iwork
- is the work area used by this subroutine if liwork <>
0, where:
If liwork <> 0 and liwork <> -1,
then its size is (at least) of length liwork.
If liwork = -1, then its size is (at least) of length
1.
Scope: local
Returned as: an area of storage, where:
If liwork >= 1 or liwork = -1, then
iwork1 is set to the minimum liwork value and
contains numbers of the data type indicated in Table 102. Except for iwork1, the contents
of iwork are overwritten on return.
- ifail
- has the following meaning:
If jobz = 'N', then ifail is
ignored.
If jobz = 'V', it is vector ifail,
where:
- If there is a normal exit (see info), the first m
elements of ifail are zero.
- If there is an error exit (where one or more eigenvectors failed to
converge--see info), ifail contains the indices of
the eigenvectors that failed to converge.
Scope: global
Returned as: a one-dimensional array of (at least) length n,
containing fullword integers;
0 <= ifaili <= n.
- iclustr
- has the following meaning:
If jobz = 'N', then iclustr is
ignored.
If jobz = 'V', it is vector iclustr,
containing the indices of the eigenvectors corresponding to a cluster of
eigenvalues that could not be reorthogonalized due to insufficient
workspace. Eigenvectors corresponding to clusters of eigenvalues
indexed iclustr2i-1 to
iclustr2i could not be reorthogonalized due to
lack of workspace. Hence, the eigenvectors corresponding to these
clusters may not be orthogonal.
iclustr is a zero-terminated vector; that is, the last
element of iclustr is set to zero. Assuming that k
is the number of clusters, then:
- iclustr2k <> 0 and
iclustr2k+1 = 0
Scope: global
Returned as: a one-dimensional array of (at least) length
2(nprow)(npcol), containing fullword integers;
0 <= iclustri <= n.
- gap
- has the following meaning:
If jobz = 'N', then gap is
ignored.
If jobz = 'V', it is vector gap,
containing the gap between the eigenvalues whose eigenvectors could not be
reorthogonalized. The values in this vector correspond to the clusters
indicated by iclustr. As a result, the dot product between
the eigenvectors corresponding to the i-th cluster may be as high as
(C)(n)/gapi, where
C is a small constant.
Scope: global
Returned as: a one-dimensional array of (at least) length
(nprow)(npcol), containing numbers of the data type
indicated in Table 102.
- info
- has the following meaning:
If info = 0, then no input-argument errors or
computational errors occurred. This indicates a normal exit.
- Note:
- One use of info in ScaLAPACK is to identify whether input-argument
errors occurred. Because Parallel ESSL terminates the application if
input-argument errors occur, the setting of info is irrelevant for
these errors.
If info > 0, then one or more of the following
computational errors occurred and the appropriate error messages were issued,
indicating an error exit, where:
- If mod(info, 2) <> 0, then one or more eigenvectors
failed to converge. Their indices are stored in
ifail. (Ensure that
abstol = (2)(unfl).)
- If mod(info/2, 2) <> 0, then the eigenvectors
corresponding to one or more clusters of eigenvalues could not be
reorthogonalized because of insufficient workspace. The indices of the
clusters are stored in iclustr.
- If mod(info/4, 2) <> 0, then all the
eigenvectors between vl and vu could not be computed because
of insufficient space. The number of eigenvectors computed is returned
in nz.
- If mod(info/8, 2) <> 0, then one of more
eigenvalues were not computed. (Ensure that
abstol = (2)(unfl).)
Scope: global
Returned as: a fullword integer;
info >= 0.
- This subroutine accepts lowercase letters for the jobz,
range, and uplo arguments.
- In your C program, argument info must be passed by
reference.
- A, Z, w, ifail,
iclustr, gap, work, rwork, and
iwork must have no common elements; otherwise, results are
unpredictable.
- The NUMROC utility subroutine can be used to determine the values of
LOCp(M_) and LOCq(N_) used in the argument descriptions above. For
details, see Determining the Number of Rows and Columns in Your Local Arrays and NUMROC--Compute the Number of Rows or Columns of a Block-Cyclically Distributed Matrix Contained in a Process.
- The global matrix A must be distributed using a square
block-cyclic distribution; that is, MB_A = NB_A.
- The global matrix A must be aligned on a block boundary;
that is:
- ia-1 must be a multiple of MB_A
- ja-1 must be a multiple of NB_A
- If jobz = 'V', then also follow these
rules:
- In the process grid, the process row containing the first row of the
submatrix A must also contain the first row of the submatrix
Z; that is: iarow = izrow
where:
- iarow = mod(RSRC_A+(ia-1)/MB_A,
p)
- izrow = mod(RSRC_Z+(iz-1)/MB_Z,
p)
- M_A = M_Z
- MB_A = MB_Z
- NB_A = NB_Z
- RSRC_A = RSRC_Z
- CSRC_A = CSRC_Z
- CTXT_A = CTXT_Z
- The block row offset of the global matrix A must be equal to
the block row offset of the global general matrix Z; that
is:
- mod((ia-1, MB_A) = mod(iz-1, MB_Z))
- Eigenvectors associated with tightly clustered eigenvalues may not be
orthogonal.
- Eigenvectors that are on different processes are not
reorthogonalized. For details, see the lwork and
lrwork arguments.
- An example of the use of PDSYEVX in a thermal diffusion application
program is shown in Appendix B, Sample Programs. See Program Main.
- If lwork = -1 on any process, it must equal
-1 on all processes. That is, if a subset of the processes
specifies -1 for the work area size, they must all specify
-1.
- If lrwork = -1 on any process, it must equal
-1 on all processes. That is, if a subset of the processes
specifies -1 for the work area size, they must all specify
-1.
- If liwork = -1 on any process, it must equal
-1 on all processes. That is, if a subset of the processes
specifies -1 for the work area size, they must all specify
-1.
- The following describes the relationship between
workspace, orthogonality, and performance.
Let clustersize be the number of eigenvalues in the largest
cluster, where a cluster is defined as a set of close eigenvalues:
- {wk, ...,
wk+iclustrsz-1 |
wj+1 <=
wj+orfac(2)(norm(A))}
- If clustersize is:
then providing enough space to compute all the eigenvectors orthogonally
causes serious degradation in performance. In the limit
(clustersize = n-1), performance may be no
better than using one process.
- If clustersize is:
then reorthogonalizing all eigenvectors increases the total execution time
by a factor of 2 or more.
- If clustersize is:
then execution time grows as the square of the cluster size, assuming all
other factors remain equal and there is enough workspace. Less
workspace means less reorthogonalization, but faster execution.
For PDSYEVX, see the description of work ***. For PZHEEVX, see the description of rwork ***.
This subroutine computes selected eigenvalues and, optionally, the
eigenvectors of a real symmetric or complex Hermitian matrix
A. Eigenvalues and eigenvectors can be selected by
specifying a range of values or a range of indices for the eigenvalues.
The computation involves the following steps:
- Reduce the matrix A to real symmetric tridiagonal form.
- Compute the requested eigenvalues of the real symmetric tridiagonal matrix
using bisection.
- If requested, compute the eigenvectors of the real symmetric tridiagonal
matrix using inverse iteration, and then back transform the eigenvectors to
obtain the eigenvectors of the matrix A.
- Note:
- For more details, see output argument info.
- Bisection failed to converge for some eigenvalues. The eigenvalues
may not be as accurate as the absolute and relative tolerances.
- The number of eigenvalues computed does not match the number of
eigenvalues requested.
- No eigenvalues were computed, because the Gershgorin interval initially
used was incorrect.
- Some eigenvectors failed to converge. The indices are stored in
ifail.
- Eigenvectors corresponding to one or more clusters of eigenvalues could
not be reorthogonalized because of insufficient workspace. The indices
of the clusters are stored in iclustr.
- All the eigenvectors between vl and vu could not be
computed due to insufficient workspace. The number of eigenvectors
computed is returned in nz.
- (lwork = 0, lrwork = 0, or
liwork = 0) and unable to allocate work space
Stage 1:
- DTYPE_A is invalid.
- DTYPE_Z is invalid and jobz = 'V'
Stage 2:
- CTXT_A is invalid.
Stage 3:
- This subroutine has been called from outside the process grid.
Stage 4:
- jobz <> 'N' or 'V'
- range <> 'A', 'V', or 'I'
- uplo <> 'U' or 'L'
- n < 0
- M_A < 0 and n = 0; M_A < 1
otherwise
- N_A < 0 and n = 0; N_A < 1
otherwise
- MB_A < 1
- NB_A < 1
- RSRC_A < 0 or RSRC_A >= p
- CSRC_A < 0 or CSRC_A >= q
- ia < 1
- ja < 1
If jobz = 'V':
- M_Z < 0 and n = 0; M_Z < 1
otherwise
- N_Z < 0 and n = 0; N_Z < 1
otherwise
- MB_Z < 1
- NB_Z < 1
- RSRC_Z < 0 or RSRC_Z >= p
- CSRC_Z < 0 or CSRC_Z >= q
- iz < 1
- jz < 1
- CTXT_A <> CTXT_Z
Stage 5:
- vu <= vl and
range = 'V' and n <> 0
- il < 1 and range = 'I'
- (iu < min(n, il) or
iu > n) and range = 'I'
If n <> 0:
- ia > M_A
- ja > N_A
- ia+n-1 > M_A
- ja+n-1 > N_A
If n <> 0 and jobz = 'V':
- iz > M_Z
- jz > N_Z
- iz+n-1 > M_Z
- jz+n-1 > N_Z
In all cases:
- MB_A <> NB_A
- mod(ia-1, MB_A) <> 0
- mod(ja-1, NB_A) <> 0
If jobz = 'V':
- M_A <> M_Z
- MB_A <> MB_Z
- NB_A <> NB_Z
- mod(iz-1, MB_Z) <> mod(ia-1,
MB_A)
- In the process grid, the process row containing the first row of the
submatrix A does not contain the first row of the submatrix
Z; that is, iarow <> izrow,
where:
- iarow = mod(RSRC_A + (ia-1)/MB_A,
p)
- izrow = mod(RSRC_Z + (iz-1)/MB_Z,
p)
- RSRC_A <> RSRC_Z
- CSRC_A <> CSRC_Z
Stage 6:
- LLD_A < max(1, LOCp(M_A))
- lwork <> 0, lwork <> -1, and
lwork < (minimum value). (For the
minimum value, see the lwork argument description.)
- lrwork <> 0, lrwork <> -1, and
lrwork < (minimum value). (For
the minimum value, see the lrwork argument description.)
- liwork <> 0, liwork <> -1, and
liwork < (minimum value). (For
the minimum value, see the liwork argument description.)
If jobz = 'V':
- LLD_Z < max(1, LOCp(M_Z))
Stage 7:
Each of the following global input arguments are checked to determine
whether its value differs from the value specified on process
P00:
- jobz differs.
- range differs.
- uplo differs.
- n differs.
- ia differs.
- ja differs.
- DTYPE_A differs.
- M_A differs.
- N_A differs.
- MB_A differs.
- NB_A differs.
- RSRC_A differs.
- CSRC_A differs.
- ABSTOL differs.
Also:
- lwork = -1 on a subset of processes.
- lrwork = -1 on a subset of processes.
- liwork = -1 on a subset of processes.
Stage 8:
Each of the following global input arguments are checked to determine
whether its value differs from the value specified on process
P00:
If range = 'V':
- vl differs.
- vu differs.
If range = 'I':
- il differs.
- iu differs.
If jobz = 'V':
- iz differs.
- jz differs.
- DTYPE_Z differs.
- M_Z differs.
- N_Z differs.
- MB_Z differs.
- NB_Z differs.
- RSRC_Z differs.
- CSRC_Z differs.
- ORFAC differs.
This example shows how to find all the eigenvalues and eigenvectors of a
real symmetric matrix A of order 4 using a 2 × 2
process grid.
Notes:
- Because range = 'A', arguments vl,
vu, il, and iu are not referenced.
- Because lwork = 0 and liwork = 0,
PDSYEVX dynamically allocates the work areas used by this subroutine.
ORDER = 'R'
NPROW = 2
NPCOL = 2
CALL BLACS_GET(0, 0, ICONTXT)
CALL BLACS_GRIDINIT(ICONTXT, ORDER, NPROW, NPCOL)
CALL BLACS_GRIDINFO(ICONTXT, NPROW, NPCOL, MYROW, MYCOL)
JOBZ RANGE UPLO N A IA JA DESC_A VL VU IL IU ABSTOL M NZ W
| | | | | | | | | | | | | | | |
CALL PDSYEVX( 'V', 'A', 'U', 4, A, 1, 1, DESC_A, 0.0D0, 0.0D0, 0, 0, -1.0D0, M, NZ, W,
ORFAC Z IZ JZ DESC_Z WORK LWORK IWORK LIWORK IFAIL ICLUSTR GAP INFO
+ | | | | | | | | | | | | |
-1.0D0, Z, 1, 1, DESC_Z, WORK , 0 , IWORK , 0 , IFAIL, ICLUSTR, GAP, INFO)
| DESC_A
| DESC_Z
|
| DTYPE_
| 1
| 1
|
| CTXT_
| icontxt(IITOOT7)
| icontxt(IITOOT7)
|
| M_
| 4
| 4
|
| N_
| 4
| 4
|
| MB_
| 1
| 1
|
| NB_
| 1
| 1
|
| RSRC_
| 0
| 0
|
| CSRC_
| 0
| 0
|
| LLD_
| See below(EPSSTL7)
| See below(EPSSTL7)
|
|
Notes:
- icontxt is the output of the BLACS_GRIDINIT
call.
- Each process should set the LLD_ as follows:
LLD_A = MAX(1,NUMROC(M_A, MB_A, MYROW, RSRC_A, NPROW))
LLD_Z = MAX(1,NUMROC(M_Z, MB_Z, MYROW, RSRC_Z, NPROW))
In this example, LLD_A = LLD_Z = 2 on all
processes.
|
Global real symmetric matrix A of order 4 with block sizes
1 × 1:
B,D 0 1 2 3
* *
0 | 5.0 | 4.0 | 1.0 | 1.0 |
| ------|--------|--------|------ |
1 | . | 5.0 | 1.0 | 1.0 |
| ------|--------|--------|------ |
2 | . | . | 4.0 | 2.0 |
| ------|--------|--------|------ |
3 | . | . | . | 4.0 |
* *
The following is the 2 × 2 process grid:
B,D | 0 2 | 1 3
-----| ------- |-----
0 | P00 | P01
2 | |
-----| ------- |-----
1 | P10 | P11
3 | |
Local arrays for A:
p,q | 0 | 1
-----|------------|------------
0 | 5.0 1.0 | 4.0 1.0
| . 4.0 | . 2.0
-----|------------|------------
1 | . 1.0 | 5.0 1.0
| . . | . 4.0
Output:
The upper triangle, including the diagonal, of the global real symmetric
matrix A is overwritten; that is, the original input is not
preserved.
On all processes, m = 4 and
nz = 4.
Global vector w of length 4 is the same on all processes:
- w = (1.00, 2.00, 5.00,
10.00)
Global general matrix Z of order 4 with block sizes
1 × 1:
B,D 0 1 2 3
* *
0 | 0.7071 | 0.0000 | -0.3162 | -0.6325 |
| ---------|-----------|-----------|--------- |
1 | -0.7071 | 0.0000 | -0.3162 | -0.6325 |
| ---------|-----------|-----------|--------- |
2 | 0.0000 | -0.7071 | 0.6325 | -0.3162 |
| ---------|-----------|-----------|--------- |
3 | 0.0000 | 0.7071 | 0.6325 | -0.3162 |
* *
The following is the 2 × 2 process grid:
B,D | 0 2 | 1 3
-----| ------- |-----
0 | P00 | P01
2 | |
-----| ------- |-----
1 | P10 | P11
3 | |
Local arrays for Z:
p,q | 0 | 1
-----|-------------------|-------------------
0 | 0.7071 -0.3162 | 0.0000 -0.6325
| 0.0000 0.6325 | -0.7071 -0.3162
-----|-------------------|-------------------
1 | -0.7071 -0.3162 | 0.0000 -0.6325
| 0.0000 0.6325 | 0.7071 -0.3162
Global vector ifail of length 4 is the same on all
processes:
- ifail = (0, 0, 0, 0)
Global vector iclustr of length 8
( = 2(nprow)(npcol)) is the same on all
processes:
- iclustr = (0, 0, 0, 0, 0, 0, 0, 0)
Global vector gap of length 4
( = (nprow)(npcol)) is the same on all
processes:
- gap = (-1.0, -1.0,
-1.0, -1.0)
The value of info is 0 on all processes.
This example shows how to find all the eigenvalues and eigenvectors of a
complex Hermitian matrix A of order 4 using a 2 × 2
process grid.
Notes:
- Because range = 'A', arguments vl,
vu, il, and iu are not referenced.
- Because lwork = 0, lrwork = 0, and
liwork = 0, PZHEEVX dynamically allocates the work areas used
by this subroutine.
ORDER = 'R'
NPROW = 2
NPCOL = 2
CALL BLACS_GET(0, 0, ICONTXT)
CALL BLACS_GRIDINIT(ICONTXT, ORDER, NPROW, NPCOL)
CALL BLACS_GRIDINFO(ICONTXT, NPROW, NPCOL, MYROW, MYCOL)
JOBZ RANGE UPLO N A IA JA DESC_A VL VU IL IU ABSTOL M NZ W ORFAC
| | | | | | | | | | | | | | | | |
CALL PZHEEVX( 'V', 'A', 'L', 4, A, 1, 1, DESC_A, 0.0D0, 0.0D0, 0, 0, -1.0D0, M, NZ, W, -1.0D0,
Z IZ JZ DESC_Z WORK LWORK RWORK LRWORK IWORK LIWORK IFAIL ICLUSTR GAP INFO
+ | | | | | | | | | | | | | |
Z, 1, 1, DESC_Z, WORK , 0, RWORK, 0, IWORK , 0, IFAIL, ICLUSTR, GAP, INFO)
| DESC_A
| DESC_Z
|
| DTYPE_
| 1
| 1
|
| CTXT_
| icontxt(IITOOT8)
| icontxt(IITOOT8)
|
| M_
| 4
| 4
|
| N_
| 4
| 4
|
| MB_
| 1
| 1
|
| NB_
| 1
| 1
|
| RSRC_
| 0
| 0
|
| CSRC_
| 0
| 0
|
| LLD_
| See below(EPSSTL8)
| See below(EPSSTL8)
|
|
Notes:
- icontxt is the output of the BLACS_GRIDINIT
call.
- Each process should set the LLD_ as follows:
LLD_A = MAX(1,NUMROC(M_A, MB_A, MYROW, RSRC_A, NPROW))
LLD_Z = MAX(1,NUMROC(M_Z, MB_Z, MYROW, RSRC_Z, NPROW))
In this example, LLD_A = LLD_Z = 2 on all
processes.
|
Global complex Hermitian matrix A of order 4 with block sizes
1 × 1:
B,D 0 1 2 3
* *
0 | (5.0, 0.0) | . | . | . |
|------------|------------|------------|------------|
1 | (4.0, 1.0) | (5.0, 0.0) | . | . |
|------------|------------|------------|------------|
2 | (1.0, 2.0) | (1.0, 0.0) | (4.0, 0.0) | . |
|------------|------------|------------|------------|
3 | (2.0, 3.0) | (3.0, 2.0) | (5.0, 1.0) | (4.0, 0.0) |
* *
The following is the 2 × 2 process grid:
B,D | 0 2 | 1 3
-----| ------- |-----
0 | P00 | P01
2 | |
-----| ------- |-----
1 | P10 | P11
3 | |
Local arrays for A:
p,q | 0 | 1
-----|------------------------|------------------------
0 | (5.0, . ) . | . .
| (1.0, 2.0) (4.0, . ) | (1.0, 0.0) .
-----|------------------------|------------------------
1 | (4.0, 1.0) . | (5.0, . ) .
| (2.3, 3.0) (5.0, 1.0) | (3.0, 2.0) (4.0, . )
Output:
The lower triangle, including the diagonal, of the global complex Hermitian
matrix A is overwritten; that is, the original input is not
preserved.
On all processes, m = 4 and
nz = 4.
Global vector w of length 4 is the same on all processes:
- w = (-1.765, 0.727, 4.664,
14.374)
Global general matrix Z of order 4 with block sizes
1 × 1:
B,D 0 1 2 3
* *
0 |( .0926, .0000) |( .7591, .0000) |( .3758, .0000) |(-.5234, .0000) |
|----------------|----------------|----------------|----------------|
1 |( .0840,-.2873) |(-.5874, .0177) |( .5370,-.2067) |(-.4515,-.1735) |
|----------------|----------------|----------------|----------------|
2 |( .5013,-.3461) |( .0526,-.0674) |(-.6287,-.2149) |(-.2864,-.3134) |
|----------------|----------------|----------------|----------------|
3 |(-.6703, .2854) |(-.0155,-.2662) |(-.2294,-.1834) |(-.3059,-.4672) |
* *
The following is the 2 × 2 process grid:
B,D | 0 2 | 1 3
-----| ------- |-----
0 | P00 | P01
2 | |
-----| ------- |-----
1 | P10 | P11
3 | |
Local arrays for Z:
p,q | 0 | 1
-----|---------------------------------|--------------------------------
0 | ( .0926, .0000) ( .3758, .0000) | ( .7591, .0000) (-.5234, .0000)
| ( .5013,-.3461) (-.6287,-.2149) | ( .0526,-.0674) (-.2864,-.3134)
-----|---------------------------------|--------------------------------
1 | ( .0840,-.2873) ( .5370,-.2067) | (-.5874, .0177) (-.4515,-.1735)
| (-.6703, .2854) (-.2294,-.1834) | (-.0155,-.2662) (-.3059,-.4672)
Global vector ifail of length 4 is the same on all
processes:
- ifail = (0, 0, 0, 0)
Global vector iclustr of length 8
( = 2(nprow)(npcol)) is the same on all
processes:
- iclustr = (0, 0, 0, 0, 0, 0, 0, 0)
Global vector gap of length 4
( = (nprow)(npcol)) is the same on all
processes:
- gap = (-1.0, -1.0,
-1.0, -1.0)
The value of info is 0 on all processes.
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]