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_zhseqr (f08ps)

## Purpose

nag_lapack_zhseqr (f08ps) computes all the eigenvalues and, optionally, the Schur factorization of a complex Hessenberg matrix or a complex general matrix which has been reduced to Hessenberg form.

## Syntax

[h, w, z, info] = f08ps(job, compz, ilo, ihi, h, z, 'n', n)
[h, w, z, info] = nag_lapack_zhseqr(job, compz, ilo, ihi, h, z, 'n', n)

## Description

nag_lapack_zhseqr (f08ps) computes all the eigenvalues and, optionally, the Schur factorization of a complex upper Hessenberg matrix H$H$:
 H = ZTZH , $H = ZTZH ,$
where T$T$ is an upper triangular matrix (the Schur form of H$H$), and Z$Z$ is the unitary matrix whose columns are the Schur vectors zi${z}_{i}$. The diagonal elements of T$T$ are the eigenvalues of H$H$.
The function may also be used to compute the Schur factorization of a complex general matrix A$A$ which has been reduced to upper Hessenberg form H$H$:
 A = QHQH, where ​Q​ is unitary, = (QZ)T(QZ)H.
$A = QHQH, where ​Q​ is unitary, = (QZ)T(QZ)H.$
In this case, after nag_lapack_zgehrd (f08ns) has been called to reduce A$A$ to Hessenberg form, nag_lapack_zunghr (f08nt) must be called to form Q$Q$ explicitly; Q$Q$ is then passed to nag_lapack_zhseqr (f08ps), which must be called with compz = 'V'${\mathbf{compz}}=\text{'V'}$.
The function can also take advantage of a previous call to nag_lapack_zgebal (f08nv) which may have balanced the original matrix before reducing it to Hessenberg form, so that the Hessenberg matrix H$H$ has the structure:
 H11 H12 H13 H22 H23 H33
$H11 H12 H13 H22 H23 H33$
where H11${H}_{11}$ and H33${H}_{33}$ are upper triangular. If so, only the central diagonal block H22${H}_{22}$ (in rows and columns ilo${i}_{\mathrm{lo}}$ to ihi${i}_{\mathrm{hi}}$) needs to be further reduced to Schur form (the blocks H12${H}_{12}$ and H23${H}_{23}$ are also affected). Therefore the values of ilo${i}_{\mathrm{lo}}$ and ihi${i}_{\mathrm{hi}}$ can be supplied to nag_lapack_zhseqr (f08ps) directly. Also, nag_lapack_zgebak (f08nw) must be called after this function to permute the Schur vectors of the balanced matrix to those of the original matrix. If nag_lapack_zgebal (f08nv) has not been called however, then ilo${i}_{\mathrm{lo}}$ must be set to 1$1$ and ihi${i}_{\mathrm{hi}}$ to n$n$. Note that if the Schur factorization of A$A$ is required, nag_lapack_zgebal (f08nv) must not be called with job = 'S'${\mathbf{job}}=\text{'S'}$ or 'B'$\text{'B'}$, because the balancing transformation is not unitary.
nag_lapack_zhseqr (f08ps) uses a multishift form of the upper Hessenberg QR$QR$ algorithm, due to Bai and Demmel (1989). The Schur vectors are normalized so that zi2 = 1${‖{z}_{i}‖}_{2}=1$, but are determined only to within a complex factor of absolute value 1$1$.

## References

Bai Z and Demmel J W (1989) On a block implementation of Hessenberg multishift QR$QR$ iteration Internat. J. High Speed Comput. 1 97–112
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     job – string (length ≥ 1)
Indicates whether eigenvalues only or the Schur form T$T$ is required.
job = 'E'${\mathbf{job}}=\text{'E'}$
Eigenvalues only are required.
job = 'S'${\mathbf{job}}=\text{'S'}$
The Schur form T$T$ is required.
Constraint: job = 'E'${\mathbf{job}}=\text{'E'}$ or 'S'$\text{'S'}$.
2:     compz – string (length ≥ 1)
Indicates whether the Schur vectors are to be computed.
compz = 'N'${\mathbf{compz}}=\text{'N'}$
No Schur vectors are computed (and the array z is not referenced).
compz = 'I'${\mathbf{compz}}=\text{'I'}$
The Schur vectors of H$H$ are computed (and the array z is initialized by the function).
compz = 'V'${\mathbf{compz}}=\text{'V'}$
The Schur vectors of A$A$ are computed (and the array z must contain the matrix Q$Q$ on entry).
Constraint: compz = 'N'${\mathbf{compz}}=\text{'N'}$, 'V'$\text{'V'}$ or 'I'$\text{'I'}$.
3:     ilo – int64int32nag_int scalar
4:     ihi – int64int32nag_int scalar
If the matrix A$A$ has been balanced by nag_lapack_zgebal (f08nv), then ilo and ihi must contain the values returned by that function. Otherwise, ilo must be set to 1$1$ and ihi to n.
Constraint: ilo1${\mathbf{ilo}}\ge 1$ and min (ilo,n) ihin $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ilo}},{\mathbf{n}}\right)\le {\mathbf{ihi}}\le {\mathbf{n}}$.
5:     h(ldh, : $:$) – complex array
The first dimension of the array h must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The n$n$ by n$n$ upper Hessenberg matrix H$H$, as returned by nag_lapack_zgehrd (f08ns).
6:     z(ldz, : $:$) – complex array
The first dimension, ldz, of the array z must satisfy
• if compz = 'I'${\mathbf{compz}}=\text{'I'}$ or 'V'$\text{'V'}$, ldz max (1,n) $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if compz = 'N'${\mathbf{compz}}=\text{'N'}$, ldz1$\mathit{ldz}\ge 1$.
The second dimension of the array must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$ and at least 1$1$ if compz = 'N'${\mathbf{compz}}=\text{'N'}$
If compz = 'V'${\mathbf{compz}}=\text{'V'}$, z must contain the unitary matrix Q$Q$ from the reduction to Hessenberg form.
If compz = 'I'${\mathbf{compz}}=\text{'I'}$, z need not be set.

### Optional Input Parameters

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

### Input Parameters Omitted from the MATLAB Interface

ldh ldz work lwork

### Output Parameters

1:     h(ldh, : $:$) – complex array
The first dimension of the array h will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
ldhmax (1,n)$\mathit{ldh}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
If job = 'E'${\mathbf{job}}=\text{'E'}$, the array contains no useful information.
If job = 'S'${\mathbf{job}}=\text{'S'}$, h stores the upper triangular matrix T$T$ from the Schur decomposition (the Schur form) unless ${\mathbf{INFO}}>{\mathbf{0}}$.
2:     w( : $:$) – complex array
Note: the dimension of the array w must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The computed eigenvalues, unless ${\mathbf{INFO}}>{\mathbf{0}}$ (in which case see Section [Error Indicators and Warnings]). The eigenvalues are stored in the same order as on the diagonal of the Schur form T$T$ (if computed).
3:     z(ldz, : $:$) – complex array
The first dimension, ldz, of the array z will be
• if compz = 'I'${\mathbf{compz}}=\text{'I'}$ or 'V'$\text{'V'}$, ldz max (1,n) $\mathit{ldz}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if compz = 'N'${\mathbf{compz}}=\text{'N'}$, ldz1$\mathit{ldz}\ge 1$.
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$ and at least 1$1$ if compz = 'N'${\mathbf{compz}}=\text{'N'}$
If compz = 'V'${\mathbf{compz}}=\text{'V'}$ or 'I'$\text{'I'}$, z contains the unitary matrix of the required Schur vectors, unless ${\mathbf{INFO}}>{\mathbf{0}}$.
If compz = 'N'${\mathbf{compz}}=\text{'N'}$, z is not referenced.
4:     info – int64int32nag_int scalar
info = 0${\mathbf{info}}=0$ unless the function detects an error (see Section [Error Indicators and Warnings]).

## Error Indicators and Warnings

info = i${\mathbf{info}}=-i$
If info = i${\mathbf{info}}=-i$, parameter i$i$ had an illegal value on entry. The parameters are numbered as follows:
1: job, 2: compz, 3: n, 4: ilo, 5: ihi, 6: h, 7: ldh, 8: w, 9: z, 10: ldz, 11: work, 12: lwork, 13: 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.
INFO > 0${\mathbf{INFO}}>0$
The algorithm has failed to find all the eigenvalues after a total of 30 × (ihiilo + 1)$30×\left({\mathbf{ihi}}-{\mathbf{ilo}}+1\right)$ iterations. If info = i${\mathbf{info}}=i$, elements 1,2,,ilo1$1,2,\dots ,{\mathbf{ilo}}-1$ and i + 1,i + 2,,n$i+1,i+2,\dots ,n$ of w contain the eigenvalues which have been found.
If job = 'E'${\mathbf{job}}=\text{'E'}$, then on exit, the remaining unconverged eigenvalues are the eigenvalues of the upper Hessenberg matrix $\stackrel{^}{H}$, formed from h(,) ${\mathbf{h}}\left({\mathbf{ilo}}:{\mathbf{info}},{\mathbf{ilo}}:{\mathbf{info}}\right)$, i.e., the ilo through info rows and columns of the final output matrix H$H$.
If job = 'S'${\mathbf{job}}=\text{'S'}$, then on exit
 ( * )   Hi U = U H̃ $(*) Hi U = U H~$
for some matrix U$U$, where Hi${H}_{i}$ is the input upper Hessenberg matrix and $\stackrel{~}{H}$ is an upper Hessenberg matrix formed from h(info + 1 : ihi,info + 1 : ihi) ${\mathbf{h}}\left({\mathbf{info}}+1:{\mathbf{ihi}},{\mathbf{info}}+1:{\mathbf{ihi}}\right)$.
If compz = 'V'${\mathbf{compz}}=\text{'V'}$, then on exit
 Zout = Zin U $Zout = Zin U$
where U$U$ is defined in ( * )$\left(*\right)$ (regardless of the value of job).
If compz = 'I'${\mathbf{compz}}=\text{'I'}$, then on exit
 Zout = U $Zout = U$
where U$U$ is defined in ( * )$\left(*\right)$ (regardless of the value of job).
If ${\mathbf{INFO}}>{\mathbf{0}}$ and compz = 'N'${\mathbf{compz}}=\text{'N'}$, then z is not accessed.

## Accuracy

The computed Schur factorization is the exact factorization of a nearby matrix (H + E)$\left(H+E\right)$, where
 ‖E‖2 = O(ε) ‖H‖2 , $‖E‖2 = O(ε) ‖H‖2 ,$
and ε$\epsilon$ is the machine precision.
If λi${\lambda }_{i}$ is an exact eigenvalue, and λ̃i${\stackrel{~}{\lambda }}_{i}$ is the corresponding computed value, then
 |λ̃i − λi| ≤ ( c (n) ε ‖H‖2 )/(si) , $| λ~i - λi | ≤ c (n) ε ‖H‖2 si ,$
where c(n)$c\left(n\right)$ is a modestly increasing function of n$n$, and si${s}_{i}$ is the reciprocal condition number of λi${\lambda }_{i}$. The condition numbers si${s}_{i}$ may be computed by calling nag_lapack_ztrsna (f08qy).

The total number of real floating point operations depends on how rapidly the algorithm converges, but is typically about:
• 25n3$25{n}^{3}$ if only eigenvalues are computed;
• 35n3$35{n}^{3}$ if the Schur form is computed;
• 70n3$70{n}^{3}$ if the full Schur factorization is computed.
The real analogue of this function is nag_lapack_dhseqr (f08pe).

## Example

```function nag_lapack_zhseqr_example
job = 'Schur form';
compz = 'Initialize Z';
ilo = int64(1);
ihi = int64(4);
h = [ -3.97 - 5.04i,  -1.1318 - 2.5693i,  -4.6027 - 0.1426i,  -1.4249 + 1.733i;
-5.4797 + 0i,  1.8585 - 1.5502i,  4.4145 - 0.7638i,  -0.4805 - 1.1976i;
0 + 0i,  6.2673 + 0i,  -0.4504 - 0.029i,  -1.3467 + 1.6579i;
0 + 0i,  0 + 0i,  -3.5 + 0i,  2.5619 - 3.3708i];
z = complex(zeros(4, 4));
[hOut, w, zOut, info] = nag_lapack_zhseqr(job, compz, ilo, ihi, h, z)
```
```

hOut =

-6.0004 - 6.9998i  -0.0742 + 0.5103i   0.4759 - 0.1949i   0.9082 - 0.1070i
0.0000 + 0.0000i  -5.0000 + 2.0060i   0.7123 - 0.1200i   0.2535 + 0.0734i
0.0000 + 0.0000i   0.0000 + 0.0000i   7.9982 - 0.9964i  -1.0700 + 0.1332i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   3.0023 - 3.9998i

w =

-6.0004 - 6.9998i
-5.0000 + 2.0060i
7.9982 - 0.9964i
3.0023 - 3.9998i

zOut =

-0.5312 - 0.6581i   0.0973 - 0.3733i  -0.0936 - 0.2735i   0.2111 - 0.0884i
-0.4344 - 0.0123i   0.4959 + 0.0995i   0.4497 + 0.5162i  -0.2518 + 0.1525i
0.1709 - 0.2340i  -0.5888 - 0.4211i   0.4034 + 0.4342i  -0.1037 - 0.1731i
0.0249 - 0.1062i  -0.0857 - 0.2531i  -0.2899 - 0.1115i  -0.7190 + 0.5507i

info =

0

```
```function f08ps_example
job = 'Schur form';
compz = 'Initialize Z';
ilo = int64(1);
ihi = int64(4);
h = [ -3.97 - 5.04i,  -1.1318 - 2.5693i,  -4.6027 - 0.1426i,  -1.4249 + 1.733i;
-5.4797 + 0i,  1.8585 - 1.5502i,  4.4145 - 0.7638i,  -0.4805 - 1.1976i;
0 + 0i,  6.2673 + 0i,  -0.4504 - 0.029i,  -1.3467 + 1.6579i;
0 + 0i,  0 + 0i,  -3.5 + 0i,  2.5619 - 3.3708i];
z = complex(zeros(4, 4));
[hOut, w, zOut, info] = f08ps(job, compz, ilo, ihi, h, z)
```
```

hOut =

-6.0004 - 6.9998i  -0.0742 + 0.5103i   0.4759 - 0.1949i   0.9082 - 0.1070i
0.0000 + 0.0000i  -5.0000 + 2.0060i   0.7123 - 0.1200i   0.2535 + 0.0734i
0.0000 + 0.0000i   0.0000 + 0.0000i   7.9982 - 0.9964i  -1.0700 + 0.1332i
0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   3.0023 - 3.9998i

w =

-6.0004 - 6.9998i
-5.0000 + 2.0060i
7.9982 - 0.9964i
3.0023 - 3.9998i

zOut =

-0.5312 - 0.6581i   0.0973 - 0.3733i  -0.0936 - 0.2735i   0.2111 - 0.0884i
-0.4344 - 0.0123i   0.4959 + 0.0995i   0.4497 + 0.5162i  -0.2518 + 0.1525i
0.1709 - 0.2340i  -0.5888 - 0.4211i   0.4034 + 0.4342i  -0.1037 - 0.1731i
0.0249 - 0.1062i  -0.0857 - 0.2531i  -0.2899 - 0.1115i  -0.7190 + 0.5507i

info =

0

```