f08 Chapter Contents
f08 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_zhseqr (f08psc)

## 1  Purpose

nag_zhseqr (f08psc) 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.

## 2  Specification

 #include #include
 void nag_zhseqr (Nag_OrderType order, Nag_JobType job, Nag_ComputeZType compz, Integer n, Integer ilo, Integer ihi, Complex h[], Integer pdh, Complex w[], Complex z[], Integer pdz, NagError *fail)

## 3  Description

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

## 4  References

Bai Z and Demmel J W (1989) On a block implementation of Hessenberg multishift $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

## 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 $\mathrm{Nag_ColMajor}$.
2:     jobNag_JobTypeInput
On entry: indicates whether eigenvalues only or the Schur form $T$ is required.
${\mathbf{job}}=\mathrm{Nag_EigVals}$
Eigenvalues only are required.
${\mathbf{job}}=\mathrm{Nag_Schur}$
The Schur form $T$ is required.
Constraint: ${\mathbf{job}}=\mathrm{Nag_EigVals}$ or $\mathrm{Nag_Schur}$.
3:     compzNag_ComputeZTypeInput
On entry: indicates whether the Schur vectors are to be computed.
${\mathbf{compz}}=\mathrm{Nag_NotZ}$
No Schur vectors are computed (and the array z is not referenced).
${\mathbf{compz}}=\mathrm{Nag_InitZ}$
The Schur vectors of $H$ are computed (and the array z is initialized by the function).
${\mathbf{compz}}=\mathrm{Nag_UpdateZ}$
The Schur vectors of $A$ are computed (and the array z must contain the matrix $Q$ on entry).
Constraint: ${\mathbf{compz}}=\mathrm{Nag_NotZ}$, $\mathrm{Nag_UpdateZ}$ or $\mathrm{Nag_InitZ}$.
4:     nIntegerInput
On entry: $n$, the order of the matrix $H$.
Constraint: ${\mathbf{n}}\ge 0$.
5:     iloIntegerInput
6:     ihiIntegerInput
On entry: if the matrix $A$ has been balanced by nag_zgebal (f08nvc), then ilo and ihi must contain the values returned by that function. Otherwise, ilo must be set to $1$ and ihi to n.
Constraint: ${\mathbf{ilo}}\ge 1$ and $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ilo}},{\mathbf{n}}\right)\le {\mathbf{ihi}}\le {\mathbf{n}}$.
7:     h[$\mathit{dim}$]ComplexInput/Output
Note: the dimension, dim, of the array h must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdh}}×{\mathbf{n}}\right)$.
Where ${\mathbf{H}}\left(i,j\right)$ appears in this document, it refers to the array element
• ${\mathbf{h}}\left[\left(j-1\right)×{\mathbf{pdh}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{h}}\left[\left(i-1\right)×{\mathbf{pdh}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the $n$ by $n$ upper Hessenberg matrix $H$, as returned by nag_zgehrd (f08nsc).
On exit: if ${\mathbf{job}}=\mathrm{Nag_EigVals}$, the array contains no useful information.
If ${\mathbf{job}}=\mathrm{Nag_Schur}$, h is overwritten by the upper triangular matrix $T$ from the Schur decomposition (the Schur form) unless ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_CONVERGENCE.
8:     pdhIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array h.
Constraint: ${\mathbf{pdh}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
9:     w[$\mathit{dim}$]ComplexOutput
Note: the dimension, dim, of the array w must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On exit: the computed eigenvalues, unless ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_CONVERGENCE (in which case see Section 6). The eigenvalues are stored in the same order as on the diagonal of the Schur form $T$ (if computed).
10:   z[$\mathit{dim}$]ComplexInput/Output
Note: the dimension, dim, of the array z must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdz}}×{\mathbf{n}}\right)$ when ${\mathbf{compz}}=\mathrm{Nag_UpdateZ}$ or $\mathrm{Nag_InitZ}$ and ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,×{\mathbf{pdz}}\right)$ when ${\mathbf{compz}}=\mathrm{Nag_UpdateZ}$ or $\mathrm{Nag_InitZ}$ and ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $1$ when ${\mathbf{compz}}=\mathrm{Nag_NotZ}$.
The $\left(i,j\right)$th element of the matrix $Z$ is stored in
• ${\mathbf{z}}\left[\left(j-1\right)×{\mathbf{pdz}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{z}}\left[\left(i-1\right)×{\mathbf{pdz}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: if ${\mathbf{compz}}=\mathrm{Nag_UpdateZ}$, z must contain the unitary matrix $Q$ from the reduction to Hessenberg form.
If ${\mathbf{compz}}=\mathrm{Nag_InitZ}$, z need not be set.
On exit: if ${\mathbf{compz}}=\mathrm{Nag_UpdateZ}$ or $\mathrm{Nag_InitZ}$, z contains the unitary matrix of the required Schur vectors, unless ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_CONVERGENCE.
If ${\mathbf{compz}}=\mathrm{Nag_NotZ}$, z is not referenced.
11:   pdzIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array z.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$,
• if ${\mathbf{compz}}=\mathrm{Nag_InitZ}$ or $\mathrm{Nag_UpdateZ}$, ${\mathbf{pdz}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compz}}=\mathrm{Nag_NotZ}$, ${\mathbf{pdz}}\ge 1$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$,
• if ${\mathbf{compz}}=\mathrm{Nag_UpdateZ}$ or $\mathrm{Nag_InitZ}$, ${\mathbf{pdz}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{compz}}=\mathrm{Nag_NotZ}$, ${\mathbf{pdz}}\ge 1$.
12:   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_CONVERGENCE
The algorithm has failed to find all the eigenvalues after a total of $30\left({\mathbf{ihi}}-{\mathbf{ilo}}+1\right)$ iterations.
NE_ENUM_INT_2
On entry, ${\mathbf{compz}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{pdz}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{compz}}=\mathrm{Nag_InitZ}$ or $\mathrm{Nag_UpdateZ}$, ${\mathbf{pdz}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
if ${\mathbf{compz}}=\mathrm{Nag_NotZ}$, ${\mathbf{pdz}}\ge 1$.
NE_INT
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{pdh}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdh}}>0$.
On entry, ${\mathbf{pdz}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdz}}>0$.
NE_INT_2
On entry, ${\mathbf{pdh}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdh}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
NE_INT_3
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{ilo}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ihi}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ilo}}\ge 1$ and $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ilo}},{\mathbf{n}}\right)\le {\mathbf{ihi}}\le {\mathbf{n}}$.
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 Schur factorization is the exact factorization of a nearby matrix $\left(H+E\right)$, where
 $E2 = Oε H2 ,$
and $\epsilon$ is the machine precision.
If ${\lambda }_{i}$ is an exact eigenvalue, and ${\stackrel{~}{\lambda }}_{i}$ is the corresponding computed value, then
 $λ~i - λi ≤ c n ε H2 si ,$
where $c\left(n\right)$ is a modestly increasing function of $n$, and ${s}_{i}$ is the reciprocal condition number of ${\lambda }_{i}$. The condition numbers ${s}_{i}$ may be computed by calling nag_ztrsna (f08qyc).

## 8  Parallelism and Performance

nag_zhseqr (f08psc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_zhseqr (f08psc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

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

## 10  Example

This example computes all the eigenvalues and the Schur factorization of the upper Hessenberg matrix $H$, where
 $H = -3.9700-5.0400i -1.1318-2.5693i -4.6027-0.1426i -1.4249+1.7330i -5.4797+0.0000i 1.8585-1.5502i 4.4145-0.7638i -0.4805-1.1976i 0.0000+0.0000i 6.2673+0.0000i -0.4504-0.0290i -1.3467+1.6579i 0.0000+0.0000i 0.0000+0.0000i -3.5000+0.0000i 2.5619-3.3708i .$
See also Section 10 in nag_zunghr (f08ntc), which illustrates the use of this function to compute the Schur factorization of a general matrix.

### 10.1  Program Text

Program Text (f08psce.c)

### 10.2  Program Data

Program Data (f08psce.d)

### 10.3  Program Results

Program Results (f08psce.r)