gather - Transfer distributed array, Composite object, or

    gpuArray object to local workspace - MATLAB ([original](http://www.mathworks.com/help/parallel-computing/gpuarray.gather.html)) ([raw](?raw))

Transfer distributed array, Composite object, orgpuArray object to local workspace

Syntax

Description

X = gather([A](#mw%5F96da83a0-d59a-4dee-b374-0884af189d39)) can operate on the following array data:

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 (Seegather (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 orRun MATLAB Functions with Distributed Arrays.

X = gather(gpuArray(X)), X = gather(distributed(X)), or X = gather(codistributed(X)) return the original array X.

example

[X1,X2,...,Xn] = gather(A1,A2,...,An) gathers multiple arraysA1,A2,...,An into the corresponding outputsX1,X2,...,Xn. The number of input arguments and output arguments must match.

X = gather([Cd](#mw%5Fbc61494a-ffc3-4014-9670-360aa017e84e),destination) converts a codistributed array Cd to a variant array X, such that all of the elements are contained on the worker specified bydestination, and X is a 0-by-0 empty double on all other workers.

example

[X1,X2,...,Xn] = gather(Cd1,Cd2,...,Cdn,destination) gathers codistributed arrays Cd1,Cd2,...,Cdn into corresponding outputsX1,X2,...,Xn, with all elements on the worker specified bydestination. The number of input arguments and output arguments must match.

X = gather([Cp](#mw%5F43146650-0023-4e84-ad3d-af5b719bb03e)) gathers all the elements of Composite array Cp from the multiple workers to the local workspace and assigns them to cell array X.The number of cells inX is dependent on number of workers referenced byCp. (since R2023a)

example

[X1,X2,...,Xn] = gather(Cp1,Cp2,...,Cpn) gathers Composite arraysCp1,Cp2,...,Cpn into corresponding cell arraysX1,X2,...,Xn. The number of input arguments and output arguments must match. (since R2023a)

Examples

collapse all

Gather the results of a GPU operation to the MATLAB® workspace.

G = gpuArray(rand(1024,1)); F = sqrt(G); % Input and output are both gpuArray W = gather(G); % Return array to workspace whos

Name Size Bytes Class Attributes

F 1024x1 8192 gpuArray
G 1024x1 8192 gpuArray
W 1024x1 8192 double

Gather all of the elements from a distributed array D onto the client.

n = 10; parpool('Processes',4); D = distributed(magic(n)); % Distribute array to workers M = gather(D) % Return array to client

Distribute a magic square across your workers, then gather the whole matrix onto every worker and then onto the client. This code results in the equivalent of M = magic(n) on all workers and the client.

n = 10; parpool('Processes',4); spmd Cd = codistributed(magic(n)); M = gather(Cd); % Gather all elements to all workers end S = gather(Cd) % Gather elements to client

Gather all of the elements of Cd onto worker 1, for operations that cannot be performed across distributed arrays.

n = 10; spmd Cd = codistributed(magic(n)); out = gather(Cd,1); if spmdIndex == 1 % Characteristic sum for this magic square: characteristicSum = sum(1:n^2)/n; % Ensure that the diagonal sums are equal to the % characteristic sum: areDiagonalsEqual = isequal ... (trace(out),trace(flipud(out)),characteristicSum) end end

Worker 1:

areDiagonalsEqual =

logical

 1

Since R2023a

Gather all of the elements of the composite arrayCp stored on parallel workers onto the client.

Use an spmd statement to create a magic square on your workers and a Composite array Cp on the client.

n = 10 p = parpool('Processes',4); spmd Cp = magic(n); end

Gather the results stored on your workers onto the client.

results =

1×4 cell array

{10×10 double}    {10×10 double}    {10×10 double}    {10×10 double}

Input Arguments

collapse all

Codistributed array to gather, specified as a codistributed array.

Since R2023a

Composite array to gather, specified as a Composite array.

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 usinggather 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 runninggather in a communicating job, you can return the gathered array to the client as an output argument from the task.
As the gather function on a distributed or codistributed array 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.
You can gather gpuArray objects by right-clicking the variable in the workspace, and then selecting . (since R2025a)

Version History

Introduced in R2006b

expand all

You can now gather gpuArray objects by right-clicking the variable in the workspace, and then selecting . This is equivalent to calling the gather function on agpuArray.

You can now use the gather function to gather elements of aComposite array on parallel workers to the local workspace.

Previously, when you use gather on a Composite array, MATLAB returns the same Composite array as the output.