Learn more about Parallel Computing Toolbox

Programming with User Configurations

On this page…
Defining Configurations Exporting and Importing Configurations Validating Configurations Applying Configurations in Client Code

Defining Configurations

Configurations allow you to define certain parameters and properties, then have your settings applied when creating objects in the MATLAB client. The functions that support the use of configurations are

• batch (also supports default configuration)

• createJob (also supports default configuration)

• createMatlabPoolJob (also supports default configuration)

• createParallelJob (also supports default configuration)

• createTask

• dfeval

• dfevalasync

• findResource

• matlabpool (also supports default configuration)

• pmode (also supports default configuration)

• set

You create and modify configurations through the Configurations Manager. You access the Configurations Manager using the Parallel pull-down menu on the MATLAB desktop. Select Parallel > Manage Configurations to open the Configurations Manger.

The first time you open the Configurations Manager, it lists only one configuration called local, which at first is the default configuration and has only default settings.

The following example provides instructions on how to create and modify configurations using the Configurations Manager and its menus and dialog boxes.

Example — Creating and Modifying User Configurations

Suppose you want to create a configuration to set several properties for some jobs being run by a job manager.

1. In the Configurations Manager, select New > jobmanager. This specifies that you want a new configuration whose type of scheduler is a job manager.

   

   This opens a new Job Manager Configuration Properties dialog box.

2. Enter a configuration name MyJMconfig1 and a description as shown in the following figure. In the Scheduler tab, enter the host name for the machine on which the job manager is running and the name of the job manager. If you are entering information for an actual job manager already running on your network, enter the appropriate text. If you are unsure about job manager names and locations on your network, ask your system administrator for help.

   

3. In the Jobs tab, enter 4 and 4 for the maximum and minimum number of workers. This specifies that for jobs using this configuration, they require at least four workers and use no more than four workers. Therefore, the job runs on exactly four workers, even if it has to wait until four workers are available before starting.

   

4. Click OK to save the configuration and close the dialog box. Your new configuration now appears in the Configurations Manager listing.

5. To create a similar configuration with just a few differences, you can duplicate an existing configuration and modify only the parts you need to change:

   1. In the Configurations Manager, right-click the configuration MyJMconfig1 in the list and select Duplicate.

      

      The duplicate configuration is created with a default name using the original name along with the extension .copy1.

   2. Double-click the new configuration to open its properties dialog.

   3. Change the name of the new configuration to MyJMconfig2.

   4. Edit the description field to change its text to My job manager and any workers.

6. Select the Jobs tab. Remove the 4 from each of the fields for minimum and maximum workers.

   

7. Click OK to save the configuration and close the properties dialog.

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

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

Back to Top

Exporting and Importing Configurations

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

To export a parallel configuration:

1. In the Configurations Manager, select (highlight) the configuration you want to export.

2. Click File > Export. (Alternatively, you can right-click the configuration in the listing and select Export.)

3. In the Export Configuration dialog box, specify a location and name for the file. The default file name is the same as the name of the configuration it contains, with a .mat extension appended; these do not need to be the same, so you can alter the names if you want to.

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

1. In the Configuration Manager, click File > Import.

2. In the Import Configuration dialog box, browse to find the .mat file for the configuration you want to import. Select the file and click Import.

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

Exporting Configurations for MATLAB Compiler

You can use an exported configuration with MATLAB^® Compiler™ to identify cluster setup information for running compiled applications on a cluster. For example, the setmcruserdata function can use the exported configuration file name to set the value for the key ParallelConfigurationFile. For more information, see Improving Data Access Using the MCR User Data Interface in the MATLAB Compiler documentation.

Note   MATLAB Compiler does not support configurations that use the local scheduler or local workers.

Back to Top

Validating Configurations

The Configurations Manager includes a tool for validating configurations.

To validate a configuration, follow these steps:

1. Open the Configurations Manager by selecting on the desktop Parallel > Manage Configurations.

2. In the Configurations Manager, click the name of the configuration you want to test in the the list of those available. Note that you can highlight a configuration this way without changing the selected default configuration. So a configuration selected for validation does not need to be your default configuration.

3. Click Start Validation.

The Configuration Validation tool attempts four operations to validate the chosen configuration:

• Uses findResource to locate the scheduler

• Runs a distributed job using the configuration

• Runs a parallel job using the configuration

• Runs a MATLAB pool job using the configuration

While the tests are running, the Configurations Manager displays their progress as shown here.

You can adjust the timeout allowed for each stage of the testing. If your cluster does not have enough workers available to perform the validation, the test times out and returns a failure.

Note   You cannot run a configuration validation if you have a MATLAB pool open.

The configuration listing displays the overall validation result for each configuration. The following figure shows overall validation results for one configuration that passed and one that failed. The selected configuration is the one that failed.

Note   When using an mpiexec scheduler, a failure is expected for the Distributed Job stage. It is normal for the test then to proceed to the Parallel Job and Matlabpool stages.

For each stage of the validation testing, you can click Details to get more information about that stage. This information includes any error messages, debug logs, and other data that might be useful in diagnosing problems or helping to determine proper configuration or network settings.

The Configuration Validation tool keeps the test results available until the current MATLAB session closes.

Back to Top

Applying Configurations in Client Code

In the MATLAB client where you create and define your parallel computing objects, you can use configurations when creating the objects, or you can apply configurations to objects that already exist.

Selecting a Default Configuration

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

• In the MATLAB desktop, click Parallel > Select Configuration, and from there, all your configurations are available. The current default configuration appears with a dot next to it. You can select any configuration on the list as the default.

• In the Configurations Manager, the Default column indicates with a radio button which configuration is currently the default configuration. You can click any other button in this column to change the default configuration.

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

  defaultParallelConfig('MyJMconfig1')
  matlabpool open

  matlabpool open MyJMconfig1

Finding Schedulers

When executing the findResource function, you can use configurations to identify a particular scheduler and apply property values. For example,

jm = findResource('scheduler', 'Configuration', 'our_jobmanager')

This command finds the scheduler defined by the settings of the configuration named our_jobmanager and sets property values on the scheduler object based on settings in the configuration. The advantage of configurations is that you can alter your scheduler choices without changing your MATLAB application code, merely by changing the configuration settings

For a third-party scheduler such as Platform LSF, the command might look like

lsfsched = findResource('scheduler', 'Configuration', 'my_lsf_config');

Creating Jobs

Because the properties of scheduler, job, and task objects can be defined in a configuration, you do not have to define them in your application. Therefore, the code itself can accommodate any type of scheduler. For example,

job1 = createJob(sched, 'Configuration', 'MyConfig');

The configuration defined as MyConfig must define any and all properties necessary and appropriate for your scheduler and configuration, and the configuration must not include any parameters inconsistent with your setup. All changes necessary to use a different scheduler can now be made in the configuration, without any modification needed in the application.

Setting Job and Task Properties

You can set the properties of a job or task with configurations when you create the objects, or you can apply a configuration after you create the object. The following code creates and configures two jobs with the same property values.

job1 = createJob(jm, 'Configuration', 'our_jobmanager_config')
job2 = createJob(jm)
set(job2, 'Configuration', 'our_jobmanager_config')

Notice that the Configuration property of a job indicates the configuration that was applied to the job.

get(job1, 'Configuration')
    our_jobmanager_config

When you apply a configuration to an object, all the properties defined in that configuration get applied to the object, and the object's Configuration property is set to reflect the name of the configuration that you applied. If you later directly change any of the object's individual properties, the object's Configuration property is cleared.

Back to Top

Life Cycle of a Job

Programming Tips and Notes

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