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_zunmhr (f08nu)

## Purpose

nag_lapack_zunmhr (f08nu) multiplies an arbitrary complex matrix $C$ by the complex unitary matrix $Q$ which was determined by nag_lapack_zgehrd (f08ns) when reducing a complex general matrix to Hessenberg form.

## Syntax

[c, info] = f08nu(side, trans, ilo, ihi, a, tau, c, 'm', m, 'n', n)
[c, info] = nag_lapack_zunmhr(side, trans, ilo, ihi, a, tau, c, 'm', m, 'n', n)

## Description

nag_lapack_zunmhr (f08nu) is intended to be used following a call to nag_lapack_zgehrd (f08ns), which reduces a complex general matrix $A$ to upper Hessenberg form $H$ by a unitary similarity transformation: $A=QH{Q}^{\mathrm{H}}$. nag_lapack_zgehrd (f08ns) represents the matrix $Q$ as a product of ${i}_{\mathrm{hi}}-{i}_{\mathrm{lo}}$ elementary reflectors. Here ${i}_{\mathrm{lo}}$ and ${i}_{\mathrm{hi}}$ are values determined by nag_lapack_zgebal (f08nv) when balancing the matrix; if the matrix has not been balanced, ${i}_{\mathrm{lo}}=1$ and ${i}_{\mathrm{hi}}=n$.
This function may be used to form one of the matrix products
 $QC , QHC , CQ ​ or ​ CQH ,$
overwriting the result on $C$ (which may be any complex rectangular matrix).
A common application of this function is to transform a matrix $V$ of eigenvectors of $H$ to the matrix $\mathit{QV}$ of eigenvectors of $A$.

## 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{side}$ – string (length ≥ 1)
Indicates how $Q$ or ${Q}^{\mathrm{H}}$ is to be applied to $C$.
${\mathbf{side}}=\text{'L'}$
$Q$ or ${Q}^{\mathrm{H}}$ is applied to $C$ from the left.
${\mathbf{side}}=\text{'R'}$
$Q$ or ${Q}^{\mathrm{H}}$ is applied to $C$ from the right.
Constraint: ${\mathbf{side}}=\text{'L'}$ or $\text{'R'}$.
2:     $\mathrm{trans}$ – string (length ≥ 1)
Indicates whether $Q$ or ${Q}^{\mathrm{H}}$ is to be applied to $C$.
${\mathbf{trans}}=\text{'N'}$
$Q$ is applied to $C$.
${\mathbf{trans}}=\text{'C'}$
${Q}^{\mathrm{H}}$ is applied to $C$.
Constraint: ${\mathbf{trans}}=\text{'N'}$ or $\text{'C'}$.
3:     $\mathrm{ilo}$int64int32nag_int scalar
4:     $\mathrm{ihi}$int64int32nag_int scalar
These must be the same arguments ilo and ihi, respectively, as supplied to nag_lapack_zgehrd (f08ns).
Constraints:
• if ${\mathbf{side}}=\text{'L'}$ and ${\mathbf{m}}>0$, $1\le {\mathbf{ilo}}\le {\mathbf{ihi}}\le {\mathbf{m}}$;
• if ${\mathbf{side}}=\text{'L'}$ and ${\mathbf{m}}=0$, ${\mathbf{ilo}}=1$ and ${\mathbf{ihi}}=0$;
• if ${\mathbf{side}}=\text{'R'}$ and ${\mathbf{n}}>0$, $1\le {\mathbf{ilo}}\le {\mathbf{ihi}}\le {\mathbf{n}}$;
• if ${\mathbf{side}}=\text{'R'}$ and ${\mathbf{n}}=0$, ${\mathbf{ilo}}=1$ and ${\mathbf{ihi}}=0$.
5:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension, $\mathit{lda}$, of the array a must satisfy
• if ${\mathbf{side}}=\text{'L'}$, $\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{side}}=\text{'R'}$, $\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$ if ${\mathbf{side}}=\text{'L'}$ and at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{side}}=\text{'R'}$.
Details of the vectors which define the elementary reflectors, as returned by nag_lapack_zgehrd (f08ns).
6:     $\mathrm{tau}\left(:\right)$ – complex array
The dimension of the array tau must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-1\right)$ if ${\mathbf{side}}=\text{'L'}$ and at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}-1\right)$ if ${\mathbf{side}}=\text{'R'}$
Further details of the elementary reflectors, as returned by nag_lapack_zgehrd (f08ns).
7:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – complex array
The first dimension of the array c must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The second dimension of the array c must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The $m$ by $n$ matrix $C$.

### Optional Input Parameters

1:     $\mathrm{m}$int64int32nag_int scalar
Default: the first dimension of the array c.
$m$, the number of rows of the matrix $C$; $m$ is also the order of $Q$ if ${\mathbf{side}}=\text{'L'}$.
Constraint: ${\mathbf{m}}\ge 0$.
2:     $\mathrm{n}$int64int32nag_int scalar
Default: the second dimension of the array c.
$n$, the number of columns of the matrix $C$; $n$ is also the order of $Q$ if ${\mathbf{side}}=\text{'R'}$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – complex array
The first dimension of the array c will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The second dimension of the array c will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
c stores $QC$ or ${Q}^{\mathrm{H}}C$ or $CQ$ or $C{Q}^{\mathrm{H}}$ as specified by side and trans.
2:     $\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: side, 2: trans, 3: m, 4: n, 5: ilo, 6: ihi, 7: a, 8: lda, 9: tau, 10: c, 11: ldc, 12: work, 13: lwork, 14: 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 result differs from the exact result by a matrix $E$ such that
 $E2 = Oε C2 ,$
where $\epsilon$ is the machine precision.

The total number of real floating-point operations is approximately $8n{q}^{2}$ if ${\mathbf{side}}=\text{'L'}$ and $8m{q}^{2}$ if ${\mathbf{side}}=\text{'R'}$, where $q={i}_{\mathrm{hi}}-{i}_{\mathrm{lo}}$.
The real analogue of this function is nag_lapack_dormhr (f08ng).

## Example

This example computes all the eigenvalues of the matrix $A$, where
 $A = -3.97-5.04i -4.11+3.70i -0.34+1.01i 1.29-0.86i 0.34-1.50i 1.52-0.43i 1.88-5.38i 3.36+0.65i 3.31-3.85i 2.50+3.45i 0.88-1.08i 0.64-1.48i -1.10+0.82i 1.81-1.59i 3.25+1.33i 1.57-3.44i ,$
and those eigenvectors which correspond to eigenvalues $\lambda$ such that $\mathrm{Re}\left(\lambda \right)<0$. Here $A$ is general and must first be reduced to upper Hessenberg form $H$ by nag_lapack_zgehrd (f08ns). The program then calls nag_lapack_zhseqr (f08ps) to compute the eigenvalues, and nag_lapack_zhsein (f08px) to compute the required eigenvectors of $H$ by inverse iteration. Finally nag_lapack_zunmhr (f08nu) is called to transform the eigenvectors of $H$ back to eigenvectors of the original matrix $A$.
```function f08nu_example

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

n   = int64(4);
ilo = int64(1);
ihi = n;
a = [ -3.97 - 5.04i, -4.11 + 3.70i, -0.34 + 1.01i,  1.29 - 0.86i;
0.34 - 1.50i,  1.52 - 0.43i,  1.88 - 5.38i,  3.36 + 0.65i;
3.31 - 3.85i,  2.50 + 3.45i,  0.88 - 1.08i,  0.64 - 1.48i;
-1.10 + 0.82i,  1.81 - 1.59i,  3.25 + 1.33i,  1.57 - 3.44i];

% Reduce A to upper Hessenberg Form
[H, tau, info] = f08ns(ilo, ihi, a);

% Form Q
[Q, info] = f08nt(ilo, ihi, H, tau);

% Schur factorize H = Y*T*Y^H
job   = 'Schur form';
compz = 'Vectors';
[~, w, ~, info] = f08ps( ...
job, compz, ilo, ihi, H, Q);

disp('Eigenvalues of A');
disp(w);

% Calculate eigenvectors of H for negative real part eigenvalues
select = (real(w) < 0);

job = 'Right';
eigsrc = 'QR';
initv = 'No initial vectors';
vl = [];
vr = complex(zeros(n,n));
[~, ~, VR, m, ifaill, ifailr, info] = ...
f08px(...
job, eigsrc, initv, select, H, w, vl, vr, n);

% Eigenvectors of A = Q*VR
side = 'Left';
trans = 'No transpose';
[Z, info] = f08nu(side, trans, ilo, ihi, H, tau, VR);

% Normalize Z: largest elements are real
for i = 1:m
[~,k] = max(abs(real(Z(:,i)))+abs(imag(Z(:,i))));
Z(:,i) = Z(:,i)*conj(Z(k,i))/abs(Z(k,i));
end
disp('Eigenvectors corresponding to eigenvalues with negative real part');
disp(Z);

```
```f08nu example results

Eigenvalues of A
-6.0004 - 6.9998i
-5.0000 + 2.0060i
7.9982 - 0.9964i
3.0023 - 3.9998i

Eigenvectors corresponding to eigenvalues with negative real part
0.8079 + 0.0000i  -0.4076 + 0.1827i
-0.0169 + 0.2900i  -0.3732 + 0.4776i
0.0836 + 0.2975i   0.6457 + 0.0000i
-0.0536 - 0.2776i  -0.0906 - 0.3463i

```