Main Content

randi

Create codistributed array of uniformly distributed random integers

    Description

    example

    X = randi(r,n) creates an n-by-n codistributed matrix of uniformly distributed random integers in the range defined by r.

    • If r is a scalar, the function creates random integers in the range 1 to r.

    • If r is a vector, the function creates random integers in the range r(1) to r(2).

    When you create the codistributed array in a communicating job or spmd block, the function creates an array on each worker. If you create a codistributed array outside of a communicating job or spmd block, the array is stored only on the worker or client that creates the codistributed array.

    By default, the codistributed array has the underlying type double.

    X = randi(r,sz1,...,szN) creates an sz1-by-...-by-szN codistributed array of uniformly distributed random integers 1 to imax. sz1,...,szN indicates the size of each dimension.

    X = randi(r,sz) creates a codistributed array of uniformly distributed random integers where the size vector sz defines the size of X. For example, randi(codistributed(5),codistributed([2 3])) creates a 2-by-3 codistributed array of random integers between 1 and 5.

    X = randi(___,datatype) creates a codistributed array of uniformly distributed random integers with the underlying type datatype. For example, randi(codistributed(5),"int8") creates a codistributed 8-bit random integer between 1 and 5. You can use this syntax with any of the input arguments in the previous syntaxes.

    X = randi(___,codist) uses the codistributor object codist to create a codistributed array of uniformly distributed random integers.

    Specify the distribution of the array values across the memory of workers using the codistributor object codist. For more information about creating codistributors, see codistributor1d and codistributor2dbc.

    X = randi(___,codist,"noCommunication") creates a codistributed array of uniformly distributed random integers without using communication between workers. You can specify codist or codist,"noCommunication", but not both.

    When you create very large arrays or your communicating job or spmd block uses many workers, worker-worker communication can slow down array creation. Use this syntax to improve the performance of your code by removing the time required for worker-worker communication.

    Tip

    When you use this syntax, some error checking steps are skipped. Use this syntax to improve the performance of your code after you prototype your code without specifying "noCommunication".

    X = randi(___,"like",p) uses the array p to create a codistributed array of uniformly distributed random integers. You can specify datatype or "like", but not both.

    The returned array X has the same underlying type, sparsity, and complexity (real or complex) as p.

    Examples

    collapse all

    Create a 1000-by-1000 codistributed double matrix of randi values from 0 to 12, distributed by its second dimension (columns).

    spmd(4)
    C = randi([0 12],1000,'codistributed');
    end

    With four workers, each worker contains a 1000-by-250 local piece of C.

    Create a 1000-by-1000 codistributed single matrix of randi values from 1 to 4, distributed by its columns.

    spmd(4)
    codist = codistributor('1d',2,100*[1:numlabs]);
    C = randi(4,1000,1000,'single',codist);
    end

    Each worker contains a 100-by-labindex local piece of C.

    Input Arguments

    collapse all

    Range of output values, specified as a codistributed integer scalar or vector.

    • If r is a scalar, the function creates random integers in the range 1 to r.

    • If r is a vector, the function creates random integers in the range r(1) to r(2).

    Size of the square matrix, specified as a codistributed integer.

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

    • If n is negative, then the function treats it as 0.

    Size of each dimension, specified as separate arguments of codistributed 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 the function treats it as 0.

    • Beyond the second dimension, the function ignores trailing dimensions with a size of 1.

    Size of each dimension, specified as a codistributed integer row vector. 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 the function treats it as 0.

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

    Example: sz = codistributed([2 3 4]) creates a 2-by-3-by-4 codistributed array.

    Underlying data type of the returned array, specified as one of these options:

    • "double"

    • "single"

    • "logical"

    • "int8"

    • "uint8"

    • "int16"

    • "uint16"

    • "int32"

    • "uint32"

    • "int64"

    • "uint64"

    Codistributor, specified as a codistributor1d or codistributor2dbc object. For information on creating codistributors, see the reference pages for codistributor1d and codistributor2dbc. To use the default distribution scheme, you can specify a codistributor constructor without arguments.

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

    Introduced in R2014a