gpucoder.rand

R2026b

Generate uniformly distributed random numbers on GPU

Since R2026b

collapse all in page

    Syntax

    X = gpucoder.rand
    X = gpucoder.rand(n)
    X = gpucoder.rand(sz1,...,szN)
    X = gpucoder.rand(sz)
    X = gpucoder.rand(___,typename)
    X = gpucoder.rand(___,like=p)

    Description

    The gpucoder.rand function generates random numbers from a uniform distribution. When you generate GPU code from gpucoder.rand, the code uses the NVIDIA® cuRAND library to generate random numbers on the GPU. When you call gpucoder.rand in MATLAB®, the function generates random numbers by using the rand function.

    Note

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

    X = gpucoder.rand returns a random scalar from a uniform distribution. In MATLAB, the distribution is over the open interval (0,1). In the generated GPU code, the distribution is over the half-open interval (0,1].

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

    example

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

    example

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

    example

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

    example

    X = gpucoder.rand(___,like=p) returns an array of random numbers with the same data type as p.

    example

    Examples

    collapse all

    Create a function, randMatrix, that accepts the integer n and returns an n-by-n matrix.

    function Y = randMatrix(n)
Y = gpucoder.rand(n);
end

    Generate a GPU MEX function from randMatrix by using the codegen command.

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

    Generate a 4-by-4 matrix. The function uses the cuRAND library to generate the random numbers on the GPU.

    randMatrix_mex(4)
    ans = 4×4
0.4385	0.0530	0.4822	0.5126
0.4604	0.3377	0.0428	0.2643
0.2502	0.3968	0.5084	0.0520
0.4947	0.8744	0.6545	0.5790

    Write a function, randInterval, that generates random numbers from the range (0,1], and then scales the result to be in the half-open interval bounded by a and b.

    function Y = randInterval(n,a,b)
Y = a+(b-a)*gpucoder.rand(n);
end

    To generate random numbers on the interval (-5,5], assign variables a and b to -5 and 5, respectively. Generate a GPU MEX function from randInterval.

    n = 3;
a = -5;
b = 5;
cfg = coder.gpuConfig("mex");
codegen randInterval -config cfg -args {n,a,b}

    Generate random numbers on the interval (-5,5].

    randInterval_mex(n,a,b)
    ans = 3×3
-0.6155	-0.0526	-1.0324
-0.3964	-4.4699	3.7442
-2.4979	-1.6230	-0.1783

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

    function Y = rand3DArray(m,n,k)
Y = gpucoder.rand(m,n,k);
end

    Generate a CUDA® MEX function from rand3DArray. Specify the input arguments as three scalar values.

    cfg = coder.gpuConfig("mex");
args = {2,3,4};
codegen -config cfg -args args rand3DArray;

    Create a 2-by-3-by-4 array by using the generated MEX function rand3DArray_mex.

    rand3DArray_mex(2,3,4)
    ans = 
ans(:,:,1) =

    0.4385    0.2502    0.0530
    0.4604    0.4947    0.3377


ans(:,:,2) =

    0.3968    0.4822    0.5084
    0.8744    0.0428    0.6545


ans(:,:,3) =

    0.5126    0.0520    0.3856
    0.2643    0.5790    0.9082


ans(:,:,4) =

    0.6416    0.6558    0.4146
    0.2834    0.0454    0.0573

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

    function Y = randSameSize(X)
Y = gpucoder.rand(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");
X = ones(5,4);
codegen randSameSize -config cfg -args {X}

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

    randSameSize_mex(X)
    ans = 5×4
0.4385	0.3377	0.5084	0.5790
0.4604	0.3968	0.6545	0.3856
0.2502	0.8744	0.5126	0.9082
0.4947	0.4822	0.2643	0.6416
0.0530	0.0428	0.0520	0.2834

    Create a MATLAB function, randWithGeneratorReset, 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.rand.

    function Y = randWithGeneratorReset(sz)
gpucoder.rng("default");
Y = gpucoder.rand(sz);
end

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

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

    Generate a random 1-by-5 matrix by using the generated MEX function.

    randWithGeneratorReset_mex(sz)
    ans = 1×5
0.4385	0.4604	0.2502	0.4947	0.0530

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

    randWithGeneratorReset_mex(sz)
    ans = 1×5
0.4385	0.4604	0.2502	0.4947	0.0530

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

    function Y = randWithType(sz)
Y = gpucoder.rand(sz,"single");
end

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

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

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

    randWithType_mex([4 5])
    ans = 4×5 single matrix
0.7402	0.9251	0.4702	0.7140	0.3194
0.9210	0.4464	0.5132	0.3585	0.8109
0.0390	0.6673	0.7762	0.6814	0.1541
0.9690	0.1099	0.2948	0.2920	0.4452

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

    function Y = randUsingInputType(X)
Y = gpucoder.rand(size(X),like=X);
end

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

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

    Generate random numbers by using randUsingInputType_mex on the input array.

    randUsingInputType_mex(inArray)
    ans = 3×2 single matrix
0.7402	0.9690
0.9210	0.9251
0.0390	0.4464

    Input Arguments

    collapse all

    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

    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.rand(3,1,1) returns a 3-by-1 array.

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

    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.rand([3,1,1]) returns a 3-by-1 array.

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

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

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

    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.rand(5,like=A) returns an array with the data type single.

    Data Types: single | double

    Output Arguments

    collapse all

    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

    expand all

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

    Version History

    Introduced in R2026b

    See Also

    | |

    Topics