naginterfaces.library.lapackeig.zgesvdx¶

naginterfaces.library.lapackeig.zgesvdx(jobu, jobvt, erange, a, vl, vu, il, iu)[source]

zgesvdx computes the singular value decomposition (SVD) of a complex matrix , optionally computing the left and/or right singular vectors. All singular values or a selected set of singular values may be computed.

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

https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f08/f08kzf.html

Parameters
jobustr, length 1

Specifies options for computing all or part of the matrix .

The columns of , as specified by , are returned in array .

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

jobvtstr, length 1

Specifies options for computing all or part of the matrix .

The rows of , as specified by , are returned in the array .

No rows of (no right 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.

acomplex, array-like, shape

The 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
acomplex, ndarray, shape

If and , the contents of are destroyed.

nsint

The total number of singular values found. .

If , .

If , .

If then the value of is not known in advance and so an upper limit should be used when specifying the dimensions of array , e.g., .

sfloat, ndarray, shape

The singular values of , sorted so that .

uNone or complex, ndarray, shape

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

If , is not referenced.

vtNone or complex, ndarray, shape

If , contains the first rows of (the right singular vectors, stored row-wise).

If , is not referenced.

rworkbfloat, ndarray, shape

If > 0, contains the unconverged superdiagonal elements of an upper bidiagonal matrix whose diagonal is in (not necessarily sorted). satisfies , so it has the same singular values as , and left and right singular vectors that are those of pre-multiplied by and .

jfailint, ndarray, shape

If > 0, contains, in its first nonzero elements, the indices of the eigenvectors (associated with a left or right singular vector, see dbdsvdx()) that failed to converge.

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 .

Constraint: .

(errno )

On entry, error in parameter .

(errno )

On entry, error in parameter .

(errno )

If zgesvdx did not converge, specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero.

Notes

The SVD is written as

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

Note that the function returns , not .

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

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