naginterfaces.library.lapackeig.dtgexc

naginterfaces.library.lapackeig.dtgexc(wantq, wantz, a, b, q, z, ifst, ilst)

dtgexc reorders the generalized Schur factorization of a matrix pair in real generalized Schur form.

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

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

Parameters

wantqbool

If $wantq=True$, update the left transformation matrix $Q$.

If $wantq=False$, do not update $Q$.

wantzbool

If $wantz=True$, update the right transformation matrix $Z$.

If $wantz=False$, do not update $Z$.

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

The matrix $S$ in the pair $(S,T)$.

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

The matrix $T$, in the pair $(S,T)$.

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

Note: the required extent for this argument in dimension 1 is determined as follows: if $wantq=True$: $n$; otherwise: $1$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $wantq=True$: $n$; otherwise: $1$.

If $wantq=True$, the orthogonal matrix $Q$.

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

Note: the required extent for this argument in dimension 1 is determined as follows: if $wantz=True$: $n$; otherwise: $1$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $wantz=True$: $n$; otherwise: $1$.

If $wantz=True$, the orthogonal matrix $Z$.

ifstint

The indices $i_1$ and $i_2$ that specify the reordering of the diagonal blocks of $(S,T)$. The block with row index $ifst$ is moved to row $ilst$, by a sequence of swapping between adjacent blocks.

ilstint

The indices $i_1$ and $i_2$ that specify the reordering of the diagonal blocks of $(S,T)$. The block with row index $ifst$ is moved to row $ilst$, by a sequence of swapping between adjacent blocks.

Returns

afloat, ndarray, shape $(n,n)$

The updated matrix $\hat{S}$.

bfloat, ndarray, shape $(n,n)$

The updated matrix $\hat{T}$

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

If $wantq=True$, the updated matrix $Q\hat{Q}$.

If $wantq=False$, $q$ is not referenced.

zfloat, ndarray, shape $(:,:)$

If $wantz=True$, the updated matrix $Z\hat{Z}$.

If $wantz=False$, $z$ is not referenced.

ifstint

If $ifst$ pointed on entry to the second row of a $2\times 2$ block, 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 $+1$ or $-1$).

ilstint

If $ifst$ pointed on entry to the second row of a $2\times 2$ block, 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 $+1$ or $-1$).

Raises

NagValueError

(errno $-3$)

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

Constraint: $n\ge 0$.

(errno $-13$)

On entry, error in parameter $ilst$.

Constraint: $1\le ifst\le n$ and $1\le ilst\le n$.

(errno $1$)

The transformed matrix pair would be too far from generalized Schur form; the problem is ill-conditioned. $(S,T)$ may have been partially reordered, and $ilst$ points to the first row of the current position of the block being moved.

Notes

dtgexc reorders the generalized real $n\times n$ matrix pair $(S,T)$ in real generalized Schur form, so that the diagonal element or block of $(S,T)$ with row index $i_1$ is moved to row $i_2$, using an orthogonal equivalence transformation. That is, $S$ and $T$ are factorized as

$$S=\hat{Q}\hat{S}{\hat{Z}}^T\text{,}T=\hat{Q}\hat{T}{\hat{Z}}^T\text{,}$$

where $(\hat{S},\hat{T})$ are also in real generalized Schur form.

The pair $(S,T)$ are in real generalized Schur form if $S$ is block upper triangular with $1\times 1$ and $2\times 2$ diagonal blocks and $T$ is upper triangular as returned, for example, by dgges3(), or dhgeqz() with $\text{job}=\text{'S'}$.

If $S$ and $T$ are the result of a generalized Schur factorization of a matrix pair $(A,B)$

$$A=QS{Z}^T\text{,}B=QT{Z}^T$$

then, optionally, the matrices $Q$ and $Z$ can be updated as $Q\hat{Q}$ and $Z\hat{Z}$.

References

Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, LAPACK Users’ Guide, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug