randi

Uniformly distributed pseudorandom integers

Syntax

X = randi(imax)

X = randi(imax,n)

X = randi(imax,sz1,...,szN)

X = randi(imax,sz)

X = randi(imax,typename)

X = randi(imax,n,typename)

X = randi(imax,sz1,...,szN,typename)

X = randi(imax,sz,typename)

X = randi(imax,'like',p)

X = randi(imax,n,'like',p)

X = randi(imax,sz1,...,szN,'like',p)

X = randi(imax,sz,'like',p)

X = randi([imin,imax],___)

X = randi(s,___)

Description

X = randi(imax) returns a pseudorandom scalar integer between 1 and imax.

X = randi(imax,n) returns an n-by-n matrix of pseudorandom integers drawn from the discrete uniform distribution on the interval [1,imax].

X = randi(imax,sz1,...,szN) returns an sz1-by-...-by-szN array where sz1,...,szN indicates the size of each dimension. For example, randi(10,3,4) returns a 3-by-4 array of pseudorandom integers between 1 and 10.

X = randi(imax,sz) returns an array where size vector sz defines size(X). For example, randi(10,[3,4]) returns a 3-by-4 array of pseudorandom integers between 1 and 10.

X = randi(imax,typename) returns a pseudorandom integer where typename specifies the data type. typename can be 'single', 'double', 'int8', 'uint8', 'int16', 'uint16', 'int32', or 'uint32'.

X = randi(imax,n,typename) returns an n-by-n array of data type typename.

X = randi(imax,sz1,...,szN,typename) returns an sz1-by-...-by-szN array of data type typename.

X = randi(imax,sz,typename) returns an array where size vector sz defines size(X) and typename defines class(X).

X = randi(imax,'like',p) returns a pseudorandom integer like p; that is, with the same data type (class).

X = randi(imax,n,'like',p) returns an n-by-n array like p.

X = randi(imax,sz1,...,szN,'like',p) returns an sz1-by-...-by-szN array like p.

X = randi(imax,sz,'like',p) returns an array like p where size vector sz defines size(X).

X = randi([imin,imax],___) returns an array containing integers drawn from the discrete uniform distribution on the interval [imin,imax], using any of the above syntaxes.

X = randi(s,___) generates integers from random number stream s instead of the default global stream. To create a stream, use RandStream. Specify s followed by any of the argument combinations in previous syntaxes, except for the ones that involve 'like'. This syntax does not support the 'like' input.

Examples

Square Matrix of Random Integers

Generate a 5-by-5 matrix of random integers between 1 and 10. The first input to randi indicates the largest integer in the sampling interval (the smallest integer in the interval is 1).

r = randi(10,5)

r = 5×5

     9     1     2     2     7
    10     3    10     5     1
     2     6    10    10     9
    10    10     5     8    10
     7    10     9    10     7

Random Integers Within Specified Interval

Generate a 10-by-1 column vector of uniformly distributed random integers from the sample interval [-5,5].

r = randi([-5,5],10,1)

r = 10×1

     3
     4
    -4
     5
     1
    -4
    -2
     1
     5
     5

Control Random Number Generation

Save the current state of the random number generator and create a 1-by-5 vector of random integers.

s = rng;
r = randi(10,1,5)

r = 1×5

     9    10     2    10     7

Restore the state of the random number generator to s, and then create a new 1-by-5 vector of random integers. The values are the same as before.

rng(s);
r1 = randi(10,1,5)

r1 = 1×5

     9    10     2    10     7

Always use the rng function (rather than the rand or randn functions) to specify the settings of the random number generator. For more information, see Replace Discouraged Syntaxes of rand and randn.

3-D Array of Random Integers

Create a 3-by-2-by-3 array of uniformly distributed random integers between 1 and 500.

X = randi(500,[3,2,3])

X = 
X(:,:,1) =

   408   457
   453   317
    64    49


X(:,:,2) =

   140   483
   274    79
   479   486


X(:,:,3) =

   479    71
   243   211
   401   458

Random Integers of Other Data Types

Create a 1-by-4 vector of random numbers whose elements are of type int16.

r = randi(100,1,4,'int16')

r = 1x4 int16 row vector

   82   91   13   92

class(r)

ans = 
'int16'

Size Defined by Existing Array

Create a matrix of uniformly distributed random integers between 1 and 10 with the same size as an existing array.

A = [3 2; -2 1];
sz = size(A);
X = randi(10,sz)

X = 2×2

     9     2
    10    10

It is a common pattern to combine the previous two lines of code into a single line:

X = randi(10,size(A));

Size and Numeric Data Type Defined by Existing Array

Create a 2-by-2 matrix of 8-bit signed integers.

p = int8([3 2; -2 1]);

Create an array of random integers that is the same size and data type as p.

X = randi(10,size(p),'like',p)

X = 2x2 int8 matrix

    9    2
   10   10

class(X)

ans = 
'int8'

Input Arguments

imax — Largest integer in sample interval

positive integer

Largest integer in sample interval, specified as a positive integer. randi draws values from the uniform distribution in the sample interval [1,imax].

Example: randi(10,5)

imin — Smallest integer in sample interval

1 (default) | scalar integer

Smallest integer in sample interval, specified as a scalar integer.

Both imin and imax must be integers that satisfy imin ≤ imax.

For example, randi([50,100],5) returns a 5-by-5 matrix of random integers between (and including) 50 and 100.

n — Size of square matrix

integer value

Size of square matrix, specified as an integer value.

• If n is 0, then X is an empty matrix.

• If n is negative, then it is treated as 0.

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

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

two or more integer values

Size of each dimension, specified as separate arguments of integer values.

• If the size of any dimension is 0, then X is an empty array.

• If the size of any dimension is negative, then it is treated as 0.

• Beyond the second dimension, randi ignores trailing dimensions with a size of 1. For example, randi([5,10],3,1,1,1) produces a 3-by-1 vector of random integers between 5 and 10.

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

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

integer values

Size of each dimension, specified as a row vector of integer values. Each element of this vector indicates the size of the corresponding dimension:

• If the size of any dimension is 0, then X is an empty array.

• If the size of any dimension is negative, then it is treated as 0.

• Beyond the second dimension, randi ignores trailing dimensions with a size of 1. For example, randi([5,10],[3 1 1 1]) produces a 3-by-1 vector of random integers between 5 and 10.

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

typename — Data type (class) to create

'double' (default) | 'single' | 'int8' | 'uint8' | ...

Output class, specified as 'double', 'single', 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', or the name of another class that provides randi support.

Example: randi(5,5,'int8')

Data Types: char

p — Prototype of array to create

numeric array

Prototype of array to create, specified as a numeric array.

Example: randi(5,5,'like',p)

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

s — Random number stream

RandStream object

Random number stream, specified as a RandStream object.

Example: s = RandStream('dsfmt19937'); randi(s,[5,10],[3 1])

Tips

• The sequence of numbers produced by randi is determined by the internal settings of the uniform pseudorandom number generator that underlies rand, randi, and randn. You can control that shared random number generator using rng.

• The arrays returned by randi might contain repeated integer values. This behavior is sometimes referred to as sampling with replacement. Use randperm if you require all unique values.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• The data type (class) must be a built-in MATLAB^® numeric type. Does not invoke the static randi method for other classes. For example, randi(imax,sz,'myclass') does not invoke myclass.randi(imax,sz).

• Size arguments must have a fixed size.

• See Variable-Sizing Restrictions for Code Generation of Toolbox Functions (MATLAB Coder).

• If extrinsic calls are enabled and randi is not called from inside a parfor loop, generated MEX files use the same random number state as MATLAB in serial code. Otherwise, the generated MEX code and standalone code maintain their own random number state that is initialized to the same state as MATLAB.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

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

Usage notes and limitations:

• The stream syntax randi(s,___) is not supported on a GPU.

• You can specify typename as 'gpuArray'. If you specify typename as 'gpuArray', the default underlying type of the array is double.

  To create a GPU array with underlying type datatype, specify the underlying type as an additional argument before typename. For example, X = randi(imax,3,datatype,'gpuArray') creates a 3-by-3 GPU array of random integers in the range [1 imax] with underlying type datatype.

  You can specify the underlying type datatype as one of these options:

  • 'double'

  • 'single'

  • 'logical'

  • 'int8'

  • 'uint8'

  • 'int16'

  • 'uint16'

  • 'int32'

  • 'uint32'

  • 'int64'

  • 'uint64'

• You can also specify the numeric variable p as a gpuArray.

  If you specify p as a gpuArray, the underlying type of the returned array is the same as p.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

• The stream syntax randi(s,___) is not supported for codistributed or distributed arrays.

• You can specify typename as 'codistributed' or 'distributed'. If you specify typename as 'codistributed' or 'distributed', the default underlying type of the returned array is double.

  To create a distributed or codistributed array with underlying type datatype, specify the underlying type as an additional argument before typename. For example, X = randi(imax,3,datatype,'distributed') creates a 3-by-3 distributed matrix of random integers in the range [1 imax] with underlying type datatype.

  You can specify the underlying type datatype as one of these options:

  • 'double'

  • 'single'

  • 'logical'

  • 'int8'

  • 'uint8'

  • 'int16'

  • 'uint16'

  • 'int32'

  • 'uint32'

  • 'int64'

  • 'uint64'

• You can also specify p as a codistributed or distributed array.

  If you specify p as a codistributed or distributed array, the underlying type of the returned array is the same as p.

• For additional codistributed syntaxes, see randi (codistributed) (Parallel Computing Toolbox).

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).