NAG Library Function Document

nag_dggsvp (f08vec)

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

\begin{array}{l} U^{T} A Q = \{\begin{array}{r} \begin{array}{rc} n - k - l & k & l \\ k & ( & 0 & A_{12} & A_{13} & ) \\ l & 0 & 0 & A_{23} \\ m - k - l & 0 & 0 & 0 \end{array}, if ​ m - k - l \geq 0; \\ \begin{array}{rc} n - k - l & k & l \\ k & ( & 0 & A_{12} & A_{13} & ) \\ m - k & 0 & 0 & A_{23} \end{array}, if ​ m - k - l < 0; \end{array}  \\ V^{T} B Q = \begin{array}{rc} n - k - l & k & l \\ l & ( & 0 & 0 & B_{13} & ) \\ p - l & 0 & 0 & 0 \end{array} \end{array}

where the

k

k

matrix

A_{12}

and

l

l

matrix

B_{13}

are nonsingular upper triangular;

A_{23}

l

l

upper triangular if

m - k - l \geq 0

and is

(m - k)

l

upper trapezoidal otherwise.

(k + l)

is the effective numerical rank of the

(m + p)

n

matrix

{(\begin{matrix} A^{T} & B^{T} \end{matrix})}^{T}

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: order – 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

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: jobu – Nag_ComputeUTypeInput

On entry: if

jobu = Nag_AllU

, the orthogonal matrix

U

is computed.

jobu = Nag_NotU

U

is not computed.

Constraint:

jobu = Nag_AllU

Nag_NotU

3: jobv – Nag_ComputeVTypeInput

On entry: if

jobv = Nag_ComputeV

, the orthogonal matrix

V

is computed.

jobv = Nag_NotV

V

is not computed.

Constraint:

jobv = Nag_ComputeV

Nag_NotV

4: jobq – Nag_ComputeQTypeInput

On entry: if

jobq = Nag_ComputeQ

, the orthogonal matrix

Q

is computed.

jobq = Nag_NotQ

Q

is not computed.

Constraint:

jobq = Nag_ComputeQ

Nag_NotQ

5: m – IntegerInput

On entry:

m

, the number of rows of the matrix

A

Constraint:

m \geq 0

6: p – IntegerInput

On entry:

p

, the number of rows of the matrix

B

Constraint:

p \geq 0

7: n – IntegerInput

On entry:

n

, the number of columns of the matrices

A

and

B

Constraint:

n \geq 0

8: a[ $\dim$ ] – doubleInput/Output

Note: the dimension, dim, of the array a must be at least

$\max (1, pda \times n)$ when $order = Nag_ColMajor$ ;
$\max (1, m \times pda)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

A

is stored in

$a [(j - 1) \times pda + i - 1]$ when $order = Nag_ColMajor$ ;
$a [(i - 1) \times pda + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

m

n

matrix

A

On exit: contains the triangular (or trapezoidal) matrix described in Section 3.

9: pda – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array a.

Constraints:

if $order = Nag_ColMajor$ , $pda \geq \max (1, m)$ ;
if $order = Nag_RowMajor$ , $pda \geq \max (1, n)$ .

10: b[ $\dim$ ] – doubleInput/Output

Note: the dimension, dim, of the array b must be at least

$\max (1, pdb \times n)$ when $order = Nag_ColMajor$ ;
$\max (1, p \times pdb)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

B

is stored in

$b [(j - 1) \times pdb + i - 1]$ when $order = Nag_ColMajor$ ;
$b [(i - 1) \times pdb + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

p

n

matrix

B

On exit: contains the triangular matrix described in Section 3.

11: pdb – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array b.

Constraints:

if $order = Nag_ColMajor$ , $pdb \geq \max (1, p)$ ;
if $order = Nag_RowMajor$ , $pdb \geq \max (1, n)$ .

12: tola – doubleInput

13: tolb – doubleInput

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

\begin{matrix} tola = \max (m, n) ‖A‖ ε, \\ tolb = \max (p, n) ‖B‖ ε, \end{matrix}

where

ε

is the machine precision.

The size of tola and tolb may affect the size of backward errors of the decomposition.

14: k – Integer *Output

15: l – Integer *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

{(\begin{matrix} a^{T} & b^{T} \end{matrix})}^{T}

16: u[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array u must be at least

$\max (1, pdu \times m)$ when $jobu = Nag_AllU$ ;
$1$ otherwise.

The

(i, j)

th element of the matrix

U

is stored in

$u [(j - 1) \times pdu + i - 1]$ when $order = Nag_ColMajor$ ;
$u [(i - 1) \times pdu + j - 1]$ when $order = Nag_RowMajor$ .

On exit: if

jobu = Nag_AllU

, u contains the orthogonal matrix

U

jobu = Nag_NotU

, u is not referenced.

17: pdu – IntegerInput

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 \geq \max (1, m)$ ;
otherwise $pdu \geq 1$ .

18: v[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array v must be at least

$\max (1, pdv \times p)$ when $jobv = Nag_ComputeV$ ;
$1$ otherwise.

The

(i, j)

th element of the matrix

V

is stored in

$v [(j - 1) \times pdv + i - 1]$ when $order = Nag_ColMajor$ ;
$v [(i - 1) \times pdv + j - 1]$ when $order = Nag_RowMajor$ .

On exit: if

jobv = Nag_ComputeV

, v contains the orthogonal matrix

V

jobv = Nag_NotV

, v is not referenced.

19: pdv – IntegerInput

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 \geq \max (1, p)$ ;
otherwise $pdv \geq 1$ .

20: q[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array q must be at least

$\max (1, pdq \times n)$ when $jobq = Nag_ComputeQ$ ;
$1$ otherwise.

The

(i, j)

th element of the matrix

Q

is stored in

$q [(j - 1) \times pdq + i - 1]$ when $order = Nag_ColMajor$ ;
$q [(i - 1) \times pdq + j - 1]$ when $order = Nag_RowMajor$ .

On exit: if

jobq = Nag_ComputeQ

, q contains the orthogonal matrix

Q

jobq = Nag_NotQ

, q is not referenced.

21: pdq – IntegerInput

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 \geq \max (1, n)$ ;
otherwise $pdq \geq 1$ .

22: fail – NagError *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$ , $pdq \geq \max (1, n)$ ;
otherwise $pdq \geq 1$ .; On entry, $jobu = 〈value〉$ , $pdu = 〈value〉$ and $m = 〈value〉$ .
Constraint: if $jobu = Nag_AllU$ , $pdu \geq \max (1, m)$ ;
otherwise $pdu \geq 1$ .; On entry, $jobv = 〈value〉$ , $pdv = 〈value〉$ and $p = 〈value〉$ .
Constraint: if $jobv = Nag_ComputeV$ , $pdv \geq \max (1, p)$ ;
otherwise $pdv \geq 1$ .; On entry, $pdq = 〈value〉$ , $jobq = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $jobq = Nag_ComputeQ$ , $pdq \geq \max (1, n)$ ;
otherwise $pdq \geq 1$ .
NE_INT: On entry, $m = 〈value〉$ .
Constraint: $m \geq 0$ .; On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .; On entry, $p = 〈value〉$ .
Constraint: $p \geq 0$ .; 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: $pda \geq \max (1, m)$ .; On entry, $pda = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pda \geq \max (1, n)$ .; On entry, $pdb = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdb \geq \max (1, n)$ .; On entry, $pdb = 〈value〉$ and $p = 〈value〉$ .
Constraint: $pdb \geq \max (1, 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

{‖E‖}_{2} = O (ε) {‖A‖}_{2} and {‖F‖}_{2} = O (ε) {‖B‖}_{2},

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} (\begin{matrix} 0 & S \end{matrix}) Q^{T}, B = V Σ_{2} (\begin{matrix} 0 & T \end{matrix}) Q^{T},

of the matrix pair

(\begin{matrix} A & B \end{matrix})

, where

A = (\begin{matrix} 1 & 2 & 3 \\ 3 & 2 & 1 \\ 4 & 5 & 6 \\ 7 & 8 & 8 \end{matrix}) and B = (\begin{matrix} - 2 & - 3 & 3 \\ 4 & 6 & 5 \end{matrix}) .

NAG Library Function Documentnag_dggsvp (f08vec)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_dggsvp (f08vec)