naginterfaces.library.lapackeig.ztgexc

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

ztgexc reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form.

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

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

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

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

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

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

qcomplex, 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 unitary matrix $Q$.

zcomplex, 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 unitary matrix $Z$.

ifstint

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

ilstint

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

Returns

acomplex, ndarray, shape $(n,n)$

The updated matrix $\hat{S}$.

bcomplex, ndarray, shape $(n,n)$

The updated matrix $\hat{T}$

qcomplex, ndarray, shape $(:,:)$

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

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

zcomplex, ndarray, shape $(:,:)$

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

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

ilstint

$ilst$ points to the row in its final position.

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

ztgexc reorders the generalized complex $n\times n$ matrix pair $(S,T)$ in generalized Schur form, so that the diagonal element of $(S,T)$ with row index $i_1$ is moved to row $i_2$, using a unitary equivalence transformation. That is, $S$ and $T$ are factorized as

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

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

The pair $(S,T)$ are in generalized Schur form if $S$ and $T$ are upper triangular as returned, for example, by zgges3(), or zhgeqz() 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}^H\text{,}B=QT{Z}^H$$

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