f08 Chapter Contents
f08 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_zggrqf (f08ztc)

## 1  Purpose

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

## 2  Specification

 #include #include
 void nag_zggrqf (Nag_OrderType order, Integer m, Integer p, Integer n, Complex a[], Integer pda, Complex taua[], Complex b[], Integer pdb, Complex taub[], NagError *fail)

## 3  Description

nag_zggrqf (f08ztc) forms the generalized $RQ$ factorization of an $m$ by $n$ matrix $A$ and a $p$ by $n$ matrix $B$
 $A = RQ , B= ZTQ ,$
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 = n-mmm(0R12) ; if ​ m≤n , nm-n(R11) n R21 ; if ​ m>n ,$
with ${R}_{12}$ or ${R}_{21}$ upper triangular,
 $T = nn(T11) p-n 0 ; if ​ p≥n , pn-pp(T11T12) ; if ​ p
with ${T}_{11}$ upper triangular.
In particular, if $B$ is square and nonsingular, the generalized $RQ$ factorization of $A$ and $B$ implicitly gives the $RQ$ factorization of $A{B}^{-1}$ as
 $AB-1= R T-1 ZH .$

## 4  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

## 5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or $\mathrm{Nag_ColMajor}$.
2:     mIntegerInput
On entry: $m$, the number of rows of the matrix $A$.
Constraint: ${\mathbf{m}}\ge 0$.
3:     pIntegerInput
On entry: $p$, the number of rows of the matrix $B$.
Constraint: ${\mathbf{p}}\ge 0$.
4:     nIntegerInput
On entry: $n$, the number of columns of the matrices $A$ and $B$.
Constraint: ${\mathbf{n}}\ge 0$.
5:     a[$\mathit{dim}$]ComplexInput/Output
Note: the dimension, dim, of the array a must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pda}}×{\mathbf{n}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}×{\mathbf{pda}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
Where ${\mathbf{A}}\left(i,j\right)$ appears in this document, it refers to the array element
• ${\mathbf{a}}\left[\left(j-1\right)×{\mathbf{pda}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{a}}\left[\left(i-1\right)×{\mathbf{pda}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the $m$ by $n$ matrix $A$.
On exit: if $m\le n$, the upper triangle of the subarray ${\mathbf{A}}\left(1:m,n-m+1:n\right)$ contains the $m$ by $m$ upper triangular matrix ${R}_{12}$.
If $m\ge n$, the elements on and above the $\left(m-n\right)$th subdiagonal contain the $m$ by $n$ upper trapezoidal matrix $R$; the remaining elements, with the array taua, represent the unitary matrix $Q$ as a product of $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ elementary reflectors (see Section 3.3.6 in the f08 Chapter Introduction).
6:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
7:     taua[$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)$]ComplexOutput
On exit: the scalar factors of the elementary reflectors which represent the unitary matrix $Q$.
8:     b[$\mathit{dim}$]ComplexInput/Output
Note: the dimension, dim, of the array b must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdb}}×{\mathbf{n}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}×{\mathbf{pdb}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
The $\left(i,j\right)$th element of the matrix $B$ is stored in
• ${\mathbf{b}}\left[\left(j-1\right)×{\mathbf{pdb}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{b}}\left[\left(i-1\right)×{\mathbf{pdb}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the $p$ by $n$ matrix $B$.
On exit: the elements on and above the diagonal of the array contain the $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(p,n\right)$ by $n$ upper trapezoidal matrix $T$ ($T$ is upper triangular if $p\ge n$); the elements below the diagonal, with the array taub, represent the unitary matrix $Z$ as a product of elementary reflectors (see Section 3.3.6 in the f08 Chapter Introduction).
9:     pdbIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
10:   taub[$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{p}},{\mathbf{n}}\right)$]ComplexOutput
On exit: the scalar factors of the elementary reflectors which represent the unitary matrix $Z$.
11:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_INT
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m}}\ge 0$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{p}}\ge 0$.
On entry, ${\mathbf{pda}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pda}}>0$.
On entry, ${\mathbf{pdb}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdb}}>0$.
NE_INT_2
On entry, ${\mathbf{pda}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
On entry, ${\mathbf{pda}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry, ${\mathbf{pdb}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry, ${\mathbf{pdb}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

## 7  Accuracy

The computed generalized $RQ$ 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.

## 8  Parallelism and Performance

nag_zggrqf (f08ztc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_zggrqf (f08ztc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

The unitary matrices $Q$ and $Z$ may be formed explicitly by calls to nag_zungrq (f08cwc) and nag_zungqr (f08atc) respectively. nag_zunmrq (f08cxc) may be used to multiply $Q$ by another matrix and nag_zunmqr (f08auc) may be used to multiply $Z$ by another matrix.
The real analogue of this function is nag_dggrqf (f08zfc).

## 10  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.05+0.41i -0.98+1.98i -1.20+0.19i -0.66+0.42i -0.81+0.56i 0.62-0.46i 1.01+0.02i 0.63-0.17i -1.11+0.60i 0.37+0.38i 0.19-0.54i -0.98-0.36i 0.22-0.20i 0.83+0.51i 0.20+0.01i -0.17-0.46i 1.47+1.59i 1.08-0.28i 0.20-0.12i -0.07+1.23i 0.26+0.26i ,$
 $B = 1 0 -1 0 0 1 0 -1 , c= -2.54+0.09i 1.65-2.26i -2.11-3.96i 1.82+3.30i -6.41+3.77i 2.07+0.66i and d= 0 0 .$
The constraints $Bx=d$ correspond to ${x}_{1}={x}_{3}$ and ${x}_{2}={x}_{4}$.
The solution is obtained by first obtaining 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.

### 10.1  Program Text

Program Text (f08ztce.c)

### 10.2  Program Data

Program Data (f08ztce.d)

### 10.3  Program Results

Program Results (f08ztce.r)