Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_rand_matrix_orthog (g05px)

## Purpose

nag_rand_matrix_orthog (g05px) generates a random orthogonal matrix.

## Syntax

[state, a, ifail] = g05px(side, init, state, a, 'm', m, 'n', n)
[state, a, ifail] = nag_rand_matrix_orthog(side, init, state, a, 'm', m, 'n', n)

## Description

nag_rand_matrix_orthog (g05px) 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 summarised 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_repeat (g05kf) (for a repeatable sequence if computed sequentially) or nag_rand_init_nonrepeat (g05kg) (for a non-repeatable sequence) must be called prior to the first call to nag_rand_matrix_orthog (g05px).

## 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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{side}$ – string (length ≥ 1)
Indicates whether the matrix $A$ is multiplied on the left or right by the random orthogonal matrix $U$.
${\mathbf{side}}=\text{'L'}$
The matrix $A$ is multiplied on the left, i.e., premultiplied.
${\mathbf{side}}=\text{'R'}$
The matrix $A$ is multiplied on the right, i.e., post-multiplied.
Constraint: ${\mathbf{side}}=\text{'L'}$ or $\text{'R'}$.
2:     $\mathrm{init}$ – string (length ≥ 1)
Indicates whether or not a should be initialized to the identity matrix.
${\mathbf{init}}=\text{'I'}$
a is initialized to the identity matrix.
${\mathbf{init}}=\text{'N'}$
a is not initialized and the matrix $A$ must be supplied in a.
Constraint: ${\mathbf{init}}=\text{'I'}$ or $\text{'N'}$.
3:     $\mathrm{state}\left(:\right)$int64int32nag_int array
Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).
Contains information on the selected base generator and its current state.
4:     $\mathrm{a}\left(\mathit{lda},{\mathbf{n}}\right)$ – double array
lda, the first dimension of the array, must satisfy the constraint $\mathit{lda}\ge {\mathbf{m}}$.
If ${\mathbf{init}}=\text{'N'}$, a must contain the matrix $A$.

### Optional Input Parameters

1:     $\mathrm{m}$int64int32nag_int scalar
Default: the first dimension of the array a.
$m$, the number of rows of the matrix $A$.
Constraints:
• if ${\mathbf{side}}=\text{'L'}$, ${\mathbf{m}}>1$;
• otherwise ${\mathbf{m}}\ge 1$.
2:     $\mathrm{n}$int64int32nag_int scalar
Default: the second dimension of the array a.
$n$, the number of columns of the matrix $A$.
Constraints:
• if ${\mathbf{side}}=\text{'R'}$, ${\mathbf{n}}>1$;
• otherwise ${\mathbf{n}}\ge 1$.

### Output Parameters

1:     $\mathrm{state}\left(:\right)$int64int32nag_int array
Contains updated information on the state of the generator.
2:     $\mathrm{a}\left(\mathit{lda},{\mathbf{n}}\right)$ – double array
The matrix $UA$ when ${\mathbf{side}}=\text{'L'}$ or the matrix $AU$ when ${\mathbf{side}}=\text{'R'}$.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
On entry, side is not valid.
${\mathbf{ifail}}=2$
On entry, init is not valid.
${\mathbf{ifail}}=3$
Constraint: if ${\mathbf{side}}=\text{'L'}$, ${\mathbf{m}}>1$; otherwise ${\mathbf{m}}\ge 1$.
${\mathbf{ifail}}=4$
Constraint: if ${\mathbf{side}}=\text{'R'}$, ${\mathbf{n}}>1$; otherwise ${\mathbf{n}}\ge 1$.
${\mathbf{ifail}}=5$
On entry, state vector has been corrupted or not initialized.
${\mathbf{ifail}}=7$
Constraint: $\mathit{lda}\ge {\mathbf{m}}$.
${\mathbf{ifail}}=8$
Constraint: if ${\mathbf{side}}=\text{'L'}$, ${\mathbf{m}}>1$; otherwise ${\mathbf{m}}\ge 1$.
Constraint: if ${\mathbf{side}}=\text{'R'}$, ${\mathbf{n}}>1$; otherwise ${\mathbf{n}}\ge 1$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

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

None.

## Example

Following initialization of the pseudorandom number generator by a call to nag_rand_init_repeat (g05kf), a $4$ by $4$ orthogonal matrix is generated using the ${\mathbf{init}}=\text{'I'}$ option and the result printed.
```function g05px_example

fprintf('g05px example results\n\n');

% Initialize the base generator to a repeatable sequence
seed  = [int64(1762543)];
genid = int64(1);
subid = int64(1);
[state, ifail] = g05kf( ...
genid, subid, seed);

% Control parameters
side = 'Right';
init = 'Initialize';

% Generate the random orthogonal matrix
a = zeros(4, 4);
[state, a, ifail] = g05px( ...
side, init, state, a);

disp('Random orthogonal matrix');
disp(a);

```
```g05px example results

Random orthogonal matrix
0.1756    0.7401   -0.3067   -0.5722
0.6593   -0.5781   -0.2191   -0.4279
0.6680    0.3172    0.6077    0.2895
-0.2971   -0.1323    0.6990   -0.6369

```