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_dormhr (f08ng)

## Purpose

nag_lapack_dormhr (f08ng) multiplies an arbitrary real matrix $C$ by the real orthogonal matrix $Q$ which was determined by nag_lapack_dgehrd (f08ne) when reducing a real general matrix to Hessenberg form.

## Syntax

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

## Description

nag_lapack_dormhr (f08ng) is intended to be used following a call to nag_lapack_dgehrd (f08ne), which reduces a real general matrix $A$ to upper Hessenberg form $H$ by an orthogonal similarity transformation: $A=QH{Q}^{\mathrm{T}}$. nag_lapack_dgehrd (f08ne) 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_dgebal (f08nh) 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 , QTC , CQ ​ or ​ CQT ,$
overwriting the result on $C$ (which may be any real 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{T}}$ is to be applied to $C$.
${\mathbf{side}}=\text{'L'}$
$Q$ or ${Q}^{\mathrm{T}}$ is applied to $C$ from the left.
${\mathbf{side}}=\text{'R'}$
$Q$ or ${Q}^{\mathrm{T}}$ 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{T}}$ is to be applied to $C$.
${\mathbf{trans}}=\text{'N'}$
$Q$ is applied to $C$.
${\mathbf{trans}}=\text{'T'}$
${Q}^{\mathrm{T}}$ is applied to $C$.
Constraint: ${\mathbf{trans}}=\text{'N'}$ or $\text{'T'}$.
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_dgehrd (f08ne).
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)$ – double 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_dgehrd (f08ne).
6:     $\mathrm{tau}\left(:\right)$ – double 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_dgehrd (f08ne).
7:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – double 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)$ – double 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{T}}C$ or $CQ$ or $C{Q}^{\mathrm{T}}$ 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 floating-point operations is approximately $2n{q}^{2}$ if ${\mathbf{side}}=\text{'L'}$ and $2m{q}^{2}$ if ${\mathbf{side}}=\text{'R'}$, where $q={i}_{\mathrm{hi}}-{i}_{\mathrm{lo}}$.
The complex analogue of this function is nag_lapack_zunmhr (f08nu).

## Example

This example computes all the eigenvalues of the matrix $A$, where
 $A = 0.35 0.45 -0.14 -0.17 0.09 0.07 -0.54 0.35 -0.44 -0.33 -0.03 0.17 0.25 -0.32 -0.13 0.11 ,$
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_dgehrd (f08ne). The program then calls nag_lapack_dhseqr (f08pe) to compute the eigenvalues, and nag_lapack_dhsein (f08pk) to compute the required eigenvectors of $H$ by inverse iteration. Finally nag_lapack_dormhr (f08ng) is called to transform the eigenvectors of $H$ back to eigenvectors of the original matrix $A$.
```function f08ng_example

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

n   = int64(4);
ilo = int64(1);
ihi = n;
a = [ 0.35,  0.45, -0.14, -0.17;
0.09,  0.07, -0.54,  0.35;
-0.44, -0.33, -0.03,  0.17;
0.25, -0.32, -0.13,  0.11];

% Reduce A to upper Hessenberg Form A = QHQ^T
[H, tau, info] = f08ne( ...
ilo, ihi, a);

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

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

w = wr + i*wi;
disp('Eigenvalues of A');
disp(w);

% Calculate eigenvetors of H corresponding to negative real part eigenvalues
select = (wr < 0);

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

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

% Combine columns of V into complex eigenvectors Z
j = 0;
for k = 1:n
if select(k)
j = j+1;
if (wi(k)==0)
% Normalize eigenvector: largest element positive
[~,l] = max(abs(V(:,j)));
if V(l,j) < 0;
V(:,j) = -V(:,j);
end
Z(:,j) = complex(V(:,j));
else
Z(:,j)   = V(:,j) + i*V(:,j+1);
Z(:,j+1) = V(:,j) - i*V(:,j+1);
% Normalize: largest element is real
[~,l] = max(abs(real(Z(:,j)))+abs(imag(Z(:,j))));
Z(:,j) = Z(:,j)*conj(Z(l,j))/abs(Z(l,j));
Z(:,j+1) = Z(:,j+1)*conj(Z(l,j+1))/abs(Z(l,j+1));
j = j+1;
select(k+1) = false;
end
end
end
disp('Eigenvectors corresponding to eigenvalues with negative real part');
disp(Z);

```
```f08ng example results

Eigenvalues of A
0.7995 + 0.0000i
-0.0994 + 0.4008i
-0.0994 - 0.4008i
-0.1007 + 0.0000i

Eigenvectors corresponding to eigenvalues with negative real part
-0.2379 + 0.3134i  -0.2379 - 0.3134i   0.1493 + 0.0000i
0.3100 - 0.6430i   0.3100 + 0.6430i   0.3956 + 0.0000i
0.1196 - 0.3795i   0.1196 + 0.3795i   0.7075 + 0.0000i
0.8319 + 0.0000i   0.8319 + 0.0000i   0.8603 + 0.0000i

```