g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_rand_orthog_matrix (g05pxc)

## 1  Purpose

nag_rand_orthog_matrix (g05pxc) generates a random orthogonal matrix.

## 2  Specification

 #include #include
 void nag_rand_orthog_matrix (Nag_SideType side, Nag_InitializeA init, Integer m, Integer n, Integer state[], double a[], Integer pda, NagError *fail)

## 3  Description

nag_rand_orthog_matrix (g05pxc) 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_rand_init_repeatable (g05kfc) (for a repeatable sequence if computed sequentially) or nag_rand_init_nonrepeatable (g05kgc) (for a non-repeatable sequence) must be called prior to the first call to nag_rand_orthog_matrix (g05pxc).

## 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:     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}$.
2:     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}$.
3:     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$.
4:     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$.
5:     state[$\mathit{dim}$]IntegerCommunication Array
Note: the actual argument supplied must be the array state supplied to the initialization functions nag_rand_init_repeatable (g05kfc) or nag_rand_init_nonrepeatable (g05kgc).
On entry: contains information on the selected base generator and its current state.
On exit: contains updated information on the state of the generator.
6:     a[${\mathbf{m}}×{\mathbf{pda}}$]doubleInput/Output
On entry: if ${\mathbf{init}}=\mathrm{Nag_InputA}$, a must contain the matrix $A$, with the $\left(i,j\right)$th element of $A$ stored in ${\mathbf{a}}\left[\left(\left(i-1\right)×{\mathbf{pda}}+j-1\right)×{\mathbf{pda}}+\right]$.
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 matrix column elements in the array a.
Constraint: ${\mathbf{pda}}\ge {\mathbf{n}}$.
8:     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{pda}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}>0$.
NE_INT_2
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_INVALID_STATE
On entry, state vector has been corrupted or not initialized.

## 7  Accuracy

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

None.

## 9  Example

Following initialization of the pseudorandom number generator by a call to nag_rand_init_repeatable (g05kfc), 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 (g05pxce.c)

None.

### 9.3  Program Results

Program Results (g05pxce.r)