Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 3/31/2023
Public

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

Document Table of Contents

?stedc

Computes all eigenvalues and eigenvectors of a symmetric tridiagonal matrix using the divide and conquer method.

Syntax

call sstedc(compz, n, d, e, z, ldz, work, lwork, iwork, liwork, info)

call dstedc(compz, n, d, e, z, ldz, work, lwork, iwork, liwork, info)

call cstedc(compz, n, d, e, z, ldz, work, lwork, rwork, lrwork, iwork, liwork, info)

call zstedc(compz, n, d, e, z, ldz, work, lwork, rwork, lrwork, iwork, liwork, info)

call rstedc(d, e [,z] [,compz] [,info])

call stedc(d, e [,z] [,compz] [,info])

Include Files
  • mkl.fi, lapack.f90
Description

The routine computes all the eigenvalues and (optionally) all the eigenvectors of a symmetric tridiagonal matrix using the divide and conquer method. The eigenvectors of a full or band real symmetric or complex Hermitian matrix can also be found if sytrd/hetrd or sptrd/hptrd or sbtrd/hbtrd has been used to reduce this matrix to tridiagonal form.

See also laed0, laed1, laed2, laed3, laed4, laed5, laed6, laed7, laed8, laed9, and laeda used by this function.

Input Parameters
compz

CHARACTER*1. Must be 'N' or 'I' or 'V'.

If compz = 'N', the routine computes eigenvalues only.

If compz = 'I', the routine computes the eigenvalues and eigenvectors of the tridiagonal matrix.

If compz = 'V', the routine computes the eigenvalues and eigenvectors of original symmetric/Hermitian matrix. On entry, the array z must contain the orthogonal/unitary matrix used to reduce the original matrix to tridiagonal form.

n

INTEGER. The order of the symmetric tridiagonal matrix (n 0).

d, e, rwork

REAL for single-precision flavors

DOUBLE PRECISION for double-precision flavors.

Arrays:

d(*) contains the diagonal elements of the tridiagonal matrix.

The dimension of d must be at least max(1, n).

e(*) contains the subdiagonal elements of the tridiagonal matrix.

The dimension of e must be at least max(1, n-1).

rwork is a workspace array, its dimension max(1, lrwork).

z, work

REAL for sstedc

DOUBLE PRECISION for dstedc

COMPLEX for cstedc

DOUBLE COMPLEX for zstedc.

Arrays: z(ldz, *), work(*).

If compz = 'V', then, on entry, z must contain the orthogonal/unitary matrix used to reduce the original matrix to tridiagonal form.

The second dimension of z must be at least max(1, n).

work is a workspace array, its dimension max(1, lwork).

ldz

INTEGER. The leading dimension of z. Constraints:

ldz 1 if compz = 'N';

ldz max(1, n) if compz = 'V' or 'I'.

lwork

INTEGER. The dimension of the array work.

For real functions sstedc and dstedc:

  • If compz = 'N'or n ≤ 1, lwork must be at least 1.

  • If compz = 'V' and n > 1, lwork must be at least 1 + 3*n + 2*n*log2(n) + 4*n2, where log2(n) is the smallest integer k such that 2kn.

  • If compz = 'I' and n > 1 then lwork must be at least 1 + 4*n + n2

    Note that for compz = 'I' or 'V' and if n is less than or equal to the minimum divide size, usually 25, then lwork need only be max(1, 2*(n-1)).

For complex functions cstedc and zstedc:

  • If compz = 'N'or 'I', or n ≤ 1, lwork must be at least 1.

  • If compz = 'V' and n > 1, lwork must be at least n2.

    Note that for compz = 'V', and if n is less than or equal to the minimum divide size, usually 25, then lwork need only be 1.

If lwork = -1, then a workspace query is assumed; the routine only calculates the optimal size of the work, rwork and iwork arrays, returns these values as the first entries of the work, rwork and iwork arrays, and no error message related to lwork or lrwork or liwork is issued by xerbla. See Application Notes for the required value of lwork.

lrwork

INTEGER. The dimension of the array rwork (used for complex flavors only).

If compz = 'N', or n ≤ 1, lrwork must be at least 1.

If compz = 'V' and n > 1, lrwork must be at least (1 + 3*n + 2*n*log2(n) + 4*n2), where log2(n)is the smallest integer k such that 2kn.

If compz = 'I' and n > 1, lrwork must be at least (1 + 4*n + 2*n2).

Note that for compz = 'V'or 'I', and if n is less than or equal to the minimum divide size, usually 25, then lrwork need only be max(1, 2*(n-1)).

If lrwork = -1, then a workspace query is assumed; the routine only calculates the optimal size of the work, rwork and iwork arrays, returns these values as the first entries of the work, rwork and iwork arrays, and no error message related to lwork or lrwork or liwork is issued by xerbla. See Application Notes for the required value of lrwork.

iwork

INTEGER. Workspace array, its dimension max(1, liwork).

liwork

INTEGER. The dimension of the array iwork.

If compz = 'N', or n ≤ 1, liwork must be at least 1.

If compz = 'V' and n > 1, liwork must be at least (6 + 6*n + 5*n*log2(n)), where log2(n)is the smallest integer k such that 2kn.

If compz = 'I' and n > 1, liwork must be at least (3 + 5*n).

Note that for compz = 'V'or 'I', and if n is less than or equal to the minimum divide size, usually 25, then liwork need only be 1.

If liwork = -1, then a workspace query is assumed; the routine only calculates the optimal size of the work, rwork and iwork arrays, returns these values as the first entries of the work, rwork and iwork arrays, and no error message related to lwork or lrwork or liwork is issued by xerbla. See Application Notes for the required value of liwork.

Output Parameters
d

The n eigenvalues in ascending order, unless info 0.

See also info.

e

On exit, the array is overwritten; see info.

z

If info = 0, then if compz = 'V', z contains the orthonormal eigenvectors of the original symmetric/Hermitian matrix, and if compz = 'I', z contains the orthonormal eigenvectors of the symmetric tridiagonal matrix. If compz = 'N', z is not referenced.

work(1)

On exit, if info = 0, then work(1) returns the optimal lwork.

rwork(1)

On exit, if info = 0, then rwork(1) returns the optimal lrwork (for complex flavors only).

iwork(1)

On exit, if info = 0, then iwork(1) returns the optimal liwork.

info

INTEGER.

If info = 0, the execution is successful.

If info = -i, the i-th parameter had an illegal value.

If info = i, the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and columns i/(n+1) through mod(i, n+1).

LAPACK 95 Interface Notes

Routines in Fortran 95 interface have fewer arguments in the calling sequence than their FORTRAN 77 counterparts. For general conventions applied to skip redundant or restorable arguments, see LAPACK 95 Interface Conventions.

Specific details for the routine stedc interface are the following:

d

Holds the vector of length n.

e

Holds the vector of length (n-1).

z

Holds the matrix Z of size (n,n).

compz

If omitted, this argument is restored based on the presence of argument z as follows: compz = 'I', if z is present, compz = 'N', if z is omitted.

If present, compz must be equal to 'I' or 'V' and the argument z must also be present. Note that there will be an error condition if compz is present and z omitted.

Note that two variants of Fortran 95 interface for stedc routine are needed because of an ambiguous choice between real and complex cases appear when z and work are omitted. Thus, the name rstedc is used in real cases (single or double precision), and the name stedc is used in complex cases (single or double precision).

Application Notes

The required size of workspace arrays must be as follows.

For sstedc/dstedc:

If compz = 'N' or n 1 then lwork must be at least 1.

If compz = 'V' and n > 1 then lwork must be at least (1 + 3n + 2n·log2n + 4n2), where log2(n) = smallest integer k such that 2kn.

If compz = 'I' and n > 1 then lwork must be at least (1 + 4n + n2).

If compz = 'N' or n 1 then liwork must be at least 1.

If compz = 'V' and n > 1 then liwork must be at least (6 + 6n + 5n·log2n).

If compz = 'I' and n > 1 then liwork must be at least (3 + 5n).

For cstedc/zstedc:

If compz = 'N' or 'I', or n 1, lwork must be at least 1.

If compz = 'V' and n > 1, lwork must be at least n2.

If compz = 'N' or n 1, lrwork must be at least 1.

If compz = 'V' and n > 1, lrwork must be at least (1 + 3n + 2n·log2n + 4n2), where log2(n ) = smallest integer k such that 2kn.

If compz = 'I' and n > 1, lrwork must be at least(1 + 4n + 2n2).

The required value of liwork for complex flavors is the same as for real flavors.

If lwork (or liwork or lrwork, if supplied) is equal to -1, then the routine returns immediately and provides the recommended workspace in the first element of the corresponding array (work, iwork, rwork). This operation is called a workspace query.

Note that if lwork (liwork, lrwork) is less than the minimal required value and is not equal to -1, the routine returns immediately with an error exit and does not provide any information on the recommended workspace.