naginterfaces.library.lapackeig.ztrsen

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

ztrsen reorders the Schur factorization of a complex general matrix so that a selected cluster of eigenvalues appears in the leading elements 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 f08qu

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

Specifies the eigenvalues in the selected cluster. To select a complex eigenvalue ${\lambda }_j$, $select[j-1]$ must be set $True$.

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

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

qcomplex, 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$ unitary matrix $Q$ of Schur vectors, as returned by zhseqr().

Returns

tcomplex, ndarray, shape $(n,n)$

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

qcomplex, 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.

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

The reordered eigenvalues of $\tilde{T}$. The eigenvalues are stored in the same order as on the diagonal of $\tilde{T}$.

mint

$m$, the dimension of the specified invariant subspace, which is the same as the number of selected 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 $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 $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$.

Notes

ztrsen reorders the Schur factorization of a complex general matrix $A=QT{Q}^H$, so that a selected cluster of eigenvalues appears in the leading diagonal elements of the Schur form.

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

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