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_zggqrf (f08zs)

## Purpose

nag_lapack_zggqrf (f08zs) computes a generalized QR$QR$ factorization of a complex matrix pair (A,B)$\left(A,B\right)$, where A$A$ is an n$n$ by m$m$ matrix and B$B$ is an n$n$ by p$p$ matrix.

## Syntax

[a, taua, b, taub, info] = f08zs(a, b, 'n', n, 'm', m, 'p', p)
[a, taua, b, taub, info] = nag_lapack_zggqrf(a, b, 'n', n, 'm', m, 'p', p)

## Description

nag_lapack_zggqrf (f08zs) forms the generalized QR$QR$ factorization of an n$n$ by m$m$ matrix A$A$ and an n$n$ by p$p$ matrix B$B$
 A = QR ,   B = QTZ , $A =QR , B=QTZ ,$
where Q$Q$ is an n$n$ by n$n$ unitary matrix, Z$Z$ is a p$p$ by p$p$ unitary matrix and R$R$ and T$T$ are of the form
R =
{
 mm(R11) n − m 0 ,   if ​n ≥ m ;
 nm − nn(R11R12) ,   if ​n < m,
$R = { mm(R11) n-m 0 , if ​n≥m; nm-nn(R11R12) , if ​n
with R11${R}_{11}$ upper triangular,
T =
{
 p − nnn(0T12) ,   if ​n ≤ p,
 pn − p(T11) p T21 ,   if ​n > p,
$T = { p-nnn(0T12) , if ​n≤p, pn-p(T11) p T21 , if ​n>p,$
with T12${T}_{12}$ or T21${T}_{21}$ upper triangular.
In particular, if B$B$ is square and nonsingular, the generalized QR$QR$ factorization of A$A$ and B$B$ implicitly gives the QR$QR$ factorization of B1A${B}^{-1}A$ as
 B − 1A = ZH (T − 1R) . $B-1A= ZH ( T-1 R ) .$

## References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Anderson E, Bai Z and Dongarra J (1992) Generalized QR factorization and its applications Linear Algebra Appl. (Volume 162–164) 243–271
Hammarling S (1987) The numerical solution of the general Gauss-Markov linear model Mathematics in Signal Processing (eds T S Durrani, J B Abbiss, J E Hudson, R N Madan, J G McWhirter and T A Moore) 441–456 Oxford University Press
Paige C C (1990) Some aspects of generalized QR$QR$ factorizations . In Reliable Numerical Computation (eds M G Cox and S Hammarling) 73–91 Oxford University Press

## Parameters

### Compulsory Input Parameters

1:     a(lda, : $:$) – complex array
The first dimension of the array a 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,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$
The n$n$ by m$m$ matrix A$A$.
2:     b(ldb, : $:$) – complex array
The first dimension of the array b 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,p)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$
The n$n$ by p$p$ matrix B$B$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the arrays a, b. (An error is raised if these dimensions are not equal.)
n$n$, the number of rows of the matrices A$A$ and B$B$.
Constraint: n0${\mathbf{n}}\ge 0$.
2:     m – int64int32nag_int scalar
Default: The second dimension of the array a.
m$m$, the number of columns of the matrix A$A$.
Constraint: m0${\mathbf{m}}\ge 0$.
3:     p – int64int32nag_int scalar
Default: The second dimension of the array b.
p$p$, the number of columns of the matrix B$B$.
Constraint: p0${\mathbf{p}}\ge 0$.

### Input Parameters Omitted from the MATLAB Interface

lda ldb work lwork

### Output Parameters

1:     a(lda, : $:$) – complex array
The first dimension of the array a 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,m)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$
ldamax (1,n)$\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The elements on and above the diagonal of the array contain the min (n,m)$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(n,m\right)$ by m$m$ upper trapezoidal matrix R$R$ (R$R$ is upper triangular if nm$n\ge m$); the elements below the diagonal, with the array taua, represent the unitary matrix Q$Q$ as a product of min (n,m)$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(n,m\right)$ elementary reflectors (see Section [Representation of orthogonal or unitary matrices] in the F08 Chapter Introduction).
2:     taua(min (n,m)$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{n}},{\mathbf{m}}\right)$) – complex array
The scalar factors of the elementary reflectors which represent the unitary matrix Q$Q$.
3:     b(ldb, : $:$) – complex array
The first dimension of the array b 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,p)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$
ldbmax (1,n)$\mathit{ldb}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
If np$n\le p$, the upper triangle of the subarray b( 1 : n , pn + 1 : p ) ${\mathbf{b}}\left(1:n,p-n+1:p\right)$ contains the n$n$ by n$n$ upper triangular matrix T12${T}_{12}$.
If n > p$n>p$, the elements on and above the (np)$\left(n-p\right)$th subdiagonal contain the n$n$ by p$p$ upper trapezoidal matrix T$T$; the remaining elements, with the array taub, represent the unitary matrix Z$Z$ as a product of elementary reflectors (see Section [Representation of orthogonal or unitary matrices] in the F08 Chapter Introduction).
4:     taub(min (n,p)$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{n}},{\mathbf{p}}\right)$) – complex array
The scalar factors of the elementary reflectors which represent the unitary matrix Z$Z$.
5:     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: n, 2: m, 3: p, 4: a, 5: lda, 6: taua, 7: b, 8: ldb, 9: taub, 10: work, 11: lwork, 12: 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 generalized QR$QR$ factorization is the exact factorization for nearby matrices (A + E)$\left(A+E\right)$ and (B + F)$\left(B+F\right)$, where
 ‖E‖2 = Oε ‖A‖2   and   ‖F‖2 = Oε ‖B‖2 , $‖E‖2 = O⁡ε ‖A‖2 and ‖F‖2= O⁡ε ‖B‖2 ,$
and ε$\epsilon$ is the machine precision.

The unitary matrices Q$Q$ and Z$Z$ may be formed explicitly by calls to nag_lapack_zungqr (f08at) and nag_lapack_zungrq (f08cw) respectively. nag_lapack_zunmqr (f08au) may be used to multiply Q$Q$ by another matrix and nag_lapack_zunmrq (f08cx) may be used to multiply Z$Z$ by another matrix.
The real analogue of this function is nag_lapack_dggqrf (f08ze).

## Example

```function nag_lapack_zggqrf_example
a = [ 0.96 - 0.81i,  -0.03 + 0.96i,  -0.91 + 2.06i;
-0.98 + 1.98i,  -1.2 + 0.19i,  -0.66 + 0.42i;
0.62 - 0.46i,  1.01 + 0.02i,  0.63 - 0.17i;
1.08 - 0.28i,  0.2 - 0.12i,  -0.07 + 1.23i];
b = [ 0.5 - 1i,  0 + 0i,  0 + 0i,  0 + 0i;
0 + 0i,  1 - 2i,  0 + 0i,  0 + 0i;
0 + 0i,  0 + 0i,  2 - 3i,  0 + 0i;
0 + 0i,  0 + 0i,  0 + 0i,  5 - 4i];
d = [ 6.00 - 0.40i;
-5.27 + 0.90i;
2.72 - 2.13i;
-1.30 - 2.80i];
n = 4;
m = 3;
p = 4;

% Compute the generalized QR factorization of (A,B) as
% A = Q*(R),   B = Q*(T11 T12)*Z
%       (0)          ( 0  T22)
[a, taua, b, taub, info] = nag_lapack_zggqrf(a, b);

% Compute c = (c1) = (Q**H)*d
%             (c2)
[c, info] = nag_lapack_zunmqr('Left', 'Conjugate Transpose', a, taua, d);

% Putting Z*y = w = (w1), set w1 = 0, storing the result in y1
%                   (w2)
y = zeros(p, 1);
if n > m

% Solve T22*w2 = c2 for w2, storing result in y2
[y(m+p-n+1:p), info] = nag_lapack_ztrtrs('Upper', 'No transpose', 'Non-unit', ...
complex(b(m+1:n, m+p-n+1:p)), c(m+1:n));

% Compute estimate of the square root of the residual sum of squares
% norm(y) = norm(w2)
rnorm = norm(y(m+p-n+1:p), 1);

% Form c1 - T12*w2 in c
c = c - b(:,m+p-n+1:p)*y(m+p-n+1:p);
end

% Solve R*x = c1 - T12*w2 for x
[c(1:m), info] = nag_lapack_ztrtrs('Upper', 'No transpose', 'Non-unit', a(1:m,:), c(1:m));

% Compute y = (Z^H)*w
[b(max(1, n-p+1):n,:), y, info] = ...
nag_lapack_zunmrq('Left', 'Conjugate Transpose', b(max(1, n-p+1):n,:), taub, y);

fprintf('\nGeneralized least squares solution\n');
disp(transpose(c(1:m)));

fprintf('Residual vector\n');
disp(transpose(y));

fprintf('Square root of the residual sum of squares\n');
disp(rnorm);
```
```

Generalized least squares solution
-0.9846 + 1.9950i   3.9929 - 4.9748i  -3.0026 + 0.9994i

Residual vector
0.0001 - 0.0005i   0.0011 - 0.0009i   0.0038 - 0.0018i   0.0020 + 0.0030i

Square root of the residual sum of squares
0.0058

```
```function f08zs_example
a = [ 0.96 - 0.81i,  -0.03 + 0.96i,  -0.91 + 2.06i;
-0.98 + 1.98i,  -1.2 + 0.19i,  -0.66 + 0.42i;
0.62 - 0.46i,  1.01 + 0.02i,  0.63 - 0.17i;
1.08 - 0.28i,  0.2 - 0.12i,  -0.07 + 1.23i];
b = [ 0.5 - 1i,  0 + 0i,  0 + 0i,  0 + 0i;
0 + 0i,  1 - 2i,  0 + 0i,  0 + 0i;
0 + 0i,  0 + 0i,  2 - 3i,  0 + 0i;
0 + 0i,  0 + 0i,  0 + 0i,  5 - 4i];
d = [ 6.00 - 0.40i;
-5.27 + 0.90i;
2.72 - 2.13i;
-1.30 - 2.80i];
n = 4;
m = 3;
p = 4;

% Compute the generalized QR factorization of (A,B) as
% A = Q*(R),   B = Q*(T11 T12)*Z
%       (0)          ( 0  T22)
[a, taua, b, taub, info] = f08zs(a, b);

% Compute c = (c1) = (Q**H)*d
%             (c2)
[c, info] = f08au('Left', 'Conjugate Transpose', a, taua, d);

% Putting Z*y = w = (w1), set w1 = 0, storing the result in y1
%                   (w2)
y = zeros(p, 1);
if n > m

% Solve T22*w2 = c2 for w2, storing result in y2
[y(m+p-n+1:p), info] = f07ts('Upper', 'No transpose', 'Non-unit', ...
complex(b(m+1:n, m+p-n+1:p)), c(m+1:n));

% Compute estimate of the square root of the residual sum of squares
% norm(y) = norm(w2)
rnorm = norm(y(m+p-n+1:p), 1);

% Form c1 - T12*w2 in c
c = c - b(:,m+p-n+1:p)*y(m+p-n+1:p);
end

% Solve R*x = c1 - T12*w2 for x
[c(1:m), info] = f07ts('Upper', 'No transpose', 'Non-unit', a(1:m,:), c(1:m));

% Compute y = (Z^H)*w
[b(max(1, n-p+1):n,:), y, info] = ...
f08cx('Left', 'Conjugate Transpose', b(max(1, n-p+1):n,:), taub, y);

fprintf('\nGeneralized least squares solution\n');
disp(transpose(c(1:m)));

fprintf('Residual vector\n');
disp(transpose(y));

fprintf('Square root of the residual sum of squares\n');
disp(rnorm);
```
```

Generalized least squares solution
-0.9846 + 1.9950i   3.9929 - 4.9748i  -3.0026 + 0.9994i

Residual vector
0.0001 - 0.0005i   0.0011 - 0.0009i   0.0038 - 0.0018i   0.0020 + 0.0030i

Square root of the residual sum of squares
0.0058

```