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_ztgsna (f08yy)

## Purpose

nag_lapack_ztgsna (f08yy) estimates condition numbers for specified eigenvalues and/or eigenvectors of a complex matrix pair in generalized Schur form.

## Syntax

[s, dif, m, info] = f08yy(job, howmny, select, a, b, vl, vr, mm, 'n', n)
[s, dif, m, info] = nag_lapack_ztgsna(job, howmny, select, a, b, vl, vr, mm, 'n', n)

## Description

nag_lapack_ztgsna (f08yy) estimates condition numbers for specified eigenvalues and/or right eigenvectors of an $n$ by $n$ matrix pair $\left(S,T\right)$ in generalized Schur form. The function actually returns estimates of the reciprocals of the condition numbers in order to avoid possible overflow.
The pair $\left(S,T\right)$ are in generalized Schur form if $S$ and $T$ are upper triangular as returned, for example, by nag_lapack_zgges (f08xn) or nag_lapack_zggesx (f08xp), or nag_lapack_zhgeqz (f08xs) with ${\mathbf{job}}=\text{'S'}$. The diagonal elements define the generalized eigenvalues $\left({\alpha }_{\mathit{i}},{\beta }_{\mathit{i}}\right)$, for $\mathit{i}=1,2,\dots ,n$, of the pair $\left(S,T\right)$ and the eigenvalues are given by
 $λi = αi / βi ,$
so that
 $βi S xi = αi T xi or S xi = λi T xi ,$
where ${x}_{i}$ is the corresponding (right) eigenvector.
If $S$ and $T$ are the result of a generalized Schur factorization of a matrix pair $\left(A,B\right)$
 $A = QSZH , B = QTZH$
then the eigenvalues and condition numbers of the pair $\left(S,T\right)$ are the same as those of the pair $\left(A,B\right)$.
Let $\left(\alpha ,\beta \right)\ne \left(0,0\right)$ be a simple generalized eigenvalue of $\left(A,B\right)$. Then the reciprocal of the condition number of the eigenvalue $\lambda =\alpha /\beta$ is defined as
 $sλ= yHAx 2 + yHBx 2 1/2 x2 y2 ,$
where $x$ and $y$ are the right and left eigenvectors of $\left(A,B\right)$ corresponding to $\lambda$. If both $\alpha$ and $\beta$ are zero, then $\left(A,B\right)$ is singular and $s\left(\lambda \right)=-1$ is returned.
If $U$ and $V$ are unitary transformations such that
 $UH A,B V= S,T = α * 0 S22 β * 0 T22 ,$
where ${S}_{22}$ and ${T}_{22}$ are $\left(n-1\right)$ by $\left(n-1\right)$ matrices, then the reciprocal condition number is given by
 $Difx ≡ Dify = Difα,β,S22,T22 = σmin Z ,$
where ${\sigma }_{\mathrm{min}}\left(Z\right)$ denotes the smallest singular value of the $2\left(n-1\right)$ by $2\left(n-1\right)$ matrix
 $Z = α⊗I -1⊗S22 β⊗I -1⊗T22$
and $\otimes$ is the Kronecker product.
See Sections 2.4.8 and 4.11 of Anderson et al. (1999) and Kågström and Poromaa (1996) for further details and information.

## 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
Kågström B and Poromaa P (1996) LAPACK-style algorithms and software for solving the generalized Sylvester equation and estimating the separation between regular matrix pairs ACM Trans. Math. Software 22 78–103

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{job}$ – string (length ≥ 1)
Indicates whether condition numbers are required for eigenvalues and/or eigenvectors.
${\mathbf{job}}=\text{'E'}$
Condition numbers for eigenvalues only are computed.
${\mathbf{job}}=\text{'V'}$
Condition numbers for eigenvectors only are computed.
${\mathbf{job}}=\text{'B'}$
Condition numbers for both eigenvalues and eigenvectors are computed.
Constraint: ${\mathbf{job}}=\text{'E'}$, $\text{'V'}$ or $\text{'B'}$.
2:     $\mathrm{howmny}$ – string (length ≥ 1)
Indicates how many condition numbers are to be computed.
${\mathbf{howmny}}=\text{'A'}$
Condition numbers for all eigenpairs are computed.
${\mathbf{howmny}}=\text{'S'}$
Condition numbers for selected eigenpairs (as specified by select) are computed.
Constraint: ${\mathbf{howmny}}=\text{'A'}$ or $\text{'S'}$.
3:     $\mathrm{select}\left(:\right)$ – logical array
The dimension of the array select must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{howmny}}=\text{'S'}$, and at least $1$ otherwise
Specifies the eigenpairs for which condition numbers are to be computed if ${\mathbf{howmny}}=\text{'S'}$. To select condition numbers for the eigenpair corresponding to the eigenvalue ${\lambda }_{j}$, ${\mathbf{select}}\left(j\right)$ must be set to true.
If ${\mathbf{howmny}}=\text{'A'}$, select is not referenced.
4:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a must be at least ${\mathbf{n}}$.
The second dimension of the array a must be at least ${\mathbf{n}}$.
The upper triangular matrix $S$.
5:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b must be at least ${\mathbf{n}}$.
The second dimension of the array b must be at least ${\mathbf{n}}$.
The upper triangular matrix $T$.
6:     $\mathrm{vl}\left(\mathit{ldvl},:\right)$ – complex array
The first dimension, $\mathit{ldvl}$, of the array vl must satisfy
• if ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$, $\mathit{ldvl}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldvl}\ge 1$.
The second dimension of the array vl must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$, and at least $1$ otherwise.
If ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$, vl must contain left eigenvectors of $\left(S,T\right)$, corresponding to the eigenpairs specified by howmny and select. The eigenvectors must be stored in consecutive columns of vl, as returned by nag_lapack_zggev (f08wn) or nag_lapack_ztgevc (f08yx).
If ${\mathbf{job}}=\text{'V'}$, vl is not referenced.
7:     $\mathrm{vr}\left(\mathit{ldvr},:\right)$ – complex array
The first dimension, $\mathit{ldvr}$, of the array vr must satisfy
• if ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$, $\mathit{ldvr}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldvr}\ge 1$.
The second dimension of the array vr must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$, and at least $1$ otherwise.
If ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$, vr must contain right eigenvectors of $\left(S,T\right)$, corresponding to the eigenpairs specified by howmny and select. The eigenvectors must be stored in consecutive columns of vr, as returned by nag_lapack_zggev (f08wn) or nag_lapack_ztgevc (f08yx).
If ${\mathbf{job}}=\text{'V'}$, vr is not referenced.
8:     $\mathrm{mm}$int64int32nag_int scalar
The number of elements in the arrays s and dif.
Constraints:
• if ${\mathbf{howmny}}=\text{'A'}$, ${\mathbf{mm}}\ge {\mathbf{n}}$;
• otherwise ${\mathbf{mm}}\ge \text{​ the number of selected eigenvalues}$.

### Optional Input Parameters

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

### Output Parameters

1:     $\mathrm{s}\left(:\right)$ – double array
The dimension of the array s will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$ and $1$ otherwise
If ${\mathbf{job}}=\text{'E'}$ or $\text{'B'}$, the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array.
If ${\mathbf{job}}=\text{'V'}$, s is not referenced.
2:     $\mathrm{dif}\left(:\right)$ – double array
The dimension of the array dif will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$ if ${\mathbf{job}}=\text{'V'}$ or $\text{'B'}$ and $1$ otherwise
If ${\mathbf{job}}=\text{'V'}$ or $\text{'B'}$, the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array. If the eigenvalues cannot be reordered to compute ${\mathbf{dif}}\left(j\right)$, ${\mathbf{dif}}\left(j\right)$ is set to $0$; this can only occur when the true value would be very small anyway.
If ${\mathbf{job}}=\text{'E'}$, dif is not referenced.
3:     $\mathrm{m}$int64int32nag_int scalar
The number of elements of the arrays s and dif used to store the specified condition numbers; for each selected eigenvalue one element is used.
If ${\mathbf{howmny}}=\text{'A'}$, m is set to n.
4:     $\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: job, 2: howmny, 3: select, 4: n, 5: a, 6: lda, 7: b, 8: ldb, 9: vl, 10: ldvl, 11: vr, 12: ldvr, 13: s, 14: dif, 15: mm, 16: m, 17: work, 18: lwork, 19: iwork, 20: 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

None.

An approximate asymptotic error bound on the chordal distance between the computed eigenvalue $\stackrel{~}{\lambda }$ and the corresponding exact eigenvalue $\lambda$ is
 $χλ~,λ ≤ εA,BF / Sλ$
where $\epsilon$ is the machine precision.
An approximate asymptotic error bound for the right or left computed eigenvectors $\stackrel{~}{x}$ or $\stackrel{~}{y}$ corresponding to the right and left eigenvectors $x$ and $y$ is given by
 $θz~,z ≤ ε A,BF / Dif .$
The real analogue of this function is nag_lapack_dtgsna (f08yl).

## Example

This example estimates condition numbers and approximate error estimates for all the eigenvalues and right eigenvectors of the pair $\left(S,T\right)$ given by
 $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 .$
The eigenvalues and eigenvectors are computed by calling nag_lapack_ztgevc (f08yx).
```function f08yy_example

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

% Generalized Schur form pair (S,T)
n = int64(4);
S = [ 4 + 4i,  1 + 1i,  1 + 1i,  2 - 1i;
0 + 0i,  2 + 1i,  1 + 1i,  1 + 1i;
0 + 0i,  0 + 0i,  2 - 1i,  1 + 1i;
0 + 0i,  0 + 0i,  0 + 0i,  6 - 2i];
T = [2,  1 + 1i,  1 + 1i,  3 - 1i;
0 + 0i,  1 + 0i,  2 + 1i,  1 + 1i;
0 + 0i,  0 + 0i,  1 + 0i,  1 + 1i;
0 + 0i,  0 + 0i,  0 + 0i,  2 + 0i];

% Obtain scaled eigenvectors from Schur form
job    = 'Both';
howmny = 'All';
select = [false];
Q = complex(eye(n));
Z = Q;

[VL, VR, m, info] = f08yx( ...
job, howmny, select, S, T, Q, Z, n);

% Estimate condition numbers for eigenvalues and right eigenvectors
[rconde, rcondv, m, info] = ...
f08yy( ...
job, howmny, select, S, T, VL, VR, n);

disp('Reciprocal condition numbers for eigenvalues of (S,T)');
fprintf('%11.1e',rconde);
fprintf('\n\n');
disp('Reciprocal condition numbers for right eigenvectors of (S,T)');
fprintf('%11.1e',rcondv);
fprintf('\n\n');

% Calculate approximate error estimates

snorm = norm(S,1);
tnorm = norm(T,1);
stnorm = sqrt(snorm^2 + tnorm^2);

disp('Approximate error estimates for eigenvalues of (S,T)')
erre = x02aj*stnorm./rconde;
fprintf('%11.1e',erre);
fprintf('\n\n');
disp('Approximate error estimates for right eigenvectors of (S,T)')
errv = x02aj*stnorm./rcondv;
fprintf('%11.1e',errv);
fprintf('\n');

```
```f08yy example results

Reciprocal condition numbers for eigenvalues of (S,T)
1.0e+00    8.2e-01    7.2e-01    8.2e-01

Reciprocal condition numbers for right eigenvectors of (S,T)
3.2e-01    3.6e-01    5.5e-01    2.8e-01

Approximate error estimates for eigenvalues of (S,T)
1.5e-15    1.9e-15    2.1e-15    1.9e-15

Approximate error estimates for right eigenvectors of (S,T)
4.8e-15    4.3e-15    2.8e-15    5.5e-15
```