Parallel Computing Toolbox™

gather - Convert codistributed array into replicated array

Syntax

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

Description

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

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

X = gather(D, lab) converts a codistributed 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 codistributed array in the workspaces of all the labs on which it executes, not on the MATLAB client. If you want to transfer a codistributed 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 codistributed, be aware that if you use codistributed on a nonreplicated array, gather does not return the original. For example, gather(codistributed(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 = codistributed(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 = codistributed(magic(n), 'convert');
out = gather(D, 1);
if labindex == 1
    save data.mat out;
end

See Also

codistributed, pmode

for

gcat