nag_ztgexc (f08ytc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_ztgexc (f08ytc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_ztgexc (f08ytc) reorders the generalized Schur factorization of a complex matrix pair in generalized Schur form.

2  Specification

#include <nag.h>
#include <nagf08.h>
void  nag_ztgexc (Nag_OrderType order, Nag_Boolean wantq, Nag_Boolean wantz, Integer n, Complex a[], Integer pda, Complex b[], Integer pdb, Complex q[], Integer pdq, Complex z[], Integer pdz, Integer ifst, Integer *ilst, NagError *fail)

3  Description

nag_ztgexc (f08ytc) 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 nag_zgges (f08xnc), or nag_zhgeqz (f08xsc) with job=Nag_Schur.
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:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by order=Nag_RowMajor. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: order=Nag_RowMajor or Nag_ColMajor.
2:     wantqNag_BooleanInput
On entry: if wantq=Nag_TRUE, update the left transformation matrix Q.
If wantq=Nag_FALSE, do not update Q.
3:     wantzNag_BooleanInput
On entry: if wantz=Nag_TRUE, update the right transformation matrix Z.
If wantz=Nag_FALSE, do not update Z.
4:     nIntegerInput
On entry: n, the order of the matrices S and T.
Constraint: n0.
5:     a[dim]ComplexInput/Output
Note: the dimension, dim, of the array a must be at least max1,pda×n.
The i,jth element of the matrix A is stored in
  • a[j-1×pda+i-1] when order=Nag_ColMajor;
  • a[i-1×pda+j-1] when order=Nag_RowMajor.
On entry: the matrix S in the pair S,T.
On exit: the updated matrix S^.
6:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraint: pdamax1,n.
7:     b[dim]ComplexInput/Output
Note: the dimension, dim, of the array b must be at least max1,pdb×n.
The i,jth element of the matrix B is stored in
  • b[j-1×pdb+i-1] when order=Nag_ColMajor;
  • b[i-1×pdb+j-1] when order=Nag_RowMajor.
On entry: the matrix T, in the pair S,T.
On exit: the updated matrix T^ 
8:     pdbIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
Constraint: pdbmax1,n.
9:     q[dim]ComplexInput/Output
Note: the dimension, dim, of the array q must be at least
  • max1,pdq×n when wantq=Nag_TRUE;
  • 1 otherwise.
The i,jth element of the matrix Q is stored in
  • q[j-1×pdq+i-1] when order=Nag_ColMajor;
  • q[i-1×pdq+j-1] when order=Nag_RowMajor.
On entry: if wantq=Nag_TRUE, the unitary matrix Q.
On exit: if wantq=Nag_TRUE, the updated matrix QQ^.
If wantq=Nag_FALSE, q is not referenced.
10:   pdqIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array q.
Constraints:
  • if wantq=Nag_TRUE, pdq max1,n ;
  • otherwise pdq1.
11:   z[dim]ComplexInput/Output
Note: the dimension, dim, of the array z must be at least
  • max1,pdz×n when wantz=Nag_TRUE;
  • 1 otherwise.
The i,jth element of the matrix Z is stored in
  • z[j-1×pdz+i-1] when order=Nag_ColMajor;
  • z[i-1×pdz+j-1] when order=Nag_RowMajor.
On entry: if wantz=Nag_TRUE, the unitary matrix Z.
On exit: if wantz=Nag_TRUE, the updated matrix ZZ^.
If wantz=Nag_FALSE, z is not referenced.
12:   pdzIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array z.
Constraints:
  • if wantz=Nag_TRUE, pdz max1,n ;
  • otherwise pdz1.
13:   ifstIntegerInput
14:   ilstInteger *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.
15:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_CONSTRAINT
On entry, wantq=value, pdq=value and n=value.
Constraint: if wantq=Nag_TRUE, pdq max1,n ;
otherwise pdq1.
On entry, wantz=value, pdz=value and n=value.
Constraint: if wantz=Nag_TRUE, pdz max1,n ;
otherwise pdz1.
NE_INT
On entry, n=value.
Constraint: n0.
On entry, pda=value.
Constraint: pda>0.
On entry, pdb=value.
Constraint: pdb>0.
On entry, pdq=value.
Constraint: pdq>0.
On entry, pdz=value.
Constraint: pdz>0.
NE_INT_2
On entry, pda=value and n=value.
Constraint: pdamax1,n.
On entry, pdb=value and n=value.
Constraint: pdbmax1,n.
NE_INT_3
On entry, ifst=value, ilst=value and n=value.
Constraint: 1ifstn and 1ilstn.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_SCHUR
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  Further Comments

The real analogue of this function is nag_dtgexc (f08yfc).

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 (f08ytce.c)

9.2  Program Data

Program Data (f08ytce.d)

9.3  Program Results

Program Results (f08ytce.r)


nag_ztgexc (f08ytc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

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