NAG Library Routine Document

f08ytf (ztgexc)

1
Purpose

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

2
Specification

Fortran Interface
Subroutine f08ytf ( wantq, wantz, 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
C Header Interface
#include <nagmk26.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 its LAPACK name ztgexc.

3
Description

f08ytf (ztgexc) reorders the generalized complex n by n matrix pair S,T in generalized Schur form, so that the diagonal element of S,T with row index i1 is moved to row i2, using a unitary equivalence transformation. That is, S and T are factorized as
S = Q^ S^ Z^H ,   T= Q^ T^ Z^H ,  
where S^,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 f08xnf (zgges), or f08xsf (zhgeqz) with job='S'.
If S and T are the result of a generalized Schur factorization of a matrix pair A,B 
A = QSZH ,   B= QTZH  
then, optionally, the matrices Q and Z can be updated as QQ^ and ZZ^.

4
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 http://www.netlib.org/lapack/lug

5
Arguments

1:     wantq – LogicalInput
On entry: if wantq=.TRUE., update the left transformation matrix Q.
If wantq=.FALSE., do not update Q.
2:     wantz – LogicalInput
On entry: if wantz=.TRUE., update the right transformation matrix Z.
If wantz=.FALSE., do not update Z.
3:     n – IntegerInput
On entry: n, the order of the matrices S and T.
Constraint: n0.
4:     alda* – Complex (Kind=nag_wp) arrayInput/Output
Note: the second dimension of the array a must be at least max1,n.
On entry: the matrix S in the pair S,T.
On exit: the updated matrix S^.
5:     lda – IntegerInput
On entry: the first dimension of the array a as declared in the (sub)program from which f08ytf (ztgexc) is called.
Constraint: ldamax1,n.
6:     bldb* – Complex (Kind=nag_wp) arrayInput/Output
Note: the second dimension of the array b must be at least max1,n.
On entry: the matrix T, in the pair S,T.
On exit: the updated matrix T^ 
7:     ldb – IntegerInput
On entry: the first dimension of the array b as declared in the (sub)program from which f08ytf (ztgexc) is called.
Constraint: ldbmax1,n.
8:     qldq* – Complex (Kind=nag_wp) arrayInput/Output
Note: the second dimension of the array q must be at least max1,n if wantq=.TRUE., and at least 1 otherwise.
On entry: if wantq=.TRUE., the unitary matrix Q.
On exit: if wantq=.TRUE., the updated matrix QQ^.
If wantq=.FALSE., q is not referenced.
9:     ldq – IntegerInput
On entry: the first dimension of the array q as declared in the (sub)program from which f08ytf (ztgexc) is called.
Constraints:
  • if wantq=.TRUE., ldq max1,n ;
  • otherwise ldq1.
10:   zldz* – Complex (Kind=nag_wp) arrayInput/Output
Note: the second dimension of the array z must be at least max1,n if wantz=.TRUE., and at least 1 otherwise.
On entry: if wantz=.TRUE., the unitary matrix Z.
On exit: if wantz=.TRUE., the updated matrix ZZ^.
If wantz=.FALSE., z is not referenced.
11:   ldz – IntegerInput
On entry: the first dimension of the array z as declared in the (sub)program from which f08ytf (ztgexc) is called.
Constraints:
  • if wantz=.TRUE., ldz max1,n ;
  • otherwise ldz1.
12:   ifst – IntegerInput
13:   ilst – IntegerInput/Output
On entry: the indices i1 and i2 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.
On exit: ilst points to the row in its final position.
Constraint: 1ifstn and 1ilstn.
14:   info – IntegerOutput
On exit: info=0 unless the routine detects an error (see Section 6).

6
Error Indicators and Warnings

info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info=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.

7
Accuracy

The computed generalized Schur form is nearly the exact generalized Schur form for nearby matrices S+E and T+F, where
E2 = Oε S2   and   F2= Oε T2 ,  
and ε is the machine precision. See Section 4.11 of Anderson et al. (1999) for further details of error bounds for the generalized nonsymmetric eigenproblem.

8
Parallelism and Performance

f08ytf (ztgexc) is not threaded in any implementation.

9
Further Comments

The real analogue of this routine is f08yff (dtgexc).

10
Example

This example exchanges rows 4 and 1 of the matrix pair S,T, 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.1
Program Text

Program Text (f08ytfe.f90)

10.2
Program Data

Program Data (f08ytfe.d)

10.3
Program Results

Program Results (f08ytfe.r)