NAG CL Interface
f08kjc (dgesvj)

Settings help

CL Name Style:


1 Purpose

f08kjc computes the one-sided Jacobi singular value decomposition (SVD) of a real m×n matrix A, mn, with fast scaled rotations and de Rijk’s pivoting, optionally computing the left and/or right singular vectors. For m<n, the functions f08kbc or f08kdc may be used.

2 Specification

#include <nag.h>
void  f08kjc (Nag_OrderType order, Nag_MatrixType joba, Nag_LeftVecsType jobu, Nag_RightVecsType jobv, Integer m, Integer n, double a[], Integer pda, double sva[], Integer mv, double v[], Integer pdv, double ctol, double work[], NagError *fail)
The function may be called by the names: f08kjc, nag_lapackeig_dgesvj or nag_dgesvj.

3 Description

The SVD is written as
A = UΣVT ,  
where Σ is an n×n diagonal matrix, U is an m×n orthonormal matrix, and V is an n×n orthogonal matrix. The diagonal elements of Σ are the singular values of A in descending order of magnitude. The columns of U and V are the left and the right singular vectors of A.

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: order 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 order=Nag_RowMajor. 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: order=Nag_RowMajor or Nag_ColMajor.
2: joba Nag_MatrixType Input
On entry: specifies the structure of matrix A.
joba=Nag_LowerMatrix
The input matrix A is lower triangular.
joba=Nag_UpperMatrix
The input matrix A is upper triangular.
joba=Nag_GeneralMatrix
The input matrix A is a general m×n matrix, mn.
Constraint: joba=Nag_LowerMatrix, Nag_UpperMatrix or Nag_GeneralMatrix.
3: jobu 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.
jobu=Nag_LeftSpan
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 tol=ctol×ε, where ε is the machine precision and ctol=m.
jobu=Nag_LeftVecsCtol
Analogous to jobu=Nag_LeftSpan, except that you can control the level of numerical orthogonality of the computed left singular vectors. The orthogonality threshold is set to tol=ctol×ε. The option jobu=Nag_LeftVecsCtol can be used if m×ε is a satisfactory orthogonality of the computed left singular vectors, so ctol=m could save a few sweeps of Jacobi rotations. See the descriptions of a and ctol.
jobu=Nag_NotLeftVecs
The matrix U is not computed. However, see the description of a.
Constraint: jobu=Nag_LeftSpan, Nag_LeftVecsCtol or Nag_NotLeftVecs.
4: jobv Nag_RightVecsType Input
On entry: specifies whether and how to compute the right singular vectors.
jobv=Nag_RightVecs
The matrix V is computed and returned in the array v.
jobv=Nag_RightVecsMV
The Jacobi rotations are applied to the leading mv×n part of the array v. In other words, the right singular vector matrix V is not computed explicitly, instead it is applied to an mv×n matrix initially stored in the first mv rows of v.
jobv=Nag_NotRightVecs
The matrix V is not computed and the array v is not referenced.
Constraint: jobv=Nag_RightVecs, Nag_RightVecsMV or Nag_NotRightVecs.
5: m Integer Input
On entry: m, the number of rows of the matrix A.
Constraint: m0.
6: n Integer Input
On entry: n, the number of columns of the matrix A.
Constraint: mn0.
7: a[dim] double Input/Output
Note: the dimension, dim, of the array a must be at least
  • max(1,pda×n) when order=Nag_ColMajor;
  • max(1,m×pda) when order=Nag_RowMajor.
The (i,j)th element of the matrix A is stored in
  • a[(j-1)×pda+i-1] when order=Nag_ColMajor;
  • a[(i-1)×pda+j-1] when order=Nag_RowMajor.
On entry: the m×n matrix A.
On exit: the matrix U containing the left singular vectors of A.
If jobu=Nag_LeftSpan or Nag_LeftVecsCtol
if fail.errnum=0
rank(A) orthonormal columns of U are returned in the leading rank(A) columns of the array a. Here rank(A)n is the number of computed singular values of A 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 rank(A) is returned by rounding work[1] to the nearest whole number. Also see the descriptions of sva and work. The computed columns of U are mutually numerically orthogonal up to approximately tol=m×ε; or tol=ctol×ε (jobu=Nag_LeftVecsCtol), where ε is the machine precision, see the description of jobu.
if fail.errnum>0
f08kjc did not converge in 30 iterations (sweeps). In this case, the computed columns of U may not be orthogonal up to tol. The output U (stored in a), Σ (given by the computed singular values in sva) and V is still a decomposition of the input matrix A in the sense that the residual A-α×U×Σ×VT2/A2 is small, where α is the value returned in work[0].
If jobu=Nag_NotLeftVecs
if fail.errnum=0
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 U is not an issue and iterations are stopped when the columns of the iterated matrix are numerically orthogonal up to approximately m×ε. Thus, on exit, a contains the columns of U scaled with the corresponding singular values.
if fail.errnum>0
f08kjc did not converge in 30 iterations (sweeps).
8: pda Integer Input
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraints:
  • if order=Nag_ColMajor, pdamax(1,m);
  • if order=Nag_RowMajor, pdamax(1,n).
9: sva[n] double Output
On exit: the, possibly scaled, singular values of A.
If fail.errnum=0
The singular values of A are σi=αsva[i-1], for i=1,2,,n, where α is the scale factor stored in work[0]. Normally α=1, however, if some of the singular values of A might underflow or overflow, then α1 and the scale factor needs to be applied to obtain the singular values.
If fail.errnum>0
f08kjc did not converge in 30 iterations and α×sva may not be accurate.
10: mv Integer Input
On entry: if jobv=Nag_RightVecsMV, the product of Jacobi rotations is applied to the first mv rows of v.
If jobvNag_RightVecsMV, mv is ignored. See the description of jobv.
Constraint: mv0.
11: v[dim] double Input/Output
Note: the dimension, dim, of the array v must be at least
  • max(1,pdv×n) when jobv=Nag_RightVecs;
  • max(1,pdv×n) when jobv=Nag_RightVecsMV and order=Nag_ColMajor;
  • max(1,mv×pdv) when jobv=Nag_RightVecsMV and order=Nag_RowMajor;
  • max(1,mv) otherwise.
The (i,j)th element of the matrix V is stored in
  • v[(j-1)×pdv+i-1] when order=Nag_ColMajor;
  • v[(i-1)×pdv+j-1] when order=Nag_RowMajor.
On entry: if jobv=Nag_RightVecsMV, v must contain an mv×n matrix to be premultiplied by the matrix V of right singular vectors.
On exit: the right singular vectors of A.
If jobv=Nag_RightVecs, v contains the n×n matrix of the right singular vectors.
If jobv=Nag_RightVecsMV, v contains the product of the computed right singular vector matrix and the initial matrix in the array v.
If jobv=Nag_NotRightVecs, v is not referenced.
12: pdv Integer Input
On entry: the stride separating row or column elements (depending on the value of order) in the array v.
Constraints:
  • if order=Nag_ColMajor,
    • if jobv=Nag_RightVecs, pdvmax(1,n);
    • if jobv=Nag_RightVecsMV, pdvmax(1,mv);
    • otherwise pdv1;
  • if order=Nag_RowMajor,
    • if jobv=Nag_RightVecs, pdvmax(1,n);
    • if jobv=Nag_RightVecsMV, pdvmax(1,n);
    • otherwise pdv1.
13: ctol double Input
On entry: if jobu=Nag_LeftVecsCtol, ctol=ctol, the threshold for convergence. The process stops if all columns of A are mutually orthogonal up to ctol×ε. It is required that ctol1, i.e., it is not possible to force the function to obtain orthogonality below ε. ctol greater than 1/ε is meaningless, where ε is the machine precision.
Constraint: if jobu=Nag_LeftVecsCtol, ctol1.0.
14: work[dim] double Output
On exit: contains information about the completed job.
work[0]
the scaling factor, α, such that σi=αsva[i-1], for i=1,2,,n are the computed singular values of A. (See description of sva.)
work[1]
nint(work[1])gives the number of the computed nonzero singular values.
work[2]
nint(work[2]) gives the number of the computed singular values that are larger than the underflow threshold.
work[3]
nint(work[3]) gives the number of iterations (sweeps of Jacobi rotations) needed for numerical convergence.
work[4]
maxij|cos(A(:,i),A(:,j))| in the last iteration (sweep). This is useful information in cases when f08kjc did not converge, as it can be used to estimate whether the output is still useful and for subsequent analysis.
work[5]
The largest absolute value over all sines of the Jacobi rotation angles in the last sweep. It can be useful for subsequent analysis.
15: fail 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 value had an illegal value.
NE_CONVERGENCE
f08kjc did not converge in the allowed number of iterations (30), but its output might still be useful.
NE_ENUM_INT_2
On entry, jobv=value, pdv=value and n=value.
Constraint: if jobv=Nag_RightVecs, pdvmax(1,n);
if jobv=Nag_RightVecsMV, pdvmax(1,n);
otherwise pdv1.
NE_ENUM_INT_3
On entry, jobv=value, n=value, mv=value and pdv=value.
Constraint: if jobv=Nag_RightVecs, pdvmax(1,n);
if jobv=Nag_RightVecsMV, pdvmax(1,mv);
otherwise pdv1.
NE_ENUM_REAL_1
On entry, jobu=value and ctol=value.
Constraint: if jobu=Nag_LeftVecsCtol, ctol1.0.
NE_INT
On entry, m=value.
Constraint: m0.
On entry, mv=value.
Constraint: mv0.
On entry, pda=value.
Constraint: pda>0.
On entry, pdv=value.
Constraint: pdv>0.
NE_INT_2
On entry, m=value and n=value.
Constraint: mn0.
On entry, pda=value and m=value.
Constraint: pdamax(1,m).
On entry, pda=value and n=value.
Constraint: pdamax(1,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.
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 (A+E) , where
E2 = O(ε) A2 ,  
and ε is the machine precision. In addition, the computed singular vectors are nearly orthogonal 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

f08kjc 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.

9 Further Comments

This SVD algorithm is numerically superior to the bidiagonalization based QR algorithm implemented by f08kbc and the divide and conquer algorithm implemented by f08kdc algorithms and is considerably faster than previous implementations of the (equally accurate) Jacobi SVD method. Moreover, this algorithm can compute the SVD faster than f08kbc and not much slower than f08kdc. See Section 3.3 of Drmač and Veselić (2008b) for the details.
The complex analogue of this function is f08kwc.

10 Example

This example finds the singular values and left and right singular vectors of the 6×4 matrix
A = ( 2.27 -1.54 1.15 -1.94 0.28 -1.67 0.94 -0.78 -0.48 -3.09 0.99 -0.21 1.07 1.22 0.79 0.63 -2.35 2.93 -1.45 2.30 0.62 -7.39 1.03 -2.57 ) ,  
together with approximate error bounds for the computed singular values and vectors.

10.1 Program Text

Program Text (f08kjce.c)

10.2 Program Data

Program Data (f08kjce.d)

10.3 Program Results

Program Results (f08kjce.r)