Parallel Computing Toolbox™

gather - Convert distributed array into replicated array

Syntax

X = gather(D)
X = gather(D, lab)

Description

X = gather(D) is a replicated array formed from the distributed array D.

D = distributed(gather(D),'convert') returns the original distributed array D.

X = gather(D, lab) converts a distributed array D to a variant array X, such that all of the data is contained on lab lab, and X is a 0-by-0 empty double on all other labs.

Remarks

Note that gather assembles the distributed array in the workspaces of all the labs on which it executes, not on the MATLAB^® client. If you want to transfer a distributed array into the client workspace, first gather it, then move it from a lab to the client with pmode lab2client. See the pmode reference page for more details.

As the gather function requires communication between all the labs, you cannot gather data from all the labs onto a single lab by placing the function inside a conditional statement such as if labindex == 1.

As gather performs the inverse of distributed, be aware that if you use distributed on a nonreplicated array, gather does not return the original. For example, gather(distributed(rand(n,m), 'convert')) does not return the original random matrix, because rand generates a different matrix on each lab in the first place, therefore the original matrix is variant, not replicated.

Examples

Distribute a magic square across your labs, then gather the whole matrix onto every lab. This code returns M = magic(n) on all labs.

D = distributed(magic(n), 'convert')
M = gather(D)

Gather all of the data in D onto lab 1, so that it can be saved from there.

D = distributed(magic(n), 'convert');
out = gather(D, 1);
if labindex == 1
    save data.mat out;
end

See Also

distributed, pmode

for

gcat