nag_ztgsja (f08ysc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_ztgsja (f08ysc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_ztgsja (f08ysc) computes the generalized singular value decomposition (GSVD) of two complex upper trapezoidal matrices A and B, where A is an m by n matrix and B is a p by n matrix.
A and B are assumed to be in the form returned by nag_zggsvp (f08vsc).

2  Specification

#include <nag.h>
#include <nagf08.h>
void  nag_ztgsja (Nag_OrderType order, Nag_ComputeUType jobu, Nag_ComputeVType jobv, Nag_ComputeQType jobq, Integer m, Integer p, Integer n, Integer k, Integer l, Complex a[], Integer pda, Complex b[], Integer pdb, double tola, double tolb, double alpha[], double beta[], Complex u[], Integer pdu, Complex v[], Integer pdv, Complex q[], Integer pdq, Integer *ncycle, NagError *fail)

3  Description

nag_ztgsja (f08ysc) computes the GSVD of the matrices A and B which are assumed to have the form as returned by nag_zggsvp (f08vsc)
A= 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 ; B= n-k-lkll(00B13) p-l 0 0 0 ,
where the k by k matrix A12 and the l by l matrix B13 are nonsingular upper triangular, A23 is l by l upper triangular if m-k-l0 and is m-k by l upper trapezoidal otherwise.
nag_ztgsja (f08ysc) computes unitary matrices Q, U and V, diagonal matrices D1 and D2, and an upper triangular matrix R such that
UHAQ = D1 0 R ,   VHBQ = D2 0 R .
Optionally Q, U and V may or may not be computed, or they may be premultiplied by matrices Q1, U1 and V1 respectively.
If m-k-l0 then D1, D2 and R have the form
D1= klk(I0) l 0 C m-k-l 0 0 ,
D2= kll(0S) p-l 0 0 ,
R = klk(R11R12) l 0 R22 ,
where C=diagαk+1,,,,,,αk+l,  S=diagβk+1,,,,,,βk+l.
If m-k-l<0 then D1, D2 and R have the form
D1= km-kk+l-mk(I00) m-k 0 C 0 ,
D2= km-kk+l-mm-k(0S0) k+l-m 0 0 I p-l 0 0 0 ,
R = km-kk+l-mk(R11R12R13) m-k 0 R22 R23 k+l-m 0 0 R33 ,
where C=diagαk+1,,,,,,αm,  S=diagβk+1,,,,,,βm.
In both cases the diagonal matrix C has real non-negative diagonal elements, the diagonal matrix S has real positive diagonal elements, so that S is nonsingular, and C2+S2=1. See Section 2.3.5.3 of Anderson et al. (1999) for further information.

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  Arguments

1:     orderNag_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 order=Nag_RowMajor. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: order=Nag_RowMajor or Nag_ColMajor.
2:     jobuNag_ComputeUTypeInput
On entry: if jobu=Nag_AllU, u must contain a unitary matrix U1 on entry, and the product U1U is returned.
If jobu=Nag_InitU, u is initialized to the unit matrix, and the unitary matrix U is returned.
If jobu=Nag_NotU, U is not computed.
Constraint: jobu=Nag_InitU, Nag_AllU or Nag_NotU.
3:     jobvNag_ComputeVTypeInput
On entry: if jobv=Nag_ComputeV, v must contain a unitary matrix V1 on entry, and the product V1V is returned.
If jobv=Nag_InitV, v is initialized to the unit matrix, and the unitary matrix V is returned.
If jobv=Nag_NotV, V is not computed.
Constraint: jobv=Nag_ComputeV, Nag_InitV or Nag_NotV.
4:     jobqNag_ComputeQTypeInput
On entry: if jobq=Nag_ComputeQ, q must contain a unitary matrix Q1 on entry, and the product Q1Q is returned.
If jobq=Nag_InitQ, q is initialized to the unit matrix, and the unitary matrix Q is returned.
If jobq=Nag_NotQ, Q is not computed.
Constraint: jobq=Nag_ComputeQ, Nag_InitQ or Nag_NotQ.
5:     mIntegerInput
On entry: m, the number of rows of the matrix A.
Constraint: m0.
6:     pIntegerInput
On entry: p, the number of rows of the matrix B.
Constraint: p0.
7:     nIntegerInput
On entry: n, the number of columns of the matrices A and B.
Constraint: n0.
8:     kIntegerInput
9:     lIntegerInput
On entry: k and l specify the sizes, k and l, of the subblocks of A and B, whose GSVD is to be computed by nag_ztgsja (f08ysc).
10:   a[dim]ComplexInput/Output
Note: the dimension, dim, of the array a must be at least
  • max1,pda×n when order=Nag_ColMajor;
  • max1,m×pda when order=Nag_RowMajor.
Where Ai,j appears in this document, it refers to the array element
  • a[j-1×pda+i-1] when order=Nag_ColMajor;
  • a[i-1×pda+j-1] when order=Nag_RowMajor.
On entry: the m by n matrix A.
On exit: if m-k-l0, A1:k+l,n-k-l+1:n  contains the k+l by k+l upper triangular matrix R.
If m-k-l<0, A1:m,n-k-l+1:n  contains the first m rows of the k+l by k+l upper triangular matrix R, and the submatrix R33 is returned in Bm-k+1:l,n+m-k-l+1:n .
11:   pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraints:
  • if order=Nag_ColMajor, pdamax1,m;
  • if order=Nag_RowMajor, pdamax1,n.
12:   b[dim]ComplexInput/Output
Note: the dimension, dim, of the array b must be at least
  • max1,pdb×n when order=Nag_ColMajor;
  • max1,p×pdb when order=Nag_RowMajor.
Where Bi,j appears in this document, it refers to the array element
  • b[j-1×pdb+i-1] when order=Nag_ColMajor;
  • b[i-1×pdb+j-1] when order=Nag_RowMajor.
On entry: the p by n matrix B.
On exit: if m-k-l<0 , Bm-k+1:l,n+m-k-l+1:n  contains the submatrix R33 of R.
13:   pdbIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
Constraints:
  • if order=Nag_ColMajor, pdbmax1,p;
  • if order=Nag_RowMajor, pdbmax1,n.
14:   toladoubleInput
15:   tolbdoubleInput
On entry: tola and tolb are the convergence criteria for the Jacobi–Kogbetliantz iteration procedure. Generally, they should be the same as used in the preprocessing step performed by nag_zggsvp (f08vsc), say
tola=maxm,nAε, tolb=maxp,nBε,
where ε  is the machine precision.
16:   alpha[n]doubleOutput
On exit: see the description of beta.
17:   beta[n]doubleOutput
On exit: alpha and beta contain the generalized singular value pairs of A and B;
  • alpha[i]=1 , beta[i]=0 , for i=0,1,,k-1, and
  • if m-k-l0 , alpha[i]=αi , beta[i]=βi , for i=k,,k+l-1, or
  • if m-k-l<0 , alpha[i]=αi , beta[i]=βi , for i=k,,m-1 and alpha[i]=0 , beta[i]=1 , for i=m,,k+l-1.
Furthermore, if k+l<n, alpha[i]= beta[i]=0 , for i=k+l,,n-1.
18:   u[dim]ComplexInput/Output
Note: the dimension, dim, of the array u must be at least
  • max1,pdu×m when jobu=Nag_AllU or Nag_InitU and order=Nag_ColMajor;
  • max1,×pdu when jobu=Nag_AllU or Nag_InitU and order=Nag_RowMajor;
  • 1 otherwise.
The i,jth element of the matrix U is stored in
  • u[j-1×pdu+i-1] when order=Nag_ColMajor;
  • u[i-1×pdu+j-1] when order=Nag_RowMajor.
On entry: if jobu=Nag_AllU, u must contain an m by m matrix U1 (usually the unitary matrix returned by nag_zggsvp (f08vsc)).
On exit: if jobu=Nag_InitU, u contains the unitary matrix U.
If jobu=Nag_AllU, u contains the product U1U.
If jobu=Nag_NotU, u is not referenced.
19:   pduIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array u.
Constraints:
  • if order=Nag_ColMajor,
    • if jobuNag_NotU, pdu max1,m ;
    • otherwise pdu1;
  • if order=Nag_RowMajor,
    • if jobu=Nag_AllU or Nag_InitU, pdumax1,m;
    • otherwise pdu1.
20:   v[dim]ComplexInput/Output
Note: the dimension, dim, of the array v must be at least
  • max1,pdv×p when jobv=Nag_ComputeV or Nag_InitV and order=Nag_ColMajor;
  • max1,×pdv when jobv=Nag_ComputeV or Nag_InitV and order=Nag_RowMajor;
  • 1 otherwise.
The i,jth element of the matrix V is stored in
  • v[j-1×pdv+i-1] when order=Nag_ColMajor;
  • v[i-1×pdv+j-1] when order=Nag_RowMajor.
On entry: if jobv=Nag_ComputeV, v must contain an p by p matrix V1 (usually the unitary matrix returned by nag_zggsvp (f08vsc)).
On exit: if jobv=Nag_InitV, v contains the unitary matrix V.
If jobv=Nag_ComputeV, v contains the product V1V.
If jobv=Nag_NotV, v is not referenced.
21:   pdvIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array v.
Constraints:
  • if order=Nag_ColMajor,
    • if jobvNag_NotV, pdv max1,p ;
    • otherwise pdv1;
  • if order=Nag_RowMajor,
    • if jobv=Nag_ComputeV or Nag_InitV, pdvmax1,p;
    • otherwise pdv1.
22:   q[dim]ComplexInput/Output
Note: the dimension, dim, of the array q must be at least
  • max1,pdq×n when jobq=Nag_ComputeQ or Nag_InitQ and order=Nag_ColMajor;
  • max1,×pdq when jobq=Nag_ComputeQ or Nag_InitQ and order=Nag_RowMajor;
  • 1 otherwise.
The i,jth element of the matrix Q is stored in
  • q[j-1×pdq+i-1] when order=Nag_ColMajor;
  • q[i-1×pdq+j-1] when order=Nag_RowMajor.
On entry: if jobq=Nag_ComputeQ, q must contain an n by n matrix Q1 (usually the unitary matrix returned by nag_zggsvp (f08vsc)).
On exit: if jobq=Nag_InitQ, q contains the unitary matrix Q.
If jobq=Nag_ComputeQ, q contains the product Q1Q.
If jobq=Nag_NotQ, q is not referenced.
23:   pdqIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array q.
Constraints:
  • if order=Nag_ColMajor,
    • if jobqNag_NotQ, pdq max1,n ;
    • otherwise pdq1;
  • if order=Nag_RowMajor,
    • if jobq=Nag_ComputeQ or Nag_InitQ, pdqmax1,n;
    • otherwise pdq1.
24:   ncycleInteger *Output
On exit: the number of cycles required for convergence.
25:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_CONVERGENCE
The procedure does not converge after 40 cycles.
NE_ENUM_INT_2
On entry, jobq=value, pdq=value, n=value.
Constraint: if jobq=Nag_ComputeQ or Nag_InitQ, pdqmax1,n;
otherwise pdq1.
On entry, jobu=value, pdu=value, m=value.
Constraint: if jobu=Nag_AllU or Nag_InitU, pdumax1,m;
otherwise pdu1.
On entry, jobu=value, pdu=value and m=value.
Constraint: if jobuNag_NotU, pdu max1,m ;
otherwise pdu1.
On entry, jobv=value, pdv=value, p=value.
Constraint: if jobv=Nag_ComputeV or Nag_InitV, pdvmax1,p;
otherwise pdv1.
On entry, jobv=value, pdv=value and p=value.
Constraint: if jobvNag_NotV, pdv max1,p ;
otherwise pdv1.
On entry, pdq=value, jobq=value and n=value.
Constraint: if jobqNag_NotQ, pdq max1,n ;
otherwise pdq1.
NE_INT
On entry, m=value.
Constraint: m0.
On entry, n=value.
Constraint: n0.
On entry, p=value.
Constraint: p0.
On entry, pda=value.
Constraint: pda>0.
On entry, pdb=value.
Constraint: pdb>0.
On entry, pdq=value.
Constraint: pdq>0.
On entry, pdu=value.
Constraint: pdu>0.
On entry, pdv=value.
Constraint: pdv>0.
NE_INT_2
On entry, pda=value and m=value.
Constraint: pdamax1,m.
On entry, pda=value and n=value.
Constraint: pdamax1,n.
On entry, pdb=value and n=value.
Constraint: pdbmax1,n.
On entry, pdb=value and p=value.
Constraint: pdbmax1,p.
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.

7  Accuracy

The computed generalized singular value decomposition is nearly the exact generalized singular value decomposition for nearby matrices A+E and B+F, where
E2 = Oε A2   and   F2= Oε B2 ,
and ε is the machine precision. See Section 4.12 of Anderson et al. (1999) for further details.

8  Further Comments

The real analogue of this function is nag_dtgsja (f08yec).

9  Example

This example finds the generalized singular value decomposition
A = UΣ1 0 R QH ,   B= VΣ2 0 R QH ,
of the matrix pair A,B, 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 = 1 0 -1 0 0 1 0 -1 .

9.1  Program Text

Program Text (f08ysce.c)

9.2  Program Data

Program Data (f08ysce.d)

9.3  Program Results

Program Results (f08ysce.r)


nag_ztgsja (f08ysc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012