# randn

Normally distributed random numbers

## Syntax

``X = randn``
``X = randn(n)``
``X = randn(sz1,...,szN)``
``X = randn(sz)``
``X = randn(___,typename)``
``X = randn(___,"like",p)``
``X = randn(s,___)``

## Description

````X = randn` returns a random scalar drawn from the standard normal distribution.```

example

````X = randn(n)` returns an `n`-by-`n` matrix of normally distributed random numbers.```

example

````X = randn(sz1,...,szN)` returns an `sz1`-by-...-by-`szN` array of random numbers where `sz1,...,szN` indicate the size of each dimension. For example, `randn(3,4)` returns a 3-by-4 matrix.```

example

````X = randn(sz)` returns an array of random numbers where size vector `sz` defines `size(X)`. For example, `randn([3 4])` returns a 3-by-4 matrix.```

example

``` `X = randn(___,typename)` returns an array of random numbers of data type `typename`. The `typename` input can be either `"single"` or `"double"`. You can use any of the input arguments in the previous syntaxes. ```

example

````X = randn(___,"like",p)` returns an array of random numbers like `p`; that is, of the same data type and complexity (real or complex) as `p`. You can specify either `typename` or `"like"`, but not both.```
````X = randn(s,___)` generates numbers from random number stream `s` instead of the default global stream. To create a stream, use `RandStream`. You can specify `s` followed by any of the input argument combinations in previous syntaxes.```

## Examples

collapse all

Generate a 5-by-5 matrix of normally distributed random numbers.

`r = randn(5)`
```r = 5×5 0.5377 -1.3077 -1.3499 -0.2050 0.6715 1.8339 -0.4336 3.0349 -0.1241 -1.2075 -2.2588 0.3426 0.7254 1.4897 0.7172 0.8622 3.5784 -0.0631 1.4090 1.6302 0.3188 2.7694 0.7147 1.4172 0.4889 ```

Generate values from a bivariate normal distribution with specified mean vector and covariance matrix.

```mu = [1 2]; sigma = [1 0.5; 0.5 2]; R = chol(sigma); z = repmat(mu,10,1) + randn(10,2)*R```
```z = 10×2 1.5377 0.4831 2.8339 6.9318 -1.2588 1.8302 1.8622 2.3477 1.3188 3.1049 -0.3077 1.0750 0.5664 1.6190 1.3426 4.1420 4.5784 5.6532 3.7694 5.2595 ```

Save the current state of the random number generator and create a 1-by-5 vector of random numbers.

```s = rng; r = randn(1,5)```
```r = 1×5 0.5377 1.8339 -2.2588 0.8622 0.3188 ```

Restore the state of the random number generator to `s`, and then create a new 1-by-5 vector of random numbers. The values are the same as before.

```rng(s); r1 = randn(1,5)```
```r1 = 1×5 0.5377 1.8339 -2.2588 0.8622 0.3188 ```

Create a 3-by-2-by-3 array of random numbers.

`X = randn([3,2,3])`
```X = X(:,:,1) = 0.5377 0.8622 1.8339 0.3188 -2.2588 -1.3077 X(:,:,2) = -0.4336 2.7694 0.3426 -1.3499 3.5784 3.0349 X(:,:,3) = 0.7254 -0.2050 -0.0631 -0.1241 0.7147 1.4897 ```

Create a 1-by-4 vector of random numbers whose elements are single precision.

`r = randn(1,4,"single")`
```r = 1x4 single row vector 0.5377 1.8339 -2.2588 0.8622 ```
`class(r)`
```ans = 'single' ```

Create a matrix of normally distributed random numbers with the same size as an existing array.

```A = [3 2; -2 1]; sz = size(A); X = randn(sz)```
```X = 2×2 0.5377 -2.2588 1.8339 0.8622 ```

It is a common pattern to combine the previous two lines of code into a single line.

`X = randn(size(A));`

Create a 2-by-2 matrix of single-precision random numbers.

`p = single([3 2; -2 1]);`

Create an array of random numbers that is the same size and data type as `p`.

`X = randn(size(p),"like",p)`
```X = 2x2 single matrix 0.5377 -2.2588 1.8339 0.8622 ```
`class(X)`
```ans = 'single' ```

Generate 10 random complex numbers from the standard complex normal distribution.

`a = randn(10,1,"like",1i)`
```a = 10×1 complex 0.3802 + 1.2968i -1.5972 + 0.6096i 0.2254 - 0.9247i -0.3066 + 0.2423i 2.5303 + 1.9583i -0.9545 + 2.1460i 0.5129 - 0.0446i 0.5054 - 0.1449i -0.0878 + 1.0534i 0.9963 + 1.0021i ```

By default, `randn(n,"like",1i)` generates random numbers from the standard complex normal distribution. The real and imaginary parts are independent normally distributed random variables with mean `0` and variance `1/2`. The covariance matrix is of the form `[1/2 0; 0 1/2]`.

```z = randn(50000,1,"like",1i); cov_z = cov(real(z),imag(z),1)```
```cov_z = 2×2 0.4980 0.0007 0.0007 0.4957 ```

To specify a more general complex normal distribution, define the mean and covariance matrix. For instance, specify the mean as $\mu =1+2\mathrm{i}$ and the covariance matrix as $\sigma =\left[\begin{array}{cc}{\sigma }_{\mathrm{xx}}& {\sigma }_{\mathrm{xy}}\\ {\sigma }_{\mathrm{yx}}& {\sigma }_{\mathrm{yy}}\end{array}\right]=\left[\begin{array}{cc}2& -2\\ -2& 4\end{array}\right]$.

```mu = 1 + 2i; sigma = [2 -2; -2 4];```

Transform the previously generated data to follow the newly defined complex normal distribution. Include the factor of `sqrt(2)` when scaling the data because the variance for the real and imaginary parts in the original distribution is 1/2.

```R = chol(sigma); z_comp = [real(z) imag(z)]; z = repmat(mu,50000,1) + z_comp*sqrt(2)*R*[1; 1i]; z(1:10)```
```ans = 10×1 complex 1.7604 + 3.8331i -2.1945 + 6.4138i 1.4508 - 0.3002i 0.3868 + 3.0977i 6.0606 + 0.8560i -0.9090 + 8.2011i 2.0259 + 0.8850i 2.0108 + 0.6993i 0.8244 + 4.2823i 2.9927 + 2.0115i ```

## Input Arguments

collapse all

Size of square matrix, specified as an integer value.

• If `n` is `0`, then `X` is an empty matrix.

• If `n` is negative, then it is treated as `0`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Size of each dimension, specified as separate arguments of integer values.

• If the size of any dimension is `0`, then `X` is an empty array.

• If the size of any dimension is negative, then it is treated as `0`.

• Beyond the second dimension, `randn` ignores trailing dimensions with a size of 1. For example, `randn(3,1,1,1)` produces a 3-by-1 vector of random numbers.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Size of each dimension, specified as a row vector of integer values. Each element of this vector indicates the size of the corresponding dimension:

• If the size of any dimension is `0`, then `X` is an empty array.

• If the size of any dimension is negative, then it is treated as `0`.

• Beyond the second dimension, `randn` ignores trailing dimensions with a size of 1. For example, `randn([3 1 1 1])` produces a 3-by-1 vector of random numbers.

Example: `sz = [2 3 4]` creates a 2-by-3-by-4 array.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Data type (class) to create, specified as `"double"`, `"single"`, or the name of another class that provides `randn` support.

Example: `randn(5,"single")`

Prototype of array to create, specified as a numeric array.

Example: `randn(5,"like",p)`

Data Types: `single` | `double`
Complex Number Support: Yes

Random number stream, specified as a `RandStream` object.

Example: ```s = RandStream("dsfmt19937"); randn(s,[3 1])```

collapse all

### Standard Real and Standard Complex Normal Distributions

When generating random real numbers, the `randn` function generates data that follows the standard normal distribution:

`$f\left(x\right)=\frac{1}{\sqrt{2\pi }}{e}^{-{x}^{2}/2}.$`

Here, x is a random real variable with mean 0 and variance 1.

When generating random complex numbers, such as when using the command `randn(...,"like",1i)`, the `randn` function generates data that follows the standard complex normal distribution:

`$f\left(z\right)=\frac{1}{\pi }{e}^{-{|z|}^{2}}.$`

Here, z is a random complex variable whose real and imaginary parts are independent normally distributed random variables with mean 0 and variance 1/2.

## Tips

• The sequence of numbers produced by `randn` is determined by the internal settings of the uniform pseudorandom number generator that underlies `rand`, `randi`, and `randn`. You can control that shared random number generator using `rng`.

## Version History

Introduced before R2006a

expand all