Main Content

Run Code on Parallel Pools

What Is a Parallel Pool?

A parallel pool is a set of MATLAB® workers on a compute cluster or desktop. By default, a parallel pool starts automatically when needed by parallel language features such as parfor. You can specify the default cluster in your parallel preferences. The preferences panel displays your default cluster when you select Parallel Preferences in the Parallel menu. You can also specify the default cluster in the Parallel menu. Alternatively, you can choose cluster and pool size using parcluster and parpool respectively, on the MATLAB command line. See the image for more detail.

The workers in a parallel pool can be used interactively and communicate with each other during the lifetime of the job. You can view your parpool jobs in the Job Monitor. While these pool workers are reserved for your interactive use, they are not available to other users. You can have only one parallel pool at a time from a MATLAB client session. In MATLAB, the current parallel pool is represented by a parallel.Pool object.

Diagram showing a client MATLAB and a parallel cluster. The cluster contains eight parallel workers and the client has started a parallel pool using three of the workers.

Automatically Start and Stop a Parallel Pool

By default, a parallel pool starts automatically when needed by certain parallel language features. Many functions can automatically start a parallel pool, including:

Your parallel preferences specify which cluster the pool runs on. To access your preferences, on the Home tab, in the Environment section, click Parallel > Parallel Preferences.

Alternative Ways to Start and Stop Pools

In your parallel preferences, you can turn off the option for the pool to open or close automatically. If you choose not to have the pool open automatically, you can control the pool with the following techniques.

Control the Parallel Pool from the MATLAB Desktop

You can use the parallel status indicator in the lower left corner of the MATLAB desktop to start a parallel pool manually.

The parallel status indicator, including a drop down menu showing options for starting a parallel pool and inspecting your parallel preferences.

In MATLAB Online, the parallel status indicator is not visible by default. You must start a parallel pool first by using parpool or any of the functions that automatically start a parallel pool.

Click the indicator icon, and select Start Parallel Pool. The pool cluster is specified by your default cluster. Your default cluster is indicated by a check mark on the Parallel > Default Cluster menu.

The menu options are different when a pool is running. You can:

  • View the number of workers and cluster name

  • Change the time until automatic shut-down

  • Shut down the parallel pool

The parallel status indicator, highlighted blue to indicate that a parallel pool is running. A tooltip shows that a parallel pool has been running for about one minute and will shut down if still idle in 29 minutes.

To stop a pool, you can also select Shut Down Parallel Pool.

The parallel status indicator, highlighted blue to indicate that a parallel pool is running and including a menu showing options for shutting down the parallel pool and inspecting your parallel preferences.

Programming Interface

Start a Parallel Pool.  You can start and stop a parallel pool programmatically by using default settings or specifying alternatives.

To open a parallel pool based on your default settings:

parpool

To open a pool of a specific size:

parpool(4)

To use a cluster other than your default and specify where the pool runs:

parpool('MyCluster',4)

You can run a parallel pool on different parallel environments. For more information, see Choose Between Thread-Based and Process-Based Environments.

Shut Down a Parallel Pool.  To get the current parallel pool and use that object when you want to shut down the pool:

p = gcp;
delete(p)

Ensure That No Parallel Pool Is Running.  When you issue the command gcp without arguments, you might inadvertently open a pool. To avoid this problem:

delete(gcp('nocreate'))

Note

To stop a parallel pool while it is starting, press Ctrl+C or Ctrl+Break. On Apple macOS, you also can use Command. (the Command key and the period key).

Pool Size and Cluster Selection

There are several places to specify pool size. Several factors might limit the size of a pool. The actual size of your parallel pool is determined by the combination of the following:

  1. Licensing or cluster size

    The maximum limit on the number of workers in a pool is restricted by the number of workers in your cluster. This limit might be determined by the number of MATLAB Parallel Server™ licenses available. In the case of MATLAB Job Scheduler, the limit might be determined by the number of workers running in the cluster. A local cluster running on the client machine requires no licensing beyond the one for Parallel Computing Toolbox™. The limit on the number of workers is high enough to support the range of known desktop hardware.

  2. Cluster profile number of workers (NumWorkers)

    A cluster object can set a hard limit on the number of workers, which you specify in the cluster profile. Even if you request more workers at the command line or in the PreferredPoolNumWorkers property of your cluster profile, you cannot exceed the limit set in the applicable profile. Attempting to exceed this number generates an error.

  3. Command-line argument

    If you specify a pool size at the command line, you override the value set in the PreferredPoolNumWorkers property of your cluster profile. The pool size requested at the command line must fall within the limits of the applicable cluster profile.

  4. Cluster profile preferred number of workers (PreferredPoolNumWorkers) (since R2023a)

    If you do not specify a pool size at the command line, MATLAB attempts to start a pool with the size determined by the PreferredPoolNumWorkers cluster object property of the cluster profile. This value is a preference, not a requirement or a request for a specific number of workers. Therefore if a pool cannot start with as many workers as specified in the PreferredPoolNumWorkers property, you get a smaller pool without any errors. The default values for the PreferredPoolNumWorkers property is dependent on cluster type.

    Cluster TypePreferredPoolNumWorkers Default

    MATLAB Job Scheduler

    Shared cloud

    Third-party schedulers

    32

    local Processes (since R2023b)

    Personal cloud

    Inf

    Note

    In R2023a: For local profiles, the default pool size is determined by the NumWorkers property value.

    You can set the value of the PreferredPoolNumWorkers property to a number larger than the value of the NumWorkers property, so that it never limits the size of the pool that is created. If you need an exact number of workers, specify the number at the command line.

For selection of the cluster on which the pool runs, precedence is determined by the following.

  1. The command-line cluster object argument overrides the default profile setting and uses the cluster identified by the profile 'MyProfile'.

    c = parcluster('MyProfile');
    p = parpool(c);
  2. The cluster is specified in the default profile.

    p = parpool;

See Also

| | | | | | |

Related Examples

More About