Main Content

Transfer distributed array or gpuArray to local workspace

`X = gather(`

can operate on the following
array data:`A`

)

On a gpuArray: Transfers the elements of

`A`

from the GPU to the local workspace and assigns them to`X`

.On a distributed array, outside an

`spmd`

statement: Gathers together the elements of`A`

from the multiple workers to the local workspace and assigns them to`X`

.On a codistributed array, inside an

`spmd`

statement or communicating job: Gathers together the elements of`A`

and replicates them into`X`

on every worker.

You can call `gather`

on other data types, such as tall arrays (See
`gather (tall)`

). If the data type does not support gathering, then
`gather`

has no effect.

Gathering GPU arrays or distributed arrays can be costly and is generally not necessary unless you need to use your result with functions that do not support these types of arrays. For more information on function support, see Run MATLAB Functions on a GPU or Run MATLAB Functions with Distributed Arrays.

`X = gather(gpuArray(X))`

, ```
X =
gather(distributed(X))
```

, or `X = gather(codistributed(X))`

return the original array `X`

.

`[X1,X2,...,Xn] = gather(A1,A2,...,,Xn)`

gathers multiple arrays
`A1,A2,...,,An`

into the corresponding outputs
`X1,X2,...,Xn`

. The number of input arguments and output arguments must
match.

`X = gather(C,lab)`

converts a codistributed array
`C`

to a variant array `X`

, such that all of the
elements are contained on worker `lab`

, and `X`

is a
0-by-0 empty double on all other workers.

`[X1,X2,...,Xn] = gather(C1,C2,...,Cn,lab)`

gathers codistributed
arrays `C1,C2,...,Cn`

into corresponding outputs
`X1,X2,...,Xn`

, with all elements on worker `lab`

. The
number of input arguments and output arguments must match.

Note that `gather`

assembles the codistributed or distributed array in
the workspaces of all the workers on which it executes, or on the MATLAB client, respectively, but not both. If you are using `gather`

within an `spmd`

statement, the gathered array is
accessible on the client via its corresponding `Composite`

object; see Access Worker Variables with Composites. If you
are running `gather`

in a communicating job, you can return the gathered
array to the client as an output argument from the task.

As the `gather`

function requires communication between all the workers,
you cannot gather data from all the workers onto a single worker by placing the function
inside a conditional statement such as `if labindex == 1`

.

`arrayfun`

| `bsxfun`

| `codistributed`

| `distributed`

| `gpuArray`

| `pagefun`