gpucoder.randn

R2026b

Generate normally distributed random numbers on GPU

Since R2026b

Syntax

X = gpucoder.randn

X = gpucoder.randn(n)

X = gpucoder.randn(sz1,...,szN)

X = gpucoder.randn(sz)

X = gpucoder.randn(___,typename)

X = gpucoder.randn(___,like=p)

Description

The gpucoder.randn function generates random numbers from the standard normal distribution. When you generate GPU code from gpucoder.randn, the generated code uses the NVIDIA^® cuRAND library to generate random numbers on the GPU. When you call gpucoder.randn in MATLAB^®, the function generates random numbers by using the randn function.

Note

Because the cuRAND library and MATLAB use different random number generators, the results of gpucoder.randn in MATLAB do not match the results from the generated GPU code.

X = gpucoder.randn returns a random scalar drawn from the normal distribution with a mean of 0 and standard deviation of 1.

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

X = gpucoder.randn(sz1,...,szN) returns an sz1-by-...-by-szN array of random numbers where sz1,...,szN indicates the size of each dimension.

X = gpucoder.randn(sz) returns an array of random numbers with the size sz. For example, gpucoder.randn([4 3 2]) returns a 4-by-3-by-2 array.

X = gpucoder.randn(___,typename) returns an array of numbers of data type typename.

X = gpucoder.randn(___,like=p) returns an array of number of the same data type as p.

Examples

Create Square Matrix of Random Numbers

Create a function, randnMatrix, that accepts an input variable, n, and generates an n-by-n matrix.

function Y = randnMatrix(n)
Y = gpucoder.randn(n);
end

Generate a CUDA^® MEX function from randnMatrix by using the codegen command.

cfg = coder.gpuConfig("mex");
codegen randnMatrix -config cfg -args {4}

Generate a 4-by-4 random matrix by using the generated MEX function randnMatrix_mex.

randnMatrix_mex(4)

ans = 4×4
1.0710	-0.3894	-1.5485	-0.3572
0.7085	1.6184	1.8646	-1.3120
0.8944	-0.4559	-0.1429	-0.1069
-0.8669	-1.0953	1.4666	0.5069

Generate Random Numbers with Specific Mean and Variance

The gpucoder.randn function generates random numbers from a normal distribution with a mean of 0 and a standard deviation of 1. To generate random numbers with a mean of mu and a standard deviation of sigma, create a function, randnWithMeanAndVar, that generates random numbers, multiplies them by sigma, and adds mu to the result.

function Y = randnWithMeanAndVar(n,mu,sigma)
Y = sigma*gpucoder.randn(n)+mu;
end

In this example, define the size of the square matrix as 4. Create variables mu and sigma for the mean and standard deviation, respectively.

n = 4;
mu = 43;
sigma = 2;

Generate a GPU MEX function from randnWithMeanAndVar.

codegen randnWithMeanAndVar -args {n,mu,sigma} -config cfg

Generate a 4-by-4 matrix of random numbers.

Y = randnWithMeanAndVar_mex(n,mu,sigma)

Y = 4×4
45.1420	42.2212	39.9029	42.2857
44.4169	46.2368	46.7291	40.3761
44.7887	42.0882	42.7142	42.7863
41.2661	40.8095	45.9331	44.0138

Check the variance and mean of the generated numbers. The mean and variance are approximately equal to 43 and 2, respectively.

[mean(Y,"all"), std(Y,1,"all")]

ans = 1×2
43.2319	2.0813

Create Three-Dimensional Array of Random Numbers

Create a function, randn3DArray, that generates a three-dimensional array of random numbers.

function Y = randn3DArray(m,n,k)
Y = gpucoder.randn(m,n,k);
end

Generate a MEX function from randn3DArray. Specify the input arguments as three scalar values.

cfg = coder.gpuConfig("mex");
codegen randn3DArray -config cfg -args {1,1,1}

Generate a 4-by-3-by-2 random array by using the generated MEX function.

randn3DArray_mex(4,3,2)

ans(:,:,1) =

    0.7821    0.7625   -0.8071
    0.8513    2.3092    1.1201
    1.4997    0.1610    0.1640
   -0.6420   -1.0330   -0.4070


ans(:,:,2) =

   -0.7206   -0.0740   -1.1675
    0.6068   -0.9157   -0.6306
   -0.4331   -1.8914   -0.9310
    1.5278   -1.6151   -2.2029

Create Matrix with Same Size as Input array

Create a function named randnSameSize that creates a random array with the same size as the input array X.

function Y = randnSameSize(X)
Y = gpucoder.randn(size(X));
end

Generate a MEX function, and specify the example input array as a 5-by-4 matrix of ones.

cfg = coder.gpuConfig("mex");
codegen randnSameSize -config cfg -args {ones(5,4)}

Call the generated MEX function randnSameSize_mex on a 5-by-4 array. The function returns a 5-by-4 matrix of random numbers.

randnSameSize_mex(ones(5,4))

ans = 5×4
1.0710	1.6184	-0.1429	0.5069
0.7085	-0.4559	1.4666	0.4324
0.8944	-1.0953	-0.3572	-1.1278
-0.8669	-1.5485	-1.3120	-1.1272
-0.3894	1.8646	-0.1069	2.2428

Generate and Repeat Matrix of Random Numbers

Create a MATLAB function, randnWithGeneratorReset, that accepts a two-element row vector, sz, and generates a random matrix. Insert a call to gpucoder.rng to reset the generator to its default state before calling gpucoder.randn.

function Y = randnWithGeneratorReset(sz)
gpucoder.rng("default");
Y = gpucoder.randn(sz);
end

Create a variable named sz that contains the vector [1 1]. Generate GPU code from randnWithGeneratorReset, and use sz to specify the input.

cfg = coder.gpuConfig("mex");
sz = [1 1]
codegen randnWithGeneratorReset -args {sz} -config cfg

Generate a random 2-by-3 matrix by using the generated MEX function.

randnWithGeneratorReset_mex([2,3])

ans = 2×3
1.0710	0.8944	-0.3894
0.7085	-0.8669	1.6184

Call the MEX function again. Because gpucoder.rng resets the generator each time the function runs, the output is the same.

randnWithGeneratorReset_mex([2,3])

ans = 2×3
1.0710	0.8944	-0.3894
0.7085	-0.8669	1.6184

Specify Data Type of Random Numbers

Create a function, randnWithType, that returns a random matrix with a size specified by sz and the single data type.

function Y = randnWithType(sz)
Y = gpucoder.randn(sz,"single");
end

Create a variable, sz, that stores a 1-by-2 vector. Generate a CUDA MEX function from randnWithType by using the codegen command and specifying sz as the example input.

sz = ([1 1]);
cfg = coder.gpuConfig("mex");
codegen randnWithType -config cfg -args {sz};

Generate a 4-by-5 matrix by calling randnWithType_mex.

randnWithType_mex([4 5])

ans = 4×5 single matrix
0.2925	2.5470	0.1290	0.5434	0.1374
-0.7184	-0.0034	0.3728	-0.7168	-1.2208
0.1000	0.0083	1.0822	-1.4913	0.3072
-0.3932	-0.2510	-0.6650	1.4805	1.1135

Create Random Array with Same Size and Type as Input Array

Create a function, randnUsingInputType, that generates an array with the same size and type of the input array X.

function Y = randnUsingInputType(X)
Y = gpucoder.randn(size(X),like=X);
end

Create a 3-by-2 array of single-precision numbers as input. Generate a CUDA MEX function from randnUsingInputType.

inArray = ones(3,2,"single");
codegen -config cfg -args {inArray} randnUsingInputType;

Generate random numbers by using randnUsingInputType_mex on the input array.

randnUsingInputType_mex(inArray)

ans = 3×2 single matrix
0.2925	-0.3932
-0.7184	2.5470
0.1000	-0.0034

Input Arguments

n — Size of square matrix

integer

Size of the square matrix, specified as an integer. If n is less than or equal to zero, X is an empty array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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

integer

Size of each dimension, specified as integer values in separate arguments. If the size of any dimension is less than or equal to zero, X is an empty array.

After the second dimension, the function ignores trailing dimensions with a size of 1. For example, gpucoder.randn(3,1,1) returns a 3-by-1 array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

sz — Size of each dimension as a row vector

row vector

Size of each dimension, specified as a row vector of integers. Each element of the vector indicates the size of the corresponding dimension. If the size of any dimension is less than or equal to zero, X is an empty array.

After the second dimension, the function ignores trailing dimensions with a size of 1. For example, gpucoder.randn([3,1,1]) returns a 3-by-1 array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

typename — Data type

"double" (default) | "single"

Data type to return, specified as "double" or "single".

Example: gpucoder.randn(5,"single")

p — Prototype

numeric array

Prototype of array, specified as an array of real numbers. The generated array X has the same type as p.

Example: If A is an array with the data type single, gpucoder.randn(5,like=A) returns an array with the data type single.

Data Types: single | double

Output Arguments

X — Output array

scalar | vector | matrix | multidimensional array

Output array, returned as a scalar, vector, matrix, or multidimensional array.

Limitations

• Generating complex numbers is not supported.

• For code generation, if you use the sz input argument, the vector must have a fixed size. If you use the sz1,...,szN input arguments, the number of arguments must be constant. You can change the values in sz or sz1,...,szN at run time.

Tips

• In generated GPU code, a pseudorandom number generator determines the sequence of numbers generated by gpucoder.rand, gpucoder.randi, and gpucoder.randn. To control the sequence of random numbers, use the gpucoder.rng function.

Extended Capabilities

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2026b