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.

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

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.

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.

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.

X = randn(___,'like',p) returns an array of random numbers like p; that is, of the same object type 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. Specify s followed by any of the argument combinations in previous syntaxes, except for the ones that involve 'like'. This syntax does not support the 'like' input.

Note

The 'seed', 'state', and 'twister' inputs to the randn function are not recommended. Use the rng function instead. For more information, see Replace Discouraged Syntaxes of rand and randn.

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

Random Complex Numbers

Generate a single random complex number with normally distributed real and imaginary parts.

a = randn + 1i*randn

a = 0.5377 + 1.8339i

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

Always use the rng function (rather than the rand or randn functions) to specify the settings of the random number generator. For more information, see Replace Discouraged Syntaxes of rand and randn.

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'

Clone Size from 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));

Clone Size and Data Type from 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'

Clone Distributed Array

If you have Parallel Computing Toolbox™, create a 1000-by-1000 distributed array of random numbers with underlying data type single. For the distributed data type, the 'like' syntax clones the underlying data type in addition to the primary data type.

p = randn(1000,'single','distributed');

Starting parallel pool (parpool) using the 'local' profile ...
connected to 6 workers.

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

X = randn(size(p),'like',p);

class(X)

ans =

    'distributed'

underlyingType(X)

ans =

    'single'

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

s — Random number stream

RandStream object

Random number stream, specified as a RandStream object.

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

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

Usage notes and limitations:

• The stream syntax randn(s,___) is not supported on a GPU.

• 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'

  • 'logical'

  • 'int8'

  • 'uint8'

  • 'int16'

  • 'uint16'

  • 'int32'

  • 'uint32'

  • 'int64'

  • 'uint64'

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

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'

  • 'logical'

  • 'int8'

  • 'uint8'

  • 'int16'

  • 'uint16'

  • 'int32'

  • 'uint32'

  • 'int64'

  • 'uint64'

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