naginterfaces.library.lapackeig.dtrexc

naginterfaces.library.lapackeig.dtrexc(compq, t, q, ifst, ilst)

dtrexc reorders the Schur factorization of a real general matrix.

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f08/f08qff.html

Parameters

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.

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

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

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.

ifstint

$ifst$ and $ilst$ must specify the reordering of the diagonal elements or blocks of $T$. The element or block with row index $ifst$ is moved to row $ilst$ by a sequence of exchanges between adjacent elements or blocks.

ilstint

$ifst$ and $ilst$ must specify the reordering of the diagonal elements or blocks of $T$. The element or block with row index $ifst$ is moved to row $ilst$ by a sequence of exchanges between adjacent elements or blocks.

Returns

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

$t$ is overwritten by the updated matrix $\tilde{T}$. See also Further Comments.

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

If $compq=\text{'V'}$, $q$ contains the updated matrix of Schur vectors.

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

ifstint

If $ifst$ pointed to the second row of a $2\times 2$ block on entry, it is changed to point to the first row. $ilst$ always points to the first row of the block in its final position (which may differ from its input value by $\pm 1$).

ilstint

If $ifst$ pointed to the second row of a $2\times 2$ block on entry, it is changed to point to the first row. $ilst$ always points to the first row of the block in its final position (which may differ from its input value by $\pm 1$).

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $compq$.

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

(errno $-2$)

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

Constraint: $n\ge 0$.

(errno $-7$)

On entry, error in parameter $ifst$.

(errno $-8$)

On entry, error in parameter $ilst$.

Warns

NagAlgorithmicWarning

(errno $1$)

Two adjacent diagonal elements or blocks could not be successfully exchanged. This error can only occur if the exchange involves at least one $2\times 2$ block; it implies that the problem is very ill-conditioned, and that the eigenvalues of the two blocks are very close. On exit, $T$ may have been partially reordered, and $ilst$ points to the first row of the current position of the block being moved; $Q$ (if requested) is updated consistently with $T$.

Notes

dtrexc reorders the Schur factorization of a real general matrix $A=QT{Q}^T$, so that the diagonal element or block of $T$ with row index $ifst$ is moved to row $ilst$.

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$.

References

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