naginterfaces.library.lapackeig.dbdsvdx

naginterfaces.library.lapackeig.dbdsvdx(uplo, jobz, erange, d, e, vl, vu, il, iu)[source]

dbdsvdx computes all or selected singular values and, optionally, the corresponding left and right singular vectors of a real (upper or lower) bidiagonal matrix .

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f08/f08mbf.html

Parameters
uplostr, length 1

Indicates whether is upper or lower bidiagonal.

is upper bidiagonal.

is lower bidiagonal.

jobzstr, length 1

Indicates whether singular vectors are computed.

Only singular values are computed.

Singular values and singular vectors are computed.

erangestr, length 1

Indicates which singular values should be returned.

All singular values will be found.

All singular values in the half-open interval will be found.

The th through th singular values will be found.

dfloat, array-like, shape

The diagonal elements of the bidiagonal matrix .

efloat, array-like, shape

The off-diagonal elements of the bidiagonal matrix .

vlfloat

If , the lower bound of the interval to be searched for singular values.

If or , is not referenced.

vufloat

If , the upper bound of the interval to be searched for singular values.

If or , is not referenced.

ilint

If , and specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If or , and are not referenced.

iuint

If , and specify the indices (in ascending order) of the smallest and largest singular values to be returned, respectively.

If or , and are not referenced.

Returns
nsint

The total number of singular values found. .

If , .

If , .

sfloat, ndarray, shape

The first elements contain the selected singular values in ascending order.

zfloat, ndarray, shape

If , then if the first columns of contain the singular vectors of the matrix corresponding to the selected singular values, with in rows to and in rows to .

Raises
NagValueError
(errno )

On entry, error in parameter .

Constraint: or .

(errno )

On entry, error in parameter .

Constraint: or .

(errno )

On entry, error in parameter .

Constraint: , or .

(errno )

On entry, error in parameter .

Constraint: .

(errno )

On entry, error in parameter .

Constraint: .

(errno )

On entry, error in parameter .

Constraint: .

(errno )

On entry, error in parameter .

(errno )

On entry, error in parameter .

(errno )

The algorithm failed to converge; eigenvectors of the associated eigenproblem did not converge. Their indices are stored in array .

Notes

dbdsvdx computes the singular value decomposition (SVD) of a real (upper or lower) bidiagonal matrix as

where is a diagonal matrix with non-negative diagonal elements (the singular values of ), and and are orthogonal matrices. The columns of and are the left and right singular vectors of , respectively.

Given an upper bidiagonal matrix with diagonal and superdiagonal , dbdsvdx computes the singular value decomposition of through the eigenvalues and eigenvectors of the tridiagonal matrix

If is a singular triplet of with , then and , , are eigenpairs of , with , and .

Given a matrix, you can either

  1. compute and change signs so that the singular values (and corresponding vectors) are already in descending order (as in dgesvd()) or

  2. compute and reorder the values (and corresponding vectors).

dbdsvdx implements (i) by calling dstevx() (bisection plus inverse iteration, to be replaced with a version of the Multiple Relative Robust Representation algorithm. (See Williams and Lang (2013).)

Alternative to computing all singular values of , a selected set can be computed. The set is either those singular values lying in a given interval, , or those whose index (counting from largest to smallest in magnitude) lies in a given range . In these cases, the corresponding left and right singular vectors can optionally be computed.

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

Williams, P and Lang, B, 2013, A framework for the Algorithm: theory and implementation, SIAM J. Sci. Comput. (35), 740–766