NAG Library Function Document

nag_zgelsy (f08bnc)

void	nag_zgelsy (Nag_OrderType order, Integer m, Integer n, Integer nrhs, Complex a[], Integer pda, Complex b[], Integer pdb, Integer jpvt[], double rcond, Integer rank, NagError fail)

3 Description

The right-hand side vectors are stored as the columns of the

m

r

matrix

B

and the solution vectors in the

n

r

matrix

X

nag_zgelsy (f08bnc) first computes a

Q R

factorization with column pivoting

A P = Q (\begin{array}{r} R_{11} & R_{12} \\ 0 & R_{22} \end{array}),

with

R_{11}

defined as the largest leading sub-matrix whose estimated condition number is less than

1 / rcond

. The order of

R_{11}

, rank, is the effective rank of

A

Then,

R_{22}

is considered to be negligible, and

R_{12}

is annihilated by orthogonal transformations from the right, arriving at the complete orthogonal factorization

A P = Q (\begin{array}{r} T_{11} & 0 \\ 0 & 0 \end{array}) Z .

The minimum norm solution is then

X = P Z^{H} (\begin{matrix} T_{11}^{- 1} Q_{1}^{H} b \\ 0 \end{matrix})

where

Q_{1}

consists of the first rank columns of

Q

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

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

5 Arguments

1: order – Nag_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

order = Nag_RowMajor

. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

or Nag_ColMajor.

2: m – IntegerInput

On entry:

m

, the number of rows of the matrix

A

Constraint:

m \geq 0

3: n – IntegerInput

On entry:

n

, the number of columns of the matrix

A

Constraint:

n \geq 0

4: nrhs – IntegerInput

On entry:

r

, the number of right-hand sides, i.e., the number of columns of the matrices

B

and

X

Constraint:

nrhs \geq 0

5: a[ $\dim$ ] – ComplexInput/Output

Note: the dimension, dim, of the array a must be at least

$\max (1, pda \times n)$ when $order = Nag_ColMajor$ ;
$\max (1, m \times pda)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

A

is stored in

$a [(j - 1) \times pda + i - 1]$ when $order = Nag_ColMajor$ ;
$a [(i - 1) \times pda + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

m

n

matrix

A

On exit: a has been overwritten by details of its complete orthogonal factorization.

6: pda – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array a.

Constraints:

if $order = Nag_ColMajor$ , $pda \geq \max (1, m)$ ;
if $order = Nag_RowMajor$ , $pda \geq \max (1, n)$ .

7: b[ $\dim$ ] – ComplexInput/Output

Note: the dimension, dim, of the array b must be at least

$\max (1, pdb \times nrhs)$ when $order = Nag_ColMajor$ ;
$\max (1, \max (1, m, n) \times pdb)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

B

is stored in

$b [(j - 1) \times pdb + i - 1]$ when $order = Nag_ColMajor$ ;
$b [(i - 1) \times pdb + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

m

r

right-hand side matrix

B

On exit: the

n

r

solution matrix

X

8: pdb – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array b.

Constraints:

if $order = Nag_ColMajor$ , $pdb \geq \max (1, m, n)$ ;
if $order = Nag_RowMajor$ , $pdb \geq \max (1, nrhs)$ .

9: jpvt[ $\dim$ ] – IntegerInput/Output

Note: the dimension, dim, of the array jpvt must be at least

\max (1, n)

On entry: if

jpvt [i - 1] \neq 0

, the

i

th column of

A

is permuted to the front of

A P

, otherwise column

i

is a free column.

On exit: if

jpvt [i - 1] = k

, then the

i

th column of

A P

was the

k

th column of

A

10: rcond – doubleInput

On entry: used to determine the effective rank of

A

, which is defined as the order of the largest leading triangular sub-matrix

R_{11}

in the

Q R

factorization of

A

, whose estimated condition number is

< 1 / rcond

Suggested value: if the condition number of a is not known then

rcond = \sqrt{(ε) / 2}

(where

ε

is machine precision, see nag_machine_precision (X02AJC)) 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)

that could be larger than its actual rank, leading to meaningless results.

11: rank – Integer *Output

On exit: the effective rank of

A

, i.e., the order of the sub-matrix

R_{11}

. This is the same as the order of the sub-matrix

T_{11}

in the complete orthogonal factorization of

A

12: fail – NagError *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.
NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_INT: On entry, $m = 〈value〉$ .
Constraint: $m \geq 0$ .; On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .; On entry, $nrhs = 〈value〉$ .
Constraint: $nrhs \geq 0$ .; On entry, $pda = 〈value〉$ .
Constraint: $pda > 0$ .; On entry, $pdb = 〈value〉$ .
Constraint: $pdb > 0$ .
NE_INT_2: On entry, $pda = 〈value〉$ and $m = 〈value〉$ .
Constraint: $pda \geq \max (1, m)$ .; On entry, $pda = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pda \geq \max (1, n)$ .; On entry, $pdb = 〈value〉$ and $nrhs = 〈value〉$ .
Constraint: $pdb \geq \max (1, nrhs)$ .
NE_INT_3: On entry, $pdb = 〈value〉$ , $m = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdb \geq \max (1, m, n)$ .
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

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

8 Further Comments

The real analogue of this function is nag_dgelsy (f08bac).

9 Example

This example solves the linear least squares problem

\min_{x} {‖b - A x‖}_{2}

for the solution,

x

, of minimum norm, where

A = (\begin{array}{r} 0.47 - 0.34 i & - 0.40 + 0.54 i & 0.60 + 0.01 i & 0.80 - 1.02 i \\ - 0.32 - 0.23 i & - 0.05 + 0.20 i & - 0.26 - 0.44 i & - 0.43 + 0.17 i \\ 0.35 - 0.60 i & - 0.52 - 0.34 i & 0.87 - 0.11 i & - 0.34 - 0.09 i \\ 0.89 + 0.71 i & - 0.45 - 0.45 i & - 0.02 - 0.57 i & 1.14 - 0.78 i \\ - 0.19 + 0.06 i & 0.11 - 0.85 i & 1.44 + 0.80 i & 0.07 + 1.14 i \end{array})

and

b = (\begin{array}{r} - 1.08 - 2.59 i \\ - 2.61 - 1.49 i \\ 3.13 - 3.61 i \\ 7.33 - 8.01 i \\ 9.12 + 7.63 i \end{array}) .

A tolerance of

0.01

is used to determine the effective rank of

A

NAG Library Function Documentnag_zgelsy (f08bnc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_zgelsy (f08bnc)