Syntax

Description

The SVD is written as

A = UΣVT,

A=UΣVT,

where ΣΣ is an nn by nn diagonal matrix, UU is an mm by nn orthonormal matrix, and VV is an nn by nn orthogonal matrix. The diagonal elements of ΣΣ are the singular values of AA in descending order of magnitude. The columns of UU and VV are the left and the right singular vectors of AA.

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 × εtol=ctol×ε, where εε is the machine precision and ctol = sqrt(m)ctol=m.

Analogous to jobu = 'U'jobu='U', except that you can control the level of numerical orthogonality of the computed left singular vectors. The orthogonality threshold is set to tol = ctol × εtol=ctol×ε, where ctolctol is given on input in work(1)work1. The option jobu = 'C'jobu='C' can be used if m × εm×ε is a satisfactory orthogonality of the computed left singular vectors, so ctol = mctol=m could save a few sweeps of Jacobi rotations. See the descriptions of a and work(1)work1.

The Jacobi rotations are applied to the leading mvmv by nn part of the array v. In other words, the right singular vector matrix VV is not computed explicitly, instead it is applied to an mvmv by nn matrix initially stored in the first mv rows of v.

The second dimension of the array must be at least max(1,n)max(1,n) if jobv = 'V'jobv='V' or 'A''A', and at least 11 otherwise

If jobv = 'A'jobv='A', v must contain an mvmv by nn matrix to be premultiplied by the matrix VV of right singular vectors.

7:
work(lwork) – double array

lwork, the dimension of the array, must satisfy the constraint
lwork ≥ max(6,m + n)lwork≥max(6,m+n).

If jobu = 'C'jobu='C', work(1) = ctolwork1=ctol, where ctolctol defines the threshold for convergence. The process stops if all columns of AA are mutually orthogonal up to ctol × εctol×ε. It is required that ctol ≥ 1ctol≥1, i.e., it is not possible to force the function to obtain orthogonality below εε. ctolctol greater than 1 / ε1/ε is meaningless, where εε is the machine precision.

rank(A)rank(A) orthonormal columns of UU are returned in the leading rank(A)rank(A) columns of the array a. Here rank(A) ≤ nrank(A)≤n is the number of computed singular values of AA that are above the safe range parameter, as returned by nag_machine_real_safe (x02am). The singular vectors corresponding to underflowed or zero singular values are not computed. The value of rank(A)rank(A) is returned by rounding work(2)work2 to the nearest whole number. Also see the descriptions of sva and work. The computed columns of UU are mutually numerically orthogonal up to approximately tol = sqrt(m) × εtol=m×ε; or tol = ctol × εtol=ctol×ε (jobu = 'C'jobu='C'), where εε is the machine precision and ctolctol is supplied on entry in work(1)work1, see the description of jobu.

nag_lapack_dgesvj (f08kj) did not converge in 3030 iterations (sweeps). In this case, the computed columns of UU may not be orthogonal up to toltol. The output UU (stored in a), ΣΣ (given by the computed singular values in sva) and VV is still a decomposition of the input matrix AA in the sense that the residual ‖A − α × U × Σ × VT‖2 / ‖A‖2‖A-α×U×Σ×VT‖2/‖A‖2 is small, where αα is the value returned in work(1)work1.

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 UU is not an issue and iterations are stopped when the columns of the iterated matrix are numerically orthogonal up to approximately m × εm×ε. Thus, on exit, a contains the columns of UU scaled with the corresponding singular values.

The singular values of AA are
σi = αsva(i)σi=αsvai, for i = 1,2, … ,ni=1,2,…,n, where αα is the scale factor stored in work(1)work1. Normally α = 1α=1, however, if some of the singular values of AA might underflow or overflow, then α ≠ 1α≠1 and the scale factor needs to be applied to obtain the singular values.

maxi ≠ j|cos(A( : ,i),A( : ,j))|maxi≠j|cos(A(:,i),A(:,j))| in the last iteration (sweep). This is useful information in cases when nag_lapack_dgesvj (f08kj) did not converge, as it can be used to estimate whether the output is still useful and for subsequent analysis.