NAG Library Function Document
nag_zgels (f08anc)
1
Purpose
nag_zgels (f08anc) solves linear least squares problems of the form
where
is an
by
complex matrix of full rank, using a
or
factorization of
.
2
Specification
#include <nag.h> |
#include <nagf08.h> |
void |
nag_zgels (Nag_OrderType order,
Nag_TransType trans,
Integer m,
Integer n,
Integer nrhs,
Complex a[],
Integer pda,
Complex b[],
Integer pdb,
NagError *fail) |
|
3
Description
The following options are provided:
1. |
If and : find the least squares solution of an overdetermined system, i.e., solve the least squares problem
|
2. |
If and : find the minimum norm solution of an underdetermined system . |
3. |
If and : find the minimum norm solution of an undetermined system . |
4. |
If and : find the least squares solution of an overdetermined system, i.e., solve the least squares problem
|
Several right-hand side vectors and solution vectors can be handled in a single call; they are stored as the columns of the by right-hand side matrix and the by solution matrix .
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:
– 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
. See
Section 3.3.1.3 in How to Use the NAG Library and its Documentation for a more detailed explanation of the use of this argument.
Constraint:
or .
- 2:
– Nag_TransTypeInput
-
On entry: if
, the linear system involves
.
If , the linear system involves .
Constraint:
or .
- 3:
– IntegerInput
-
On entry: , the number of rows of the matrix .
Constraint:
.
- 4:
– IntegerInput
-
On entry: , the number of columns of the matrix .
Constraint:
.
- 5:
– IntegerInput
-
On entry: , the number of right-hand sides, i.e., the number of columns of the matrices and .
Constraint:
.
- 6:
– ComplexInput/Output
-
Note: the dimension,
dim, of the array
a
must be at least
- when
;
- when
.
The
th element of the matrix
is stored in
- when ;
- when .
On entry: the by matrix .
On exit: if
,
a is overwritten by details of its
factorization, as returned by
nag_zgeqrf (f08asc).
If
,
a is overwritten by details of its
factorization, as returned by
nag_zgelqf (f08avc).
- 7:
– IntegerInput
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
a.
Constraints:
- if ,
;
- if , .
- 8:
– ComplexInput/Output
-
Note: the dimension,
dim, of the array
b
must be at least
- when
;
- when
.
The
th element of the matrix
is stored in
- when ;
- when .
On entry: the matrix
of right-hand side vectors, stored in rows or columns;
b is
by
if
, or
by
if
.
On exit:
b is overwritten by the solution vectors,
, stored in rows or columns:
- if and , or and , elements to 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 to in that column;
- otherwise, elements to in each column of b contain the minimum norm solution vectors.
- 9:
– IntegerInput
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
b.
Constraints:
- if ,
;
- if , .
- 10:
– NagError *Input/Output
-
The NAG error argument (see
Section 3.7 in How to Use the NAG Library and its Documentation).
6
Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
- NE_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_FULL_RANK
-
Diagonal element of the triangular factor of is zero, so that does not have full rank; the least squares solution could not be computed.
- NE_INT
-
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_2
-
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
- NE_INT_3
-
On entry, , and .
Constraint: .
- 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.
See
Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
See Section 4.5 of
Anderson et al. (1999) for details of error bounds.
8
Parallelism and Performance
nag_zgels (f08anc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_zgels (f08anc) 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.
Please consult the
x06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
The total number of floating-point operations required to factorize is approximately if and otherwise. Following the factorization the solution for a single vector requires operations.
The real analogue of this function is
nag_dgels (f08aac).
10
Example
This example solves the linear least squares problem
where
and
The square root of the residual sum of squares is also output.
10.1
Program Text
Program Text (f08ance.c)
10.2
Program Data
Program Data (f08ance.d)
10.3
Program Results
Program Results (f08ance.r)