f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_dtgsna (f08ylc)

## 1  Purpose

nag_dtgsna (f08ylc) estimates condition numbers for specified eigenvalues and/or eigenvectors of a matrix pair in generalized real Schur form.

## 2  Specification

 #include #include
 void nag_dtgsna (Nag_OrderType order, Nag_JobType job, Nag_HowManyType howmny, const Nag_Boolean select[], Integer n, const double a[], Integer pda, const double b[], Integer pdb, const double vl[], Integer pdvl, const double vr[], Integer pdvr, double s[], double dif[], Integer mm, Integer *m, NagError *fail)

## 3  Description

nag_dtgsna (f08ylc) estimates condition numbers for specified eigenvalues and/or right eigenvectors of an $n$ by $n$ matrix pair $\left(S,T\right)$ in real 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 real generalized Schur form if $S$ is block upper triangular with $1$ by $1$ and $2$ by $2$ diagonal blocks and $T$ is upper triangular as returned, for example, by nag_dgges (f08xac), or nag_dhgeqz (f08xec) with ${\mathbf{job}}=\mathrm{Nag_Schur}$. The diagonal elements, or blocks, 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 = QSZT , B = QTZT$
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λ= yTAx 2 + yTBx 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.
The definition of the reciprocal of the estimated condition number of the right eigenvector $x$ and the left eigenvector $y$ corresponding to the simple eigenvalue $\lambda$ depends upon whether $\lambda$ is a real eigenvalue, or one of a complex conjugate pair.
If the eigenvalue $\lambda$ is real and $U$ and $V$ are orthogonal transformations such that
 $UT 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.
If $\lambda$ is part of a complex conjugate pair and $U$ and $V$ are orthogonal transformations such that
 $UT A,B V = S,T = S11 * 0 S22 T11 * 0 T22 ,$
where ${S}_{11}$ and ${T}_{11}$ are two by two matrices, ${S}_{22}$ and ${T}_{22}$ are $\left(n-2\right)$ by $\left(n-2\right)$ matrices, and $\left({S}_{11},{T}_{11}\right)$ corresponds to the complex conjugate eigenvalue pair $\lambda$, $\stackrel{-}{\lambda }$, then there exist unitary matrices ${U}_{1}$ and ${V}_{1}$ such that
 $U1H S11 V1 = s11 s12 0 s22 and U1H T11 V1 = t11 t12 0 t22 .$
The eigenvalues are given by $\lambda ={s}_{11}/{t}_{11}$ and $\stackrel{-}{\lambda }={s}_{22}/{t}_{22}$. Then the Frobenius norm-based, estimated reciprocal condition number is bounded by
 $Difx ≡ Dify ≤ mind1,max1, Res11 / Res22 ,d2$
where $\mathrm{Re}\left(z\right)$ denotes the real part of $z$, ${d}_{1}=\mathrm{Dif}\left(\left({s}_{11},{t}_{11}\right),\left({s}_{22},{t}_{22}\right)\right)={\sigma }_{\mathrm{min}}\left({Z}_{1}\right)$, ${Z}_{1}$ is the complex two by two matrix
 $Z1 = s11 -s22 t11 -t22 ,$
and ${d}_{2}$ is an upper bound on $\mathrm{Dif}\left(\left({S}_{11},{T}_{11}\right),\left({S}_{22},{T}_{22}\right)\right)$; i.e., an upper bound on ${\sigma }_{\mathrm{min}}\left({Z}_{2}\right)$, where ${Z}_{2}$ is the $\left(2n-2\right)$ by $\left(2n-2\right)$ matrix
 $Z2 = S11T⊗I -I⊗S22 T11T⊗I -I⊗T22 .$
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.

## 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
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

## 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 ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     jobNag_JobTypeInput
On entry: indicates whether condition numbers are required for eigenvalues and/or eigenvectors.
${\mathbf{job}}=\mathrm{Nag_EigVals}$
Condition numbers for eigenvalues only are computed.
${\mathbf{job}}=\mathrm{Nag_EigVecs}$
Condition numbers for eigenvectors only are computed.
${\mathbf{job}}=\mathrm{Nag_DoBoth}$
Condition numbers for both eigenvalues and eigenvectors are computed.
Constraint: ${\mathbf{job}}=\mathrm{Nag_EigVals}$, $\mathrm{Nag_EigVecs}$ or $\mathrm{Nag_DoBoth}$.
3:     howmnyNag_HowManyTypeInput
On entry: indicates how many condition numbers are to be computed.
${\mathbf{howmny}}=\mathrm{Nag_ComputeAll}$
Condition numbers for all eigenpairs are computed.
${\mathbf{howmny}}=\mathrm{Nag_ComputeSelected}$
Condition numbers for selected eigenpairs (as specified by select) are computed.
Constraint: ${\mathbf{howmny}}=\mathrm{Nag_ComputeAll}$ or $\mathrm{Nag_ComputeSelected}$.
4:     select[$\mathit{dim}$]const Nag_BooleanInput
Note: the dimension, dim, of the array select must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ when ${\mathbf{howmny}}=\mathrm{Nag_ComputeSelected}$;
• $1$ otherwise.
On entry: specifies the eigenpairs for which condition numbers are to be computed if ${\mathbf{howmny}}=\mathrm{Nag_ComputeSelected}$. To select condition numbers for the eigenpair corresponding to the real eigenvalue ${\lambda }_{j}$, ${\mathbf{select}}\left[j-1\right]$ must be set Nag_TRUE. To select condition numbers corresponding to a complex conjugate pair of eigenvalues ${\lambda }_{j}$ and ${\lambda }_{j+1}$, ${\mathbf{select}}\left[j-1\right]$ and/or ${\mathbf{select}}\left[j\right]$ must be set to Nag_TRUE.
If ${\mathbf{howmny}}=\mathrm{Nag_ComputeAll}$, select is not referenced.
5:     nIntegerInput
On entry: $n$, the order of the matrix pair $\left(S,T\right)$.
Constraint: ${\mathbf{n}}\ge 0$.
6:     a[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pda}}×{\mathbf{n}}\right)$.
The $\left(i,j\right)$th element of the matrix $A$ is stored in
• ${\mathbf{a}}\left[\left(j-1\right)×{\mathbf{pda}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{a}}\left[\left(i-1\right)×{\mathbf{pda}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the upper quasi-triangular matrix $S$.
7:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
8:     b[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdb}}×{\mathbf{n}}\right)$.
The $\left(i,j\right)$th element of the matrix $B$ is stored in
• ${\mathbf{b}}\left[\left(j-1\right)×{\mathbf{pdb}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{b}}\left[\left(i-1\right)×{\mathbf{pdb}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the upper triangular matrix $T$.
9:     pdbIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
10:   vl[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array vl must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdvl}}×{\mathbf{mm}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$ and ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×{\mathbf{pdvl}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$ and ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $1$ otherwise.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{vl}}\left[\left(j-1\right)×{\mathbf{pdvl}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{vl}}\left[\left(i-1\right)×{\mathbf{pdvl}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, 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_dggev (f08wac) or nag_dtgevc (f08ykc).
If ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, vl is not referenced.
11:   pdvlIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array vl.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$,
• if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ${\mathbf{pdvl}}\ge 1$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$,
• if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$;
• otherwise ${\mathbf{pdvl}}\ge 1$.
12:   vr[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array vr must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdvr}}×{\mathbf{mm}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$ and ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×{\mathbf{pdvr}}\right)$ when ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$ and ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $1$ otherwise.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{vr}}\left[\left(j-1\right)×{\mathbf{pdvr}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{vr}}\left[\left(i-1\right)×{\mathbf{pdvr}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, 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_dggev (f08wac) or nag_dtgevc (f08ykc).
If ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, vr is not referenced.
13:   pdvrIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array vr.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$,
• if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ${\mathbf{pdvr}}\ge 1$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$,
• if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$;
• otherwise ${\mathbf{pdvr}}\ge 1$.
14:   s[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array s must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$.
On exit: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array. For a complex conjugate pair of eigenvalues two consecutive elements of s are set to the same value. Thus ${\mathbf{s}}\left[j-1\right]$, ${\mathbf{dif}}\left[j-1\right]$, and the $j$th columns of $\mathrm{VL}$ and $\mathrm{VR}$ all correspond to the same eigenpair (but not in general the $j$th eigenpair, unless all eigenpairs are selected).
If ${\mathbf{job}}=\mathrm{Nag_EigVecs}$, s is not referenced.
15:   dif[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array dif must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$.
On exit: if ${\mathbf{job}}=\mathrm{Nag_EigVecs}$ or $\mathrm{Nag_DoBoth}$, the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array. For a complex eigenvector two consecutive elements of dif are set to the same value. If the eigenvalues cannot be reordered to compute ${\mathbf{dif}}\left[j-1\right]$, ${\mathbf{dif}}\left[j-1\right]$ is set to $0$; this can only occur when the true value would be very small anyway.
If ${\mathbf{job}}=\mathrm{Nag_EigVals}$, dif is not referenced.
16:   mmIntegerInput
On entry: the number of elements in the arrays s and dif.
Constraint: ${\mathbf{mm}}\ge {\mathbf{n}}$.
17:   mInteger *Output
On exit: the number of elements of the arrays s and dif used to store the specified condition numbers; for each selected real eigenvalue one element is used, and for each selected complex conjugate pair of eigenvalues, two elements are used. If ${\mathbf{howmny}}=\mathrm{Nag_ComputeAll}$, m is set to n.
18:   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.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_ENUM_INT_2
On entry, ${\mathbf{job}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvl}}=〈\mathit{\text{value}}〉$, ${\mathbf{mm}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$;
otherwise ${\mathbf{pdvl}}\ge 1$.
On entry, ${\mathbf{job}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvl}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvl}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
otherwise ${\mathbf{pdvl}}\ge 1$.
On entry, ${\mathbf{job}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvr}}=〈\mathit{\text{value}}〉$, ${\mathbf{mm}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mm}}\right)$;
otherwise ${\mathbf{pdvr}}\ge 1$.
On entry, ${\mathbf{job}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdvr}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_DoBoth}$, ${\mathbf{pdvr}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
otherwise ${\mathbf{pdvr}}\ge 1$.
NE_INT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}>0$.
On entry, ${\mathbf{pdb}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdb}}>0$.
On entry, ${\mathbf{pdvl}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdvl}}>0$.
On entry, ${\mathbf{pdvr}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdvr}}>0$.
NE_INT_2
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$ and ${\mathbf{mm}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{mm}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry, ${\mathbf{pdb}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
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

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 complex analogue of this function is nag_ztgsna (f08yyc).

## 9  Example

This example estimates condition numbers and approximate error estimates for all the eigenvalues and eigenvalues and right eigenvectors of the pair $\left(S,T\right)$ given by
 $S = 4.0 1.0 1.0 2.0 0.0 3.0 -1.0 1.0 0.0 1.0 3.0 1.0 0.0 0.0 0.0 6.0 and T= 2.0 1.0 1.0 3.0 0.0 1.0 0.0 1.0 0.0 0.0 1.0 1.0 0.0 0.0 0.0 2.0 .$
The eigenvalues and eigenvectors are computed by calling nag_dtgevc (f08ykc).

### 9.1  Program Text

Program Text (f08ylce.c)

### 9.2  Program Data

Program Data (f08ylce.d)

### 9.3  Program Results

Program Results (f08ylce.r)