NAG FL Interface
f08ytf (ztgexc)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

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

3 Description

f08ytf reorders the generalized complex n×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 f08xqf, or f08xsf 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 https://www.netlib.org/lapack/lug

5 Arguments

1: wantq Logical Input
On entry: if wantq=.TRUE., update the left transformation matrix Q.
If wantq=.FALSE., do not update Q.
2: wantz Logical Input
On entry: if wantz=.TRUE., update the right transformation matrix Z.
If wantz=.FALSE., do not update Z.
3: n Integer Input
On entry: n, the order of the matrices S and T.
Constraint: n0.
4: a(lda,*) Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array a must be at least max(1,n).
On entry: the matrix S in the pair (S,T).
On exit: the updated matrix S^.
5: lda Integer Input
On entry: the first dimension of the array a as declared in the (sub)program from which f08ytf is called.
Constraint: ldamax(1,n).
6: b(ldb,*) Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array b must be at least max(1,n).
On entry: the matrix T, in the pair (S,T).
On exit: the updated matrix T^
7: ldb Integer Input
On entry: the first dimension of the array b as declared in the (sub)program from which f08ytf is called.
Constraint: ldbmax(1,n).
8: q(ldq,*) Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array q must be at least max(1,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 Integer Input
On entry: the first dimension of the array q as declared in the (sub)program from which f08ytf is called.
Constraints:
  • if wantq=.TRUE., ldq max(1,n) ;
  • otherwise ldq1.
10: z(ldz,*) Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array z must be at least max(1,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 Integer Input
On entry: the first dimension of the array z as declared in the (sub)program from which f08ytf is called.
Constraints:
  • if wantz=.TRUE., ldz max(1,n) ;
  • otherwise ldz1.
12: ifst Integer Input
13: ilst Integer Input/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 Integer Output
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

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

9 Further Comments

The real analogue of this routine is f08yff.

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)