\section{RANDN Gaussian (Normal) Random Number Generator}

\subsection{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., \verb|mu = 0, sigma = 1|). 
 Two seperate syntaxes are possible.  The first syntax specifies the array 
dimensions as a sequence of scalar dimensions:
\begin{verbatim}
  y = randn(d1,d2,...,dn).
\end{verbatim}
The resulting array has the given dimensions, and is filled with
random numbers.  The type of \verb|y| is \verb|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:
\begin{verbatim}
  y = randn([d1,d2,...,dn]).
\end{verbatim}
This syntax is more convenient for calling \verb|randn| using a 
variable for the argument.

Finally, \verb|randn| supports two additional forms that allow
you to manipulate the state of the random number generator.
The first retrieves the state
\begin{verbatim}
  y = randn('state')
\end{verbatim}
which is a 625 length integer vector.  The second form sets
the state
\begin{verbatim}
  randn('state',y)
\end{verbatim}
or alternately, you can reset the random number generator with
\begin{verbatim}
  randn('state',0)
\end{verbatim}
\subsection{Function Internals}

Recall that the
probability density function (PDF) of a normal random variable is
\[
f(x) = \frac{1}{\sqrt{2\pi \sigma^2}} e^{\frac{-(x-\mu)^2}{2\sigma^2}}.
\]
The Gaussian random numbers are generated from pairs of uniform random numbers using a transformation technique. 
\subsection{Example}

The following example demonstrates an example of using the first form of the \verb|randn| function.
\begin{verbatim}
--> 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  

\end{verbatim}
The second example demonstrates the second form of the \verb|randn| function.
\begin{verbatim}
--> 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  

\end{verbatim}
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 \verb|mean| and \verb|var|, respectively.
\begin{verbatim}
--> 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  

\end{verbatim}
Now, we use the state manipulation functions of \verb|randn| to exactly reproduce 
a random sequence.  Note that unlike using \verb|seed|, we can exactly control where
the random number generator starts by saving the state.
\begin{verbatim}
--> 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  

\end{verbatim}
