randn

Normally distributed random numbers

collapse all in page

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.

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.

example

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

Matrix of Random Numbers

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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

Open Live Script

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 $z = [Re (z), Im (z)]$ 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 $z = [z_{1}, z_{2}, \dots, z_{N}]$ that follows a normal distribution with zero mean and unit covariance matrix, you can transform $z$ to $y = μ + zR$ . The variable $y$ follows the normal distribution with mean $μ$ and covariance matrix $σ = R^{T} R$ that is symmetric positive definite. For instance, specify the mean as $μ = 1 + 2 i$ and the covariance matrix as $σ = [\begin{array}{c} σ_{xx} & σ_{xy} \\ σ_{yx} & σ_{yy} \end{array}] = [\begin{array}{c} 2 & - 2 \\ - 2 & 4 \end{array}]$ .

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

collapse all

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

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

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

`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

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 (x) = \frac{1}{\sqrt{2 π}} 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}{π} 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.

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(s,___), on a GPU, 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(s,___) is not supported for 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

expand all

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.

randn

Syntax

Description

Examples

Matrix of Random Numbers

Bivariate Normal Random Numbers

Reset Random Number Generator

3-D Array of Random Numbers

Specify Data Type of Random Numbers

Size Defined by Existing Array

Size and Data Type Defined by Existing Array

Random Complex Numbers

Random Complex Numbers with Specified Mean and Covariance

Input Arguments

`n` — Size of square matrix
integer value

`sz1,...,szN` — Size of each dimension (as separate arguments)
integer values

`sz` — Size of each dimension (as a row vector)
integer values

`typename` — Data type (class) to create
`"double"` (default) | `"single"`

`p` — Prototype of array to create
numeric array

`s` — Random number stream
`RandStream` object

More About

Standard Real and Standard Complex Normal Distributions

Pseudorandom Number Generator

Tips

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

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

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

Version History

R2022a: Match complexity with `"like"`, and use `"like"` with `RandStream` object

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

R2013b: Non-integer size inputs are not supported

R2008b: `'seed'`, `'state'`, and `'twister'` inputs are not recommended

See Also

Topics

randn

Syntax

Description

Examples

Matrix of Random Numbers

Bivariate Normal Random Numbers

Reset Random Number Generator

3-D Array of Random Numbers

Specify Data Type of Random Numbers

Size Defined by Existing Array

Size and Data Type Defined by Existing Array

Random Complex Numbers

Random Complex Numbers with Specified Mean and Covariance

Input Arguments

n — Size of square matrix integer value

sz1,...,szN — Size of each dimension (as separate arguments) integer values

sz — Size of each dimension (as a row vector) integer values

typename — Data type (class) to create "double" (default) | "single"

p — Prototype of array to create numeric array

s — Random number stream RandStream object

More About

Standard Real and Standard Complex Normal Distributions

Pseudorandom Number Generator

Tips

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

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

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

Version History

R2022a: Match complexity with "like", and use "like" with RandStream object

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

R2013b: Non-integer size inputs are not supported

R2008b: 'seed', 'state', and 'twister' inputs are not recommended

See Also

Topics

`n` — Size of square matrix
integer value

`sz1,...,szN` — Size of each dimension (as separate arguments)
integer values

`sz` — Size of each dimension (as a row vector)
integer values

`typename` — Data type (class) to create
`"double"` (default) | `"single"`

`p` — Prototype of array to create
numeric array

`s` — Random number stream
`RandStream` object

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

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

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

R2022a: Match complexity with `"like"`, and use `"like"` with `RandStream` object

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

R2008b: `'seed'`, `'state'`, and `'twister'` inputs are not recommended