naginterfaces.library.lapackeig.zggsvd3

naginterfaces.library.lapackeig.zggsvd3(jobu, jobv, jobq, a, b)[source]

zggsvd3 computes the generalized singular value decomposition (GSVD) of an complex matrix and a complex matrix .

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

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f08/f08vqf.html

Parameters
jobustr, length 1

If , the unitary matrix is computed.

If , is not computed.

jobvstr, length 1

If , the unitary matrix is computed.

If , is not computed.

jobqstr, length 1

If , the unitary matrix is computed.

If , is not computed.

acomplex, array-like, shape

The matrix .

bcomplex, array-like, shape

The matrix .

Returns
kint

and specify the dimension of the subblocks and as described in Notes; is the effective numerical rank of (A;B).

lint

and specify the dimension of the subblocks and as described in Notes; is the effective numerical rank of (A;B).

acomplex, ndarray, shape

Contains the triangular matrix , or part of . See Notes for details.

bcomplex, ndarray, shape

Contains the triangular matrix if . See Notes for details.

alphafloat, ndarray, shape

See the description of .

betafloat, ndarray, shape

and contain the generalized singular value pairs of and , and ;

,

,

and if ,

,

,

or if ,

,

,

,

, and

,

.

The notation above refers to consecutive elements , for .

ucomplex, ndarray, shape

If , contains the unitary matrix .

If , is not referenced.

vcomplex, ndarray, shape

If , contains the unitary matrix .

If , is not referenced.

qcomplex, ndarray, shape

If , contains the unitary matrix .

If , is not referenced.

iworkint, ndarray, shape

Stores the sorting information. More precisely, if is the ordered set of indices of containing (denote as , see ), then the corresponding elements contain the swap pivots, , that sorts such that is in descending numerical order.

The following pseudocode sorts the set :

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 )

The Jacobi-type procedure failed to converge.

Notes

Given an complex matrix and a complex matrix , the generalized singular value decomposition is given by

where , and are unitary matrices. Let be the effective numerical rank of and be the effective numerical rank of the matrix (A;B), then the first generalized singular values are infinite and the remaining are finite. is a nonsingular upper triangular matrix, and are and ‘diagonal’ matrices structured as follows:

if ,

where

and

is stored as a submatrix of with elements stored as on exit.

If ,

where

and

is stored as a submatrix of with stored as , and is stored as a submatrix of with stored as .

The function computes , , and, optionally, the unitary transformation matrices , and .

In particular, if is an nonsingular matrix, then the GSVD of and implicitly gives the SVD of :

If (A;B) has orthonormal columns, then the GSVD of and is also equal to the CS decomposition of and . Furthermore, the GSVD can be used to derive the solution of the eigenvalue problem:

In some literature, the GSVD of and is presented in the form

where and are orthogonal and is nonsingular, and and are ‘diagonal’. The former GSVD form can be converted to the latter form by setting

A two stage process is used to compute the GSVD of the matrix pair . The pair is first reduced to upper triangular form by unitary transformations using zggsvp3(). The GSVD of the resulting upper triangular matrix pair is then performed by ztgsja() which uses a variant of the Kogbetliantz algorithm (a cyclic Jacobi method).

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, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore