Documentation

This example uses a local scheduler and runs the workers on your local MATLAB^® client machine. It does not require an external cluster or scheduler. The steps include the pmode prompt (P>>) for commands that you type in the Parallel Command Window.

1. Start the pmode with the pmode command.

   pmode start local 4

   This starts four local workers, creates a communicating job to run on those workers, and opens the Parallel Command Window.

   

   You can control where the command history appears. For this exercise, the position is set by clicking Window > History Position > Above Prompt, but you can set it according to your own preference.

2. To illustrate that commands at the pmode prompt are executed on all workers, ask for help on a function.

   P>> help magic

3. Set a variable at the pmode prompt. Notice that the value is set on all the workers.

   P>> x = pi

   

4. A variable does not necessarily have the same value on every worker. The labindex function returns the ID particular to each worker working on this communicating job. In this example, the variable x exists with a different value in the workspace of each worker.

   P>> x = labindex

5. Return the total number of workers working on the current communicating job with the numlabs function.

   P>> all = numlabs

6. Create a replicated array on all the workers.

   P>> segment = [1 2; 3 4; 5 6]

   

7. Assign a unique value to the array on each worker, dependent on the worker number (labindex). With a different value on each worker, this is a variant array.

   P>> segment = segment + 10*labindex

   

8. Until this point in the example, the variant arrays are independent, other than having the same name. Use the codistributed.build function to aggregate the array segments into a coherent array, distributed among the workers.

   P>> codist = codistributor1d(2, [2 2 2 2], [3 8])
   P>> whole = codistributed.build(segment, codist)

   This combines four separate 3-by-2 arrays into one 3-by-8 codistributed array. The codistributor1d object indicates that the array is distributed along its second dimension (columns), with 2 columns on each of the four workers. On each worker, segment provided the data for the local portion of the whole array.

9. Now, when you operate on the codistributed array whole, each worker handles the calculations on only its portion, or segment, of the array, not the whole array.

   P>> whole = whole + 1000

10. Although the codistributed array allows for operations on its entirety, you can use the getLocalPart function to access the portion of a codistributed array on a particular worker.

    P>> section = getLocalPart(whole)

    Thus, section is now a variant array because it is different on each worker.

    

11. If you need the entire array in one workspace, use the gather function.

    P>> combined = gather(whole)

    Notice, however, that this gathers the entire array into the workspaces of all the workers. See the gather reference page for the syntax to gather the array into the workspace of only one worker.

12. Because the workers ordinarily do not have displays, if you want to perform any graphical tasks involving your data, such as plotting, you must do this from the client workspace. Copy the array to the client workspace by typing the following commands in the MATLAB (client) Command Window.

    pmode lab2client combined 1

    Notice that combined is now a 3-by-8 array in the client workspace.

    whos combined

    To see the array, type its name.

    combined

13. Many matrix functions that might be familiar can operate on codistributed arrays. For example, the eye function creates an identity matrix. Now you can create a codistributed identity matrix with the following commands in the Parallel Command Window.

    P>> distobj = codistributor1d();
    P>> I = eye(6, distobj)
    P>> getLocalPart(I)

    Calling the codistributor1d function without arguments specifies the default distribution, which is by columns in this case, distributed as evenly as possible.

    

14. If you require distribution along a different dimension, you can use the redistribute function. In this example, the argument 1 to codistributor1d specifies distribution of the array along the first dimension (rows).

    P>> distobj = codistributor1d(1);
    P>> I = redistribute(I, distobj)
    P>> getLocalPart(I)

    

15. Exit pmode and return to the regular MATLAB desktop.

    P>> pmode exit