Create parallel pool on cluster
parpool starts a parallel pool of workers using the default profile. With default preferences, MATLAB® starts a pool on the local machine with one worker per physical CPU core up to the limit set in the default profile. For more information on parallel preferences, see Specify Your Parallel Preferences.
In general, the pool size is specified by the
property of the default profile. For all factors that can affect your pool size, see
Pool Size and Cluster Selection.
parpool enables the full functionality of the parallel language features in MATLAB by creating a special job on a pool of workers, and connecting the MATLAB client to the parallel pool. Parallel language features include
distributed. If possible, the working folder on the workers is set to match that of the MATLAB client session.
parpool( creates and returns a pool with the specified number of workers.
poolsize can be a positive integer or a range specified as a 2-element vector of integers. If
poolsize is a range, the resulting pool has size as large as possible in the range requested.
poolsize overrides any value specified in the
PreferredPoolNumWorkers property, and starts a pool of exactly that number of workers, even if it has to wait for them to be available. Most clusters have a maximum number of workers they can start. If the profile specifies a MATLAB Job Scheduler cluster,
parpool reserves its workers from among those already running and available under that MATLAB Job Scheduler. If the profile specifies a local or third-party scheduler,
parpool instructs the scheduler to start the workers for the pool.
parpool(___, applies the specified values for certain properties when starting the pool.
Create Pool from Default Profile
Start a parallel pool using the default profile to define the number of workers. With default preferences, the default pool is on the local machine.
Create Pool on Local Machine
You can create pools on different types of parallel environments on your local machine.
Start a parallel pool of process workers.
Start a parallel pool of thread workers.
Fore more information on parallel environments, see Choose Between Thread-Based and Process-Based Environments.
Create Pool from Specified Profile
Start a parallel pool of 16 workers using a profile called
Create Pool on Specified Cluster
Create an object representing the cluster identified by the default profile, and use that cluster object to start a parallel pool. The pool size is determined by the default profile.
c = parcluster parpool(c)
Create Pool and Attach Files
Start a parallel pool with the default profile, and pass two code files to the workers.
Use Multiple GPUs in Parallel Pool
If you have access to several GPUs, you can perform your calculations on multiple GPUs in parallel using a parallel pool.
To determine the number of GPUs that are available for use in MATLAB, use the
availableGPUs = gpuDeviceCount("available")
availableGPUs = 3
Start a parallel pool with as many workers as available GPUs. For best performance, MATLAB assigns a different GPU to each worker by default.
Starting parallel pool (parpool) using the 'Processes' profile ... Connected to the parallel pool (number of workers: 3).
To identify which GPU each worker is using, call
gpuDevice inside an
spmd block. The
spmd block runs
gpuDevice on every worker.
spmd gpuDevice end
Use parallel language features, such as
parfeval, to distribute your computations to workers in the parallel pool. If you use
gpuArray enabled functions in your computations, these functions run on the GPU of the worker. For more information, see Run MATLAB Functions on a GPU. For an example, see Run MATLAB Functions on Multiple GPUs.
When you are done with your computations, shut down the parallel pool. You can use the
gcp function to obtain the current parallel pool.
If you want to use a different choice of GPUs, then you can use
gpuDevice to select a particular GPU on each worker, using the GPU device index. You can obtain the index of each GPU device in your system using the
Suppose you have three GPUs available in your system, but you want to use only two for a computation. Obtain the indices of the devices.
[availableGPUs,gpuIndx] = gpuDeviceCount("available")
availableGPUs = 3
gpuIndx = 1×3
1 2 3
Define the indices of the devices you want to use.
useGPUs = [1 3];
Start your parallel pool. Use an
spmd block and
gpuDevice to associate each worker with one of the GPUs you want to use, using the device index. The
spmdIndex function identifies the index of each worker.
Starting parallel pool (parpool) using the 'Processes' profile ... Connected to the parallel pool (number of workers: 2).
spmd gpuDevice(useGPUs(spmdIndex)); end
As a best practice, and for best performance, assign a different GPU to each worker.
When you are done with your computations, shut down the parallel pool.
Return Pool Object and Delete Pool
Create a parallel pool with the default profile, and later delete the pool.
poolobj = parpool; delete(poolobj)
Determine Size of Current Pool
Find the number of workers in the current parallel pool.
poolobj = gcp('nocreate'); % If no pool, do not create new one. if isempty(poolobj) poolsize = 0; else poolsize = poolobj.NumWorkers end
poolsize — Size of parallel pool
positive integer | 2-element vector of integers
Size of the parallel pool, specified as a positive integer or a range specified as a 2-element vector of integers. If
poolsize is a range, the resulting pool has size as large as possible in the range requested. Set the default preferred number of workers in the cluster profile.
resources — Resources to start pool on
'Processes' (default) |
'Threads' | profile name | cluster object
Resources to start the pool on, specified as
'Threads', a cluster profile name or cluster object.
'Processes'– Starts a pool of process workers on the local machine. For more information on process-based environments, see Choose Between Thread-Based and Process-Based Environments.
'Threads'– Starts a pool of thread workers on the local machine. For more information on thread-based environments, see Choose Between Thread-Based and Process-Based Environments.
Profile name – Starts a pool on the cluster specified by the profile. For more information on cluster profiles, see Discover Clusters and Use Cluster Profiles.
Cluster object – Starts a pool on the cluster specified by the cluster object. Use
parclusterto get a cluster object.
c = parcluster; parpool(c)
Specify optional pairs of arguments as
the argument name and
Value is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name in quotes.
AttachedFiles — Files to attach to pool
character vector | string scalar | string array | cell array of character vectors
Files to attach to pool, specified as a character vector, string or string array, or cell array of character vectors.
With this argument pair,
parpool starts a parallel pool and passes the identified files to the workers in the pool. The files specified here are appended to the
property specified in the applicable parallel profile to form the complete list of attached files. The
'AttachedFiles' property name is case sensitive, and must appear as shown.
AutoAddClientPath — Flag to specify if client path is added to worker path
true (default) |
Flag to specify if user-added entries on the client path are added to path of each worker at startup, specified as a logical value.
EnvironmentVariables — Environment variables copied to workers
character vector | string scalar | string array | cell array of character vectors
Names of environment variables to copy from the client session to the workers, specified as a character vector, string or string array, or cell array of character vectors. The names specified here are appended to the
'EnvironmentVariables' property specified in the applicable parallel profile to form the complete list of environment variables. Any variables listed which are not set are not copied to the workers. These environment variables are set on the workers for the duration of the parallel pool.
SpmdEnabled — Flag to specify if
spmd is supported on pool
true (default) |
Flag to specify if
spmd support is enabled on the pool, specified as a logical value. You can disable support only on a local or MATLAB Job Scheduler cluster.
parfor iterations do not involve communication between workers. Therefore, if
parfor-loop continues even if one or more workers aborts during loop execution.
IdleTimeout — Time after which the pool shuts down if idle
Time in minutes after which the pool shuts down if idle, specified as an integer greater than zero. A pool is idle if it is not running code on the workers. By default
'IdleTimeout' is the same as the value in your parallel preferences. For more information on parallel preferences, see Specify Your Parallel Preferences.
pool = parpool('IdleTimeout',120)
The pool status indicator in the lower-left corner of the desktop shows the client session connection to the pool and the pool status. Click the icon for a menu of supported pool actions.
With a pool running: With no pool running:
If you set your parallel preferences to automatically create a parallel pool when necessary, you do not need to explicitly call the
parpoolcommand. You might explicitly create a pool to control when you incur the overhead time of setting it up, so the pool is ready for subsequent parallel language constructs.
delete(poolobj)shuts down the parallel pool. Without a parallel pool,
parforrun as a single thread in the client, unless your parallel preferences are set to automatically start a parallel pool for them.
When you use the MATLAB editor to update files on the client that are attached to a parallel pool, those updates automatically propagate to the workers in the pool. (This automatic updating does not apply to Simulink® model files. To propagate updated model files to the workers, use the
If possible, the working folder on the workers is initially set to match that of the MATLAB client session. Subsequently, the following commands entered in the client Command Window also execute on all the workers in the pool:
This behavior allows you to set the working folder and the command search path on all the workers, so that subsequent pool activities such as
parfor-loops execute in the proper context.
When changing folders or adding a path with
addpathon clients with Windows® operating systems, the value sent to the workers is the UNC path for the folder if possible. For clients with Linux® operating systems, it is the absolute folder location.
If any of these commands does not work on the client, it is not executed on the workers either. For example, if
addpathspecifies a folder that the client cannot access, the
addpathcommand is not executed on the workers. However, if the working folder 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.
Be careful of this slight difference in behavior 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
addpathcannot work on both. In this situation, you can use the function
pctRunOnAllto assure that a command runs on all the workers.
Another difference between client and workers is that any
addpatharguments that are part of the
matlabrootfolder are not set on the workers. The assumption is that the MATLAB install base is already included in the workers’ paths. The rules for
addpathregarding workers in the pool are:
Subfolders of the
matlabrootfolder are not sent to the workers.
Any folders that appear before the first occurrence of a
matlabrootfolder are added to the top of the path on the workers.
Any folders that appear after the first occurrence of a
matlabrootfolder are added after the
matlabrootgroup of folders on the workers’ paths.
For example, suppose that
matlabrooton the client is
C:\Applications\matlab\. With an open parallel 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');
T6are 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
If you are using Macintosh or Linux, and see problems during large parallel pool creation, see Recommended System Limits for Macintosh and Linux.
Version HistoryIntroduced in R2013b
local profile is not recommended
Starting in R2022b, the
local profile has been renamed to
Processes. There are no plans to remove
local. To start a parallel pool of process workers on the local machine, use