NAG Library Function Document

nag_rngs_orthog_matrix (g05qac)

+− 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

1 Purpose

nag_rngs_orthog_matrix (g05qac) generates a random orthogonal matrix.

2 Specification

#include <nag.h>

#include <nagg05.h>

void	nag_rngs_orthog_matrix (Nag_OrderType order, Nag_SideType side, Nag_InitializeA init, Integer m, Integer n, double a[], Integer pda, Integer igen, Integer iseed[], NagError *fail)

3 Description

nag_rngs_orthog_matrix (g05qac) pre- or post-multiplies an

m

n

matrix

A

by a random orthogonal matrix

U

, overwriting

A

. The matrix

A

may optionally be initialized to the identity matrix before multiplying by

U

, hence

U

is returned.

U

is generated using the method of Stewart (1980). The algorithm can be summarized as follows.

Let

x_{1}, x_{2}, \dots, x_{n - 1}

follow independent multinormal distributions with zero mean and variance

I σ^{2}

and dimensions

n, n - 1, \dots, 2

; let

H_{j} = diag (I_{j - 1}, H_{j}^{*})

, where

I_{j - 1}

is the identity matrix and

H_{j}^{*}

is the Householder transformation that reduces

x_{j}

r_{j j} e_{1}

e_{1}

being the vector with first element one and the remaining elements zero and

r_{j j}

being a scalar, and let

D = diag (sign (r_{11}), sign (r_{22}), \dots, sign (r_{n n}))

. Then the product

U = D H_{1} H_{2} \dots H_{n - 1}

is a random orthogonal matrix distributed according to the Haar measure over the set of orthogonal matrices of

n

. See Theorem 3.3 in Stewart (1980).

One of the initialization functions nag_rngs_init_repeatable (g05kbc) (for a repeatable sequence if computed sequentially) or nag_rngs_init_nonrepeatable (g05kcc) (for a non-repeatable sequence) must be called prior to the first call to nag_rngs_orthog_matrix (g05qac).

4 References

Stewart G W (1980) The efficient generation of random orthogonal matrices with an application to condition estimates SIAM J. Numer. Anal. 17 403–409

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: side – Nag_SideTypeInput

On entry: indicates whether the matrix

A

is multiplied on the left or right by the random orthogonal matrix

U

$side = Nag_LeftSide$: The matrix $A$ is multiplied on the left, i.e., pre-multiplied.
$side = Nag_RightSide$: The matrix $A$ is multiplied on the right, i.e., post-multiplied.

Constraint:

side = Nag_LeftSide

Nag_RightSide

3: init – Nag_InitializeAInput

On entry: indicates whether or not a should be initialized to the identity matrix.

$init = Nag_InitializeI$: a is initialized to the identity matrix.
$init = Nag_InputA$: a is not initialized and the matrix $A$ must be supplied in a.

Constraint:

init = Nag_InitializeI

Nag_InputA

4: m – IntegerInput

On entry:

m

, the number of rows of the matrix

A

Constraints:

if $side = Nag_LeftSide$ , $m > 1$ ;
otherwise $m \geq 1$ .

5: n – IntegerInput

On entry:

n

, the number of columns of the matrix

A

Constraints:

if $side = Nag_RightSide$ , $n > 1$ ;
otherwise $n \geq 1$ .

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

init = Nag_InputA

, a must contain the matrix

A

On exit: the matrix

U A

when

side = Nag_LeftSide

or the matrix

A U

when

side = Nag_RightSide

7: 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 m$ ;
if $order = Nag_RowMajor$ , $pda \geq n$ .

8: igen – IntegerInput

On entry: must contain the identification number for the generator to be used to return a pseudorandom number and should remain unchanged following initialization by a prior call to nag_rngs_init_repeatable (g05kbc) or nag_rngs_init_nonrepeatable (g05kcc).

9: iseed[ $4$ ] – IntegerCommunication Array

On entry: contains values which define the current state of the selected generator.

On exit: contains updated values defining the new state of the selected generator.

10: 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: On entry, $side = 〈value〉$ and $m = 〈value〉$ .
Constraint: if $side = Nag_LeftSide$ , $m > 1$ ;
otherwise $m \geq 1$ .; On entry, $side = 〈value〉$ and $n = 〈value〉$ .
Constraint: if $side = Nag_RightSide$ , $n > 1$ ;
otherwise $n \geq 1$ .
NE_INT: On entry, $m = 〈value〉$ .
Constraint: $m \geq 1$ .; On entry, $n = 〈value〉$ .
Constraint: $n \geq 1$ .; On entry, $pda = 〈value〉$ .
Constraint: $pda > 0$ .
NE_INT_2: On entry, $pda = 〈value〉$ and $m = 〈value〉$ .
Constraint: $pda \geq m$ .; On entry, $pda = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pda \geq n$ .
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.
NE_ORTHOGONAL_MATRIX: Orthogonal matrix of dimension $1$ requested.