## RANDN Gaussian (Normal) Random Number Generator

Section: Random Number Generation

### Usage

Creates an array of pseudo-random numbers of the specified size. The numbers are normally distributed with zero mean and a unit standard deviation (i.e., `mu = 0, sigma = 1`). Two seperate syntaxes are possible. The first syntax specifies the array dimensions as a sequence of scalar dimensions:

      y = randn(d1,d2,...,dn).

The resulting array has the given dimensions, and is filled with random numbers. The type of `y` is `double`, a 64-bit floating point array. To get arrays of other types, use the typecast functions. The second syntax specifies the array dimensions as a vector, where each element in the vector specifies a dimension length:

      y = randn([d1,d2,...,dn]).

This syntax is more convenient for calling `randn` using a variable for the argument. Finally, `randn` supports two additional forms that allow you to manipulate the state of the random number generator. The first retrieves the state

      y = randn('state')

which is a 625 length integer vector. The second form sets the state

      randn('state',y)

or alternately, you can reset the random number generator with

      randn('state',0)

### Function Internals

Recall that the probability density function (PDF) of a normal random variable is

The Gaussian random numbers are generated from pairs of uniform random numbers using a transformation technique.

### Example

The following example demonstrates an example of using the first form of the `randn` function.

    --> randn(2,2,2)
    ans =
      <double>  - size: [2 2 2]
    (:,:,1) =

    Columns 1 to 2
     -1.737491659363370244  -0.566402263751049961
     -0.263398356060278116  -1.011232712469539274
    (:,:,2) =

    Columns 1 to 2
     -0.402009448685253346   0.055689142534550685
     -1.896556976523083637   0.209817389275412242

The second example demonstrates the second form of the `randn` function.

    --> randn([2,2,2])
    ans =
      <double>  - size: [2 2 2]
    (:,:,1) =

    Columns 1 to 2
     -0.71830955831772469   1.94151925659060609
      0.10096324776995144  -1.17472404899044891
    (:,:,2) =

    Columns 1 to 2
      0.30478785842683354   3.16847741522331283
     -1.41850940422073712  -0.61299342897060261

In the next example, we create a large array of 10000 normally distributed pseudo-random numbers. We then shift the mean to 10, and the variance to 5. We then numerically calculate the mean and variance using `mean` and `var`, respectively.

    --> x = 10+sqrt(5)*randn(1,10000);
    --> mean(x)
    ans =
      <double>  - size: [1 1]
     10.013484814146642
    --> var(x)
    ans =
      <double>  - size: [1 1]
     4.945755069477022

Now, we use the state manipulation functions of `randn` to exactly reproduce a random sequence. Note that unlike using `seed`, we can exactly control where the random number generator starts by saving the state.

    --> randn('state',0)    % restores us to startup conditions
    --> a = randn(1,3)      % random sequence 1
    a =
      <double>  - size: [1 3]

    Columns 1 to 3
     -0.03616399339616805  -0.14041514095502830   0.69338955190756479
    --> b = randn('state'); % capture the state vector
    --> c = randn(1,3)      % random sequence 2
    c =
      <double>  - size: [1 3]

    Columns 1 to 3
      0.5997553858968305   0.7086493510746800  -0.9394060974709659
    --> randn('state',b);   % restart the random generator so...
    --> c = randn(1,3)      % we get random sequence 2 again
    c =
      <double>  - size: [1 3]

    Columns 1 to 3
      0.5997553858968305   0.7086493510746800  -0.9394060974709659