Discover Clusters and Use Cluster Profiles

Cluster Profile Manager

Cluster profiles let you define certain properties for your cluster, then have these properties applied when you create cluster, job, and task objects in the MATLAB® client. Some of the functions that support the use of cluster profiles are

To create, edit, and import cluster profiles, you can use the Cluster Profile Manager. To open the Cluster Profile Manager, on the Home tab in the Environment section, select Parallel > Manage Cluster Profiles.

Use Parallel Menu and Cluster Profiles

Parallel Computing Toolbox™ comes pre-configured with two cluster profiles:

  • local: for running on your local desktop machine.

  • MATLAB Parallel Cloud™: for MATLAB Parallel Cloud clusters running on Amazon EC2. Updates on availability can be found here. MATLAB Parallel Cloud supports interactive parpool - based parallelism. See MATLAB Parallel Cloud.

Use the Parallel menu on the MATLAB Home tab for the following tasks:

  • Discover other clusters running on your network or on Amazon EC2 using the Parallel > Discover Clusters User Interface.

  • If you have trouble connecting to MATLAB Parallel Cloud, select Parallel > Test Cloud Connection.

  • If you want to view your license usage, select Parallel > View License Usage. Alternatively, see: https://www.mathworks.com/licensecenter to view your license usage.

  • If you want to open MathWorks Cloud Center from MATLAB in an external web browser, select Parallel > Cloud Center Web Application. For more information about Cloud Center, see: http://www.mathworks.com/help/cloudcenter/.

Discover Clusters

You can let MATLAB discover clusters for you. Use either of the following techniques to discover those clusters which are available for you to use:

  • On the Home tab in the Environment section, select Parallel > Discover Clusters

  • In the Cluster Profile Manager, select Discover Clusters

This opens the Discover Clusters dialog box, where you can search for MATLAB Distributed Computing Server™ clusters:

If you select On your network, you see a new window. Select this option if your clusters use a MATLAB job scheduler (MJS) or Microsoft Windows HPC server. As clusters are discovered, they populate a list for your selection. If you already have a profile for any of the listed clusters, those profile names are included in the list. If you want to create a new profile for one of the discovered clusters, select the name of the cluster you want to use, and select Next. The subsequent dialog box lets you choose if you want to set the new profile as your default.

If you select On Amazon EC2, you search for clusters running on Amazon EC2. To access these clusters, you must provide your MathWorks Account login information:

Requirements for Cluster Discovery

Cluster discovery is supported only for MATLAB job schedulers (MJS), Microsoft® Windows® HPC Server, and Amazon EC2 cloud clusters. The following requirements apply to these clusters.

  • MJS — MJS clusters support two different means of discovery:

    • Multicast: The discover clusters functionality uses the multicast networking protocol from the client to search for head nodes where an MJS is running. This requires that the multicast networking protocol is enabled and working on the network that connects the MJS head nodes (where the schedulers are running) and the client machines. This form of discovery might be limited to the client local subnet, and therefore not always able to discover an MJS elsewhere in your network.

    • DNS SRV: An alternative discovery technique is to search for clusters by DNS service records.

      The Domain Name System (DNS) is a standard for identifying host names with IP addresses, either on the Internet or in a private network. Using DNS allows discovery of MJS clusters by identifying specific hosts rather than broadcasting across your network.

      A DNS service (SRV) record defines the location of hosts and ports of services, such as those related to the clusters you want to discover. Your system administrator creates DNS SRV records in your organization’s DNS infrastructure. For a description of the required record, and validation information, see DNS SRV Record (MATLAB Distributed Computing Server).

  • HPC Server — The discover clusters functionality uses Active Directory Domain Services to discover head nodes. HPC Server head nodes are added to the Active Directory during installation of the HPC Server software.

  • Amazon EC2 — The discover clusters functionality requires a working network connection between the client and the Cloud Center web services running in mathworks.com.

Import and Export Cluster Profiles

Cluster profiles are stored as part of your MATLAB preferences, so they are generally available on an individual user basis. To make a cluster profile available to someone else, you can export it to a separate .settings file. In this way, a repository of profiles can be created so that all users of a computing cluster can share common profiles.

To export a cluster profile:

  1. In the Profile Clusters Manager, select (highlight) the profile you want to export.

  2. Select Export > Export. (Alternatively, you can right-click the profile in the listing and select Export.)

    If you want to export all your profiles to a single file, select Export > Export All

  3. In the Export profiles to file dialog box, specify a location and name for the file. The default file name is the same as the name of the profile it contains, with a .settings extension appended; you can alter the names if you want to.

Profiles saved in this way can then be imported by other MATLAB users:

  1. In the Cluster Profile Manager, select Import.

  2. In the Import profiles from file dialog box, browse to find the .settings file for the profile you want to import. Select the file and select Open.

    The imported profile appears in your Cluster Profile Manager list. Note that the list contains the profile name, which is not necessarily the file name. If you already have a profile with the same name as the one you are importing, the imported profile gets an extension added to its name so you can distinguish it.

You can also export and import profiles programmatically with the parallel.exportProfile and parallel.importProfile functions.

Export Profiles for MATLAB Compiler

You can use an exported profile with MATLAB Compiler™ and MATLAB Compiler SDK™ to identify cluster setup information for running compiled applications on a cluster. For example, the setmcruserdata function can use the exported profile file name to set the value for the key ParallelProfile. For more information and examples of deploying parallel applications, see Pass Parallel Computing Toolbox Profile at Run Time (MATLAB Compiler), and Use Parallel Computing Toolbox in Deployed Applications (MATLAB Compiler SDK).

A compiled application has the same default profile and the same list of alternative profiles that the compiling user had when the application was compiled. This means that in many cases the profile file is not needed, as might be the case when using the local profile for local workers. If an exported file is used, the first profile in the file becomes the default when imported. If any of the imported profiles have the same name as any of the existing profiles, they are renamed during import (though their names in the file remain unchanged).

Create and Modify Cluster Profiles

The first time you open the Cluster Profile Manager, it lists two profiles: local and MATLAB Parallel Cloud.

You can specify profile properties including:

  • NumWorkers: the number of workers to start a pool. The actual pool size might be limited by licensing, cluster size, and cluster profile settings. See Pool Size and Cluster Selection

  • NumThreads: the number of computational threads to use on each worker. You can change NumThreads, so that your workers can run in multithreaded mode and use all the cores on your cluster. This allows you to increase the number of computational threads NumThreads on each worker, without increasing the number of workers NumWorkers. If you have more cores available, increase NumThreads to take full advantage of the built-in parallelism provided by the multithreaded nature of many of the underlying MATLAB libraries. For details, see Run MATLAB on multicore and multiprocessor machines .

    Note

    Do not increase the number of threads across all workers on a machine to exceed the number of physical cores. In other words, make sure that NumWorkers x NumThreads ≤ number of physical cores on your machine. Otherwise you might have reduced performance.

  • MaxNumMachines: Maximum number of machines that MATLAB Parallel Cloud can use. When more workers are required, machines are automatically added to the cluster up to this maximum value. See MATLAB Parallel Cloud.

    To view and edit all properties of the cluster programmatically, use the parallel.cluster.Cloud object. For details, see the Cloud properties here: parallel.Cluster.

The following example provides instructions on how to create and modify profiles using the Cluster Profile Manager.

Suppose you want to create a profile to set several properties for jobs to run in an MJS cluster. The following example illustrates a possible workflow, where you create two profiles differentiated only by the number of workers they use.

  1. In the Cluster Profile Manager, select Add > Custom > MATLAB Job Scheduler (MJS). This specifies that you want a new profile for an MJS cluster.

    This creates and displays a new profile, called MJSProfile1.

  2. Double-click the new profile name in the listing, and modify the profile name to be MyMJSProfile1.

  3. Select Edit in the tool strip so that you can set your profile property values.

    In the Description field, enter the text MJS with 4 workers, as shown in the following figure. Enter the host name for the machine on which the MJS is running, and the name of the MJS. If you are entering information for an actual MJS already running on your network, enter the appropriate text. If you are unsure about the MJS (formerly known as a job manager) names and locations on your network, ask your system administrator for help.

    Note

    If the MJS is using a nondefault BASE_PORT setting as defined in the mdce_def file, the Host property in the cluster profile must be appended with this BASE_PORT number. For example, MJS-Host:40000.

  4. Scroll down to the Workers section, and for the Range of number of workers, enter the two-element vector [4 4]. This specifies that jobs using this profile require at least four workers and no more than four workers. Therefore, a job using this profile runs on exactly four workers, even if it has to wait until four workers are available before starting.

    You might want to edit other properties depending on your particular network and cluster situation.

  5. Select Done to save the profile settings.

To create a similar profile with just a few differences, you can duplicate an existing profile and modify only the parts you need to change, as follows:

  1. In the Cluster Profile Manager, right-click the profile name MyMJSProfile1 in the list and select Duplicate.

    This creates a duplicate profile with a name based on the original profile name appended with _Copy.

  2. Double-click the new profile name and edit its name to be MyMJSprofile2.

  3. Select Edit to allow you to change the profile property values.

  4. Edit the description field to change its text to MJS with any workers.

  5. Scroll down to the Workers section, and for the Range of number of workers, clear the [4 4] and leave the field blank, as highlighted in the following figure:

  6. Select Done to save the profile settings and to close the properties editor.

You now have two profiles that differ only in the number of workers required for running a job.

When creating a job, you can apply either profile to that job as a way of specifying how many workers it should run on.

You can see examples of profiles for different kinds of supported schedulers in the MATLAB Distributed Computing Server installation instructions at Configure Your Cluster (MATLAB Distributed Computing Server).

Validate Cluster Profiles

The Cluster Profile Manager includes the ability to validate profiles. Validation assures that the MATLAB client session can access the cluster, and that the cluster can run the various types of jobs with the settings of your profile.

You can choose to run a subset of the validation stages and specify the number of workers to use when validating your profile. In some cases, you may find it more appropriate or faster to do so.

To validate a profile, follow these steps:

  1. Open the Cluster Profile Manager on the Home tab in the Environment section, by selecting Parallel > Manage Cluster Profiles.

  2. In the Cluster Profile Manager, select the name of the profile you want to test. You can highlight a profile without changing the selected default profile. So a profile selected for validation does not need to be your default profile.

  3. Select the validation stages you want to run.

  4. Select the Number of workers using the spinning wheel.

  5. Select Validate.

If you have selected all stages, profile validation includes five steps:

  1. Connects to the cluster (parcluster)

  2. Runs an independent job (createJob) on the cluster using the profile

  3. Runs an SPMD-type communicating job on the cluster using the profile

  4. Runs a pool-type communicating job on the cluster using the profile

  5. Runs a parallel pool job on the cluster using the profile

While the tests are running, the Cluster Profile Manager displays progress as shown here:

You can see details of the different stages by selecting the corresponding row in the pane under Number of workers to use.

Note

Validation will fail if you already have a parallel pool open.

When the tests are complete, you can select Show Report to get more information about test results. This information includes any error messages, debug logs, and other data that might be useful in diagnosing problems or helping to determine proper network settings.

The Validation Results tab keeps the test results available until the current MATLAB session closes.

Apply Cluster Profiles in Client Code

In the MATLAB client where you create and define your parallel computing cluster, job, and task objects, you can use cluster profiles when creating these objects.

Select a Default Cluster Profile

Some functions support default profiles, so that if you do not specify a profile for them, they automatically apply the default. There are several ways to specify which of your profiles should be used as the default profile:

  • On the Home tab in the Environment section, select Parallel > Default Cluster, and from there, all your profiles are available. The default profile is indicated. You can select any profile in the list as the default.

  • The Cluster Profile Manager indicates which is the default profile. You can select any profile in the list, then select Set as Default.

  • You can get or set the default profile programmatically by using the parallel.defaultClusterProfile function. The following sets of commands achieve the same thing:

    parallel.defaultClusterProfile('MyMJSProfile1')
parpool

    or

    parpool('MyMJSProfile1')

Create Cluster Object

The parcluster function creates a cluster object in your workspace according to the specified profile. The profile identifies a particular cluster and applies property values. For example,

c = parcluster('MyMJSProfile1')

This command finds the cluster defined by the settings of the profile named MyMJSProfile1 and sets property values on the cluster object based on settings in the profile. By applying different profiles, you can alter your cluster choices without changing your MATLAB application code.

Create Jobs and Tasks

Because the properties of cluster, job, and task objects can be defined in a profile, you do not have to explicitly define them in your application. Therefore, your code can accommodate any type of cluster without being modified. For example, the following code uses one profile to set properties on cluster, job, and task objects:

c = parcluster('MyMJSProfile1');
job1 = createJob(c); % Uses profile of cluster object c.
createTask(job1,@rand,1,{3}) % Uses profile of cluster object c.

See Also

| | | | | |

Related Examples

More About

External Websites

Was this topic helpful?
Parallel Computing Toolbox Documentation
Other Documentation
Support