nag_ztrexc (f08qtc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_ztrexc (f08qtc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_ztrexc (f08qtc) reorders the Schur factorization of a complex general matrix.

2  Specification

#include <nag.h>
#include <nagf08.h>
void  nag_ztrexc (Nag_OrderType order, Nag_ComputeQType compq, Integer n, Complex t[], Integer pdt, Complex q[], Integer pdq, Integer ifst, Integer ilst, NagError *fail)

3  Description

nag_ztrexc (f08qtc) reorders the Schur factorization of a complex general matrix A=QTQH, so that the diagonal element of T with row index ifst is moved to row ilst.
The reordered Schur form T~ is computed by a unitary similarity transformation: T~=ZHTZ. Optionally the updated matrix Q~ of Schur vectors is computed as Q~=QZ, giving A=Q~T~Q~H.

4  References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

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:     compqNag_ComputeQTypeInput
On entry: indicates whether the matrix Q of Schur vectors is to be updated.
compq=Nag_UpdateSchur
The matrix Q of Schur vectors is updated.
compq=Nag_NotQ
No Schur vectors are updated.
Constraint: compq=Nag_UpdateSchur or Nag_NotQ.
3:     nIntegerInput
On entry: n, the order of the matrix T.
Constraint: n0.
4:     t[dim]ComplexInput/Output
Note: the dimension, dim, of the array t must be at least max1,pdt×n.
The i,jth element of the matrix T is stored in
  • t[j-1×pdt+i-1] when order=Nag_ColMajor;
  • t[i-1×pdt+j-1] when order=Nag_RowMajor.
On entry: the n by n upper triangular matrix T, as returned by nag_zhseqr (f08psc).
On exit: t is overwritten by the updated matrix T~.
5:     pdtIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array t.
Constraint: pdt max1,n .
6:     q[dim]ComplexInput/Output
Note: the dimension, dim, of the array q must be at least
  • max1,pdq×n when compq=Nag_UpdateSchur;
  • 1 when compq=Nag_NotQ.
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 compq=Nag_UpdateSchur, q must contain the n by n unitary matrix Q of Schur vectors.
On exit: if compq=Nag_UpdateSchur, q contains the updated matrix of Schur vectors.
If compq=Nag_NotQ, q is not referenced.
7:     pdqIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array q.
Constraints:
  • if compq=Nag_UpdateSchur, pdq max1,n ;
  • if compq=Nag_NotQ, pdq1.
8:     ifstIntegerInput
9:     ilstIntegerInput
On entry: ifst and ilst must specify the reordering of the diagonal elements of T. The element with row index ifst is moved to row ilst by a sequence of exchanges between adjacent elements.
Constraint: 1ifstn and 1ilstn.
10:   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_ENUM_INT_2
On entry, compq=value, pdq=value and n=value.
Constraint: if compq=Nag_UpdateSchur, pdq max1,n ;
if compq=Nag_NotQ, pdq1.
NE_INT
On entry, n=value.
Constraint: n0.
On entry, pdq=value.
Constraint: pdq>0.
On entry, pdt=value.
Constraint: pdt>0.
NE_INT_2
On entry, pdt=value and n=value.
Constraint: pdt max1,n .
NE_INT_3
On entry, n=value, ifst=value and ilst=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.

7  Accuracy

The computed matrix T~ is exactly similar to a matrix T+E, where
E2 = Oε T2 ,
and ε is the machine precision.
The values of the eigenvalues are never changed by the reordering.

8  Further Comments

The total number of real floating point operations is approximately 20nr if compq=Nag_NotQ, and 40nr if compq=Nag_UpdateSchur, where r=ifst-ilst.
The real analogue of this function is nag_dtrexc (f08qfc).

9  Example

This example reorders the Schur factorization of the matrix T so that element t11 is moved to t44, where
T = -6.00-7.00i 0.36-0.36i -0.19+0.48i 0.88-0.25i 0.00+0.00i -5.00+2.00i -0.03-0.72i -0.23+0.13i 0.00+0.00i 0.00+0.00i 8.00-1.00i 0.94+0.53i 0.00+0.00i 0.00+0.00i 0.00+0.00i 3.00-4.00i .

9.1  Program Text

Program Text (f08qtce.c)

9.2  Program Data

Program Data (f08qtce.d)

9.3  Program Results

Program Results (f08qtce.r)


nag_ztrexc (f08qtc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

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