nag_dggsvp (f08vec) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_dggsvp (f08vec)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_dggsvp (f08vec) uses orthogonal 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

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

3  Description

nag_dggsvp (f08vec) computes orthogonal matrices U, V and Q such that
UTAQ= n-k-lklk(0A12A13) l 0 0 A23 m-k-l 0 0 0 , if ​m-k-l0; n-k-lklk(0A12A13) m-k 0 0 A23 , if ​m-k-l<0; VTBQ= 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-l0 and is m-k by l upper trapezoidal otherwise. k+l is the effective numerical rank of the m+p by n matrix ATBTT.
This decomposition is usually used as the preprocessing step for computing the Generalized Singular Value Decomposition (GSVD), see function nag_dggsvd (f08vac).

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, the orthogonal matrix U is computed.
If jobu=Nag_NotU, U is not computed.
Constraint: jobu=Nag_AllU or Nag_NotU.
3:     jobvNag_ComputeVTypeInput
On entry: if jobv=Nag_ComputeV, the orthogonal matrix V is computed.
If jobv=Nag_NotV, V is not computed.
Constraint: jobv=Nag_ComputeV or Nag_NotV.
4:     jobqNag_ComputeQTypeInput
On entry: if jobq=Nag_ComputeQ, the orthogonal matrix Q is computed.
If jobq=Nag_NotQ, Q is not computed.
Constraint: jobq=Nag_ComputeQ 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:     a[dim]doubleInput/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.
The i,jth element of the matrix A is stored in
  • 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: contains the triangular (or trapezoidal) matrix described in Section 3.
9:     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.
10:   b[dim]doubleInput/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.
The i,jth element of the matrix B is stored in
  • 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: contains the triangular matrix described in Section 3.
11:   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.
12:   toladoubleInput
13:   tolbdoubleInput
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.
14:   kInteger *Output
15:   lInteger *Output
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.
16:   u[dim]doubleOutput
Note: the dimension, dim, of the array u must be at least
  • max1,pdu×m when jobu=Nag_AllU;
  • 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 exit: if jobu=Nag_AllU, u contains the orthogonal matrix U.
If jobu=Nag_NotU, u is not referenced.
17:   pduIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array u.
Constraints:
  • if jobu=Nag_AllU, pdu max1,m ;
  • otherwise pdu1.
18:   v[dim]doubleOutput
Note: the dimension, dim, of the array v must be at least
  • max1,pdv×p when jobv=Nag_ComputeV;
  • 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 exit: if jobv=Nag_ComputeV, v contains the orthogonal matrix V.
If jobv=Nag_NotV, v is not referenced.
19:   pdvIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array v.
Constraints:
  • if jobv=Nag_ComputeV, pdv max1,p ;
  • otherwise pdv1.
20:   q[dim]doubleOutput
Note: the dimension, dim, of the array q must be at least
  • max1,pdq×n when jobq=Nag_ComputeQ;
  • 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 exit: if jobq=Nag_ComputeQ, q contains the orthogonal matrix Q.
If jobq=Nag_NotQ, q is not referenced.
21:   pdqIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array q.
Constraints:
  • if jobq=Nag_ComputeQ, pdq max1,n ;
  • otherwise pdq1.
22:   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_ENUM_INT_2
On entry, jobq=value, pdq=value, n=value.
Constraint: if jobq=Nag_ComputeQ, pdqmax1,n;
otherwise pdq1.
On entry, jobu=value, pdu=value and m=value.
Constraint: if jobu=Nag_AllU, pdu max1,m ;
otherwise pdu1.
On entry, jobv=value, pdv=value and p=value.
Constraint: if jobv=Nag_ComputeV, pdv max1,p ;
otherwise pdv1.
On entry, pdq=value, jobq=value and n=value.
Constraint: if jobq=Nag_ComputeQ, 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 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 complex analogue of this function is nag_zggsvp (f08vsc).

9  Example

This example finds the generalized factorization
A = UΣ1 0 S QT ,   B= VΣ2 0 T QT ,
of the matrix pair AB, where
A = 123 321 456 788   and   B= -2-33 465 .

9.1  Program Text

Program Text (f08vece.c)

9.2  Program Data

Program Data (f08vece.d)

9.3  Program Results

Program Results (f08vece.r)


nag_dggsvp (f08vec) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

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