naginterfaces.library.rnla.svd_​rowext_​real

naginterfaces.library.rnla.svd_rowext_real(jobu, jobvt, a, k, statecomm, rtol_abs=- 1.0, rtol_rel=- 1.0)[source]

svd_rowext_real computes the singular value decomposition (SVD) of a real matrix , optionally computing the left and/or right singular vectors by using a randomised numerical linear algebra (RNLA) method.

For full information please refer to the NAG Library document for f10ca

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f10/f10caf.html

Parameters
jobustr, length 1

Specifies options for computing part of or none of the matrix .

The first columns of (the left singular vectors) are returned in the array .

No columns of (no left singular vectors) are computed.

jobvtstr, length 1

Specifies options for computing part of or none of the matrix .

The first rows of (the right singular vectors) are returned in the array .

No rows of (no right singular vectors) are computed.

afloat, array-like, shape

The matrix .

kint

, number of columns in random projection, .

statecommdict, RNG communication object, modified in place

RNG communication structure.

This argument must have been initialized by a prior call to rand.init_repeat or rand.init_nonrepeat.

rtol_absfloat, optional

The absolute tolerance, used in defining the threshold on estimating the rank of . If then is used unless in which case is used.

rtol_relfloat, optional

The relative tolerance, used in defining the threshold on estimating the rank of . If then is used unless in which case is used.

Returns
sfloat, ndarray, shape

The largest singular values of in descending order.

uNone or float, ndarray, shape

If , contains the first columns of (the left singular vectors, stored column-wise).

vtNone or float, ndarray, shape

If , contains the first rows of (the right singular vectors).

rint

, contains estimated rank of array .

Raises
NagValueError
(errno )

On entry, .

Constraint: or .

(errno )

On entry, .

Constraint: or .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, [‘state’] vector has been corrupted or not initialized.

(errno )

On entry, and .

Constraint: if , .

(errno )

On entry, and .

Constraint: if , .

(errno )

On exit, , the rank of may be larger than .

Increase to obtain a more accurate rank estimate.

Smallest diagonal element of , from of , .

Tolerance used to determine rank .

(errno )

has effective rank of zero.

First diagonal element of , from of , .

Tolerance used to determine rank .

Notes

The SVD is written as

where is an matrix which is zero except for its diagonal elements, is an orthogonal matrix, and is an orthogonal matrix. The diagonal elements of are the singular values of ; they are real and non-negative, and are returned in descending order. The first columns of and are the left and right singular vectors of .

Note that the function returns , not .

If the rank of is , then has nonzero elements, and only columns of and are well-defined. In this case we can reduce to an matrix, to an matrix and to an matrix.

svd_rowext_real is designed for efficiently computing the SVD in the case . The input argument should be greater than by a small oversampling parameter, , such that . A reasonable value for , to compute the SVD to within machine precision, is . The value of should not vary based on or . If is not known then the function can be used iteratively to refine the estimate and accuracy of the computed SVD; using a larger value of than necessary increases the computational cost of the function.

As a by-product of computing the SVD, the function estimates .

If the input argument is less than the accuracy depends on the th singular value, . See Accuracy for more details.

A call to svd_rowext_real consists of the following:

  1. A random projection is applied, , where is an matrix. (Note that the product is computed using a Fast Fourier Transform, so can be computed in time.) See randproj_dct_real() for more details on the random projection.

  2. A pivoted decomposition of is calculated (see lapackeig.dgeqp3 for more details). The rank estimate is then such that, on the diagonal of ,

    where and are the absolute and relative error tolerances, respectively, and is the largest diagonal index for which the above relation holds.

  3. Obtain the SVD from the decomposition of (or, depending on the rank, an approximation to the SVD) of . This is referred to as row extraction.

Further details of the randomized SVD procedure can be found in Sections 4 and 5 of Halko et al. (2011).

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

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore

Halko, N, 2012, Randomized methods for computing low-rank approximations of matrices, PhD thesis

Halko, N, Martinsson, P G and Tropp, J A, 2011, Finding structure with randomness: Probabilistic algorithms for constructing approximate matrix decompositions, SIAM Rev. (53(2)), 217–288, https://epubs.siam.org/doi/abs/10.1137/090771806