gather

Transfer distributed array or gpuArray to local workspace

Syntax

X = gather(A)
X = gather(C,lab)


Description

X = gather(A) can operate inside an spmd statement, pmode, or communicating job to gather together the elements of a codistributed array, or outside an spmd statement to gather the elements of a distributed array. If you execute this inside an spmd statement, pmode, or communicating job, X is a replicated array with all the elements of the array on every worker. If you execute this outside an spmd statement, X is an array in the local workspace, with the elements transferred from the multiple workers.

X = gather(distributed(X)) or X = gather(codistributed(X)) returns the original array X.

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.

For a gpuArray input, X = gather(A) transfers the array elements from the GPU to the local workspace.

If the input argument to gather is not a distributed, a codistributed, or a gpuArray, the output is the same as the input.

Examples

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;
spmd
  C = codistributed(magic(n));
  M = gather(C) % Gather all elements to all workers
end
S = gather(C)   % Gather elements to client

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

n = 10;
spmd
  C = codistributed(magic(n));
  out = gather(C,1);
  if labindex == 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

Lab 1:
  areDiagonalsEqual =
    1

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

n = 10;
D = distributed(magic(n)); % Distribute array to workers
M = gather(D)              % Return array to client

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

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

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 labindex == 1.