?trsna

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

Date 10/31/2024

Version

Public

Visible to Intel only — GUID: GUID-859D90A3-6336-4C9A-95D2-ABF40FE19965

View Details

?trsna

Estimates condition numbers for specified eigenvalues and right eigenvectors of an upper (quasi-) triangular matrix.

Syntax

call strsna(job, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr, s, sep, mm, m, work, ldwork, iwork, info)

call dtrsna(job, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr, s, sep, mm, m, work, ldwork, iwork, info)

call ctrsna(job, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr, s, sep, mm, m, work, ldwork, rwork, info)

call ztrsna(job, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr, s, sep, mm, m, work, ldwork, rwork, info)

call trsna(t [, s] [,sep] [,vl] [,vr] [,select] [,m] [,info])

Include Files

mkl.fi, mkl_lapack.f90

Description

The routine estimates condition numbers for specified eigenvalues and/or right eigenvectors of an upper triangular matrix T (or, for real flavors, upper quasi-triangular matrix T in canonical Schur form). These are the same as the condition numbers of the eigenvalues and right eigenvectors of an original matrix A = Z*T*Z^H (with unitary or, for real flavors, orthogonal Z), from which T may have been derived.

The routine computes the reciprocal of the condition number of an eigenvalue λ_i as s_i = |v^T*u|/(||u||_E||v||_E) for real flavors and s_i = |v^H*u|/(||u||_E||v||_E) for complex flavors,

where:

u and v are the right and left eigenvectors of T, respectively, corresponding to λ_i.
v^T/v^H denote transpose/conjugate transpose of v, respectively.

This reciprocal condition number always lies between zero (ill-conditioned) and one (well-conditioned).

An approximate error estimate for a computed eigenvalue λ_i is then given by ε*||T||/s_i, where ε is the machine precision.

To estimate the reciprocal of the condition number of the right eigenvector corresponding to λ_i, the routine first calls trexc to reorder the diagonal elements of matrix T so that λ_i is in the leading position:

The reciprocal condition number of the eigenvector is then estimated as sep_i, the smallest singular value of the matrix T₂₂ - λ_i*I.

An approximate error estimate for a computed right eigenvector u corresponding to λ_i is then given by ε*||T||/sep_i.

Input Parameters

job

CHARACTER*1. Must be 'E' or 'V' or 'B'.

If job = 'E', then condition numbers for eigenvalues only are computed.

If job = 'V', then condition numbers for eigenvectors only are computed.

If job = 'B', then condition numbers for both eigenvalues and eigenvectors are computed.

howmny

CHARACTER*1. Must be 'A' or 'S'.

If howmny = 'A', then the condition numbers for all eigenpairs are computed.

If howmny = 'S', then condition numbers for selected eigenpairs (as specified by select) are computed.

select

LOGICAL.

Array, size at least max (1, n) if howmny = 'S' and at least 1 otherwise.

Specifies the eigenpairs for which condition numbers are to be computed if howmny= 'S'.

For real flavors:

To select condition numbers for the eigenpair corresponding to the real eigenvalue λ_j, select(j) must be set .TRUE.;

to select condition numbers for the eigenpair corresponding to a complex conjugate pair of eigenvalues λ_j and λ_{j + 1}), select(j) and/or select(j + 1) must be set .TRUE.

For complex flavors

To select condition numbers for the eigenpair corresponding to the eigenvalue λ_j, select(j) must be set .TRUE.select is not referenced if howmny = 'A'.

n

INTEGER. The order of the matrix T (n≥ 0).

t, vl, vr, work

REAL for strsna

DOUBLE PRECISION for dtrsna

COMPLEX for ctrsna

DOUBLE COMPLEX for ztrsna.

Arrays:

t(ldt,*) contains the n-by-n matrix T.

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

vl(ldvl,*)

If job = 'E' or 'B', then vl must contain the left eigenvectors of T (or of any matrix Q*T*Q^H with Q unitary or orthogonal) corresponding to the eigenpairs specified by howmny and select. The eigenvectors must be stored in consecutive columns of vl, as returned by trevc or hsein.

The second dimension of vl must be at least max(1, mm) if job = 'E' or 'B' and at least 1 if job = 'V'.

The array vl is not referenced if job = 'V'.

vr(ldvr,*)

If job = 'E' or 'B', then vr must contain the right eigenvectors of T (or of any matrix Q*T*Q^H with Q unitary or orthogonal) corresponding to the eigenpairs specified by howmny and select. The eigenvectors must be stored in consecutive columns of vr, as returned by trevc or hsein.

The second dimension of vr must be at least max(1, mm) if job = 'E' or 'B' and at least 1 if job = 'V'.

The array vr is not referenced if job = 'V'.

work is a workspace array, its dimension (ldwork,n+6).

The array work is not referenced if job = 'E'.

ldt

INTEGER. The leading dimension of t; at least max(1, n).

ldvl

INTEGER. The leading dimension of vl.

If job = 'E' or 'B', ldvl≥ max(1,n) .

If job = 'V', ldvl≥ 1.

ldvr

INTEGER. The leading dimension of vr.

If job = 'E' or 'B', ldvr≥ max(1,n) .

If job = 'R', ldvr≥ 1.

mm

INTEGER. The number of elements in the arrays s and sep, and the number of columns in vl and vr (if used). Must be at least m (the precise number required).

If howmny = 'A', mm = n;

if howmny = 'S', for real flavorsmm is obtained by counting 1 for each selected real eigenvalue and 2 for each selected complex conjugate pair of eigenvalues.

for complex flavorsmm is the number of selected eigenpairs (see select). Constraint:

0 ≤mm≤n.

ldwork

INTEGER. The leading dimension of work.

If job = 'V' or 'B', ldwork≥ max(1,n).

If job = 'E', ldwork≥ 1.

rwork

REAL for ctrsna, ztrsna.

Array, size at least max (1, n). The array is not referenced if job = 'E'.

iwork

INTEGER for strsna, dtrsna.

Array, size at least max (1, 2*(n - 1)). The array is not referenced if job = 'E'.

Output Parameters

s

REAL for single-precision flavors

DOUBLE PRECISION for double-precision flavors.

Array, size at least max(1, mm) if job = 'E' or 'B' and at least 1 if job = 'V'.

Contains the reciprocal condition numbers of the selected eigenvalues if job = 'E' or 'B', stored in consecutive elements of the array. Thus s(j), sep(j) and the j-th columns of vl and vr all correspond to the same eigenpair (but not in general the j th eigenpair unless all eigenpairs have been selected).

For real flavors: for a complex conjugate pair of eigenvalues, two consecutive elements of s are set to the same value. The array s is not referenced if job = 'V'.

sep

REAL for single-precision flavors

DOUBLE PRECISION for double-precision flavors.

Array, size at least max(1, mm) if job = 'V' or 'B' and at least 1 if job = 'E'. Contains the estimated reciprocal condition numbers of the selected right eigenvectors if job = 'V' or 'B', stored in consecutive elements of the array.

For real flavors: for a complex eigenvector, two consecutive elements of sep are set to the same value; if the eigenvalues cannot be reordered to compute sep(j), then sep(j) is set to zero; this can only occur when the true value would be very small anyway. The array sep is not referenced if job = 'E'.

m

INTEGER.

For complex flavors: the number of selected eigenpairs.

If howmny = 'A', m is set to n.

For real flavors: the number of elements of s and/or sep actually used to store the estimated condition numbers.

If howmny = 'A', m is set to n.

info

INTEGER.

If info = 0, the execution is successful.

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

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 trsna interface are the following:

t

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

s

Holds the vector of length (mm).

sep

Holds the vector of length (mm).

vl

Holds the matrix VL of size (n,mm).

vr

Holds the matrix VR of size (n,mm).

select

Holds the vector of length n.

job

Restored based on the presence of arguments s and sep as follows:

job = 'B', if both s and sep are present,

job = 'E', if s is present and sep omitted,

job = 'V', if s is omitted and sep present.

Note an error condition if both s and sep are omitted.

howmny

Restored based on the presence of the argument select as follows:

howmny = 'S', if select is present,

howmny = 'A', if select is omitted.

Note that the arguments s, vl, and vr must either be all present or all omitted.

Otherwise, an error condition is observed.

Application Notes

The computed values sep_i may overestimate the true value, but seldom by a factor of more than 3.

Parent topic: Nonsymmetric Eigenvalue Problems: LAPACK Computational Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

?trsna

Syntax

Include Files

Description

Input Parameters

Output Parameters

LAPACK 95 Interface Notes

Application Notes