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$ factorization of a complex matrix pair $\left(A,B\right)$, where $A$ is an $n$ by $m$ matrix and $B$ is an $n$ by $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$ factorization of an $n$ by $m$ matrix $A$ and an $n$ by $p$ matrix $B$
 $A =QR , B=QTZ ,$
where $Q$ is an $n$ by $n$ unitary matrix, $Z$ is a $p$ by $p$ unitary matrix and $R$ and $T$ are of the form
 $R = mmR11n-m0() , if ​n≥m; nm-nnR11R12() , if ​n
with ${R}_{11}$ upper triangular,
 $T = p-nnn0T12() , if ​n≤p, pn-pT11pT21() , if ​n>p,$
with ${T}_{12}$ or ${T}_{21}$ upper triangular.
In particular, if $B$ is square and nonsingular, the generalized $QR$ factorization of $A$ and $B$ implicitly gives the $QR$ factorization of ${B}^{-1}A$ as
 $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$ factorizations . In Reliable Numerical Computation (eds M G Cox and S Hammarling) 73–91 Oxford University Press

## Parameters

### Compulsory Input Parameters

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

### Optional Input Parameters

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

### Output Parameters

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

The unitary matrices $Q$ and $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$ by another matrix and nag_lapack_zunmrq (f08cx) may be used to multiply $Z$ by another matrix.
The real analogue of this function is nag_lapack_dggqrf (f08ze).

## Example

This example solves the general Gauss–Markov linear model problem
 $minx y2 subject to d=Ax+By$
where
 $A = 0.96-0.81i -0.03+0.96i -0.91+2.06i -0.98+1.98i -1.20+0.19i -0.66+0.42i 0.62-0.46i 1.01+0.02i 0.63-0.17i 1.08-0.28i 0.20-0.12i -0.07+1.23i ,$
 $B = 0.5-1.0i 0.0i+0.0 0.0i+0.0 0.0i+0.0 0.0i+0.0 1.0-2.0i 0.0i+0.0 0.0i+0.0 0.0i+0.0 0.0i+0.0 2.0-3.0i 0.0i+0.0 0.0i+0.0 0.0i+0.0 0.0i+0.0 5.0-4.0i$
and
 $d = 6.00-0.40i -5.27+0.90i 2.72-2.13i -1.30-2.80i .$
The solution is obtained by first computing a generalized $QR$ factorization of the matrix pair $\left(A,B\right)$. The example illustrates the general solution process, although the above data corresponds to a simple weighted least squares problem.
Note that the block size (NB) of $64$ assumed in this example is not realistic for such a small problem, but should be suitable for large problems.
```function f08zs_example

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

a = [ 0.96 - 0.81i, -0.03 + 0.96i, -0.91 + 2.06i;
-0.98 + 1.98i, -1.20 + 0.19i, -0.66 + 0.42i;
0.62 - 0.46i,  1.01 + 0.02i,  0.63 - 0.17i;
1.08 - 0.28i,  0.20 - 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,m] = size(a);
p = size(b,2);

% 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
indy = m+p-n+1:p;
[y(indy), info] = f07ts( ...
'Upper', 'No transpose', 'Non-unit', ...
complex(b(m+1:n, indy)), c(m+1:n));

% Compute estimate of the square root of the residual sum of squares
% norm(y) = norm(w2)
rnorm = norm(y(indy), 1);

% Form c1 - T12*w2 in c
c = c - b(:,indy)*y(indy);
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);

disp('Generalized least squares solution');
disp(c(1:m));

ncols  = int64(80);
indent = int64(0);
[ifail] = x04db( ...
'Gen', ' ', y, 'B', '1P,E10.2', 'Residual vector', ...
'N', 'N', ncols, indent);

fprintf('\nSquare root of the residual sum of squares\n%11.2e\n', ...
rnorm);

```
```f08zs example results

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

Residual vector
(  1.26E-04, -4.66E-04)
(  1.11E-03, -8.61E-04)
(  3.84E-03, -1.82E-03)
(  2.03E-03,  3.02E-03)

Square root of the residual sum of squares
5.79e-03
```