naginterfaces.library.lapackeig.dtrsna

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

dtrsna estimates condition numbers for specified eigenvalues and/or right eigenvectors of a real upper quasi-triangular matrix.

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

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f08/f08qlf.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.

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

The $n\times n$ upper quasi-triangular matrix $T$ in canonical Schur form, as returned by dhseqr().

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 real eigenvalue ${\lambda }_j$, $select[j-1]$ must be set $True$. To select condition numbers corresponding to a complex conjugate pair of eigenvalues ${\lambda }_j$ and ${\lambda }_{j+1}$, $select[j-1]$ and/or $select\left[j\right]$ must be set to $True$.

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

vlNone or float, 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}^T$ with $Q$ orthogonal) corresponding to the eigenpairs specified by $howmny$ and $select$. The eigenvectors must be stored in consecutive columns of $vl$, as returned by dtrevc() or dhsein().

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

vrNone or float, 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}^T$ with $Q$ orthogonal) corresponding to the eigenpairs specified by $howmny$ and $select$. The eigenvectors must be stored in consecutive columns of $vr$, as returned by dtrevc() or dhsein().

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). For a complex conjugate pair of eigenvalues, two consecutive elements of $s$ are set to the same value.

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. For a complex eigenvector, two consecutive elements of $sep$ are set to the same value. If the eigenvalues cannot be reordered to compute $sep\left[j\right]$, $sep\left[j\right]$ is set to zero; this can only occur when the true value would be very small anyway.

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

mint

$m$, the number of elements of $s$ and/or $sep$ actually used to store the estimated condition numbers. 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}$.

Notes

dtrsna estimates condition numbers for specified eigenvalues and/or right eigenvectors of a real 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=ZT{Z}^T$ (with orthogonal $Z$), from which $T$ may have been derived.

dtrsna 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 dtrexc() 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^T\\ 0& T_{22}\end{array}\right)Q^T\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