naginterfaces.library.lapackeig.dtrsen

naginterfaces.library.lapackeig.dtrsen(job, compq, select, t, q)

dtrsen reorders the Schur factorization of a real general matrix so that a selected cluster of eigenvalues appears in the leading elements or blocks on the diagonal of the Schur form. The function also optionally computes the reciprocal condition numbers of the cluster of eigenvalues and/or the invariant subspace.

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

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f08/f08qgf.html

Parameters

jobstr, length 1

Indicates whether condition numbers are required for the cluster of eigenvalues and/or the invariant subspace.

$job=\text{'N'}$

No condition numbers are required.

$job=\text{'E'}$

Only the condition number for the cluster of eigenvalues is computed.

$job=\text{'V'}$

Only the condition number for the invariant subspace is computed.

$job=\text{'B'}$

Condition numbers for both the cluster of eigenvalues and the invariant subspace are computed.

compqstr, length 1

Indicates whether the matrix $Q$ of Schur vectors is to be updated.

$compq=\text{'V'}$

The matrix $Q$ of Schur vectors is updated.

$compq=\text{'N'}$

No Schur vectors are updated.

selectbool, array-like, shape $\left(n\right)$

The eigenvalues in the selected cluster. To select a real eigenvalue ${\lambda }_j$, $select[j-1]$ must be set $True$. To select a complex conjugate pair of eigenvalues ${\lambda }_j$ and ${\lambda }_{j+1}$ (corresponding to a $2\times 2$ diagonal block), $select[j-1]$ and/or $select\left[j\right]$ must be set to $True$. A complex conjugate pair of eigenvalues must be either both included in the cluster or both excluded. See also Further Comments.

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

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

qfloat, array-like, shape $(:,:)$

Note: the required extent for this argument in dimension 1 is determined as follows: if $compq=\text{'V'}$: $n$; if $compq=\text{'N'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $compq=\text{'V'}$: $n$; if $compq=\text{'N'}$: $1$; otherwise: $0$.

If $compq=\text{'V'}$, $q$ must contain the $n\times n$ orthogonal matrix $Q$ of Schur vectors, as returned by dhseqr().

Returns

tfloat, ndarray, shape $(n,n)$

$t$ is overwritten by the updated matrix $\tilde{T}$.

qfloat, ndarray, shape $(:,:)$

If $compq=\text{'V'}$, $q$ contains the updated matrix of Schur vectors; the first $m$ columns of $Q$ form an orthonormal basis for the specified invariant subspace.

If $compq=\text{'N'}$, $q$ is not referenced.

wrfloat, ndarray, shape $\left(n\right)$

The real and imaginary parts, respectively, of the reordered eigenvalues of $\tilde{T}$. The eigenvalues are stored in the same order as on the diagonal of $\tilde{T}$; see Further Comments for details. Note that if a complex eigenvalue is sufficiently ill-conditioned, then its value may differ significantly from its value before reordering.

wifloat, ndarray, shape $\left(n\right)$

The real and imaginary parts, respectively, of the reordered eigenvalues of $\tilde{T}$. The eigenvalues are stored in the same order as on the diagonal of $\tilde{T}$; see Further Comments for details. Note that if a complex eigenvalue is sufficiently ill-conditioned, then its value may differ significantly from its value before reordering.

mint

$m$, the dimension of the specified invariant subspace. The value of $m$ is obtained by counting $1$ for each selected real eigenvalue and $2$ for each selected complex conjugate pair of eigenvalues (see $select$); $0\le m\le n$.

sfloat

If $job=\text{'E'}$ or $\text{'B'}$, $s$ is a lower bound on the reciprocal condition number of the average of the selected cluster of eigenvalues. If $m=0$ or $n$, $s=1$; if $errno$ = 1 (see Exceptions), $s$ is set to zero.

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

sepfloat

If $job=\text{'V'}$ or $\text{'B'}$, $sep$ is the estimated reciprocal condition number of the specified invariant subspace. If $m=0$ or $n$, $sep=\parallel T\parallel$; if $errno$ = 1 (see Exceptions), $sep$ is set to zero.

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

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $job$.

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

(errno $-2$)

On entry, error in parameter $compq$.

Constraint: $compq=\text{'V'}$ or $\text{'N'}$.

(errno $-4$)

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

Constraint: $n\ge 0$.

Warns

NagAlgorithmicWarning

(errno $1$)

The reordering of $T$ failed because a selected eigenvalue was too close to an unselected eigenvalue.

Notes

dtrsen reorders the Schur factorization of a real general matrix $A=QT{Q}^T$, so that a selected cluster of eigenvalues appears in the leading diagonal elements or blocks of the Schur form.

The reordered Schur form $\tilde{T}$ is computed by an orthogonal similarity transformation: $\tilde{T}=Z^{T}TZ$. Optionally the updated matrix $\tilde{Q}$ of Schur vectors is computed as $\tilde{Q}=QZ$, giving $A=\tilde{Q}\tilde{T}{\tilde{Q}}^T$.

Let $\tilde{T}=\left(\begin{array}{cc}{T}_{11}& T_{12}\\ 0& T_{22}\end{array}\right)$, where the selected eigenvalues are precisely the eigenvalues of the leading $m\times m$ sub-matrix $T_{11}$. Let $\tilde{Q}$ be correspondingly partitioned as $\left(\begin{array}{cc}{Q}_1& Q_2\end{array}\right)$ where $Q_1$ consists of the first $m$ columns of $Q$. Then $A{Q}_1=Q_1{T}_{11}$, and so the $m$ columns of $Q_1$ form an orthonormal basis for the invariant subspace corresponding to the selected cluster of eigenvalues.

Optionally the function also computes estimates of the reciprocal condition numbers of the average of the cluster of eigenvalues and of the invariant subspace.

References

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