NAG FL Interfacef08ytf (ztgexc)

▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

1Purpose

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

2Specification

Fortran Interface
 Subroutine f08ytf ( n, a, lda, b, ldb, q, ldq, z, ldz, ifst, ilst, info)
 Integer, Intent (In) :: n, lda, ldb, ldq, ldz, ifst Integer, Intent (Inout) :: ilst Integer, Intent (Out) :: info Complex (Kind=nag_wp), Intent (Inout) :: a(lda,*), b(ldb,*), q(ldq,*), z(ldz,*) Logical, Intent (In) :: wantq, wantz
#include <nag.h>
 void f08ytf_ (const logical *wantq, const logical *wantz, const Integer *n, Complex a[], const Integer *lda, Complex b[], const Integer *ldb, Complex q[], const Integer *ldq, Complex z[], const Integer *ldz, const Integer *ifst, Integer *ilst, Integer *info)
The routine may be called by the names f08ytf, nagf_lapackeig_ztgexc or its LAPACK name ztgexc.

3Description

f08ytf reorders the generalized complex $n×n$ matrix pair $\left(S,T\right)$ in generalized Schur form, so that the diagonal element of $\left(S,T\right)$ 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 = Q^ S^ Z^H , T= Q^ T^ Z^H ,$
where $\left(\stackrel{^}{S},\stackrel{^}{T}\right)$ are also in generalized Schur form.
The pair $\left(S,T\right)$ are in generalized Schur form if $S$ and $T$ are upper triangular as returned, for example, by f08xqf, or f08xsf with ${\mathbf{job}}=\text{'S'}$.
If $S$ and $T$ are the result of a generalized Schur factorization of a matrix pair $\left(A,B\right)$
 $A = QSZH , B= QTZH$
then, optionally, the matrices $Q$ and $Z$ can be updated as $Q\stackrel{^}{Q}$ and $Z\stackrel{^}{Z}$.

4References

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

5Arguments

1: $\mathbf{wantq}$Logical Input
On entry: if ${\mathbf{wantq}}=\mathrm{.TRUE.}$, update the left transformation matrix $Q$.
If ${\mathbf{wantq}}=\mathrm{.FALSE.}$, do not update $Q$.
2: $\mathbf{wantz}$Logical Input
On entry: if ${\mathbf{wantz}}=\mathrm{.TRUE.}$, update the right transformation matrix $Z$.
If ${\mathbf{wantz}}=\mathrm{.FALSE.}$, do not update $Z$.
3: $\mathbf{n}$Integer Input
On entry: $n$, the order of the matrices $S$ and $T$.
Constraint: ${\mathbf{n}}\ge 0$.
4: $\mathbf{a}\left({\mathbf{lda}},*\right)$Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry: the matrix $S$ in the pair $\left(S,T\right)$.
On exit: the updated matrix $\stackrel{^}{S}$.
5: $\mathbf{lda}$Integer Input
On entry: the first dimension of the array a as declared in the (sub)program from which f08ytf is called.
Constraint: ${\mathbf{lda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
6: $\mathbf{b}\left({\mathbf{ldb}},*\right)$Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry: the matrix $T$, in the pair $\left(S,T\right)$.
On exit: the updated matrix $\stackrel{^}{T}$
7: $\mathbf{ldb}$Integer Input
On entry: the first dimension of the array b as declared in the (sub)program from which f08ytf is called.
Constraint: ${\mathbf{ldb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
8: $\mathbf{q}\left({\mathbf{ldq}},*\right)$Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array q must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{wantq}}=\mathrm{.TRUE.}$, and at least $1$ otherwise.
On entry: if ${\mathbf{wantq}}=\mathrm{.TRUE.}$, the unitary matrix $Q$.
On exit: if ${\mathbf{wantq}}=\mathrm{.TRUE.}$, the updated matrix $Q\stackrel{^}{Q}$.
If ${\mathbf{wantq}}=\mathrm{.FALSE.}$, q is not referenced.
9: $\mathbf{ldq}$Integer Input
On entry: the first dimension of the array q as declared in the (sub)program from which f08ytf is called.
Constraints:
• if ${\mathbf{wantq}}=\mathrm{.TRUE.}$, ${\mathbf{ldq}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ${\mathbf{ldq}}\ge 1$.
10: $\mathbf{z}\left({\mathbf{ldz}},*\right)$Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array z must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{wantz}}=\mathrm{.TRUE.}$, and at least $1$ otherwise.
On entry: if ${\mathbf{wantz}}=\mathrm{.TRUE.}$, the unitary matrix $Z$.
On exit: if ${\mathbf{wantz}}=\mathrm{.TRUE.}$, the updated matrix $Z\stackrel{^}{Z}$.
If ${\mathbf{wantz}}=\mathrm{.FALSE.}$, z is not referenced.
11: $\mathbf{ldz}$Integer Input
On entry: the first dimension of the array z as declared in the (sub)program from which f08ytf is called.
Constraints:
• if ${\mathbf{wantz}}=\mathrm{.TRUE.}$, ${\mathbf{ldz}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ${\mathbf{ldz}}\ge 1$.
12: $\mathbf{ifst}$Integer Input
13: $\mathbf{ilst}$Integer Input/Output
On entry: the indices ${i}_{1}$ and ${i}_{2}$ that specify the reordering of the diagonal elements of $\left(S,T\right)$. The element with row index ifst is moved to row ilst, by a sequence of swapping between adjacent diagonal elements.
On exit: ilst points to the row in its final position.
Constraint: $1\le {\mathbf{ifst}}\le {\mathbf{n}}$ and $1\le {\mathbf{ilst}}\le {\mathbf{n}}$.
14: $\mathbf{info}$Integer Output
On exit: ${\mathbf{info}}=0$ unless the routine detects an error (see Section 6).

6Error Indicators and Warnings

${\mathbf{info}}<0$
If ${\mathbf{info}}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.
${\mathbf{info}}=1$
The transformed matrix pair would be too far from generalized Schur form; the problem is ill-conditioned. $\left(S,T\right)$ may have been partially reordered, and ilst points to the first row of the current position of the block being moved.

7Accuracy

The computed generalized Schur form is nearly the exact generalized Schur form for nearby matrices $\left(S+E\right)$ and $\left(T+F\right)$, where
 $‖E‖2 = O⁡ε ‖S‖2 and ‖F‖2= O⁡ε ‖T‖2 ,$
and $\epsilon$ is the machine precision. See Section 4.11 of Anderson et al. (1999) for further details of error bounds for the generalized nonsymmetric eigenproblem.

8Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
f08ytf is not threaded in any implementation.

The real analogue of this routine is f08yff.

10Example

This example exchanges rows 4 and 1 of the matrix pair $\left(S,T\right)$, where
 $S = ( 4.0+4.0i 1.0+1.0i 1.0+1.0i 2.0-1.0i 0.0i+0.0 2.0+1.0i 1.0+1.0i 1.0+1.0i 0.0i+0.0 0.0i+0.0 2.0-1.0i 1.0+1.0i 0.0i+0.0 0.0i+0.0 0.0i+0.0 6.0-2.0i )$
and
 $T = ( 2.0 1.0+1.0i 1.0+1.0i 3.0-1.0i 0.0 1.0i+0.0 2.0+1.0i 1.0+1.0i 0.0 0.0i+0.0 1.0i+0.0 1.0+1.0i 0.0 0.0i+0.0 0.0i+0.0 2.0i+0.0 ) .$

10.1Program Text

Program Text (f08ytfe.f90)

10.2Program Data

Program Data (f08ytfe.d)

10.3Program Results

Program Results (f08ytfe.r)