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 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 that follows a normal distribution with zero mean and unit covariance matrix, you can transform to . The variable follows the normal distribution with mean and covariance matrix that is symmetric positive definite. For instance, specify the mean as and the covariance matrix as .
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
is0
, thenX
is an empty matrix.If
n
is negative, then it is treated as0
.
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
, thenX
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
, thenX
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:
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:
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 underliesrand
,randi
, andrandn
. You can control that shared random number generator usingrng
.
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 invokemyclass.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 aparfor
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 specifytypename
as'gpuArray'
, the default underlying type of the array isdouble
.To create a GPU array with underlying type
datatype
, specify the underlying type as an additional argument beforetypename
. For example,X = randn(3,datatype,'gpuArray')
creates a 3-by-3 GPU array of random numbers with underlying typedatatype
.You can specify the underlying type
datatype
as one of these options:'double'
'single'
You can also specify the numeric variable
p
as agpuArray
.If you specify
p
as agpuArray
, the underlying type of the returned array is the same asp
.To use the stream syntax,
randn(
, on a GPU,s
,___)s
must be aparallel.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 fors
,___)codistributed
ordistributed
arrays.You can specify
typename
as'codistributed'
or'distributed'
. If you specifytypename
as'codistributed'
or'distributed'
, the default underlying type of the returned array isdouble
.To create a distributed or codistributed array with underlying type
datatype
, specify the underlying type as an additional argument beforetypename
. For example,X = randn(3,datatype,'distributed')
creates a 3-by-3 distributed matrix of random numbers with underlying typedatatype
.You can specify the underlying type
datatype
as one of these options:'double'
'single'
You can also specify
p
as acodistributed
ordistributed
array.If you specify
p
as acodistributed
ordistributed
array, the underlying type of the returned array is the same asp
.For additional
codistributed
syntaxes, seerandn (codistributed)
(Parallel Computing Toolbox).
For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).
Version History
Introduced before R2006aR2022a: 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
andrandn
.
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)