naginterfaces.library.lapackeig.ztrsna

naginterfaces.library.lapackeig.ztrsna(job, howmny, t, select=None, vl=None, vr=None)

ztrsna estimates condition numbers for specified eigenvalues and/or right eigenvectors of a complex upper triangular matrix.

For full information please refer to the NAG Library document for f08qy

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08qyf.html

Parameters

jobstr, length 1

Indicates whether condition numbers are required for eigenvalues and/or eigenvectors.

$job=\text{'E'}$

Condition numbers for eigenvalues only are computed.

$job=\text{'V'}$

Condition numbers for eigenvectors only are computed.

$job=\text{'B'}$

Condition numbers for both eigenvalues and eigenvectors are computed.

howmnystr, length 1

Indicates how many condition numbers are to be computed.

$howmny=\text{'A'}$

Condition numbers for all eigenpairs are computed.

$howmny=\text{'S'}$

Condition numbers for selected eigenpairs (as specified by $select$) are computed.

tcomplex, array-like, shape $(n,n)$

The $n\times n$ upper triangular matrix $T$, as returned by zhseqr().

selectNone or bool, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $howmny=\text{'S'}$: $n$; otherwise: $1$.

Specifies the eigenpairs for which condition numbers are to be computed if $howmny=\text{'S'}$. To select condition numbers for the eigenpair corresponding to the eigenvalue ${\lambda }_j$, $select[j-1]$ must be set to $True$.

If $howmny=\text{'A'}$, $select$ is not referenced.

vlNone or complex, array-like, shape $(:,:)$, optional

Note: the required extent for this argument in dimension 1 is determined as follows: if $job\text{in}(\text{'E'},\text{'B'})$: $n$; if $job=\text{'V'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $job\text{in}(\text{'E'},\text{'B'})$: $\text{mm}$; otherwise: $0$.

If $job=\text{'E'}$ or $\text{'B'}$, $vl$ must contain the left eigenvectors of $T$ (or of any matrix $QT{Q}^H$ with $Q$ unitary) corresponding to the eigenpairs specified by $howmny$ and $select$. The eigenvectors must be stored in consecutive columns of $vl$, as returned by ztrevc() or zhsein().

If $job=\text{'V'}$, $vl$ is not referenced.

vrNone or complex, array-like, shape $(:,:)$, optional

Note: the required extent for this argument in dimension 1 is determined as follows: if $job\text{in}(\text{'E'},\text{'B'})$: $n$; if $job=\text{'V'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $job\text{in}(\text{'E'},\text{'B'})$: $\text{mm}$; otherwise: $0$.

If $job=\text{'E'}$ or $\text{'B'}$, $vr$ must contain the right eigenvectors of $T$ (or of any matrix $QT{Q}^H$ with $Q$ unitary) corresponding to the eigenpairs specified by $howmny$ and $select$. The eigenvectors must be stored in consecutive columns of $vr$, as returned by ztrevc() or zhsein().

If $job=\text{'V'}$, $vr$ is not referenced.

Returns

sNone or float, ndarray, shape $(:)$

The reciprocal condition numbers of the selected eigenvalues if $job=\text{'E'}$ or $\text{'B'}$, stored in consecutive elements of the array. Thus $s[j-1]$, $sep[j-1]$ 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).

If $job=\text{'V'}$, $s$ is not referenced.

sepNone or float, ndarray, shape $(:)$

The estimated reciprocal condition numbers of the selected right eigenvectors if $job=\text{'V'}$ or $\text{'B'}$, stored in consecutive elements of the array.

If $job=\text{'E'}$, $sep$ is not referenced.

mint

$\text{m}$, the number of selected eigenpairs. If $howmny=\text{'A'}$, $m$ is set to $n$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $job$.

Constraint: $job=\text{'E'}$, $\text{'V'}$ or $\text{'B'}$.

(errno $-2$)

On entry, error in parameter $howmny$.

Constraint: $howmny=\text{'A'}$ or $\text{'S'}$.

(errno $-4$)

On entry, error in parameter $\text{n}$.

Constraint: $n\ge 0$.

(errno $-13$)

On entry, error in parameter $\text{mm}$.

Constraint: $\text{mm}\ge n$.

(errno $-13$)

On entry, error in parameter $\text{mm}$.

Constraint: $\text{mm}\ge \text{m}$.

Notes

ztrsna estimates condition numbers for specified eigenvalues and/or right eigenvectors of a complex upper triangular matrix $T$. These are the same as the condition numbers of the eigenvalues and right eigenvectors of an original matrix $A=ZT{Z}^H$ (with unitary $Z$), from which $T$ may have been derived.

ztrsna computes the reciprocal of the condition number of an eigenvalue ${\lambda }_i$ as

$$s_i=\frac{\left|v^{H}u\right|}{{\parallel u\parallel }_E{\parallel v\parallel }_E}\text{,}$$

where $u$ and $v$ are the right and left eigenvectors of $T$, respectively, corresponding to ${\lambda }_i$. This reciprocal condition number always lies between zero (i.e., ill-conditioned) and one (i.e., well-conditioned).

An approximate error estimate for a computed eigenvalue ${\lambda }_i$ is then given by

$$\frac{ϵ\parallel T\parallel }{s_i}\text{,}$$

where $ϵ$ is the machine precision.

To estimate the reciprocal of the condition number of the right eigenvector corresponding to ${\lambda }_i$, the function first calls ztrexc() to reorder the eigenvalues so that ${\lambda }_i$ is in the leading position:

$$\begin{array}{c}T=Q\left(\begin{array}{cc}{\lambda }_i& c^H\\ 0& T_{22}\end{array}\right)Q^H\text{.}\end{array}$$

The reciprocal condition number of the eigenvector is then estimated as ${\text{sep}}_i$, the smallest singular value of the matrix $(T_{22}-{\lambda }_{i}I)$. This number ranges from zero (i.e., ill-conditioned) to very large (i.e., well-conditioned).

An approximate error estimate for a computed right eigenvector $u$ corresponding to ${\lambda }_i$ is then given by

$$\frac{ϵ\parallel T\parallel }{{\text{sep}}_i}\text{.}$$

References

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore