Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_ztrexc (f08qt)

## Purpose

nag_lapack_ztrexc (f08qt) reorders the Schur factorization of a complex general matrix.

## Syntax

[t, q, info] = f08qt(compq, t, q, ifst, ilst, 'n', n)
[t, q, info] = nag_lapack_ztrexc(compq, t, q, ifst, ilst, 'n', n)

## Description

nag_lapack_ztrexc (f08qt) reorders the Schur factorization of a complex general matrix $A=QT{Q}^{\mathrm{H}}$, so that the diagonal element of $T$ with row index ifst is moved to row ilst.
The reordered Schur form $\stackrel{~}{T}$ is computed by a unitary similarity transformation: $\stackrel{~}{T}={Z}^{\mathrm{H}}TZ$. Optionally the updated matrix $\stackrel{~}{Q}$ of Schur vectors is computed as $\stackrel{~}{Q}=QZ$, giving $A=\stackrel{~}{Q}\stackrel{~}{T}{\stackrel{~}{Q}}^{\mathrm{H}}$.

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{compq}$ – string (length ≥ 1)
Indicates whether the matrix $Q$ of Schur vectors is to be updated.
${\mathbf{compq}}=\text{'V'}$
The matrix $Q$ of Schur vectors is updated.
${\mathbf{compq}}=\text{'N'}$
No Schur vectors are updated.
Constraint: ${\mathbf{compq}}=\text{'V'}$ or $\text{'N'}$.
2:     $\mathrm{t}\left(\mathit{ldt},:\right)$ – complex array
The first dimension of the array t must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array t must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The $n$ by $n$ upper triangular matrix $T$, as returned by nag_lapack_zhseqr (f08ps).
3:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – complex array
The first dimension, $\mathit{ldq}$, of the array q must satisfy
• if ${\mathbf{compq}}=\text{'V'}$, $\mathit{ldq}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compq}}=\text{'N'}$, $\mathit{ldq}\ge 1$.
The second dimension of the array q must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compq}}=\text{'V'}$ and at least $1$ if ${\mathbf{compq}}=\text{'N'}$.
If ${\mathbf{compq}}=\text{'V'}$, q must contain the $n$ by $n$ unitary matrix $Q$ of Schur vectors.
4:     $\mathrm{ifst}$int64int32nag_int scalar
5:     $\mathrm{ilst}$int64int32nag_int scalar
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: $1\le {\mathbf{ifst}}\le {\mathbf{n}}$ and $1\le {\mathbf{ilst}}\le {\mathbf{n}}$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array t and the second dimension of the array t. (An error is raised if these dimensions are not equal.)
$n$, the order of the matrix $T$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{t}\left(\mathit{ldt},:\right)$ – complex array
The first dimension of the array t will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array t will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
t stores the updated matrix $\stackrel{~}{T}$.
2:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – complex array
The first dimension, $\mathit{ldq}$, of the array q will be
• if ${\mathbf{compq}}=\text{'V'}$, $\mathit{ldq}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compq}}=\text{'N'}$, $\mathit{ldq}=1$.
The second dimension of the array q will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{compq}}=\text{'V'}$ and at least $1$ if ${\mathbf{compq}}=\text{'N'}$.
If ${\mathbf{compq}}=\text{'V'}$, q contains the updated matrix of Schur vectors.
If ${\mathbf{compq}}=\text{'N'}$, q is not referenced.
3:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:
1: compq, 2: n, 3: t, 4: ldt, 5: q, 6: ldq, 7: ifst, 8: ilst, 9: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.

## Accuracy

The computed matrix $\stackrel{~}{T}$ is exactly similar to a matrix $\left(T+E\right)$, where
 $E2 = Oε T2 ,$
and $\epsilon$ is the machine precision.
The values of the eigenvalues are never changed by the reordering.

The total number of real floating-point operations is approximately $20nr$ if ${\mathbf{compq}}=\text{'N'}$, and $40nr$ if ${\mathbf{compq}}=\text{'V'}$, where $r=\left|{\mathbf{ifst}}-{\mathbf{ilst}}\right|$.
The real analogue of this function is nag_lapack_dtrexc (f08qf).

## Example

This example reorders the Schur factorization of the matrix $T$ so that element ${t}_{11}$ is moved to ${t}_{44}$, 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 .$
```function f08qt_example

fprintf('f08qt example results\n\n');

% Matrix T in real Schur form
t = [-6 - 7i,  0.36 - 0.36i, -0.19 + 0.48i,  0.88 - 0.25i;
0 + 0i, -5    + 2i,    -0.03 - 0.72i, -0.23 + 0.13i;
0 + 0i,  0    + 0i,     8    - 1i,     0.94 + 0.53i;
0 + 0i,  0    + 0i,     0    + 0i,     3    - 4i];

% Reorder Schure form so that the first diagonal element is moved to the last
compq = 'No update';
q    = [complex(0)];
ifst = int64(1);
ilst = int64(4);
[t, q, info] = f08qt( ...
compq, t, q, ifst, ilst);

mtitle = 'Reordered Schur Form';
ncols  = int64(80);
indent = int64(0);

[ifail] = x04db( ...
'Gen', ' ', t, 'Brac', 'F7.4', mtitle, ...
'Int', 'Int', ncols, indent);

```
```f08qt example results

Reordered Schur Form
1                 2                 3                 4
1  (-5.0000, 2.0000) (-0.1574, 0.7143) ( 0.1781,-0.1913) ( 0.3950, 0.3861)
2  ( 0.0000, 0.0000) ( 8.0000,-1.0000) ( 1.0742, 0.1447) ( 0.2515,-0.3397)
3  ( 0.0000, 0.0000) ( 0.0000, 0.0000) ( 3.0000,-4.0000) ( 0.2264, 0.8962)
4  ( 0.0000, 0.0000) ( 0.0000, 0.0000) ( 0.0000, 0.0000) (-6.0000,-7.0000)
```