Syntax

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

See Also

arrayfun | bsxfun | codistributed | distributed | gpuArray | pagefun | pmode