NAG Library Function Document

nag_ztgsja (f08ysc)

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)

\begin{matrix} A = & \{\begin{matrix} \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{matrix} \\ B = & \begin{array}{rc} n - k - l & k & l \\ l & ( & 0 & 0 & B_{13} & ) \\ p - l & 0 & 0 & 0 \end{array}, \end{matrix}

where the

k

k

matrix

A_{12}

and the

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.

nag_ztgsja (f08ysc) computes unitary matrices

Q

U

and

V

, diagonal matrices

D_{1}

and

D_{2}

, and an upper triangular matrix

R

such that

U^{H} A Q = D_{1} (\begin{matrix} 0 & R \end{matrix}), V^{H} B Q = D_{2} (\begin{matrix} 0 & R \end{matrix}) .

Optionally

Q

U

and

V

may or may not be computed, or they may be premultiplied by matrices

Q_{1}

U_{1}

and

V_{1}

respectively.

(m - k - l) \geq 0

then

D_{1}

D_{2}

and

R

have the form

D_{1} = \begin{array}{rc} k & l \\ k & ( & I & 0 & ) \\ l & 0 & C \\ m - k - l & 0 & 0 \end{array},

D_{2} = \begin{array}{rc} k & l \\ l & ( & 0 & S & ) \\ p - l & 0 & 0 \end{array},

R = \begin{array}{rc} k & l \\ k & ( & R_{11} & R_{12} & ) \\ l & 0 & R_{22} \end{array},

where

C = diag (α_{k + 1},,, \dots,,, α_{k + l}), S = diag (β_{k + 1},,, \dots,,, β_{k + l})

(m - k - l) < 0

then

D_{1}

D_{2}

and

R

have the form

D_{1} = \begin{array}{rc} k & m - k & k + l - m \\ k & ( & I & 0 & 0 & ) \\ m - k & 0 & C & 0 \end{array},

D_{2} = \begin{array}{rc} k & m - k & k + l - m \\ m - k & ( & 0 & S & 0 & ) \\ k + l - m & 0 & 0 & I \\ p - l & 0 & 0 & 0 \end{array},

R = \begin{array}{rc} k & m - k & k + l - m \\ k & ( & R_{11} & R_{12} & R_{13} & ) \\ m - k & 0 & R_{22} & R_{23} \\ k + l - m & 0 & 0 & R_{33} \end{array},

where

C = diag (α_{k + 1},,, \dots,,, α_{m}), S = diag (β_{k + 1},,, \dots,,, β_{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

C^{2} + S^{2} = 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: 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

, u must contain a unitary matrix

U_{1}

on entry, and the product

U_{1} U

is returned.

jobu = Nag_InitU

, u is initialized to the unit matrix, and the unitary matrix

U

is returned.

jobu = Nag_NotU

U

is not computed.

Constraint:

jobu = Nag_InitU

Nag_AllU

Nag_NotU

3: jobv – Nag_ComputeVTypeInput

On entry: if

jobv = Nag_ComputeV

, v must contain a unitary matrix

V_{1}

on entry, and the product

V_{1} V

is returned.

jobv = Nag_InitV

, v is initialized to the unit matrix, and the unitary matrix

V

is returned.

jobv = Nag_NotV

V

is not computed.

Constraint:

jobv = Nag_ComputeV

Nag_InitV

Nag_NotV

4: jobq – Nag_ComputeQTypeInput

On entry: if

jobq = Nag_ComputeQ

, q must contain a unitary matrix

Q_{1}

on entry, and the product

Q_{1} Q

is returned.

jobq = Nag_InitQ

, q is initialized to the unit matrix, and the unitary matrix

Q

is returned.

jobq = Nag_NotQ

Q

is not computed.

Constraint:

jobq = Nag_ComputeQ

Nag_InitQ

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: k – IntegerInput

9: l – IntegerInput

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

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

Where

A (i, j)

appears in this document, it refers to the array element

$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: if

m - k - l \geq 0

A (1 : k + l, n - k - l + 1 : n)

contains the

(k + l)

(k + l)

upper triangular matrix

R

m - k - l < 0

A (1 : m, n - k - l + 1 : n)

contains the first

m

rows of the

(k + l)

(k + l)

upper triangular matrix

R

, and the submatrix

R_{33}

is returned in

B (m - k + 1 : l, n + m - k - l + 1 : n)

11: 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)$ .

12: b[ $\dim$ ] – ComplexInput/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$ .

Where

B (i, j)

appears in this document, it refers to the array element

$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: if

m - k - l < 0

B (m - k + 1 : l, n + m - k - l + 1 : n)

contains the submatrix

R_{33}

R

13: 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)$ .

14: tola – doubleInput

15: tolb – doubleInput

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

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

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, \dots, k - 1$ , and
if $m - k - l \geq 0$ , $alpha [i] = α_{i}$ , $beta [i] = β_{i}$ , for $i = k, \dots, k + l - 1$ , or
if $m - k - l < 0$ , $alpha [i] = α_{i}$ , $beta [i] = β_{i}$ , for $i = k, \dots, m - 1$ and $alpha [i] = 0$ , $beta [i] = 1$ , for $i = m, \dots, k + l - 1$ .

Furthermore, if

k + l < n

alpha [i] = beta [i] = 0

, for

i = k + l, \dots, n - 1

18: u[ $\dim$ ] – ComplexInput/Output

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

$\max (1, pdu \times m)$ when $jobu = Nag_AllU$ or $Nag_InitU$ and $order = Nag_ColMajor$ ;
$\max (1, \times pdu)$ when $jobu = Nag_AllU$ or $Nag_InitU$ and $order = Nag_RowMajor$ ;
$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 entry: if

jobu = Nag_AllU

, u must contain an

m

m

matrix

U_{1}

(usually the unitary matrix returned by nag_zggsvp (f08vsc)).

On exit: if

jobu = Nag_InitU

, u contains the unitary matrix

U

jobu = Nag_AllU

, u contains the product

U_{1} U

jobu = Nag_NotU

, u is not referenced.

19: pdu – IntegerInput

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 $jobu \neq Nag_NotU$ , $pdu \geq \max (1, m)$ ;
- otherwise $pdu \geq 1$ ;
if order=Nag_RowMajor,
- if $jobu = Nag_AllU$ or $Nag_InitU$ , $pdu \geq \max (1, m)$ ;
- otherwise $pdu \geq 1$ .

20: v[ $\dim$ ] – ComplexInput/Output

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

$\max (1, pdv \times p)$ when $jobv = Nag_ComputeV$ or $Nag_InitV$ and $order = Nag_ColMajor$ ;
$\max (1, \times pdv)$ when $jobv = Nag_ComputeV$ or $Nag_InitV$ and $order = Nag_RowMajor$ ;
$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 entry: if

jobv = Nag_ComputeV

, v must contain an

p

p

matrix

V_{1}

(usually the unitary matrix returned by nag_zggsvp (f08vsc)).

On exit: if

jobv = Nag_InitV

, v contains the unitary matrix

V

jobv = Nag_ComputeV

, v contains the product

V_{1} V

jobv = Nag_NotV

, v is not referenced.

21: pdv – IntegerInput

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 $jobv \neq Nag_NotV$ , $pdv \geq \max (1, p)$ ;
- otherwise $pdv \geq 1$ ;
if order=Nag_RowMajor,
- if $jobv = Nag_ComputeV$ or $Nag_InitV$ , $pdv \geq \max (1, p)$ ;
- otherwise $pdv \geq 1$ .

22: q[ $\dim$ ] – ComplexInput/Output

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

$\max (1, pdq \times n)$ when $jobq = Nag_ComputeQ$ or $Nag_InitQ$ and $order = Nag_ColMajor$ ;
$\max (1, \times pdq)$ when $jobq = Nag_ComputeQ$ or $Nag_InitQ$ and $order = Nag_RowMajor$ ;
$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 entry: if

jobq = Nag_ComputeQ

, q must contain an

n

n

matrix

Q_{1}

(usually the unitary matrix returned by nag_zggsvp (f08vsc)).

On exit: if

jobq = Nag_InitQ

, q contains the unitary matrix

Q

jobq = Nag_ComputeQ

, q contains the product

Q_{1} Q

jobq = Nag_NotQ

, q is not referenced.

23: pdq – IntegerInput

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 $jobq \neq Nag_NotQ$ , $pdq \geq \max (1, n)$ ;
- otherwise $pdq \geq 1$ ;
if order=Nag_RowMajor,
- if $jobq = Nag_ComputeQ$ or $Nag_InitQ$ , $pdq \geq \max (1, n)$ ;
- otherwise $pdq \geq 1$ .

24: ncycle – Integer *Output

On exit: the number of cycles required for convergence.

25: 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_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$ , $pdq \geq \max (1, n)$ ;
otherwise $pdq \geq 1$ .; On entry, $jobu = 〈value〉$ , $pdu = 〈value〉$ , $m = 〈value〉$ .
Constraint: if $jobu = Nag_AllU$ or $Nag_InitU$ , $pdu \geq \max (1, m)$ ;
otherwise $pdu \geq 1$ .; On entry, $jobu = 〈value〉$ , $pdu = 〈value〉$ and $m = 〈value〉$ .
Constraint: if $jobu \neq Nag_NotU$ , $pdu \geq \max (1, m)$ ;
otherwise $pdu \geq 1$ .; On entry, $jobv = 〈value〉$ , $pdv = 〈value〉$ , $p = 〈value〉$ .
Constraint: if $jobv = Nag_ComputeV$ or $Nag_InitV$ , $pdv \geq \max (1, p)$ ;
otherwise $pdv \geq 1$ .; On entry, $jobv = 〈value〉$ , $pdv = 〈value〉$ and $p = 〈value〉$ .
Constraint: if $jobv \neq Nag_NotV$ , $pdv \geq \max (1, p)$ ;
otherwise $pdv \geq 1$ .; On entry, $pdq = 〈value〉$ , $jobq = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $jobq \neq Nag_NotQ$ , $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 generalized singular value decomposition is nearly the exact generalized singular value decomposition 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. 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} (\begin{matrix} 0 & R \end{matrix}) Q^{H}, B = V Σ_{2} (\begin{matrix} 0 & R \end{matrix}) Q^{H},

of the matrix pair

(A, B)

, where

A = (\begin{array}{r} 0.96 - 0.81 i & - 0.03 + 0.96 i & - 0.91 + 2.06 i & - 0.05 + 0.41 i \\ - 0.98 + 1.98 i & - 1.20 + 0.19 i & - 0.66 + 0.42 i & - 0.81 + 0.56 i \\ 0.62 - 0.46 i & 1.01 + 0.02 i & 0.63 - 0.17 i & - 1.11 + 0.60 i \\ 0.37 + 0.38 i & 0.19 - 0.54 i & - 0.98 - 0.36 i & 0.22 - 0.20 i \\ 0.83 + 0.51 i & 0.20 + 0.01 i & - 0.17 - 0.46 i & 1.47 + 1.59 i \\ 1.08 - 0.28 i & 0.20 - 0.12 i & - 0.07 + 1.23 i & 0.26 + 0.26 i \end{array})

and

B = (\begin{array}{r} 1 & 0 & - 1 & 0 \\ 0 & 1 & 0 & - 1 \end{array}) .

NAG Library Function Documentnag_ztgsja (f08ysc)

+− 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_ztgsja (f08ysc)