# randi

Create codistributed array of uniformly distributed random integers

## Syntax

``cR = randi(r,n,codist)``
``cR = randi(r,sz,codist)``
``cR = randi(r,sz1,...,szN,codist)``
``cR = randi(___,datatype,codist)``
``cR = randi(___,"noCommunication")``
``cR = randi(___,like=p)``

## Description

example

````cR = randi(r,n,codist)` creates an `n`-by-`n` codistributed matrix of uniformly distributed random integers in the range defined by `r` and uses `codist` to specify the distribution of the array values across the workers.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)`.Specify `codist` as `"codistributed"` to use the default `codistributor1d` distribution scheme or the distribution scheme defined by a `codistributor1d` or `codistributor2dbc` object.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`. ```
````cR = randi(r,sz,codist)` creates a codistributed array of uniformly distributed random integers where the size vector `sz` defines the size of `cR`. For example, `randi(5,[2 3],"codistributed")` creates a 2-by-3 codistributed array of random integers between `1` and `5`.```
````cR = randi(r,sz1,...,szN,codist)` creates an `sz1`-by-...-by-`szN` codistributed array of uniformly distributed random integers between `1` to `r`. `sz1,...,szN` indicates the size of each dimension.```
````cR = randi(___,datatype,codist)` creates a codistributed array of uniformly distributed random integers with the underlying type `datatype`. For example, `randi([1,5],1,"int8","codistributed")` creates a codistributed 8-bit random integer between `10` and `50`. You can use this syntax with any of the size arguments in the previous syntaxes. You must specify `codist` after the array size and data type arguments.```
````cR = randi(___,"noCommunication")` creates a codistributed array of uniformly distributed random integers without using communication between workers. 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. TipWhen 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"`. You must specify `"noCommunication"` after the size, data type and `codist` arguments.```
````cR = randi(___,like=p)` uses the array `p` to create a codistributed array of uniformly distributed random integers. You can also specify `"noCommunication"` as part of the function call.The returned array `cR` 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 = codistributor1d(2,100*[1:spmdSize]); C = randi(4,1000,1000,"single",codist); end```

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

## Input Arguments

collapse all

Range of output values, specified as an 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 an integer.

• If `n` is `0`, then `cR` is an empty matrix.

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

Distribution scheme for codistributed array, specified as one of these options:

• `"codistributed"` — Uses the default distribution scheme defined by the default `codistributor1d` object.

• `codistributor1d` object — Uses the one-dimensional distribution scheme defined in a `codistributor1d` object. To use the default 1-D distribution scheme, you can specify the `codistributor1d` function without arguments.

• `codistributor2dbc` object — Uses the two-dimensional block-cyclic distribution scheme defined in a `codistributor2dbc` object. To use the default 2-D block-cyclic distribution scheme, you can specify the `codistributor2dbc` function without arguments.

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

• If the size of any dimension is `0`, then `cR` 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(10,[3 1 1 1],"codistributed")` produces a 3-by-1 codistributed vector of uniformly distributed random integers.

Example: `[2 3 4]` creates a 2-by-3-by-4 codistributed array.

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

• If the size of any dimension is `0`, then `cR` 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`.

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

• `"double"`

• `"single"`

• `"logical"`

• `"int8"`

• `"uint8"`

• `"int16"`

• `"uint16"`

• `"int32"`

• `"uint32"`

• `"int64"`

• `"uint64"`

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

If you do not specify the `datatype`, the resulting codistributed array has the same underlying type, sparsity, and complexity (real or complex) as `p`.

## Version History

Introduced in R2014a