g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_rngs_orthog_matrix (g05qac)

## 1  Purpose

nag_rngs_orthog_matrix (g05qac) generates a random orthogonal matrix.

## 2  Specification

 #include #include
 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$ by $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{\sigma }^{2}$ and dimensions $n,n-1,\dots ,2$; let ${H}_{j}=\mathrm{diag}\left({I}_{j-1},{H}_{j}^{*}\right)$, where ${I}_{j-1}$ is the identity matrix and ${H}_{j}^{*}$ is the Householder transformation that reduces ${x}_{j}$ to ${r}_{jj}{e}_{1}$, ${e}_{1}$ being the vector with first element one and the remaining elements zero and ${r}_{jj}$ being a scalar, and let $D=\mathrm{diag}\left(\mathrm{sign}\left({r}_{11}\right),\mathrm{sign}\left({r}_{22}\right),\dots ,\mathrm{sign}\left({r}_{nn}\right)\right)$. 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:     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 ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     sideNag_SideTypeInput
On entry: indicates whether the matrix $A$ is multiplied on the left or right by the random orthogonal matrix $U$.
${\mathbf{side}}=\mathrm{Nag_LeftSide}$
The matrix $A$ is multiplied on the left, i.e., pre-multiplied.
${\mathbf{side}}=\mathrm{Nag_RightSide}$
The matrix $A$ is multiplied on the right, i.e., post-multiplied.
Constraint: ${\mathbf{side}}=\mathrm{Nag_LeftSide}$ or $\mathrm{Nag_RightSide}$.
3:     initNag_InitializeAInput
On entry: indicates whether or not a should be initialized to the identity matrix.
${\mathbf{init}}=\mathrm{Nag_InitializeI}$
a is initialized to the identity matrix.
${\mathbf{init}}=\mathrm{Nag_InputA}$
a is not initialized and the matrix $A$ must be supplied in a.
Constraint: ${\mathbf{init}}=\mathrm{Nag_InitializeI}$ or $\mathrm{Nag_InputA}$.
4:     mIntegerInput
On entry: $m$, the number of rows of the matrix $A$.
Constraints:
• if ${\mathbf{side}}=\mathrm{Nag_LeftSide}$, ${\mathbf{m}}>1$;
• otherwise ${\mathbf{m}}\ge 1$.
5:     nIntegerInput
On entry: $n$, the number of columns of the matrix $A$.
Constraints:
• if ${\mathbf{side}}=\mathrm{Nag_RightSide}$, ${\mathbf{n}}>1$;
• otherwise ${\mathbf{n}}\ge 1$.
6:     a[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array a must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pda}}×{\mathbf{n}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}×{\mathbf{pda}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
The $\left(i,j\right)$th element of the matrix $A$ is stored in
• ${\mathbf{a}}\left[\left(j-1\right)×{\mathbf{pda}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{a}}\left[\left(i-1\right)×{\mathbf{pda}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: if ${\mathbf{init}}=\mathrm{Nag_InputA}$, a must contain the matrix $A$.
On exit: the matrix $UA$ when ${\mathbf{side}}=\mathrm{Nag_LeftSide}$ or the matrix $AU$ when ${\mathbf{side}}=\mathrm{Nag_RightSide}$.
7:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pda}}\ge {\mathbf{m}}$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pda}}\ge {\mathbf{n}}$.
8:     igenIntegerInput
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:   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.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_ENUM_INT
On entry, ${\mathbf{side}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{side}}=\mathrm{Nag_LeftSide}$, ${\mathbf{m}}>1$;
otherwise ${\mathbf{m}}\ge 1$.
On entry, ${\mathbf{side}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{side}}=\mathrm{Nag_RightSide}$, ${\mathbf{n}}>1$;
otherwise ${\mathbf{n}}\ge 1$.
NE_INT
On entry, ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{m}}\ge 1$.
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 1$.
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}>0$.
NE_INT_2
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}\ge {\mathbf{m}}$.
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}\ge {\mathbf{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.

## 7  Accuracy

The maximum error in ${U}^{\mathrm{T}}U$ should be a modest multiple of machine precision (see Chapter x02).

nag_rngs_corr_matrix (g05qbc) computes a random correlation matrix from a random orthogonal matrix.

## 9  Example

Following initialization of the pseudorandom number generator by a call to nag_rngs_init_repeatable (g05kbc), a $4$ by $4$ orthogonal matrix is generated using the ${\mathbf{init}}=\mathrm{Nag_InitializeI}$ option and the result printed.

### 9.1  Program Text

Program Text (g05qace.c)

None.

### 9.3  Program Results

Program Results (g05qace.r)