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_zungbr (f08kt)

## Purpose

nag_lapack_zungbr (f08kt) generates one of the complex unitary matrices Q$Q$ or PH${P}^{\mathrm{H}}$ which were determined by nag_lapack_zgebrd (f08ks) when reducing a complex matrix to bidiagonal form.

## Syntax

[a, info] = f08kt(vect, k, a, tau, 'm', m, 'n', n)
[a, info] = nag_lapack_zungbr(vect, k, a, tau, 'm', m, 'n', n)

## Description

nag_lapack_zungbr (f08kt) is intended to be used after a call to nag_lapack_zgebrd (f08ks), which reduces a complex rectangular matrix A$A$ to real bidiagonal form B$B$ by a unitary transformation: A = QBPH$A=QB{P}^{\mathrm{H}}$. nag_lapack_zgebrd (f08ks) represents the matrices Q$Q$ and PH${P}^{\mathrm{H}}$ as products of elementary reflectors.
This function may be used to generate Q$Q$ or PH${P}^{\mathrm{H}}$ explicitly as square matrices, or in some cases just the leading columns of Q$Q$ or the leading rows of PH${P}^{\mathrm{H}}$.
The various possibilities are specified by the parameters vect, m, n and k. The appropriate values to cover the most likely cases are as follows (assuming that A$A$ was an m$m$ by n$n$ matrix):
1. To form the full m$m$ by m$m$ matrix Q$Q$:
```[a, info] = f08kt('Q', n, a, tau);
```
(note that the array a must have at least m$m$ columns).
2. If m > n$m>n$, to form the n$n$ leading columns of Q$Q$:
```[a, info] = f08kt('Q', n, a(1:m,1:n), tau);
```
3. To form the full n$n$ by n$n$ matrix PH${P}^{\mathrm{H}}$:
```[a, info] = f08kt('P', m, a, tau);
```
(note that the array a must have at least n$n$ rows).
4. If m < n$m, to form the m$m$ leading rows of PH${P}^{\mathrm{H}}$:
```[a, info] = f08kt('P', m, a(1:m,1:n), tau);
```

## References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     vect – string (length ≥ 1)
Indicates whether the unitary matrix Q$Q$ or PH${P}^{\mathrm{H}}$ is generated.
vect = 'Q'${\mathbf{vect}}=\text{'Q'}$
Q$Q$ is generated.
vect = 'P'${\mathbf{vect}}=\text{'P'}$
PH${P}^{\mathrm{H}}$ is generated.
Constraint: vect = 'Q'${\mathbf{vect}}=\text{'Q'}$ or 'P'$\text{'P'}$.
2:     k – int64int32nag_int scalar
If vect = 'Q'${\mathbf{vect}}=\text{'Q'}$, the number of columns in the original matrix A$A$.
If vect = 'P'${\mathbf{vect}}=\text{'P'}$, the number of rows in the original matrix A$A$.
Constraint: k0${\mathbf{k}}\ge 0$.
3:     a(lda, : $:$) – complex array
The first dimension of the array a must be at least max (1,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\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)$
Details of the vectors which define the elementary reflectors, as returned by nag_lapack_zgebrd (f08ks).
4:     tau( : $:$) – complex array
Note: the dimension of the array tau must be at least max (1,min (m,k))$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{k}}\right)\right)$ if vect = 'Q'${\mathbf{vect}}=\text{'Q'}$ and at least max (1,min (n,k))$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{n}},{\mathbf{k}}\right)\right)$ if vect = 'P'${\mathbf{vect}}=\text{'P'}$.
Further details of the elementary reflectors, as returned by nag_lapack_zgebrd (f08ks) in its parameter tauq if vect = 'Q'${\mathbf{vect}}=\text{'Q'}$, or in its parameter taup if vect = 'P'${\mathbf{vect}}=\text{'P'}$.

### Optional Input Parameters

1:     m – int64int32nag_int scalar
Default: The first dimension of the array a.
m$m$, the number of rows of the unitary matrix Q$Q$ or PH${P}^{\mathrm{H}}$ to be returned.
Constraint: m0${\mathbf{m}}\ge 0$.
2:     n – int64int32nag_int scalar
Default: The second dimension of the array a.
n$n$, the number of columns of the unitary matrix Q$Q$ or PH${P}^{\mathrm{H}}$ to be returned.
Constraints:
• n0${\mathbf{n}}\ge 0$;
• if vect = 'Q'${\mathbf{vect}}=\text{'Q'}$ and m > k${\mathbf{m}}>{\mathbf{k}}$, mnk${\mathbf{m}}\ge {\mathbf{n}}\ge {\mathbf{k}}$;
• if vect = 'Q'${\mathbf{vect}}=\text{'Q'}$ and mk${\mathbf{m}}\le {\mathbf{k}}$, m = n${\mathbf{m}}={\mathbf{n}}$;
• if vect = 'P'${\mathbf{vect}}=\text{'P'}$ and n > k${\mathbf{n}}>{\mathbf{k}}$, nmk${\mathbf{n}}\ge {\mathbf{m}}\ge {\mathbf{k}}$;
• if vect = 'P'${\mathbf{vect}}=\text{'P'}$ and nk${\mathbf{n}}\le {\mathbf{k}}$, n = m${\mathbf{n}}={\mathbf{m}}$.

lda work lwork

### Output Parameters

1:     a(lda, : $:$) – complex array
The first dimension of the array a will be max (1,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$
The second dimension of the array will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
ldamax (1,m)$\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The unitary matrix Q$Q$ or PH${P}^{\mathrm{H}}$, or the leading rows or columns thereof, as specified by vect, m and n.
2:     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: vect, 2: m, 3: n, 4: k, 5: a, 6: lda, 7: tau, 8: work, 9: lwork, 10: 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 matrix Q$Q$ differs from an exactly unitary matrix by a matrix E$E$ such that
 ‖E‖2 = O(ε) , $‖E‖2 = O(ε) ,$
where ε$\epsilon$ is the machine precision. A similar statement holds for the computed matrix PH${P}^{\mathrm{H}}$.

The total number of real floating point operations for the cases listed in Section [Description] are approximately as follows:
1. To form the whole of Q$Q$:
• (16/3)n(3m23mn + n2)$\frac{16}{3}n\left(3{m}^{2}-3mn+{n}^{2}\right)$ if m > n$m>n$,
• (16/3)m3$\frac{16}{3}{m}^{3}$ if mn$m\le n$;
2. To form the n$n$ leading columns of Q$Q$ when m > n$m>n$:
• (8/3)n2(3mn)$\frac{8}{3}{n}^{2}\left(3m-n\right)$;
3. To form the whole of PH${P}^{\mathrm{H}}$:
• (16/3)n3$\frac{16}{3}{n}^{3}$ if mn$m\ge n$,
• (16/3)m3(3n23mn + m2)$\frac{16}{3}{m}^{3}\left(3{n}^{2}-3mn+{m}^{2}\right)$ if m < n$m;
4. To form the m$m$ leading rows of PH${P}^{\mathrm{H}}$ when m < n$m:
• (8/3)m2(3nm)$\frac{8}{3}{m}^{2}\left(3n-m\right)$.
The real analogue of this function is nag_lapack_dorgbr (f08kf).

## Example

```function nag_lapack_zungbr_example
vect = 'P';
k = int64(6);
a = [complex(-3.087005021051958),  2.112571007455839 + 0i, ...
0.05433411079440312 + 0.4543118496773522i,  0.375743827925403 + 0.1070087304094524i;
0 + 0i,  2.066039276679068 + 0i, ...
1.262810106655224 + 0i,  0.02827717828732752 + 0.165005610304937i;
0 + 0i,  0 + 0i,  1.873128891125711 + 0i,  -1.612633872800393 + 0i;
0 + 0i,  0 + 0i,  0 + 0i,  2.002182866206992 + 0i];
tau = [ 1.231234531617602 - 0.5404263814542949i;
1.262279868392228 - 0.928646196138089i;
1.782899043025449 - 0.6221487671207239i;
0 + 0i];
[aOut, info] = nag_lapack_zungbr(vect, k, a, tau)
```
```

aOut =

1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
0.0000 + 0.0000i  -0.2312 - 0.5404i   0.1786 - 0.5887i  -0.4048 - 0.3348i
0.0000 + 0.0000i   0.4962 + 0.2648i  -0.3556 - 0.6888i   0.2757 - 0.0819i
0.0000 + 0.0000i   0.2918 + 0.5030i   0.0485 + 0.1349i  -0.7156 - 0.3596i

info =

0

```
```function f08kt_example
vect = 'P';
k = int64(6);
a = [complex(-3.087005021051958),  2.112571007455839 + 0i, ...
0.05433411079440312 + 0.4543118496773522i,  0.375743827925403 + 0.1070087304094524i;
0 + 0i,  2.066039276679068 + 0i, ...
1.262810106655224 + 0i,  0.02827717828732752 + 0.165005610304937i;
0 + 0i,  0 + 0i,  1.873128891125711 + 0i,  -1.612633872800393 + 0i;
0 + 0i,  0 + 0i,  0 + 0i,  2.002182866206992 + 0i];
tau = [ 1.231234531617602 - 0.5404263814542949i;
1.262279868392228 - 0.928646196138089i;
1.782899043025449 - 0.6221487671207239i;
0 + 0i];
[aOut, info] = f08kt(vect, k, a, tau)
```
```

aOut =

1.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i   0.0000 + 0.0000i
0.0000 + 0.0000i  -0.2312 - 0.5404i   0.1786 - 0.5887i  -0.4048 - 0.3348i
0.0000 + 0.0000i   0.4962 + 0.2648i  -0.3556 - 0.6888i   0.2757 - 0.0819i
0.0000 + 0.0000i   0.2918 + 0.5030i   0.0485 + 0.1349i  -0.7156 - 0.3596i

info =

0

```