lognrnd

Lognormal random numbers

Syntax

r = lognrnd(mu,sigma)

r = lognrnd(mu,sigma,sz1,...,szN)

r = lognrnd(mu,sigma,sz)

Description

r = lognrnd(mu,sigma) generates a random number from the lognormal distribution with the distribution parameters mu (mean of logarithmic values) and sigma (standard deviation of logarithmic values).

r = lognrnd(mu,sigma,sz1,...,szN) generates an array of lognormal random numbers, where sz1,...,szN indicates the size of each dimension.

r = lognrnd(mu,sigma,sz) generates an array of lognormal random numbers, where vector sz specifies size(r).

Examples

Generate Lognormal Random Number

Find the distribution parameters from the mean and variance of a lognormal distribution and generate a lognormal random value from the distribution.

Find the distribution parameters mu and sigma from the mean and variance.

m = 1; % mean
v = 2; % variance
mu = log((m^2)/sqrt(v+m^2))

mu = 
-0.5493

sigma = sqrt(log(v/(m^2)+1))

sigma = 
1.0481

Generate a lognormal random value.

rng('default') % For reproducibility
r = lognrnd(mu,sigma)

r = 
1.0144

Reset Random Number Generator

Save the current state of the random number generator. Then create a 1-by-5 vector of lognormal random numbers from the lognormal distribution with the parameters 3 and 10.

s = rng;
r = lognrnd(3,10,[1,5])

r = 1×5
109 ×

    0.0000    1.8507    0.0000    0.0001    0.0000

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 = lognrnd(3,10,[1,5])

r1 = 1×5
109 ×

    0.0000    1.8507    0.0000    0.0001    0.0000

Clone Size from Existing Array

Create a matrix of lognormally distributed random numbers with the same size as an existing array.

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

R = 2×2

    1.7120    0.1045
    6.2582    2.3683

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

R = lognrnd(1,0,size(A));

Input Arguments

mu — Mean of logarithmic values

scalar value | array of scalar values

Mean of logarithmic values for the lognormal distribution, specified as a scalar value or an array of scalar values.

To generate random numbers from multiple distributions, specify mu and sigma using arrays. If both mu and sigma are arrays, then the array sizes must be the same. If either mu or sigma is a scalar, then lognrnd expands the scalar argument into a constant array of the same size as the other argument. Each element in r is the random number generated from the distribution specified by the corresponding elements in mu and sigma.

Example: [0 1 2; 0 1 2]

Data Types: single | double

sigma — Standard deviation of logarithmic values

nonnegative scalar value | array of nonnegative scalar values

Standard deviation of logarithmic values for the lognormal distribution, specified as a nonnegative scalar value or an array of nonnegative scalar values.

If sigma is zero, then the output r is always equal to exp(mu).

To generate random numbers from multiple distributions, specify mu and sigma using arrays. If both mu and sigma are arrays, then the array sizes must be the same. If either mu or sigma is a scalar, then lognrnd expands the scalar argument into a constant array of the same size as the other argument. Each element in r is the random number generated from the distribution specified by the corresponding elements in mu and sigma.

Example: [1 1 1; 2 2 2]

Data Types: single | double

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

integers

Size of each dimension, specified as separate arguments of integers. For example, specifying 5,3,2 generates a 5-by-3-by-2 array of random numbers from the lognormal probability distribution.

If either mu or sigma is an array, then the specified dimensions sz1,...,szN must match the common dimensions of mu and sigma 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-by-sz1.

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

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

Example: 5,3,2

Data Types: single | double

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

row vector of integers

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

If either mu or sigma is an array, then the specified dimensions sz must match the common dimensions of mu and sigma after any necessary scalar expansion. The default values of sz are the common dimensions.

• If you specify a single value [sz1], then r is a square matrix of size sz1-by-sz1.

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

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

Example: [5 3 2]

Data Types: single | double

Output Arguments

r — Lognormal random numbers

scalar value | array of scalar values

Lognormal random numbers, returned as a scalar value or an array of scalar values with the dimensions specified by sz1,...,szN or sz. Each element in r is the random number generated from the distribution specified by the corresponding elements in mu and sigma.

More About

Lognormal Distribution

The lognormal distribution is a probability distribution whose logarithm has a normal distribution.

The mean m and variance v of a lognormal random variable are functions of the lognormal distribution parameters µ and σ:

$$\begin{array}{l}m=\exp \left(\mu +{\sigma }^2/2\right)\\ v=\exp \left(2\mu +{\sigma }^2\right)\left(\exp \left({\sigma }^2\right)-1\right)\end{array}$$

Also, you can compute the lognormal distribution parameters µ and σ from the mean m and variance v:

$$\begin{array}{l}\mu =\log \left(m^2/\sqrt{v+m^2}\right)\\ \sigma =\sqrt{\log \left(v/m^2+1\right)}\end{array}$$

Alternative Functionality

• lognrnd is a function specific to lognormal distribution. Statistics and Machine Learning Toolbox™ also offers the generic function random, which supports various probability distributions. To use random, create a LognormalDistribution probability distribution object and pass the object as an input argument or specify the probability distribution name and its parameters. Note that the distribution-specific function lognrnd is faster than the generic function random.

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

References

[1] Marsaglia, G., and W. W. Tsang. “A Fast, Easily Implemented Method for Sampling from Decreasing or Symmetric Unimodal Density Functions.” SIAM Journal on Scientific and Statistical Computing. Vol. 5, Number 2, 1984, pp. 349–359.

[2] Evans, M., N. Hastings, and B. Peacock. Statistical Distributions. 2nd ed., Hoboken, NJ: John Wiley & Sons, Inc., 1993.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

The generated code can return a different sequence of numbers than MATLAB^® if either of the following is true:

• The output is nonscalar.

• An input parameter is invalid for the distribution.

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

GPU Arrays

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

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a