NAG CL Interface
f08kwc (zgesvj)
1
Purpose
f08kwc computes the one-sided Jacobi singular value decomposition (SVD) of a complex
by
, general or triangular, matrix
,
, with fast scaled rotations and de Rijk’s pivoting, optionally computing the left and/or right singular vectors. For
, the functions
f08kpc or
f08krc may be used.
2
Specification
void |
f08kwc (Nag_OrderType order,
Nag_MatrixType joba,
Nag_LeftVecsType jobu,
Nag_RightVecsType jobv,
Integer m,
Integer n,
Complex a[],
Integer pda,
double sva[],
Integer mv,
Complex v[],
Integer pdv,
double ctol,
double rwork[],
NagError *fail) |
|
The function may be called by the names: f08kwc, nag_lapackeig_zgesvj or nag_zgesvj.
3
Description
The SVD is written as
where
is an
by
diagonal matrix,
is an
by
unitary matrix, and
is an
by
unitary matrix. The diagonal elements of
are the singular values of
in descending order of magnitude. The columns of
and
are the left and the right singular vectors of
, respectively.
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
https://www.netlib.org/lapack/lug
Drmač Z and Veselić K (2008a) New fast and accurate Jacobi SVD Algorithm I SIAM J. Matrix Anal. Appl. 29 4
Drmač Z and Veselić K (2008b) New fast and accurate Jacobi SVD Algorithm II SIAM J. Matrix Anal. Appl. 29 4
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
5
Arguments
-
1:
– Nag_OrderType
Input
-
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.1.3 in the Introduction to the NAG Library CL Interface for a more detailed explanation of the use of this argument.
Constraint:
or .
-
2:
– Nag_MatrixType
Input
-
On entry: specifies the structure of matrix
.
- The input matrix is lower triangular.
- The input matrix is upper triangular.
- The input matrix is a general by matrix, .
Constraint:
, or .
-
3:
– Nag_LeftVecsType
Input
-
On entry: specifies whether to compute the left singular vectors and if so whether you want to control their numerical orthogonality threshold.
- The left singular vectors corresponding to the nonzero singular values are computed and returned in the leading columns of a. See more details in the description of a. The numerical orthogonality threshold is set to approximately , where is the machine precision.
- Analogous to , except that you can control the level of numerical orthogonality of the computed left singular vectors. The orthogonality threshold is set to , where is given on input in . The option can be used if is a satisfactory orthogonality of the computed left singular vectors, so could save a few sweeps of Jacobi rotations. See the descriptions of a and .
- The matrix is not computed. However, see the description of a.
Constraint:
, or .
-
4:
– Nag_RightVecsType
Input
-
On entry: specifies whether and how to compute the right singular vectors.
- The matrix is computed and returned in the array v.
- The Jacobi rotations are applied to the leading by part of the array v. In other words, the right singular vector matrix is not computed explicitly, instead it is applied to an by matrix initially stored in the first mv rows of v.
- The matrix is not computed and the array v is not referenced.
Constraint:
, or .
-
5:
– Integer
Input
-
On entry: , the number of rows of the matrix .
Constraint:
.
-
6:
– Integer
Input
-
On entry: , the number of columns of the matrix .
Constraint:
.
-
7:
– Complex
Input/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: the matrix
containing the left singular vectors of
.
- If or
-
- if
- unitary columns of are returned in the leading columns of the array a. Here is the number of computed singular values of that are above the safe range parameter, as returned by X02AMC. The singular vectors corresponding to underflowed or zero singular values are not computed. The value of is returned by rounding to the nearest whole number. Also see the descriptions of sva and rwork. The computed columns of are mutually numerically unitary up to approximately ; or (), where is the machine precision and is supplied on entry in , see the description of jobu.
- if
- f08kwc did not converge in iterations (sweeps). In this case, the computed columns of may not be unitary up to . The output (stored in a), (given by the computed singular values in sva) and is still a decomposition of the input matrix in the sense that the residual is small, where is the value returned in .
- If
-
- if
- Note that the left singular vectors are ‘for free’ in the one-sided Jacobi SVD algorithm. However, if only the singular values are needed, the level of numerical orthogonality of is not an issue and iterations are stopped when the columns of the iterated matrix are numerically unitary up to approximately . Thus, on exit, a contains the columns of scaled with the corresponding singular values.
- if
- f08kwc did not converge in iterations (sweeps).
-
8:
– Integer
Input
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
a.
Constraints:
- if ,
;
- if , .
-
9:
– double
Output
-
On exit: the, possibly scaled, singular values of
.
- If
- The singular values of are
, for , where is the scale factor stored in . Normally , however, if some of the singular values of might underflow or overflow, then and the scale factor needs to be applied to obtain the singular values.
- If
- f08kwc did not converge in iterations and may not be accurate.
-
10:
– Integer
Input
-
On entry: if
, the product of Jacobi rotations is applied to the first
rows of
v.
If
,
mv is ignored. See the description of
jobv.
Constraint:
.
-
11:
– Complex
Input/Output
-
Note: the dimension,
dim, of the array
v
must be at least
- when
;
- when
and
;
- when
and
;
- otherwise.
The
th element of the matrix
is stored in
- when ;
- when .
On entry: if
,
v must contain an
by
matrix to be premultiplied by the matrix
of right singular vectors.
On exit: the right singular vectors of
.
If
,
v contains the
by
matrix of the right singular vectors.
If
,
v contains the product of the computed right singular vector matrix and the initial matrix in the array
v.
If
,
v is not referenced.
-
12:
– Integer
Input
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
v.
Constraints:
- if ,
- if , ;
- if , ;
- otherwise ;
- if ,
- if ,
;
- if ,
;
- otherwise .
-
13:
– double
Input
-
On entry: if , ,
the threshold for convergence. The process stops if all columns of are mutually orthogonal up to . It is required that , i.e., it is not possible to force the function to obtain orthogonality below . greater than is meaningless, where is the machine precision.
Constraint:
if , .
-
14:
– double
Input/Output
-
On exit: contains information about the completed job.
- The scaling factor, , such that
, for , are the computed singular values of . (See the description of sva.)
- gives, as nearest integer, the number of the computed nonzero singular values.
- gives, as nearest integer, the number of the computed singular values that are larger than the underflow threshold.
- gives, as nearest integer, the number of iterations (sweeps of Jacobi rotations) needed for numerical convergence.
- in the last iteration (sweep). This is useful information in cases when f08kwc did not converge, as it can be used to estimate whether the output is still useful and for subsequent analysis.
- The largest absolute value over all sines of the Jacobi rotation angles in the last sweep. It can be useful for subsequent analysis.
-
15:
– NagError *
Input/Output
-
The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
6
Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
- NE_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_CONVERGENCE
-
f08kwc did not converge in the allowed number of iterations (), but its output might still be useful.
- NE_ENUM_INT_2
-
On entry, , and .
Constraint: if ,
;
if ,
;
otherwise .
- NE_ENUM_INT_3
-
On entry, , , and .
Constraint: if , ;
if , ;
otherwise .
- NE_ENUM_REAL_1
-
On entry, and .
Constraint: if , .
- NE_INT
-
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_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 7.5 in the Introduction to the NAG Library CL Interface for further information.
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library CL Interface for further information.
7
Accuracy
The computed SVD is nearly the exact SVD for a nearby matrix
, where
and
is the
machine precision. In addition, the computed singular vectors are nearly unitary to working precision. See Section 4.9 of
Anderson et al. (1999) for further details.
See Section 6 of
Drmač and Veselić (2008a) for a detailed discussion of the accuracy of the computed SVD.
8
Parallelism and Performance
f08kwc 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.
This SVD algorithm is numerically superior to the bidiagonalization based
algorithm implemented by
f08kpc and the divide and conquer algorithm implemented by
f08krc and is considerably faster than previous implementations of the (equally accurate) Jacobi SVD method. Moreover, this algorithm can compute the SVD faster than
f08kpc and not much slower than
f08krc. See Section 3.3 of
Drmač and Veselić (2008b) for the details.
The real analogue of this function is
f08kjc.
10
Example
This example finds the singular values and left and right singular vectors of the
by
matrix
together with approximate error bounds for the computed singular values and vectors.
10.1
Program Text
10.2
Program Data
10.3
Program Results