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_zgelsy (f08bn)

## Purpose

nag_lapack_zgelsy (f08bn) computes the minimum norm solution to a complex linear least squares problem
 min ‖b − Ax‖2 x
$minx ‖b-Ax‖2$
using a complete orthogonal factorization of A$A$. A$A$ is an m$m$ by n$n$ matrix which may be rank-deficient. Several right-hand side vectors b$b$ and solution vectors x$x$ can be handled in a single call.

## Syntax

[a, b, jpvt, rank, info] = f08bn(a, b, jpvt, rcond, 'm', m, 'n', n, 'nrhs_p', nrhs_p)
[a, b, jpvt, rank, info] = nag_lapack_zgelsy(a, b, jpvt, rcond, 'm', m, 'n', n, 'nrhs_p', nrhs_p)

## Description

The right-hand side vectors are stored as the columns of the m$m$ by r$r$ matrix B$B$ and the solution vectors in the n$n$ by r$r$ matrix X$X$.
nag_lapack_zgelsy (f08bn) first computes a QR$QR$ factorization with column pivoting
AP = Q
 ( R11 R12 ) 0 R22
,
$AP= Q R11 R12 0 R22 ,$
with R11${R}_{11}$ defined as the largest leading sub-matrix whose estimated condition number is less than 1 / rcond$1/{\mathbf{rcond}}$. The order of R11${R}_{11}$, rank, is the effective rank of A$A$.
Then, R22${R}_{22}$ is considered to be negligible, and R12${R}_{12}$ is annihilated by orthogonal transformations from the right, arriving at the complete orthogonal factorization
AP = Q
 ( T11 0 ) 0 0
Z .
$AP= Q T11 0 0 0 Z .$
The minimum norm solution is then
X = PZH
 ( T11 − 1 Q1H b ) 0
$X = PZH T11-1 Q1H b 0$
where Q1${Q}_{1}$ consists of the first rank columns of Q$Q$.

## 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
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     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)$
The m$m$ by n$n$ matrix A$A$.
2:     b(ldb, : $:$) – complex array
The first dimension of the array b must be at least max (1,m,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{n}}\right)$
The second dimension of the array must be at least max (1,nrhs)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{nrhs}}\right)$
The m$m$ by r$r$ right-hand side matrix B$B$.
3:     jpvt( : $:$) – int64int32nag_int array
Note: the dimension of the array jpvt must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
If jpvt(i)0${\mathbf{jpvt}}\left(i\right)\ne 0$, the i$i$th column of A$A$ is permuted to the front of AP$AP$, otherwise column i$i$ is a free column.
4:     rcond – double scalar
Used to determine the effective rank of A$A$, which is defined as the order of the largest leading triangular sub-matrix R11${R}_{11}$ in the QR$QR$ factorization of A$A$, whose estimated condition number is < 1 / rcond$\text{}<1/{\mathbf{rcond}}$.
Suggested value: if the condition number of a is not known then rcond = sqrt((ε) / 2)${\mathbf{rcond}}=\sqrt{\left(\epsilon \right)/2}$ (where ε$\epsilon$ is machine precision, see nag_machine_precision (x02aj)) is a good choice. Negative values or values less than machine precision should be avoided since this will cause a to have an effective rank = min (m,n)$\text{rank}=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)$ that could be larger than its actual rank, leading to meaningless results.

### Optional Input Parameters

1:     m – int64int32nag_int scalar
Default: The first dimension of the array a.
m$m$, the number of rows of the matrix A$A$.
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 matrix A$A$.
Constraint: n0${\mathbf{n}}\ge 0$.
3:     nrhs_p – int64int32nag_int scalar
Default: The second dimension of the array b.
r$r$, the number of right-hand sides, i.e., the number of columns of the matrices B$B$ and X$X$.
Constraint: nrhs0${\mathbf{nrhs}}\ge 0$.

### Input Parameters Omitted from the MATLAB Interface

lda ldb work lwork rwork

### 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)$.
a stores details of its complete orthogonal factorization.
2:     b(ldb, : $:$) – complex array
The first dimension of the array b will be max (1,m,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{n}}\right)$
The second dimension of the array will be max (1,nrhs)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{nrhs}}\right)$
ldbmax (1,m,n)$\mathit{ldb}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}},{\mathbf{n}}\right)$.
The n$n$ by r$r$ solution matrix X$X$.
3:     jpvt( : $:$) – int64int32nag_int array
Note: the dimension of the array jpvt must be at least max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
If jpvt(i) = k${\mathbf{jpvt}}\left(i\right)=k$, then the i$i$th column of AP$AP$ was the k$k$th column of A$A$.
4:     rank – int64int32nag_int scalar
The effective rank of A$A$, i.e., the order of the sub-matrix R11${R}_{11}$. This is the same as the order of the sub-matrix T11${T}_{11}$ in the complete orthogonal factorization of A$A$.
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: m, 2: n, 3: nrhs_p, 4: a, 5: lda, 6: b, 7: ldb, 8: jpvt, 9: rcond, 10: rank, 11: work, 12: lwork, 13: rwork, 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

See Section 4.5 of Anderson et al. (1999) for details of error bounds.

The real analogue of this function is nag_lapack_dgelsy (f08ba).

## Example

```function nag_lapack_zgelsy_example
a = [ 0.47 - 0.34i,  -0.4 + 0.54i,  0.6 + 0.01i,  0.8 - 1.02i;
-0.32 - 0.23i,  -0.05 + 0.2i,  -0.26 - 0.44i,  -0.43 + 0.17i;
0.35 - 0.6i,  -0.52 - 0.34i,  0.87 - 0.11i,  -0.34 - 0.09i;
0.89 + 0.71i,  -0.45 - 0.45i,  -0.02 - 0.57i,  1.14 - 0.78i;
-0.19 + 0.06i,  0.11 - 0.85i,  1.44 + 0.8i,  0.07 + 1.14i];
b = [ -1.08 - 2.59i;
-2.61 - 1.49i;
3.13 - 3.61i;
7.33 - 8.01i;
9.12 + 7.63i];
jpvt = [int64(0);0;0;0];
rcond = 0.01;
[aOut, bOut, jpvtOut, rank, info] = nag_lapack_zgelsy(a, b, jpvt, rcond)
```
```

aOut =

2.5031 + 0.0000i   0.4809 - 0.6802i  -0.3516 - 1.0496i   0.0243 - 0.2110i
-0.1420 + 0.0082i  -1.9697 + 0.0000i   0.6274 + 0.2048i  -0.0617 + 0.1246i
-0.0906 - 0.0591i  -0.4734 + 0.1684i  -1.2204 + 0.0000i  -0.2462 - 0.2637i
0.4082 - 0.1178i   0.2585 + 0.0267i   0.0451 + 0.5815i  -0.0094 + 0.0000i
-0.0896 + 0.3397i  -0.6872 + 0.0317i  -0.1171 - 0.0121i   0.8616 - 0.2123i

bOut =

1.1669 - 3.3224i
1.3486 + 5.5027i
4.1764 + 2.3435i
0.6467 + 0.0107i
-0.1224 - 0.0933i

jpvtOut =

4
3
2
1

rank =

3

info =

0

```
```function f08bn_example
a = [ 0.47 - 0.34i,  -0.4 + 0.54i,  0.6 + 0.01i,  0.8 - 1.02i;
-0.32 - 0.23i,  -0.05 + 0.2i,  -0.26 - 0.44i,  -0.43 + 0.17i;
0.35 - 0.6i,  -0.52 - 0.34i,  0.87 - 0.11i,  -0.34 - 0.09i;
0.89 + 0.71i,  -0.45 - 0.45i,  -0.02 - 0.57i,  1.14 - 0.78i;
-0.19 + 0.06i,  0.11 - 0.85i,  1.44 + 0.8i,  0.07 + 1.14i];
b = [ -1.08 - 2.59i;
-2.61 - 1.49i;
3.13 - 3.61i;
7.33 - 8.01i;
9.12 + 7.63i];
jpvt = [int64(0);0;0;0];
rcond = 0.01;
[aOut, bOut, jpvtOut, rank, info] = f08bn(a, b, jpvt, rcond)
```
```

aOut =

2.5031 + 0.0000i   0.4809 - 0.6802i  -0.3516 - 1.0496i   0.0243 - 0.2110i
-0.1420 + 0.0082i  -1.9697 + 0.0000i   0.6274 + 0.2048i  -0.0617 + 0.1246i
-0.0906 - 0.0591i  -0.4734 + 0.1684i  -1.2204 + 0.0000i  -0.2462 - 0.2637i
0.4082 - 0.1178i   0.2585 + 0.0267i   0.0451 + 0.5815i  -0.0094 + 0.0000i
-0.0896 + 0.3397i  -0.6872 + 0.0317i  -0.1171 - 0.0121i   0.8616 - 0.2123i

bOut =

1.1669 - 3.3224i
1.3486 + 5.5027i
4.1764 + 2.3435i
0.6467 + 0.0107i
-0.1224 - 0.0933i

jpvtOut =

4
3
2
1

rank =

3

info =

0

```