matlabpool - Open or close pool of MATLAB sessions for parallel computation

Syntax

Description

matlabpool enables the parallel language features in the MATLAB language (e.g., parfor) by starting a parallel job that connects this MATLAB client with a number of workers.

matlabpool or matlabpool open starts a worker pool using the default cluster profile, with the pool size specified by that profile. (For information about setting up and selecting profiles, see Cluster Profiles.) You can also specify the pool size using matlabpool open poolsize, but most clusters have a maximum number of processes that they can start (12 for a local scheduler). If the profile specifies an MJS as the cluster, matlabpool reserves its workers from among those already running and available under that MJS. If the profile specifies a third-party scheduler, matlabpool instructs the scheduler to start the workers.

Note   When you first open a MATLAB pool from your desktop session, an indicator appears in the lower-right corner of the desktop to show that this desktop session is connected to an open pool. The number indicates how many workers are in the pool.

matlabpool open profilename or matlabpool open profilename poolsize starts a worker pool using the Parallel Computing Toolbox cluster profile identified by profilename rather than the default cluster profile to locate a cluster. If the pool size is specified, it overrides the number of workers range specified in the profile, and starts a pool of exactly that number of workers, even if it has to wait for them to be available.

Without specifying open or close, the command default is open. So, matlabpool poolsize, matlabpool(poolsize), matlabpool profilename, and matlabpool profilename poolsize operate as matlabpool open ..., and are provided for convenience.

matlabpool(clusterobj) or matlabpool(clusterobj, 'open') is the same as matlabpool open, except that the worker pool is started on the cluster specified by the object clusterobj.

matlabpool(clusterobj, 'open', ...) is the same as matlabpool('open', ...) except that the worker pool is started on the cluster specified by the object clusterobj.

matlabpool(clusterobj, poolsize) is the same as matlabpool poolsize except that the worker pool is started on the cluster specified by the object clusterobj.

matlabpool close stops the worker pool, deletes the pool job, and makes all parallel language features revert to using the MATLAB client for computing their results.

matlabpool close force deletes all pool jobs created by matlabpool for the current user under the cluster specified by the default profile, including any jobs currently running.

matlabpool close force profilename deletes all pool jobs being run under the cluster specified in the profile profilename.

matlabpool size returns the size of the worker pool if it is open, or 0 if the pool is closed.

matlabpool('open', ...) and matlabpool('close', ...) can be invoked as functions with optional arguments, such as profile name and pool size. The default is 'open'. For example, the following are equivalent:

matlabpool open MyProfile 4
matlabpool('MyProfile', 4)

matlabpool('open',..., 'AttachedFiles', filecell) starts a worker pool and allows you to specify attached files so that you can pass necessary files to the workers in the pool. The cell array filecell is appended to the AttachedFiles property specified in the profile used for startup. The 'AttachedFiles' property name is case sensitive, and must appear as shown. (Note: This form of the command does not allow you to directly specify any other job property-value pairs when opening a pool.)

matlabpool('addattachedfiles', filecell) allows you to add extra attached files to an already running pool. filecell is a cell array of strings, identical in form to those you use when adding attached files to a job or when you open a MATLAB pool. Each string can specify either absolute or relative files, folders, or a file on the MATLAB path. The command transfers the files to each worker, placing the files in the attached files folder, exactly the same as if you sent them at the time the pool was opened.

matlabpool updateattachedfiles checks all the attached files of the current pool to see if they have changed, and replicates any changes to each of the workers in the pool. In this way, you can send code changes out to remote workers. This checks files that you added with the matlabpool addattachedfiles command, as well as those you specified when the pool was started (by a profile or command-line argument).

Tips

When a pool of workers is open, the following commands entered in the client's Command Window also execute on all the workers:

• cd

• addpath

• rmpath

This enables you to set the working directory and the path on all the workers, so that a subsequent parfor-loop executes in the proper context.

If any of these commands does not work on the client, it is not executed on the workers either. For example, if addpath specifies a folder that the client cannot see or access, the addpath command is not executed on the workers. However, if the working directory or path can be set on the client, but cannot be set as specified on any of the workers, you do not get an error message returned to the client Command Window.

This slight difference in behavior might be an issue in a mixed-platform environment where the client is not the same platform as the workers, where folders local to or mapped from the client are not available in the same way to the workers, or where folders are in a nonshared file system. For example, if you have a MATLAB client running on a Microsoft Windows operating system while the MATLAB workers are all running on Linux^® operating systems, the same argument to addpath cannot work on both. In this situation, you can use the function pctRunOnAll to assure that a command runs on all the workers.

Another difference between client and workers is that any addpath arguments that are part of the matlabroot folder are not set on the workers. The assumption is that the MATLAB install base is already included in the workers' paths. The rules for addpath regarding workers in the pool are:

• Subfolders of the matlabroot folder are not sent to the workers.

• Any folders that appear before the first occurrence of a matlabroot folder are added to the top of the path on the workers.

• Any folders that appear after the first occurrence of a matlabroot folder are added after the matlabroot group of folders on the workers' paths.

For example, suppose that matlabroot on the client is C:\Applications\matlab\. With an open MATLAB pool, execute the following to set the path on the client and all workers:

addpath('P1',
        'P2',
        'C:\Applications\matlab\T3',
        'C:\Applications\matlab\T4',
        'P5',
        'C:\Applications\matlab\T6',
        'P7',
        'P8');

Because T3, T4, and T6 are subfolders of matlabroot, they are not set on the workers' paths. So on the workers, the pertinent part of the path resulting from this command is:

P1
P2
<worker original matlabroot folders...>
P5
P7
P8

Examples

Start a pool using the default profile to define the number of workers:

matlabpool

Start a pool of 16 workers using a profile called myProf:

matlabpool open myProf 16

Start a pool of 2 workers using the local profile:

matlabpool local 2

Run matlabpool as a function to check whether the worker pool is currently open:

isOpen = matlabpool('size') > 0

Start a pool with the default profile, and pass two code files to the workers:

matlabpool('open', 'AttachedFiles', {'mod1.m', 'mod2.m'})

Start a MATLAB pool with the cluster and pool size determined by the default profile:

c = parcluster
matlabpool(c)

See Also

defaultParallelConfig | parfor | pctRunOnAll

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