naginterfaces.library.rand.matrix_​orthog

naginterfaces.library.rand.matrix_orthog(side, init, statecomm, a)

matrix_orthog generates a random orthogonal matrix.

For full information please refer to the NAG Library document for g05px

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/g05/g05pxf.html

Parameters

sidestr, length 1

Indicates whether the matrix $A$ is multiplied on the left or right by the random orthogonal matrix $U$.

$side=\text{'L'}$

The matrix $A$ is multiplied on the left, i.e., premultiplied.

$side=\text{'R'}$

The matrix $A$ is multiplied on the right, i.e., post-multiplied.

initstr, length 1

Indicates whether or not $a$ should be initialized to the identity matrix.

$init=\text{'I'}$

$a$ is initialized to the identity matrix.

$init=\text{'N'}$

$a$ is not initialized and the matrix $A$ must be supplied in $a$.

statecommdict, RNG communication object, modified in place

RNG communication structure.

This argument must have been initialized by a prior call to init_repeat() or init_nonrepeat().

afloat, array-like, shape $(m,n)$

If $init=\text{'N'}$, $a$ must contain the matrix $A$.

Returns

afloat, ndarray, shape $(m,n)$

The matrix $UA$ when $side=\text{'L'}$ or the matrix $AU$ when $side=\text{'R'}$.

Raises

NagValueError

(errno $1$)

On entry, $side$ is not valid: $side=⟨value⟩$.

(errno $2$)

On entry, $init$ is not valid: $init=⟨value⟩$.

(errno $3$)

On entry, $side=⟨value⟩$, $m=⟨value⟩$.

Constraint: if $side=\text{'L'}$, $m>1$; otherwise $m\ge 1$.

(errno $4$)

On entry, $side=⟨value⟩$, $n=⟨value⟩$.

Constraint: if $side=\text{'R'}$, $n>1$; otherwise $n\ge 1$.

(errno $5$)

On entry, $statecomm$[‘state’] vector has been corrupted or not initialized.

(errno $8$)

On entry, $side=⟨value⟩$, $m=⟨value⟩$.

Constraint: if $side=\text{'L'}$, $m>1$; otherwise $m\ge 1$.

(errno $8$)

On entry, $side=⟨value⟩$, $n=⟨value⟩$.

Constraint: if $side=\text{'R'}$, $n>1$; otherwise $n\ge 1$.

Notes

matrix_orthog pre - or post-multiplies an $m\times 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=diag(I_{j-1},H_j^{\ast })$, where $I_{j-1}$ is the identity matrix and $H_j^{\ast }$ 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=diag(sign\left(r_{11}\right),sign\left(r_{22}\right),\dots ,sign\left(r_{nn}\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 init_repeat() (for a repeatable sequence if computed sequentially) or init_nonrepeat() (for a non-repeatable sequence) must be called prior to the first call to matrix_orthog.

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