gpucoder.randi

R2026b

Generate uniformly distributed random integers on GPU

Since R2026b

collapse all in page

    Syntax

    X = gpucoder.randi(imax)
    X = gpucoder.randi(imax,n)
    X = gpucoder.randi(imax,sz1,...,szN)
    X = gpucoder.randi(imax,sz)
    X = gpucoder.randi(___,typename)
    X = gpucoder.randi(___,like=p)
    X = gpucoder.randi([imin,imax],___)

    Description

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

    Note

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

    X = gpucoder.randi(imax) returns a random integer from the discrete uniform distribution on the interval [1,imax].

    X = gpucoder.randi(imax,n) returns an n-by-n matrix of random integers.

    example

    X = gpucoder.randi(imax,sz1,...,szN) returns an sz1-by-...-by-szN array where each argument in sz1,...,szN indicates the size of each dimension.

    example

    X = gpucoder.randi(imax,sz) returns an array of random integers with the size sz. For example, gpucoder.randi(5,[3 4]) returns a 3-by-4 matrix of random integers between 1 and 5.

    example

    X = gpucoder.randi(___,typename) returns an array of integers of data type typename.

    example

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

    example

    X = gpucoder.randi([imin,imax],___) returns an array of integers from the discrete uniform distribution over the interval [imin,imax].

    example

    Examples

    collapse all

    Create a MATLAB function that accepts an integer value, imax, and a size value, n, and generates a square matrix of random integers.

    function Y = randiMatrix(imax,n)
Y = gpucoder.randi(imax,n);
end

    Generate a GPU MEX function from randiMatrix.

    cfg = coder.gpuConfig("mex");
imax = 13;
n = 4;
codegen randiMatrix -args {imax,n} -config cfg

    Generate a 4-by-4 matrix of random integers up to and including the value 13 by using the generated MEX function.

    Y = randiMatrix_mex(imax,n)
    Y = 4×4
6	1	7	7
6	5	1	4
4	6	7	1
7	12	9	8

    Create a function named randiInterval that generates a sz1-by-sz2 matrix of random integers between the input values imin and imax.

    function Y = randiInterval(imin,imax,sz1,sz2)
Y = gpucoder.randi([imin,imax],sz1,sz2);
end

    For this example, use a minimum value of -5 and maximum value of 5. Generate a GPU MEX function from randiInterval.

    imin = -5;
imax = 5;
sz1 = 4;
sz2 = 3;
cfg = coder.gpuConfig("mex");
codegen randiInterval -args {imin,imax,sz1,sz2} -config cfg

    Generate a random 4-by-3 matrix of random integers.

    randiInterval_mex(imin,imax,sz1,sz2)
    ans = 4×3
-1	-5	0
0	-2	-5
-3	-1	0
0	4	2

    Create a function, randi4DArray, that generates a four-dimensional array of random integers.

    function Y = randi4DArray(imax,m,n,p,q)
Y = gpucoder.randi(imax,m,n,p,q);
end

    Generate a CUDA® MEX function from randi4DArray. Specify the input arguments as five scalar values.

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

    Create a 2-by-3-by-4-by-2 array of random integers between 1 and 10 by using the generated MEX function randi4DArray_mex.

    randi4DArray_mex(10,2,3,4,2)
    ans(:,:,1,1) =

     5     3     1
     5     5     4


ans(:,:,2,1) =

     4     5     6
     9     1     7


ans(:,:,3,1) =

     6     1     4
     3     6    10


ans(:,:,4,1) =

     7     7     5
     3     1     1


ans(:,:,1,2) =

     1     9    10
     2     7    10


ans(:,:,2,2) =

     2     2     1
     4     8     1


ans(:,:,3,2) =

     5     4     3
     7     3     7


ans(:,:,4,2) =

     8     7     8
     2     7     1

    Create a function, randiUsingInputSize, that generates an array of random integers up to a value, imax, that has the same size as an input matrix, X.

    function Y = randiUsingInputSize(imax,X)
Y = gpucoder.randi(imax,size(X));
end

    Create a 2-by-4 matrix of ones, X, and generate a CUDA MEX function from randiUsingInputSize by using the matrix as an example input.

    X = ones(2,4);
imax = 20;
cfg = coder.gpuConfig("mex");
codegen randiUsingInputSize -args {imax,X} -config cfg

    Generate a random matrix of integers with the same size as X.

    Y = randiUsingInputSize(imax,X)
    Y = 2×4
9	6	2	8
10	10	7	18

    Create a MATLAB function, randiWithGeneratorReset, that accepts a maximum integer value, imax, and a two-element row vector, sz, and generates a random integer matrix. Use the gpucoder.rng function to reset the generator to its default state before calling gpucoder.randi.

    function Y = randiWithGeneratorReset(imax,sz)
gpucoder.rng("default");
Y = gpucoder.randi(imax,sz);
end

    Create variables named imax and sz that contain the maximum integer value, 10, and the vector [3 4]. Generate GPU code from randiWithGeneratorReset, and use imax and sz to specify the inputs.

    cfg = coder.gpuConfig("mex");
imax = 10;
sz = [3 4];
codegen randiWithGeneratorReset -args {imax,sz} -config cfg

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

    Y1 = randiWithGeneratorReset_mex(imax,sz)
    Y1 = 3×4
5	5	4	1
5	1	9	6
3	4	5	7

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

    Y2 = randiWithGeneratorReset_mex(imax,sz)
    Y2 = 3×4
5	5	4	1
5	1	9	6
3	4	5	7

    Create a function, randiWithType, that returns a random integer matrix with a size specified by sz and the int32 data type.

    function Y = randiWithType(imax,sz)
Y = gpucoder.randi(imax,sz,"int32");
end

    Create variables, imax and sz, that store the maximum integer value and a 1-by-2 vector. Generate a CUDA MEX function from randiWithType by using the codegen command and specifying imax and sz as the example inputs.

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

    Generate a 4-by-5 matrix that uses the int32 data type by calling randiWithType_mex.

    randiWithType_mex(100,[4 5])
    ans = 4×5 int32 matrix
75	93	48	72	32
93	45	52	36	82
4	67	78	69	16
97	11	30	30	45

    Create a function, randiLogical, that generates an n-by-n square matrix of random zeroes and ones. Specify the output type as logical.

    function TF = randiLogical(n)
TF = gpucoder.randi([0,1],n,"logical");
end

    Generate a GPU MEX function from randiLogical.

    n = 3;
cfg = coder.gpuConfig("mex");
codegen randiLogical -args {n} -config cfg

    Create a 3-by-3 matrix of random logical values.

    TF = randiLogical_mex(n)
    TF = 3×3 logical array
1	1	1
1	1	0
0	0	0

    Create a function, randiUsingInputSizeAndType, that accepts an integer, imax, and an array, X. Generate an array of random integers from the discrete uniform distribution between 1 and imax with the same size and type as X.

    function Y = randiUsingInputSizeAndType(imax,X)
Y = gpucoder.randi(imax,size(X),like=X);
end

    Define the variable X as a 3-by-2 matrix of int32 values. Generate a GPU MEX function from randiUsingInputSizeAndType, and use the matrix X as an example input.

    X = ones(3,2,"int32");
imax = 31;
cfg = coder.gpuConfig("mex");
codegen randiUsingInputSizeAndType -args {imax,X} -config cfg

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

    Y = randiUsingInputSizeAndType_mex(imax,X)
    Y = 3×2 int32 matrix
23	31
29	29
2	14

    Input Arguments

    collapse all

    Maximum integer in the sample interval, specified as an integer. If you do not specify imin, imax must be a positive integer, and the function uses the distribution over the range [1,imax].

    Example: gpucoder.randi(10,4)

    Minimum integer in the sample interval, specified as an integer. The minimum integer must be less than or equal to imax.

    Example: gpucoder.randi([0,8],3)

    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.randi(10,3,1,1) returns a 3-by-1 array of integers between 1 and 10.

    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.randi(10,[3,1,1]) returns a 3-by-1 array of integers between 1 and 10.

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

    Data type to return, specified as "double", "single", "int8", "uint8", "int16", "uint16", "int32", "uint32", or "logical".

    Example: gpucoder.randi(10,5,"uint8")

    Example: gpucoder.randi([-127,128],4,"int8")

    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 int32, gpucoder.randi(imax,n,like=A) returns an int32 array.

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

    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.

    • If imin or imax are outside of the minimum or maximum values of the selected type, gpucoder.randi first generates random integers in the range [imin,imax]. The function then maps values outside of the minimum or maximum value of the output type to the nearest endpoint.

    Extended Capabilities

    expand all

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

    Version History

    Introduced in R2026b

    See Also

    | |

    Topics