F08YTF (ZTGEXC) (PDF version)
F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

F08YTF (ZTGEXC)

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

F08YTF (ZTGEXC) reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form.

2  Specification

SUBROUTINE F08YTF ( WANTQ, WANTZ, N, A, LDA, B, LDB, Q, LDQ, Z, LDZ, IFST, ILST, INFO)
INTEGER  N, LDA, LDB, LDQ, LDZ, IFST, ILST, INFO
COMPLEX (KIND=nag_wp)  A(LDA,*), B(LDB,*), Q(LDQ,*), Z(LDZ,*)
LOGICAL  WANTQ, WANTZ
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  Parameters

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:     A(LDA,*) – 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:     B(LDB,*) – 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:     Q(LDQ,*) – 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:   Z(LDZ,*) – 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

Errors or warnings detected by the routine:
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 S^,T^ 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  Further Comments

The real analogue of this routine is F08YFF (DTGEXC).

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

9.1  Program Text

Program Text (f08ytfe.f90)

9.2  Program Data

Program Data (f08ytfe.d)

9.3  Program Results

Program Results (f08ytfe.r)


F08YTF (ZTGEXC) (PDF version)
F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012