NAG Library Function Document

nag_dgels (f08aac)

void	nag_dgels (Nag_OrderType order, Nag_TransType trans, Integer m, Integer n, Integer nrhs, double a[], Integer pda, double b[], Integer pdb, NagError *fail)

3 Description

The following options are provided:

If $trans = Nag_NoTrans$ and $m \geq n$ : find the least squares solution of an overdetermined system, i.e., solve the least squares problem
$\min_{x} {‖b - A x‖}_{2} .$
If $trans = Nag_NoTrans$ and $m < n$ : find the minimum norm solution of an underdetermined system $A x = b$ .
If $trans = Nag_Trans$ and $m \geq n$ : find the minimum norm solution of an undetermined system $A^{T} x = b$ .
If $trans = Nag_Trans$ and $m < n$ : find the least squares solution of an overdetermined system, i.e., solve the least squares problem
$\min_{x} {‖b - A^{T} x‖}_{2} .$

Several right-hand side vectors

b

and solution vectors

x

can be handled in a single call; they are stored as the columns of the

m

r

right-hand side matrix

B

and the

n

r

solution matrix

X

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: trans – Nag_TransTypeInput

On entry: if

trans = Nag_NoTrans

, the linear system involves

A

trans = Nag_Trans

, the linear system involves

A^{T}

Constraint:

trans = Nag_NoTrans

Nag_Trans

3: m – IntegerInput

On entry:

m

, the number of rows of the matrix

A

Constraint:

m \geq 0

4: n – IntegerInput

On entry:

n

, the number of columns of the matrix

A

Constraint:

n \geq 0

5: 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

6: a[ $\dim$ ] – doubleInput/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: if

m \geq n

, a is overwritten by details of its

Q R

factorization as returned by nag_dgeqrf (f08aec).

m < n

, a is overwritten by details of its

L Q

factorization as returned by nag_dgelqf (f08ahc).

7: 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)$ .

8: b[ $\dim$ ] – doubleInput/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 matrix

B

of right-hand side vectors, stored in rows or columns; b is

m

r

trans = Nag_NoTrans

, or

n

r

trans = Nag_Trans

On exit: b is overwritten by the solution vectors,

x

, stored in rows or columns:

if $trans = Nag_NoTrans$ and $m \geq n$ , or $trans = Nag_Trans$ and $m < n$ , elements $1$ to $\min (m, n)$ in each column of b contain the least squares solution vectors; the residual sum of squares for the solution is given by the sum of squares of the modulus of elements $(\min (m, n) + 1)$ to $\max (m, n)$ in that column;
otherwise, elements $1$ to $\max (m, n)$ in each column of b contain the minimum norm solution vectors.

9: 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)$ .

10: 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_FULL_RANK: Diagonal element $〈value〉$ of the triangular factor of $A$ is zero, so that $A$ does not have full rank; the least squares solution could not be computed.
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 total number of floating point operations required to factorize

A

is approximately

\frac{2}{3} n^{2} (3 m - n)

m \geq n

and

\frac{2}{3} m^{2} (3 n - m)

otherwise. Following the factorization the solution for a single vector

x

requires

O (\min (m^{2}, n^{2}))

operations.

The complex analogue of this function is nag_zgels (f08anc).

9 Example

This example solves the linear least squares problem

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

where

A = (\begin{array}{r} - 0.57 & - 1.28 & - 0.39 & 0.25 \\ - 1.93 & 1.08 & - 0.31 & - 2.14 \\ 2.30 & 0.24 & 0.40 & - 0.35 \\ - 1.93 & 0.64 & - 0.66 & 0.08 \\ 0.15 & 0.30 & 0.15 & - 2.13 \\ - 0.02 & 1.03 & - 1.43 & 0.50 \end{array}) and b = (\begin{array}{r} - 2.67 \\ - 0.55 \\ 3.34 \\ - 0.77 \\ 0.48 \\ 4.10 \end{array}) .

The square root of the residual sum of squares is also output.

NAG Library Function Documentnag_dgels (f08aac)

+− 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_dgels (f08aac)