Learn more about Parallel Computing Toolbox

Accessing Data with Composites

On this page…
Introduction Creating Composites in spmd Statements Variable Persistence and Sequences of spmd Creating Composites Outside spmd Statements

Introduction

Composite objects in the MATLAB client session let you directly access data values on the labs. Most often you assigned these variables within spmd statements. In their display and usage, Composites resemble cell arrays. There are two ways to create Composites:

• Using the Composite function on the client. Values assigned to the Composite elements are stored on the labs.

• Defining variables on labs inside an spmd statement. After the spmd statement, the stored values are accessible on the client as Composites.

Back to Top

Creating Composites in spmd Statements

When you define or assign values to variables inside an spmd statement, the data values are stored on the labs.

After the spmd statement, those data values are accessible on the client as Composites. Composite objects resemble cell arrays, and behave similarly. On the client, a Composite has one element per lab. For example, suppose you open a MATLAB pool of three local workers and run an spmd statement on that pool:

matlabpool open local 3

spmd  % Uses all 3 workers
    MM = magic(labindex+2); % MM is a variable on each lab
end
MM{1} % In the client, MM is a Composite with one element per lab
     8     1     6
     3     5     7
     4     9     2

MM{2}
    16     2     3    13
     5    11    10     8
     9     7     6    12
     4    14    15     1

A variable might not be defined on every lab. For the labs on which a variable is not defined, the corresponding Composite element has no value. Trying to read that element throws an error.

spmd
    if labindex > 1
         HH = rand(4)
    end
end
HH
     1: No data
     2: class = double, size = [4  4]
     3: class = double, size = [4  4] 

You can also set values of Composite elements from the client. This causes a transfer of data, storing the value on the appropriate lab even though it is not executed within an spmd statement:

MM{3} = eye(4);

In this case, MM must already exist as a Composite, otherwise MATLAB interprets it as a cell array.

Now when you do enter an spmd statement, the value of the variable MM on lab 3 is as set:

spmd
    if labindex == 3, MM, end
end
Lab 3: 
    MM =
         1     0     0     0
         0     1     0     0
         0     0     1     0
         0     0     0     1

Data transfers from lab to client when you explicitly assign a variable in the client workspace using a Composite element:

M = MM{1} % Transfer data from lab 1 to variable M on the client

     8     1     6
     3     5     7
     4     9     2

Assigning an entire Composite to another Composite does not cause a data transfer. Instead, the client merely duplicates the Composite as a reference to the appropriate data stored on the labs:

NN = MM % Set entire Composite equal to another, without transfer

However, accessing a Composite's elements to assign values to other Composites does result in a transfer of data from the labs to the client, even if the assignment then goes to the same lab. In this case, NN must already exist as a Composite:

NN{1} = MM{1} % Transfer data to the client and then to lab

When finished, you can close the pool:

matlabpool close

Back to Top

Variable Persistence and Sequences of spmd

The values stored on the labs are retained between spmd statements. This allows you to use multiple spmd statements in sequence, and continue to use the same variables defined in previous spmd blocks.

The values are retained on the labs until the corresponding Composites are cleared on the client, or until the MATLAB pool is closed. The following example illustrates data value lifespan with spmd blocks, using a pool of four workers:

matlabpool open local 4

spmd
    AA = labindex; % Initial setting
end
AA(:)  % Composite
    [1]
    [2]
    [3]
    [4]
spmd
    AA = AA * 2; % Multiply existing value
end
AA(:)  % Composite
    [2]
    [4]
    [6]
    [8]
clear AA % Clearing in client also clears on labs

spmd; AA = AA * 2; end   % Generates error

matlabpool close

Back to Top

Creating Composites Outside spmd Statements

The Composite function creates Composite objects without using an spmd statement. This might be useful to prepopulate values of variables on labs before an spmd statement begins executing on those labs. Assume a MATLAB pool is already open:

PP = Composite()

By default, this creates a Composite with an element for each lab in the MATLAB pool. You can also create Composites on only a subset of the labs in the pool. See the Composite reference page for more details. The elements of the Composite can now be set as usual on the client, or as variables inside an spmd statement. When you set an element of a Composite, the data is immediately transferred to the appropriate lab:

for ii = 1:numel(PP)
    PP{ii} = ii; 
end

Back to Top

Using spmd Constructs

Distributing Arrays

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS