# naginterfaces.library.lapackeig.zgesvj¶

naginterfaces.library.lapackeig.zgesvj(joba, jobu, jobv, a, mv, v, ctol)[source]

zgesvj computes the one-sided Jacobi singular value decomposition (SVD) of a complex , general or triangular, matrix , , with fast scaled rotations and de Rijk’s pivoting, optionally computing the left and/or right singular vectors. For , the functions zgesvd() or zgesdd() may be used.

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

https://www.nag.com/numeric/nl/nagdoc_28.7/flhtml/f08/f08kwf.html

Parameters
jobastr, length 1

Specifies the structure of matrix .

The input matrix is lower triangular.

The input matrix is upper triangular.

The input matrix is a general matrix, .

jobustr, length 1

Specifies whether to compute the left singular vectors and if so whether you want to control their numerical orthogonality threshold.

The left singular vectors corresponding to the nonzero singular values are computed and returned in the leading columns of . See more details in the description of . The numerical orthogonality threshold is set to approximately , where is the machine precision.

Analogous to , except that you can control the level of numerical orthogonality of the computed left singular vectors. The orthogonality threshold is set to . The option can be used if is a satisfactory orthogonality of the computed left singular vectors, so could save a few sweeps of Jacobi rotations. See the descriptions of and .

The matrix is not computed. However, see the description of .

jobvstr, length 1

Specifies whether and how to compute the right singular vectors.

The matrix is computed and returned in the array .

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

The matrix is not computed and the array is not referenced.

acomplex, array-like, shape

The matrix .

mvint

If , the product of Jacobi rotations is applied to the first rows of .

If , is ignored.

See the description of .

vcomplex, array-like, shape

Note: the required extent for this argument in dimension 1 is determined as follows: if : ; if : ; otherwise: .

Note: the required extent for this argument in dimension 2 is determined as follows: if : ; otherwise: .

If , must contain an matrix to be premultiplied by the matrix of right singular vectors.

ctolfloat

If , , the threshold for convergence. The process stops if all columns of are mutually orthogonal up to . It is required that , i.e., it is not possible to force the function to obtain orthogonality below . greater than is meaningless, where is the machine precision.

Returns
acomplex, ndarray, shape

The matrix containing the left singular vectors of .

If or

if

unitary columns of are returned in the leading columns of the array . Here is the number of computed singular values of that are above the safe range parameter, as returned by machine.real_safe. The singular vectors corresponding to underflowed or zero singular values are not computed. The value of is returned by rounding to the nearest whole number. Also see the descriptions of and . The computed columns of are mutually numerically unitary up to approximately ; or (), where is the machine precision, see the description of .

if

zgesvj did not converge in iterations (sweeps). In this case, the computed columns of may not be unitary up to . The output (stored in ), (given by the computed singular values in ) and is still a decomposition of the input matrix in the sense that the residual is small, where is the value returned in .

If

if

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

if

zgesvj did not converge in iterations (sweeps).

svafloat, ndarray, shape

The, possibly scaled, singular values of .

If

The singular values of are , for , where is the scale factor stored in . Normally , however, if some of the singular values of might underflow or overflow, then and the scale factor needs to be applied to obtain the singular values.

If

zgesvj did not converge in iterations and may not be accurate.

vcomplex, ndarray, shape

The right singular vectors of .

If , contains the matrix of the right singular vectors.

If , contains the product of the computed right singular vector matrix and the initial matrix in the array .

If , is not referenced.

rworkfloat, ndarray, shape

Contains information about the completed job.

The scaling factor, , such that , for , are the computed singular values of . (See the description of .)

gives the number of the computed nonzero singular values.

gives the number of the computed singular values that are larger than the underflow threshold.

gives the number of iterations (sweeps of Jacobi rotations) needed for numerical convergence.

in the last iteration (sweep). This is useful information in cases when zgesvj did not converge, as it can be used to estimate whether the output is still useful and for subsequent analysis.

The largest absolute value over all sines of the Jacobi rotation angles in the last sweep. It can be useful for subsequent analysis.

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

Warns
NagAlgorithmicWarning
(errno )

zgesvj did not converge in the allowed number of iterations (), but its output might still be useful.

Notes

The SVD is written as

where is an diagonal matrix, is an unitary matrix, and is an unitary matrix. The diagonal elements of are the singular values of in descending order of magnitude. The columns of and are the left and the right singular vectors of , respectively.

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, 2008, New fast and accurate Jacobi SVD Algorithm I, SIAM J. Matrix Anal. Appl. (29 4)

Drmač, Z and Veselić, K, 2008, 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