Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 7/13/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

p?syevr

Computes selected eigenvalues and, optionally, eigenvectors of a real symmetric matrix using Relatively Robust Representation.

Syntax

call pssyevr( jobz, range, uplo, n, a, ia, ja, desca, vl, vu, il, iu, m, nz, w, z, iz, jz, descz, work, lwork, iwork, liwork, info )

call pdsyevr( jobz, range, uplo, n, a, ia, ja, desca, vl, vu, il, iu, m, nz, w, z, iz, jz, descz, work, lwork, iwork, liwork, info )

Include Files

Description

p?syevr computes selected eigenvalues and, optionally, eigenvectors of a real symmetric matrix A distributed in 2D blockcyclic format by calling the recommended sequence of ScaLAPACK routines.

First, the matrix A is reduced to real symmetric tridiagonal form. Then, the eigenproblem is solved using the parallel MRRR algorithm. Last, if eigenvectors have been computed, a backtransformation is done.

Upon successful completion, each processor stores a copy of all computed eigenvalues in w. The eigenvector matrix z is stored in 2D block-cyclic format distributed over all processors.

Note that subsets of eigenvalues/vectors can be selected by specifying a range of values or a range of indices for the desired eigenvalues.

Product and Performance Information

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

Notice revision #20201201

Input Parameters

jobz

(global) CHARACTER*1

Specifies whether or not to compute the eigenvectors:

= 'N': Compute eigenvalues only.

= 'V': Compute eigenvalues and eigenvectors.

range

(global) CHARACTER*1

= 'A': all eigenvalues will be found.

= 'V': all eigenvalues in the interval [vl,vu] will be found.

= 'I': the il-th through iu-th eigenvalues will be found.

uplo

(global) CHARACTER*1

Specifies whether the upper or lower triangular part of the symmetric matrix A is stored:

= 'U': Upper triangular

= 'L': Lower triangular

n

(global ) INTEGER

The number of rows and columns of the matrix a. n 0

a

REAL for pssyevr

DOUBLE PRECISION for pdsyevr

Block cyclic array of global size (n, n), local size ( lld_a, LOCc(ja+n-1) ).

This array contains the local pieces of the symmetric distributed matrix A. If uplo = 'U', only the upper triangular part of a is used to define the elements of the symmetric matrix. If uplo = 'L', only the lower triangular part of a is used to define the elements of the symmetric matrix.

On exit, the lower triangle (if uplo='L') or the upper triangle (if uplo='U') of a, including the diagonal, is destroyed.

ia

(global ) INTEGER

Global row index in the global matrix A that points to the beginning of the submatrix which is to be operated on. It should be set to 1 when operating on a full matrix.

ja

(global ) INTEGER

Global column index in the global matrix A that points to the beginning of the submatrix which is to be operated on. It should be set to 1 when operating on a full matrix.

desca

(global and local) INTEGER array of size dlen_=9.

The array descriptor for the distributed matrix a.

vl

REAL for pssyevr

DOUBLE PRECISION for pdsyevr

(global )

If range='V', the lower bound of the interval to be searched for eigenvalues. Not referenced if range = 'A' or 'I'.

vu

REAL for pssyevr

DOUBLE PRECISION for pdsyevr

(global )

If range='V', the upper bound of the interval to be searched for eigenvalues. Not referenced if range = 'A' or 'I'.

il

(global ) INTEGER

If range='I', the index (from smallest to largest) of the smallest eigenvalue to be returned. il 1.

Not referenced if range = 'A'.

iu

(global ) INTEGER

If range='I', the index (from smallest to largest) of the largest eigenvalue to be returned. min(il,n) iun.

Not referenced if range = 'A'.

iz

(global ) INTEGER

Global row index in the global matrix Z that points to the beginning of the submatrix which is to be operated on. It should be set to 1 when operating on a full matrix.

jz

(global ) INTEGER

Global column index in the global matrix Z that points to the beginning of the submatrix which is to be operated on. It should be set to 1 when operating on a full matrix.

descz

INTEGER array of size dlen_.

The array descriptor for the distributed matrix z.

The context descz( ctxt_ ) must equal desca( ctxt_ ). Also note the array alignment requirements specified below.

work

REAL for pssyevr

DOUBLE PRECISION for pdsyevr

(local workspace) array of size lwork

lwork

(local ) INTEGER

Size of work, must be at least 3.

See below for definitions of variables used to define lwork.

If no eigenvectors are requested (jobz = 'N') then

lwork 2 + 5*n + max( 12 * nn, neig * ( np0 + 1 ) )

If eigenvectors are requested (jobz = 'V' ) then the amount of workspace required is:

lwork 2 + 5*n + max( 18*nn, np0 * mq0 + 2 * neig * neig ) + (2 + iceil( neig, nprow*npcol))*nn

Variable definitions:

neig = number of eigenvectors requested

nb = desca( mb_ ) = desca( nb_ ) = descz( mb_ ) = descz( nb_ )

nn = max( n, neig, 2 )

desca( rsrc_ ) = desca( csrc_nb_ ) = descz( rsrc_ ) = descz( csrc_ ) = 0

np0 = numroc( nn, neig, 0, 0, nprow )

mq0 = numroc( max( neig, neig, 2 ), neig, 0, 0, npcol )

iceil( x, y ) is a ScaLAPACK function returning ceiling(x/y), and nprow and npcol can be determined by calling the subroutine blacs_gridinfo.

If lwork = -1, then lwork is global input and a workspace query is assumed; the routine only calculates the size required for optimal performance for all work arrays. Each of these values is returned in the first entry of the corresponding work arrays, and no error message is issued by pxerbla.

liwork

(local ) INTEGER

size of iwork

Let nnp = max( n, nprow*npcol + 1, 4 ). Then:

liwork 12*nnp + 2*n when the eigenvectors are desired

liwork 10*nnp + 2*n when only the eigenvalues have to be computed

If liwork = -1, then liwork is global input and a workspace query is assumed; the routine only calculates the minimum and optimal size for all work arrays. Each of these values is returned in the first entry of the corresponding work array, and no error message is issued by pxerbla.

OUTPUT Parameters

m

(global ) INTEGER

Total number of eigenvalues found. 0 mn.

nz

(global ) INTEGER

Total number of eigenvectors computed. 0 nzm.

The number of columns of z that are filled.

If jobz 'V', nz is not referenced.

If jobz = 'V', nz = m

w

REAL for pssyevr

DOUBLE PRECISION for pdsyevr

(global ) array of size n

Upon successful exit, the first m entries contain the selected eigenvalues in ascending order.

z

REAL for pssyevr

DOUBLE PRECISION for pdsyevr

Block-cyclic array, global size(n, n), local size ( lld_z, LOCc(jz+n-1) ) .

On exit, contains local pieces of distributed matrix Z.

work

On return, work(1) contains the optimal amount of workspace required for efficient execution. If jobz='N' work(1) = optimal amount of workspace required to compute the eigenvalues. If jobz='V' work(1) = optimal amount of workspace required to compute eigenvalues and eigenvectors.

iwork

(local workspace) INTEGER array

On return, iwork(1) contains the amount of integer workspace required.

info

(global ) INTEGER

= 0: successful exit

< 0: If the i-th argument is an array and the jth-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.

Application Notes

The distributed submatrices a(ia:*, ja:*) and z(iz:iz+m-1,jz:jz+n-1) must satisfy the following alignment properties:

  1. Identical (quadratic) dimension: desca(m_) = descz(m_) = desca(n_) = descz(n_)

  2. Quadratic conformal blocking: desca(mb_) = desca(nb_) = descz(mb_) = descz(nb_), desca(rsrc_) = descz(rsrc_)

  3. mod( ia-1, mb_a ) = mod( iz-1, mb_z ) = 0

NOTE:

mod(x,y) is the integer remainder of x/y.

See Also