NAG Library Function Document
nag_complex_svd (f02xec)
1 Purpose
nag_complex_svd (f02xec) returns all, or part, of the singular value decomposition of a general complex matrix.
2 Specification
#include <nag.h> |
#include <nagf02.h> |
void |
nag_complex_svd (Integer m,
Integer n,
Complex a[],
Integer tda,
Integer ncolb,
Complex b[],
Integer tdb,
Nag_Boolean wantq,
Complex q[],
Integer tdq,
double sv[],
Nag_Boolean wantp,
Complex ph[],
Integer tdph,
Integer *iter,
double e[],
Integer *failinfo,
NagError *fail) |
|
3 Description
The
by
matrix
is factorized as
where
is an
by
unitary matrix,
is an
by
unitary matrix and
is a
by
diagonal matrix with real non-negative diagonal elements,
, ordered such that
The first
columns of
are the left-hand singular vectors of
, the diagonal elements of
are the singular values of
and the first
columns of
are the right-hand singular vectors of
.
Either or both of the left-hand and right-hand singular vectors of
may be requested and the matrix
given by
where
is an
by
given matrix, may also be requested.
The function obtains the singular value decomposition by first reducing to upper triangular form by means of Householder transformations, from the left when and from the right when The upper triangular form is then reduced to bidiagonal form by Givens plane rotations and finally the algorithm is used to obtain the singular value decomposition of the bidiagonal form.
Good background descriptions to the singular value decomposition are given in
Dongarra et al. (1979),
Hammarling (1985) and
Wilkinson (1978). Note that this function is not based on the LINPACK routine CSVDC.
Note that if
is any unitary diagonal matrix such that
then
is also a singular value decomposition of
.
4 References
Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) LINPACK Users' Guide SIAM, Philadelphia
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Wilkinson J H (1978) Singular Value Decomposition – Basic Aspects Numerical Software – Needs and Availability (ed D A H Jacobs) Academic Press
5 Arguments
- 1:
m – IntegerInput
On entry: the number of rows, , of the matrix .
Constraint:
.
When then an immediate return is effected.
- 2:
n – IntegerInput
On entry: the number of columns, , of the matrix .
Constraint:
.
When then an immediate return is effected.
- 3:
a[] – ComplexInput/Output
-
Note: the th element of the matrix is stored in .
On entry: the leading
by
part of the array
a must contain the matrix
whose singular value decomposition is required.
On exit: if
and
, then the leading
by
part of
a will contain the first
columns of the unitary matrix
.
If
and
, then the leading
by
part of
a will contain the first
rows of the unitary matrix
.
If
and
and
, then the leading
by
part of
a will contain the first
rows of the unitary matrix
.
Otherwise the contents of the leading
by
part of
a are indeterminate.
- 4:
tda – IntegerInput
-
On entry: the stride separating matrix column elements in the array
a.
Constraint:
.
- 5:
ncolb – IntegerInput
On entry:
, the number of columns of the matrix
. When
the array
b is not referenced and may be
NULL.
Constraint:
.
- 6:
b[] – ComplexInput/Output
-
Note: the th element of the matrix is stored in .
On entry: if
, the leading
by
part of the array
b must contain the matrix to be transformed.
If
the array
b is not referenced and may be
NULL.
On exit:
b is overwritten by the
by
matrix
.
- 7:
tdb – IntegerInput
-
On entry: the stride separating matrix column elements in the array
b.
Constraint:
if then .
- 8:
wantq – Nag_BooleanInput
-
On entry:
wantq must be Nag_TRUE if the left-hand singular vectors are required. If
then the array
q is not referenced and may be
NULL.
- 9:
q[] – ComplexOutput
-
Note: the th element of the matrix is stored in .
On exit: if
and
, the leading
by
part of the array
q will contain the unitary matrix
. Otherwise the array
q is not referenced and may be
NULL.
- 10:
tdq – IntegerInput
-
On entry: the stride separating matrix column elements in the array
q.
Constraint:
if and ,
- 11:
sv[] – doubleOutput
-
On exit: the diagonal elements of the matrix .
- 12:
wantp – Nag_BooleanInput
-
On entry:
wantp must be Nag_TRUE if the right-hand singular vectors are required. If
wantp = Nag_FALSE then the array
ph is not referenced and may be
NULL.
- 13:
ph[] – ComplexOutput
-
Note: the th element of the matrix is stored in .
On exit: if
and
wantq and
wantp are Nag_TRUE, the leading
by
part of the array
ph will contain the unitary matrix
. Otherwise the array
ph is not referenced and may be
NULL.
- 14:
tdph – IntegerInput
-
On entry: the stride separating matrix column elements in the array
ph.
Constraint:
if and and ,
- 15:
iter – Integer *Output
-
On exit: the total number of iterations taken by the algorithm.
- 16:
e[] – doubleOutput
-
On exit: if the error
NE_QR_NOT_CONV occurs the array
e contains the super-diagonal elements of matrix
in the factorization of
according to
. See
Section 6 for further details.
- 17:
failinfo – Integer *Output
-
On exit: if the error
NE_QR_NOT_CONV occurs
failinfo contains the number of singular values which may not have been found correctly. See
Section 6 for details.
- 18:
fail – NagError *Input/Output
-
The NAG error argument (see
Section 3.6 in the Essential Introduction).
6 Error Indicators and Warnings
- NE_2_INT_ARG_LT
-
On entry, while . These arguments must satisfy .
On entry, while . These arguments must satisfy .
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
- NE_INT_ARG_LT
-
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_QR_NOT_CONV
-
The QR algorithm has failed to converge in iterations. Singular values may not have been found correctly and the remaining singular values may not be the smallest. The matrix will nevertheless have been factorized as , where the leading by part of is a bidiagonal matrix with as the diagonal elements and as the super-diagonal elements. This failure is not likely to occur.
- NE_TDP_LT_N
-
On entry,
while
. When
wantq and
wantp are Nag_TRUE and
then relationship
must be satisfied.
- NE_TDQ_LT_M
-
On entry,
while
. When
wantq is Nag_TRUE and
then relationship
must be satisfied.
7 Accuracy
The computed factors
,
and
satisfy the relation
where
,
being the
machine precision,
is a modest function of
and
and
denotes the spectral (two) norm. Note that
.
8 Parallelism and Performance
Not applicable.
None.
10 Example
For this function two examples are presented. There is a single example program for nag_complex_svd (f02xec), with a main program and the code to solve the two example problems is given in the functions ex1 and ex2.
Example 1 (ex1)
To find the singular value decomposition of the 5 by 3 matrix
together with the vector
for the vector
Example 2 (ex2)
To find the singular value decomposition of the 3 by 5 matrix
10.1 Program Text
Program Text (f02xece.c)
10.2 Program Data
Program Data (f02xece.d)
10.3 Program Results
Program Results (f02xece.r)