F08VSF (ZGGSVP) (PDF version)
F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

F08VSF (ZGGSVP)

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

+− Contents

    1  Purpose
    2  Specification
    3  Description
    4  References
    5  Parameters
    6  Error Indicators and Warnings
    7  Accuracy
    8  Further Comments
+− 9  Example

1  Purpose

F08VSF (ZGGSVP) uses unitary transformations to simultaneously reduce the m by n matrix A and the p by n matrix B to upper triangular form. This factorization is usually used as a preprocessing step for computing the generalized singular value decomposition (GSVD).

2  Specification

SUBROUTINE F08VSF ( JOBU, JOBV, JOBQ, M, P, N, A, LDA, B, LDB, TOLA, TOLB, K, L, U, LDU, V, LDV, Q, LDQ, IWORK, RWORK, TAU, WORK, INFO)
INTEGER  M, P, N, LDA, LDB, K, L, LDU, LDV, LDQ, IWORK(N), INFO
REAL (KIND=nag_wp)  TOLA, TOLB, RWORK(2*N)
COMPLEX (KIND=nag_wp)  A(LDA,*), B(LDB,*), U(LDU,*), V(LDV,*), Q(LDQ,*), TAU(N), WORK(max(3*N,M,P))
CHARACTER(1)  JOBU, JOBV, JOBQ
The routine may be called by its LAPACK name zggsvp.

3  Description

F08VSF (ZGGSVP) computes unitary matrices U, V and Q such that
UHAQ= n-k-lklk(0A12A13) l 0 0 A23 m-k-l 0 0 0 , if ​m-k-l≥0; n-k-lklk(0A12A13) m-k 0 0 A23 , if ​m-k-l<0; VHBQ= n-k-lkll(00B13) p-l 0 0 0
where the k by k matrix A12 and l by l matrix B13 are nonsingular upper triangular; A23 is l by l upper triangular if m-k-l≥0 and is m-k by l upper trapezoidal otherwise. k+l is the effective numerical rank of the m+p by n matrix AHBHH.
This decomposition is usually used as the preprocessing step for computing the Generalized Singular Value Decomposition (GSVD), see routine F08VNF (ZGGSVD).

4  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 http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

5  Parameters

1:     JOBU – CHARACTER(1)Input
On entry: if JOBU='U', the orthogonal matrix U is computed.
If JOBU='N', U is not computed.
Constraint: JOBU='U' or 'N'.
2:     JOBV – CHARACTER(1)Input
On entry: if JOBV='V', the unitary matrix V is computed.
If JOBV='N', V is not computed.
Constraint: JOBV='V' or 'N'.
3:     JOBQ – CHARACTER(1)Input
On entry: if JOBQ='Q', the unitary matrix Q is computed.
If JOBQ='N', Q is not computed.
Constraint: JOBQ='Q' or 'N'.
4:     M – INTEGERInput
On entry: m, the number of rows of the matrix A.
Constraint: M≥0.
5:     P – INTEGERInput
On entry: p, the number of rows of the matrix B.
Constraint: P≥0.
6:     N – INTEGERInput
On entry: n, the number of columns of the matrices A and B.
Constraint: N≥0.
7:     A(LDA,*) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array A must be at least max1,N.
On entry: the m by n matrix A.
On exit: contains the triangular (or trapezoidal) matrix described in Section 3.
8:     LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which F08VSF (ZGGSVP) is called.
Constraint: LDA≥max1,M.
9:     B(LDB,*) – COMPLEX (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array B must be at least max1,N.
On entry: the p by n matrix B.
On exit: contains the triangular matrix described in Section 3.
10:   LDB – INTEGERInput
On entry: the first dimension of the array B as declared in the (sub)program from which F08VSF (ZGGSVP) is called.
Constraint: LDB≥max1,P.
11:   TOLA – REAL (KIND=nag_wp)Input
12:   TOLB – REAL (KIND=nag_wp)Input
On entry: TOLA and TOLB are the thresholds to determine the effective numerical rank of matrix B and a subblock of A. Generally, they are set to
TOLA=maxM,NAε, TOLB=maxP,NBε,
where ε  is the machine precision.
The size of TOLA and TOLB may affect the size of backward errors of the decomposition.
13:   K – INTEGEROutput
14:   L – INTEGEROutput
On exit: K and L specify the dimension of the subblocks k and l as described in Section 3; k+l is the effective numerical rank of ATBTT.
15:   U(LDU,*) – COMPLEX (KIND=nag_wp) arrayOutput
Note: the second dimension of the array U must be at least max1,M if JOBU='U', and at least 1 otherwise.
On exit: if JOBU='U', U contains the unitary matrix U.
If JOBU='N', U is not referenced.
16:   LDU – INTEGERInput
On entry: the first dimension of the array U as declared in the (sub)program from which F08VSF (ZGGSVP) is called.
Constraints:
  • if JOBU='U', LDU≥max1,M;
  • otherwise LDU≥1.
17:   V(LDV,*) – COMPLEX (KIND=nag_wp) arrayOutput
Note: the second dimension of the array V must be at least max1,M if JOBV='V', and at least 1 otherwise.
On exit: if JOBV='V', V contains the unitary matrix V.
If JOBV='N', V is not referenced.
18:   LDV – INTEGERInput
On entry: the first dimension of the array V as declared in the (sub)program from which F08VSF (ZGGSVP) is called.
Constraints:
  • if JOBV='V', LDV≥max1,P;
  • otherwise LDV≥1.
19:   Q(LDQ,*) – COMPLEX (KIND=nag_wp) arrayOutput
Note: the second dimension of the array Q must be at least max1,N if JOBQ='Q', and at least 1 otherwise.
On exit: if JOBQ='Q', Q contains the unitary matrix Q.
If JOBQ='N', Q is not referenced.
20:   LDQ – INTEGERInput
On entry: the first dimension of the array Q as declared in the (sub)program from which F08VSF (ZGGSVP) is called.
Constraints:
  • if JOBQ='Q', LDQ≥max1,N;
  • otherwise LDQ≥1.
21:   IWORK(N) – INTEGER arrayWorkspace
22:   RWORK(2×N) – REAL (KIND=nag_wp) arrayWorkspace
23:   TAU(N) – COMPLEX (KIND=nag_wp) arrayWorkspace
24:   WORK(max3×N,M,P) – COMPLEX (KIND=nag_wp) arrayWorkspace
25:   INFO – INTEGEROutput
On exit: INFO=0 unless the routine detects an error (see Section 6).

6  Error Indicators and Warnings

Errors or warnings detected by the routine:
INFO<0
If INFO=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.

7  Accuracy

The computed factorization is nearly the exact factorization for nearby matrices A+E and B+F, where
E2 = OεA2   and   F2= OεB2,
and ε is the machine precision.

8  Further Comments

The real analogue of this routine is F08VEF (DGGSVP).

9  Example

This example finds the generalized factorization
A = UΣ1 0 S QH ,   B= VΣ2 0 T QH ,
of the matrix pair AB, where
A = 0.96-0.81i -0.03+0.96i -0.91+2.06i -0.05+0.41i -0.98+1.98i -1.20+0.19i -0.66+0.42i -0.81+0.56i 0.62-0.46i 1.01+0.02i 0.63-0.17i -1.11+0.60i 0.37+0.38i 0.19-0.54i -0.98-0.36i 0.22-0.20i 0.83+0.51i 0.20+0.01i -0.17-0.46i 1.47+1.59i 1.08-0.28i 0.20-0.12i -0.07+1.23i 0.26+0.26i
and
B = 10-10 010-1 .

9.1  Program Text

Program Text (f08vsfe.f90)

9.2  Program Data

Program Data (f08vsfe.d)

9.3  Program Results

Program Results (f08vsfe.r)

F08VSF (ZGGSVP) (PDF version)
F08 Chapter Contents
F08 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2011