# gather

Transfer distributed array, `Composite`

object, or
`gpuArray`

object to local workspace

## Syntax

## Description

`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,...,An)`

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(`

converts a
codistributed array `Cd`

,destination)`Cd`

to a variant array `X`

, such
that all of the elements are contained on the worker specified by
`destination`

, and `X`

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

`[X1,X2,...,Xn] = gather(Cd1,Cd2,...,Cdn,destination)`

gathers
codistributed arrays `Cd1,Cd2,...,Cdn`

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

, with all elements on the worker specified by
`destination`

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

`X = gather(`

gathers all the elements of
Composite array `Cp`

)`Cp`

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

.The number of cells in
`X`

is dependent on number of workers referenced by
`Cp`

.* (since R2023a)*

`[X1,X2,...,Xn] = gather(Cp1,Cp2,...,Cpn)`

gathers Composite arrays
`Cp1,Cp2,...,Cpn`

into corresponding cell arrays
`X1,X2,...,Xn`

. The number of input arguments and output arguments must
match.* (since R2023a)*

## Examples

## Input Arguments

## Tips

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 spmdIndex == 1`

.

## Version History

**Introduced in R2006b**

## See Also

`arrayfun`

| `codistributed`

| `distributed`

| `gpuArray`

| `Composite`

| `pagefun`