The function may be called by the names: f08vcc, nag_lapackeig_dggsvd3 or nag_dggsvd3.
3Description
Given an real matrix and a real matrix , the generalized singular value decomposition is given by
where , and are orthogonal matrices. Let be the effective numerical rank of and be the effective numerical rank of the matrix , 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 orthogonal transformation matrices , and .
In particular, if is an nonsingular matrix, then the GSVD of and implicitly gives the SVD of :
If 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 orthogonal transformations using f08vgc. The GSVD of the resulting upper triangular matrix pair is then performed by f08yec which uses a variant of the Kogbetliantz algorithm (a cyclic Jacobi method).
4References
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
5Arguments
1: – Nag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by . See Section 3.1.3 in the Introduction to the NAG Library CL Interface for a more detailed explanation of the use of this argument.
Constraint:
or .
2: – Nag_ComputeUTypeInput
On entry: if , the orthogonal matrix is computed.
If , is not computed.
Constraint:
or .
3: – Nag_ComputeVTypeInput
On entry: if , the orthogonal matrix is computed.
If , is not computed.
Constraint:
or .
4: – Nag_ComputeQTypeInput
On entry: if , the orthogonal matrix is computed.
If , is not computed.
Constraint:
or .
5: – IntegerInput
On entry: , the number of rows of the matrix .
Constraint:
.
6: – IntegerInput
On entry: , the number of columns of the matrices and .
Constraint:
.
7: – IntegerInput
On entry: , the number of rows of the matrix .
Constraint:
.
8: – Integer *Output
9: – Integer *Output
On exit: k and l specify the dimension of the subblocks and as described in Section 3; is the effective numerical rank of .
10: – doubleInput/Output
Note: the dimension, dim, of the array a
must be at least
when
;
when
.
The th element of the matrix is stored in
when ;
when .
On entry: the matrix .
On exit: contains the triangular matrix , or part of . See Section 3 for details.
11: – IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraints:
if ,
;
if , .
12: – doubleInput/Output
Note: the dimension, dim, of the array b
must be at least
when
;
when
.
The th element of the matrix is stored in
when ;
when .
On entry: the matrix .
On exit: contains the triangular matrix if . See Section 3 for details.
13: – IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
On entry: the stride separating row or column elements (depending on the value of order) in the array q.
Constraints:
if , ;
otherwise .
22: – IntegerOutput
On exit: stores the sorting information. More precisely, if is the ordered set of indices of alpha containing (denote as , see beta), then the corresponding elements contain the swap pivots, , that sorts such that is in descending numerical order.
The following pseudocode sorts the set :
23: – NagError *Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).
6Error Indicators and Warnings
NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
NE_BAD_PARAM
On entry, argument had an illegal value.
NE_CONVERGENCE
The Jacobi-type procedure failed to converge.
NE_ENUM_INT_2
On entry, , and .
Constraint: if , ;
otherwise .
On entry, , and .
Constraint: if , ;
otherwise .
On entry, , and .
Constraint: if , ;
otherwise .
NE_INT
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, . Constraint: .
On entry, . Constraint: .
On entry, . Constraint: .
On entry, . Constraint: .
On entry, . Constraint: .
NE_INT_2
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
7Accuracy
The computed generalized singular value decomposition is nearly the exact generalized singular value decomposition for nearby matrices and , where
and is the machine precision. See Section 4.12 of Anderson et al. (1999) for further details.
8Parallelism and Performance
f08vcc is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
f08vcc makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.
9Further Comments
This function replaces the deprecated function f08vac which used an unblocked algorithm and, therefore, did not make best use of Level 3 BLAS functions.