MATLAB DCS

From UABgrid Documentation
(Difference between revisions)
Jump to: navigation, search
(MATLAB Submit Functions: refine text and provide additional context)
(Parallel Computing Toolbox Configuration: Clarify section.)
Line 58: Line 58:
  
 
==== Parallel Computing Toolbox Configuration ====
 
==== Parallel Computing Toolbox Configuration ====
In this section we will add the cheaha configuration to the Parallel Computing Toolbox followed by a quick validation test.
 
  
Please follow the instructions for the appropriate version of MATLAB
+
The Parallel Computing Toolbox (PCT) enables language extensions in MATLAB that support dividing your application into tasks that can be executed in parallel.  By default, all of these tasks will run on your local workstation using the pre-defined "local" PCT configuration.
  
'''Prior to continuing''', make sure that you've completed the following:
+
To run these tasks on the Cheaha compute cluster, a new configuration for the PCT must be defined.  In this section we will create the "cheaha" configuration and run a quick validation test to confirm its operation.
# Tested your connection to Cheaha
+
# Downloaded and extracted the latest MATLAB submission scripts to your MATLAB PATH
+
  
Now that the prerequisites are complete:
+
'''Prior to continuing''', make sure you:
# Download and save the [http://projects.uabgrid.uab.edu/matlab/browser/trunk/parallel-configs/cheaha.mat?format=raw Cheaha cluster configuration file], this will be imported into MATLAB further down
+
* can establish an SSH connection to Cheaha
# Start the MATLAB client on your workstation (Windows users should have a MATLAB icon on the desktop), Linux may have to use the command line. On Mac, from '''Finder''' click on the MATLAB icon located at '''/Applications/'''
+
* have followed the steps in the previous section
# Click the Parallel menu
+
# Click Manage Configurations
+
# Click File -> Import
+
# Browse to the location where you saved the '''cheaha.mat''' file select it and click Open
+
  
The Configuration Manager should now list a new entry for cheaha.
+
===== Create the "cheaha" PCT Configuration =====
[[Image:2011_config_mngr.png]]
+
# Download and save the [http://projects.uabgrid.uab.edu/matlab/browser/trunk/parallel-configs/cheaha.mat?format=raw Cheaha cluster configuration file] in a file named "cheaha.mat".
 +
# Start MATLAB on your workstation
 +
# Click the "Parallel" menu
 +
# Click "Manage Configurations"
 +
# In the "Configurations Manager" window, click "File -> Import"
 +
# Browse to the location where you saved the '''cheaha.mat''' file, select it, and click "Open"
  
* Double click on cheaha in the Configuration Manager window to open the configuration window
+
The Configuration Manager should now list a new entry named "cheaha" as shown in the following image:
** Stretch the window to the right so that you can view all of the text in the SubmitFcn field (makes it easier to modify)
+
[[Image:2011_config_mngr.png|none|x400px]]
** '''ClusterMatlabRoot''': If necessary, change the Root directory of MATLAB installation for workers to the correct version, R2011a in this example: '''/share/apps/mathworks/R2011a'''
+
** '''DataLocation'''    : Change the local directory where job data is stored to an existing directory on your workstation: '''C:\Users\YOURUSERNAME\Documents\MATLAB''' (this directory is created by default by MATLAB. Please confirm the path of the directory)
+
** '''ParallelSubmitFcn''': Change "YOURUSERID" to your Cheaha user id
+
** '''SubmitFcn'''        : Change "YOURUSERID" to your Cheaha user id
+
  
The configuration will look similar to this screen shot.
+
===== Personalize the "cheaha" PCT Configuration =====
  
[[Image:Cheaha_parallel_config.png]]
+
#Double click on cheaha in the Configuration Manager window to open the configuration editor. (Note: stretch the "Generic Scheduler Configuration Properties" window to the right so that you can view all of the text in the fields making it easier to read and edit correctly.)
 +
# Edit the following fields to use your personal data directories
 +
#* '''ClusterMatlabRoot''': Make sure that the Root directory of MATLAB installation for workers matches the exact version of MATLAB you are using on your workstation. In this example '''/share/apps/mathworks/R2011a''' matches a MATLAB R2011a workstation install.  Change the "R2011a" to match your workstation MATLAB install.
 +
#* '''DataLocation'''    : Change the directory path where job data is stored to an existing directory on your workstation. For example, on Windows  the directory '''C:\Users\<USERNAME>\Documents\MATLAB''' is created by default by MATLAB. Please confirm this directory is valid.
 +
#* '''ParallelSubmitFcn''': Change the text "YOURUSERID" to your login id on Cheaha
 +
#* '''SubmitFcn'''        : Change the text "YOURUSERID" to your login id on Cheaha
 +
# Click 'OK'to save the configuration
  
 +
The initial configuration will look similar to this screen shot.  You will need to edit the fields as describe in the preceding steps before you can use the configuration.  '''NOTE: be sure to replace the template user name settings "YOURUSERNAME" with the appropriate settings for your desktop and cluster account.'''
  
* Click 'OK'to save the configuration
+
[[Image:Cheaha_parallel_config.png|none|x650px]]
  
* Select Cheaha on the configuration manager page and click 'Start Validation'
+
===== Validate the "cheaha" PCT Configuration =====
  
* Allow validation to complete. It might take a few minutes and ask for User credentials on Cheaha. All tests other than 'Matlabpool' validate on the Cheaha and the output is as shown.
+
# Select Cheaha on the configuration manager page and click 'Start Validation'
 +
# Wait for the validation to complete. This might take a few minutes and you ask for User credentials on Cheaha. All tests other than 'Matlabpool' validate on the Cheaha and the output is as shown.
  
[[Image:Validation.png]]
+
[[Image:Validation.png|none|x400px]]
  
* MATLAB DCS is now configured for Desktop usage. A simple job to test the configuration is described in [[MatLab_DCS_Examples]].
+
===== Begin Using MATLAB DCS from your Desktop =====
 +
 
 +
The MATLAB DCS is now configured for Desktop usage. A simple job to test the configuration is described in [[MatLab_DCS_Examples]].
  
 
=== MATLAB DCS from Cheaha ===
 
=== MATLAB DCS from Cheaha ===

Revision as of 16:56, 7 September 2011

The MATLAB Distributed Computing Server (MATLAB DCS) is a parallel computing extension to MATLAB that enables processing to be spread across a large number of worker nodes, accelerating the speed at which compute intensive operations can complete.

UAB IT Research Computing maintains a 128 worker node license for the the Cheaha computing platform. In order to use DCS on Cheaha, you will need to use a MATLAB instance with the Parallel Computing Toolbox installed.

In order to leverage the MATLAB worker nodes on Cheaha the Parallel Computing Toolbox will need to be configured to submit compute tasks to Cheaha by following the steps in this document.

Please see the MATLAB application page for more information and a general overview of MATLAB and its use at UAB.

Contents

Overview

The following outline highlights the steps involved to configure your MatLab install and write programs that submit tasks to the worker nodes of the Distributed Computing Server on Cheaha:

  • Configure the Task Submit Environment (One-time Setup)
    • Install MatLab with the Parallel Computing Toolbox on your Windows / Linux / Mac workstation
    • Download and extract the MatLab task submission functions to your workstation MatLab environment
    • Define the "cheaha" parallel configuration in your workstation MatLab environment to submit tasks to Cheaha
    • Run the validation tests to ensure your "cheaha" parallel configuration works
  • Develop and Run Parallel Computing Applications
    • Write, test and debug your parallel code on your local workstation using the default "local" parallel configuration
    • Once the code is ready for production, select the "cheaha" parallel configuration to submit tasks to the Cheaha cluster. Note: your workstation MatLab application does not need to keep running after the tasks are submitted.
    • You will receive an email when the tasks you submitted are complete
    • Use your workstation MatLab application to retrieve the results
    • When you are finished with your job contexts, clean up the job related content to free disk space

Using MATLAB DCS

The MATLAB Distributed Computing Services (DCS) are accessed via the Parallel Computing Toolbox (PCT) which is installed as part of your desktop MATLAB installation. The PCT allows MATLAB running on your workstation to send MATLAB code and data (tasks) to the cluster directly from the comfort of your familiar MATLAB environment on your desktop. This makes the expanded compute power of Cheaha available to processes work loads that exceed the capabilities of your desktop computer. Once your tasks are submitted to Cheaha, your desktop MATLAB is also free to move on to other tasks or be closed completely, freeing your desktop or laptop for your other activities.

Configuring the Parallel Computing Toolbox involves three steps documented below:

  1. install MATLAB submit functions on your workstation
  2. configure the "cheaha" parallel computing target to which PCT tasks can be submitted
  3. run the validation tests to confirm a working installation.

This page documents the DCS configuration for MATLAB 2010b and later. For DCS configuration instructions on previous versions of MATLAB, please see the page MatLab DCS R2010a and Earlier

Using MATLAB DCS requires you have a cluster account on Cheaha. Please request an account by sending an email to [[1]] and include your campus affiliation and a brief statement of your research interests for using the cluster.

MATLAB DCS from Your Desktop

MATLAB Submit Functions

The MATLAB submit functions create a cluster job context for your code and are responsible for transferring your code and the data it analyzes to the cluster for processing.

These submit functions must be installed on your computer and must be accessible to MATLAB via the MATLAB PATH environment. The easiest way to accomplish this is to copy the submit functions to the default directory created for by MATLAB. These directories on the respective operating systems are listed below.

All operating systems (Windows, Linux and Mac) are supported by the same set of submit functions. The functions are written in MATLAB making them cross-platform and only dependent on the version of MATLAB in use.

  1. Download the MATLAB submit functions
  2. Unzip the files to a directory included in your MATLAB PATH setting. Recommended locations are:
    • Windows:
      My Documents\MATLAB
    • Linux:
      $HOME/Documents/MATLAB
    • Mac:
      $HOME/Documents/MATLAB

Once the submit function files have been downloaded and unzipped in the above paths, restart MATLAB to ensure they are properly loaded in your environment.

NOTE: If you choose not to use the above path recommendations, your MATLAB PATH may be viewed/altered by starting the MATLAB client on your workstation and clicking File -> Set Path and adding the path in which you unpacked the submit functions.

Parallel Computing Toolbox Configuration

The Parallel Computing Toolbox (PCT) enables language extensions in MATLAB that support dividing your application into tasks that can be executed in parallel. By default, all of these tasks will run on your local workstation using the pre-defined "local" PCT configuration.

To run these tasks on the Cheaha compute cluster, a new configuration for the PCT must be defined. In this section we will create the "cheaha" configuration and run a quick validation test to confirm its operation.

Prior to continuing, make sure you:

  • can establish an SSH connection to Cheaha
  • have followed the steps in the previous section
Create the "cheaha" PCT Configuration
  1. Download and save the Cheaha cluster configuration file in a file named "cheaha.mat".
  2. Start MATLAB on your workstation
  3. Click the "Parallel" menu
  4. Click "Manage Configurations"
  5. In the "Configurations Manager" window, click "File -> Import"
  6. Browse to the location where you saved the cheaha.mat file, select it, and click "Open"

The Configuration Manager should now list a new entry named "cheaha" as shown in the following image:

2011 config mngr.png
Personalize the "cheaha" PCT Configuration
  1. Double click on cheaha in the Configuration Manager window to open the configuration editor. (Note: stretch the "Generic Scheduler Configuration Properties" window to the right so that you can view all of the text in the fields making it easier to read and edit correctly.)
  2. Edit the following fields to use your personal data directories
    • ClusterMatlabRoot: Make sure that the Root directory of MATLAB installation for workers matches the exact version of MATLAB you are using on your workstation. In this example /share/apps/mathworks/R2011a matches a MATLAB R2011a workstation install. Change the "R2011a" to match your workstation MATLAB install.
    • DataLocation  : Change the directory path where job data is stored to an existing directory on your workstation. For example, on Windows the directory C:\Users\<USERNAME>\Documents\MATLAB is created by default by MATLAB. Please confirm this directory is valid.
    • ParallelSubmitFcn: Change the text "YOURUSERID" to your login id on Cheaha
    • SubmitFcn  : Change the text "YOURUSERID" to your login id on Cheaha
  3. Click 'OK'to save the configuration

The initial configuration will look similar to this screen shot. You will need to edit the fields as describe in the preceding steps before you can use the configuration. NOTE: be sure to replace the template user name settings "YOURUSERNAME" with the appropriate settings for your desktop and cluster account.

Cheaha parallel config.png
Validate the "cheaha" PCT Configuration
  1. Select Cheaha on the configuration manager page and click 'Start Validation'
  2. Wait for the validation to complete. This might take a few minutes and you ask for User credentials on Cheaha. All tests other than 'Matlabpool' validate on the Cheaha and the output is as shown.
Validation.png
Begin Using MATLAB DCS from your Desktop

The MATLAB DCS is now configured for Desktop usage. A simple job to test the configuration is described in MatLab_DCS_Examples.

MATLAB DCS from Cheaha

References

Parallel Computing Toolbox User's Guide - This is the official 655 page MATLAB user guide for the Parallel Computing Toolbox and is recommended reading!

MATLAB Support / Mailing List

As with any application or computer language, learning to use MATLAB to analyze data or to develop or modify MATLAB applications is an individual responsibility. There is ample application documentation available from the Mathworks website, potential outreach to colleagues who also use MATLAB, and options for consultation with Mathworks. Mathworks also host on-campus training seminars several times a year and provides many on-line learning tutorials.

Installation support for MATLAB at UAB is provided by your local IT support organization and the Docs wiki.

Mathworks Website

Your first and best option for application-specific questions on MATLAB is to refer to the on-line MATLAB documentation. The Mathworks site also provides a a support matrix and an on-line knowledge base.

UAB MATLAB Wiki

The MATLAB page on the Docs wiki is the starting point for installing MATLAB at UAB and, optionally, configuring it to use cluster computing. All users are encouraged to contribute to the MATLAB knowledge in this wiki, especially if you see areas where improvements are needed. Remember, this knowledge base is only as good as the people who contribute to it.

Contributing to the wiki is as easy as clicking the login link on the top-right of the page and signing in with your UAB BlazerID. If you are unsure about making an edit, you can make suggestions for improvement on the page's Discussion tab or discuss the proposed improvement in the MATLAB user group.

UAB MATLAB User Group

At UAB, MATLAB installation support is provided by your local IT support group. Support for application specific questions is available from peers in your research group. We realize that some people are not as familiar with MATLAB as others. For this reason, we have established a MATLAB user forum (mailing list) where users of MATLAB at UAB can help answer each others questions.

This is a network of volunteers sharing their knowledge with peers. You are encouraged to reach out to this community for questions on using MATLAB by

Archives of MATLAB user group discussions are available on-line at https://vo.uabgrid.uab.edu/sympa/arc/matlab-user. You may find your question is already answered in these archives.


UAB MATLAB announce mailing list

To receive information about UAB's MATLAB license and announcements please subscribe to the matlab-annc mailing list by

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox