# randn

Normally distributed random numbers

## Syntax

## Description

`X = randn`

returns a random scalar drawn from the standard normal
distribution.

`X = randn(`

returns
an `sz1,...,szN`

)`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.

`X = randn(___,`

returns an
array of random numbers of data type `typename`

)`typename`

. The
`typename`

input can be either `"single"`

or
`"double"`

. You can use any of the input arguments in the previous
syntaxes.

`X = randn(`

generates
numbers from random number stream `s`

,___)`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

### Matrix of Random Numbers

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

### Bivariate Normal Random Numbers

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

### Reset Random Number Generator

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

### 3-D Array of Random Numbers

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

### Specify Data Type of Random Numbers

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'

### Size Defined by Existing Array

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));

### Size and Data Type Defined by Existing Array

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'

### Random Complex Numbers

*Since R2022a*

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

### Random Complex Numbers with Specified Mean and Covariance

*Since R2022a*

By default, `randn(__,"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 for a 2-D random variable $\mathbf{z}=\left[\mathrm{Re}\left(\mathit{z}\right),\mathrm{Im}\left(\mathit{z}\right)\right]$ is `[1/2 0; 0 1/2]`

. To show this default behavior, generate 50,000 random numbers using `randn`

and calculate their covariance.

```
n = 50000;
z = randn(n,1,"like",1i);
cov_z = cov(real(z),imag(z),1)
```

`cov_z = `*2×2*
0.4980 0.0007
0.0007 0.4957

To generate random numbers from a more general complex normal distribution with specific mean and covariance, transform the data generated from the default distribution. For an *N*-dimensional random variable $\mathbf{z}=\left[{\mathit{z}}_{1},{\mathit{z}}_{2},\dots ,{\mathit{z}}_{\mathit{N}}\right]$ that follows a normal distribution with zero mean and unit covariance matrix, you can transform $\mathbf{z}$ to $\mathbf{y}=\mu +\mathbf{zR}$. The variable $\mathbf{y}$ follows the normal distribution with mean $\mu $ and covariance matrix $\sigma ={\mathbf{R}}^{\mathit{T}}\mathbf{R}$ that is symmetric positive definite. 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];

Perform the Cholesky decomposition of the covariance matrix. The result is an upper triangular matrix `R`

such that `sigma = R'*R`

. Scale the original data by also applying a factor of `sqrt(2)`

because the variance of the real and imaginary parts in the original distribution is `1/2`

. Then, shift the scaled data to the specified mean.

R = chol(sigma); z_scaled = sqrt(2)*[real(z) imag(z)]*R*[1; 1i]; y = mu + z_scaled;

Display the first 10 generated complex numbers.

y(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

`n`

— Size of square matrix

integer value

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`

`sz1,...,szN`

— Size of each dimension (as separate arguments)

integer values

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`

`sz`

— Size of each dimension (as a row vector)

integer values

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`

`typename`

— Data type (class) to create

`"double"`

(default) | `"single"`

Data type (class) to create, specified as `"double"`

,
`"single"`

, or the name of another class that provides
`randn`

support.

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

`p`

— Prototype of array to create

numeric array

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

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

**Data Types: **`single`

| `double`

**Complex Number Support: **Yes

`s`

— Random number stream

`RandStream`

object

Random number stream, specified as a `RandStream`

object.

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

## More About

### Standard Real and Standard Complex Normal Distributions

When generating random real numbers, the `randn`

function generates data that follows the standard normal distribution:

$$f(x)=\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(z)=\frac{1}{\pi}{e}^{-{\left|z\right|}^{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.

### Pseudorandom Number Generator

The underlying number generator for `randn`

is a pseudorandom number
generator, which creates a deterministic sequence of numbers that appear random. These
numbers are predictable if the seed and the deterministic algorithm of the generator are
known. While not truly random, the generated numbers pass various statistical tests of
randomness, satisfying the independent and identically distributed (i.i.d.) condition, and
justifying the name *pseudorandom*.

## 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`

.

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

The data type (class) must be a built-in MATLAB

^{®}numeric type. For other classes, the static`randn`

method is not invoked. For example,`randn(sz,'myclass')`

does not invoke`myclass.randn(sz)`

.Size arguments must have a fixed size.

See Variable-Sizing Restrictions for Code Generation of Toolbox Functions (MATLAB Coder).

If extrinsic calls are enabled and

`randn`

is not called from inside a`parfor`

loop, generated MEX files use the same random number state as MATLAB in serial code. Otherwise, the generated MEX code and standalone code maintain their own random number state that is initialized to the same state as MATLAB.

### Thread-Based Environment

Run code in the background using MATLAB® `backgroundPool`

or accelerate code with Parallel Computing Toolbox™ `ThreadPool`

.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

### GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The `randn`

function
supports GPU array input with these usage notes and limitations:

You can specify

`typename`

as`'gpuArray'`

. If you specify`typename`

as`'gpuArray'`

, the default underlying type of the array is`double`

.To create a GPU array with underlying type

`datatype`

, specify the underlying type as an additional argument before`typename`

. For example,`X = randn(3,datatype,'gpuArray')`

creates a 3-by-3 GPU array of random numbers with underlying type`datatype`

.You can specify the underlying type

`datatype`

as one of these options:`'double'`

`'single'`

You can also specify the numeric variable

`p`

as a`gpuArray`

.If you specify

`p`

as a`gpuArray`

, the underlying type of the returned array is the same as`p`

.To use the stream syntax,

`randn(`

, on a GPU,`s`

,___)`s`

must be a`parallel.gpu.RandStream`

(Parallel Computing Toolbox) object.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

### Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

The stream syntax

`randn(`

is not supported for`s`

,___)`codistributed`

or`distributed`

arrays.You can specify

`typename`

as`'codistributed'`

or`'distributed'`

. If you specify`typename`

as`'codistributed'`

or`'distributed'`

, the default underlying type of the returned array is`double`

.To create a distributed or codistributed array with underlying type

`datatype`

, specify the underlying type as an additional argument before`typename`

. For example,`X = randn(3,datatype,'distributed')`

creates a 3-by-3 distributed matrix of random numbers with underlying type`datatype`

.You can specify the underlying type

`datatype`

as one of these options:`'double'`

`'single'`

You can also specify

`p`

as a`codistributed`

or`distributed`

array.If you specify

`p`

as a`codistributed`

or`distributed`

array, the underlying type of the returned array is the same as`p`

.For additional

`codistributed`

syntaxes, see`randn (codistributed)`

(Parallel Computing Toolbox).

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

## Version History

**Introduced before R2006a**

### R2022a: Match complexity with `"like"`

, and use `"like"`

with `RandStream`

object

The `"like"`

input supports both real and complex prototype arrays. For
example:

r = randn(2,2,"like",1i)

r = 0.3802 + 1.2968i 0.2254 - 0.9247i -1.5972 + 0.6096i -0.3066 + 0.2423i

All syntaxes support this feature. Also, you can now use `"like"`

with
a `RandStream`

object as the first input of
`randn`

.

### R2014a: Match data type of an existing variable with `'like'`

To generate random numbers with the same data type as an existing variable, use the
syntax `randn(__,'like',p)`

. For
example:

A = single(pi); r = randn(4,4,'like',A); class(r)

ans = single

This feature is not available when passing a `RandStream`

object as the
first input to `randn`

.

### R2013b: Non-integer size inputs are not supported

Specifying a dimension that is not an integer causes an error. Use `floor`

to convert non-integer size inputs to integers.

### R2008b: `'seed'`

, `'state'`

, and `'twister'`

inputs are not recommended

There are no plans to remove these inputs, which control the random number generator
that underlies `rand`

, `randi`

and
`randn`

. However, the `rng`

function is recommended instead for these reasons:

The

`'seed'`

and`'state'`

generators are flawed.The terms

`'seed'`

and`'state'`

are misleading names for the generators.`'seed'`

refers to the MATLAB v4 generator, not the seed initialization value.`'state'`

refers to the v5 generators, not the internal state of the generator.These three inputs unnecessarily use different generators for

`rand`

and`randn`

.

For information on updating your code, see Replace Discouraged Syntaxes of rand and randn.

## See Also

`randi`

| `rand`

| `rng`

| `RandStream`

| `sprand`

| `sprandn`

| `randperm`

### Topics

- Create Arrays of Random Numbers
- Controlling Random Number Generation
- Random Numbers Within a Specific Range
- Random Numbers from Normal Distribution with Specific Mean and Variance
- Random Numbers and Vectors from Multivariate Normal Distributions
- Class Support for Array-Creation Functions
- Why Do Random Numbers Repeat After Startup?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)