random

Random numbers

Syntax

R = random('name',A)

R = random('name',A,B)

R = random('name',A,B,C)

R = random('name',A,B,C,D)

R = random(pd)

R = random(___,sz1,...,szN)

R = random(___,[sz1,...,szN])

Description

R = random('name',A) returns a random number from the one-parameter distribution family specified by 'name' and the distribution parameter A.

R = random('name',A,B) returns a random number from the two-parameter distribution family specified by 'name' and the distribution parameters A and B.

R = random('name',A,B,C) returns a random number from the three-parameter distribution family specified by 'name' and the distribution parameters A, B, and C.

R = random('name',A,B,C,D) returns a random number from the four-parameter distribution family specified by 'name' and the distribution parameters A, B, C, and D.

R = random(pd) returns a random number from the probability distribution object pd.

R = random(___,sz1,...,szN) or R = random(___,[sz1,...,szN]) generates a sz1-by-⋯-by-szN array of random numbers from the specified probability distribution using input arguments from any of the previous syntaxes.

Examples

Generate One Random Number

Create a standard normal probability distribution object.

pd = makedist('Normal')

pd = 
  NormalDistribution

  Normal distribution
       mu = 0
    sigma = 1

Generate one random number from the distribution.

rng('default') % For reproducibility
r1 = random(pd)

r1 = 0.5377

Alternatively, you can generate a standard normal random number by specifying its name and parameters.

r2 = random('Normal',0,1)

r2 = 1.8339

Reset Random Number Generator

Save the current state of the random number generator. Then generate a random number from the Poisson distribution with rate parameter 5.

s = rng;
r = random('Poisson',5)

r = 5

Restore the state of the random number generator to s, and then create a new random number. The value is the same as before.

rng(s);
r1 = random('Poisson',5)

r1 = 5

Clone Size from Existing Array

Create a matrix of random numbers with the same size as an existing array. Use the stable distribution with shape parameters 2 and 0, scale parameter 1, and location parameter 0.

A = [3 2; -2 1];
sz = size(A);
R = random('Stable',2,0,1,0,sz)

R = 2×2

    0.7604   -3.1945
    2.5935    1.2193

You can combine the previous two lines of code into a single line.

R = random('Stable',2,0,1,0,size(A))

R = 2×2

    0.4508   -0.6132
   -1.8494    0.4845

Generate Multiple Random Numbers

Create a Weibull probability distribution object using the default parameter values.

pd = makedist('Weibull')

pd = 
  WeibullDistribution

  Weibull distribution
    A = 1
    B = 1

Generate random numbers from the distribution.

rng('default')  % For reproducibility
r = random(pd,10000,1);

Construct a histogram using 100 bins with a Weibull distribution fit.

histfit(r,100,'weibull')

Generate Multidimensional Array of Random Numbers

Create a standard normal probability distribution object.

pd = makedist('Normal')

pd = 
  NormalDistribution

  Normal distribution
       mu = 0
    sigma = 1

Generate a 2-by-3-by-2 array of random numbers from the distribution.

r = random(pd,[2,3,2])

r = 
r(:,:,1) =

    0.5377   -2.2588    0.3188
    1.8339    0.8622   -1.3077


r(:,:,2) =

   -0.4336    3.5784   -1.3499
    0.3426    2.7694    3.0349

Input Arguments

'name' — Probability distribution name

character vector or string scalar of probability distribution name

Probability distribution name, specified as one of the probability distribution names in this table.

'name'	Distribution	Input Parameter A	Input Parameter B	Input Parameter C	Input Parameter D
'Beta'	Beta Distribution	a first shape parameter	b second shape parameter	—	—
'Binomial'	Binomial Distribution	n number of trials	p probability of success for each trial	—	—
'BirnbaumSaunders'	Birnbaum-Saunders Distribution	β scale parameter	γ shape parameter	—	—
'Burr'	Burr Type XII Distribution	α scale parameter	c first shape parameter	k second shape parameter	—
'Chisquare'	Chi-Square Distribution	ν degrees of freedom	—	—	—
'Exponential'	Exponential Distribution	μ mean	—	—	—
'Extreme Value'	Extreme Value Distribution	μ location parameter	σ scale parameter	—	—
'F'	F Distribution	ν1 numerator degrees of freedom	ν2 denominator degrees of freedom	—	—
'Gamma'	Gamma Distribution	a shape parameter	b scale parameter	—	—
'Generalized Extreme Value'	Generalized Extreme Value Distribution	k shape parameter	σ scale parameter	μ location parameter	—
'Generalized Pareto'	Generalized Pareto Distribution	k tail index (shape) parameter	σ scale parameter	μ threshold (location) parameter	—
'Geometric'	Geometric Distribution	p probability parameter	—	—	—
'HalfNormal'	Half-Normal Distribution	μ location parameter	σ scale parameter	—	—
'Hypergeometric'	Hypergeometric Distribution	m size of the population	k number of items with the desired characteristic in the population	n number of samples drawn	—
'InverseGaussian'	Inverse Gaussian Distribution	μ scale parameter	λ shape parameter	—	—
'Logistic'	Logistic Distribution	μ mean	σ scale parameter	—	—
'LogLogistic'	Loglogistic Distribution	μ mean of logarithmic values	σ scale parameter of logarithmic values	—	—
'Lognormal'	Lognormal Distribution	μ mean of logarithmic values	σ standard deviation of logarithmic values	—	—
'Nakagami'	Nakagami Distribution	μ shape parameter	ω scale parameter	—	—
'Negative Binomial'	Negative Binomial Distribution	r number of successes	p probability of success in a single trial	—	—
'Noncentral F'	Noncentral F Distribution	ν1 numerator degrees of freedom	ν2 denominator degrees of freedom	δ noncentrality parameter	—
'Noncentral t'	Noncentral t Distribution	ν degrees of freedom	δ noncentrality parameter	—	—
'Noncentral Chi-square'	Noncentral Chi-Square Distribution	ν degrees of freedom	δ noncentrality parameter	—	—
'Normal'	Normal Distribution	μ mean	σ standard deviation	—	—
'Poisson'	Poisson Distribution	λ mean	—	—	—
'Rayleigh'	Rayleigh Distribution	b scale parameter	—	—	—
'Rician'	Rician Distribution	s noncentrality parameter	σ scale parameter	—	—
'Stable'	Stable Distribution	α first shape parameter	β second shape parameter	γ scale parameter	δ location parameter
'T'	Student's t Distribution	ν degrees of freedom	—	—	—
'tLocationScale'	t Location-Scale Distribution	μ location parameter	σ scale parameter	ν shape parameter	—
'Uniform'	Uniform Distribution (Continuous)	a lower endpoint (minimum)	b upper endpoint (maximum)	—	—
'Discrete Uniform'	Uniform Distribution (Discrete)	n maximum observable value	—	—	—
'Weibull'	Weibull Distribution	a scale parameter	b shape parameter	—	—

Example: 'Normal'

A — First probability distribution parameter

scalar value | array of scalar values

First probability distribution parameter, specified as a scalar value or an array of scalar values.

If one or more of the input arguments A, B, C, and D are arrays, then the array sizes must be the same. In this case, random expands each scalar input into a constant array of the same size as the array inputs. See 'name' for the definitions of A, B, C, and D for each distribution.

Data Types: single | double

B — Second probability distribution parameter

scalar value | array of scalar values

Second probability distribution parameter, specified as a scalar value or an array of scalar values.

If one or more of the input arguments A, B, C, and D are arrays, then the array sizes must be the same. In this case, random expands each scalar input into a constant array of the same size as the array inputs. See 'name' for the definitions of A, B, C, and D for each distribution.

Data Types: single | double

C — Third probability distribution parameter

scalar value | array of scalar values

Third probability distribution parameter, specified as a scalar value or an array of scalar values.

If one or more of the input arguments A, B, C, and D are arrays, then the array sizes must be the same. In this case, random expands each scalar input into a constant array of the same size as the array inputs. See 'name' for the definitions of A, B, C, and D for each distribution.

Data Types: single | double

D — Fourth probability distribution parameter

scalar value | array of scalar values

Fourth probability distribution parameter, specified as a scalar value or an array of scalar values.

If one or more of the input arguments A, B, C, and D are arrays, then the array sizes must be the same. In this case, random expands each scalar input into a constant array of the same size as the array inputs. See 'name' for the definitions of A, B, C, and D for each distribution.

Data Types: single | double

pd — Probability distribution

probability distribution object

Probability distribution, specified as a probability distribution object created with a function or app in this table.

Function or App	Description
makedist	Create a probability distribution object using specified parameter values.
fitdist	Fit a probability distribution object to sample data.
Distribution Fitter	Fit a probability distribution to sample data using the interactive Distribution Fitter app and export the fitted object to the workspace.
paretotails	Create a piecewise distribution object that has generalized Pareto distributions in the tails.

sz1,...,szN — Size of each dimension

integer values | row vector of integer values

Size of each dimension, specified as integer values or a row vector of integer values. For example, specifying 5,3,2 or [5,3,2] generates a 5-by-3-by-2 array of random numbers from the specified probability distribution.

If one or more of the input arguments A, B, C, and D are arrays, then the specified dimensions sz1,...,szN must match the common dimensions of A, B, C, and D after any necessary scalar expansion. The default values of sz1,...,szN are the common dimensions.

• If you specify a single value sz1, then R is a square matrix of size sz1.

• If the size of any dimension is 0 or negative, then R is an empty array.

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

Data Types: single | double

Output Arguments

R — Random number

scalar value | array of scalar values

Random number generated from the specified probability distribution, returned as a scalar value or an array of scalar values with the dimensions specified by sz1,...,szN.

If you specify distribution parameters A, B, C, or D, then each element in R is the random number generated from the distribution specified by the corresponding elements in A, B, C, and D.

Alternative Functionality

• random is a generic function that accepts either a distribution by its name 'name' or a probability distribution object pd. It is faster to use a distribution-specific function, such as randn and normrnd for the normal distribution and binornd for the binomial distribution. For a list of distribution-specific functions, see Supported Distributions.

• To generate random numbers interactively, use randtool, a random number generation user interface.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• The input argument 'name' must be a compile-time constant. For example, to use the normal distribution, include coder.Constant('Normal') in the -args value of codegen.

• Code generation does not support the probability distribution object (pd) input argument.

For more information on code generation, see Introduction to Code Generation and General Code Generation Workflow.