The IMSL_RAND_ORTH_MAT function generates a pseudorandom orthogonal matrix or a correlation matrix.

IMSL_RAND_ORTH_MAT generates a pseudorandom orthogonal matrix from the invariant Haar measure. For each column, a random vector from a uniform distribution on a hypersphere is selected and then is projected onto the orthogonal complement of the columns already formed. The method is described by Heiberger (1978). (See also Tanner and Thisted 1982.)

If EIGENVALUES is used, a correlation matrix is formed by applying a sequence of planar rotations to matrix ATDA, where D = diag(Eigenvalues(0), ..., Eigenvalues(n-1)), so as to yield ones along the diagonal. The planar rotations are applied in such an order that in the two by two matrix that determines the rotation, one diagonal element is less than 1.0 and one is greater than 1.0. This method is discussed by Bendel and Mickey (1978) and by Lin and Bendel (1985).

The distribution of the correlation matrices produced by this method is not known.

See Bendel and Mickey (1978) and Johnson and Welch (1980).

For larger matrices, rounding can become severe; and the double precision results may differ significantly from single precision results.

## Examples

In this example, IMSL_RAND_ORTH_MAT is used to generate a 4 by 4 pseudorandom correlation matrix with eigenvalues in the ratio 1:2:3:4.

`IMSL_RANDOMOPT, set = 123457`
`a = IMSL_RAND_ORTH_MAT(4)`
`ev = .4d0*[1.0d0, 2.0d0, 3.0d0, 4.0d0]`
`cor = IMSL_RAND_ORTH_MAT(4, EIGENVALUES = ev, A_MATRIX= a)`
`PM, cor`
` `
`1.00000 -0.235786 -0.325795 -0.110139`
`-0.235786 1.00000 0.190564 -0.0172391`
`-0.325795 0.190564 1.00000 -0.435339`
`-0.110139 -0.0172391 -0.435339 1.00000`

## Syntax

Result = IMSL_RAND_ORTH_MAT(N [, A_MATRIX=array] [, /DOUBLE] [, EIGENVALUES=array])

## Return Value

A two-dimensional array containing the N by N random correlation matrix.

## Arguments

### N

The order of the matrix to be generated.

## Keywords

### A_MATRIX (optional)

Two-dimensional array containing n by n random orthogonal matrix. A random correlation matrix is generated using orthogonal matrix input in A_MATRIX. Eigenvalues must also be supplied if A_MATRIX is used.

### DOUBLE (optional)

If present and nonzero, double precision is used.

### EIGENVALUES (optional)

One-dimensional array of length N containing the eigenvalues of the correlation matrix to be generated. The elements of EIGENVALUES must be positive, they must sum to N, and they cannot all be equal.

## Version History

 6.4 Introduced