NAG Library Function Document
nag_zgelsy (f08bnc)
1
Purpose
nag_zgelsy (f08bnc) computes the minimum norm solution to a complex linear least squares problem
using a complete orthogonal factorization of
.
is an
by
matrix which may be rank-deficient. Several right-hand side vectors
and solution vectors
can be handled in a single call.
2
Specification
#include <nag.h> |
#include <nagf08.h> |
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 by matrix and the solution vectors in the by matrix .
nag_zgelsy (f08bnc) first computes a
factorization with column pivoting
with
defined as the largest leading sub-matrix whose estimated condition number is less than
. The order of
,
rank, is the effective rank of
.
Then,
is considered to be negligible, and
is annihilated by orthogonal transformations from the right, arriving at the complete orthogonal factorization
The minimum norm solution is then
where
consists of the first
rank columns of
.
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:
– IntegerInput
-
On entry: , the number of rows of the matrix .
Constraint:
.
- 3:
– IntegerInput
-
On entry: , the number of columns of the matrix .
Constraint:
.
- 4:
– IntegerInput
-
On entry: , the number of right-hand sides, i.e., the number of columns of the matrices and .
Constraint:
.
- 5:
– 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:
a has been overwritten by details of its complete orthogonal factorization.
- 6:
– IntegerInput
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
a.
Constraints:
- if ,
;
- if , .
- 7:
– 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 by right-hand side matrix .
On exit: the by solution matrix .
- 8:
– IntegerInput
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
b.
Constraints:
- if ,
;
- if , .
- 9:
– IntegerInput/Output
-
Note: the dimension,
dim, of the array
jpvt
must be at least
.
On entry: if , the th column of is permuted to the front of , otherwise column is a free column.
On exit: if , the th column of was the th column of .
- 10:
– doubleInput
-
On entry: used to determine the effective rank of , which is defined as the order of the largest leading triangular sub-matrix in the factorization of , whose estimated condition number is .
Suggested value:
if the condition number of
a is not known then
(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
that could be larger than its actual rank, leading to meaningless results.
- 11:
– Integer *Output
-
On exit: the effective rank of , i.e., the order of the sub-matrix . This is the same as the order of the sub-matrix in the complete orthogonal factorization of .
- 12:
– 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_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_zgelsy (f08bnc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_zgelsy (f08bnc) 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 real analogue of this function is
nag_dgelsy (f08bac).
10
Example
This example solves the linear least squares problem
for the solution,
, of minimum norm, where
A tolerance of is used to determine the effective rank of .
10.1
Program Text
Program Text (f08bnce.c)
10.2
Program Data
Program Data (f08bnce.d)
10.3
Program Results
Program Results (f08bnce.r)