28-Aug-2008

Introduction

The following are instructions on how to run Matlab on the Cray XD1 (Ada). Matlab uses PBS to schedule jobs using its own job manager and the Distributed Computing Engine toolbox. You do not need to write your own PBS batch scripts to run Matlab jobs. Matlab will submit jobs directly to PBS for you. At the present time Matlab only supports the submission of distributed jobs. Parallel job support is not available.

NOTE: While it is possible to submit Matlab jobs directly in your own PBS script, these jobs will not take advantage of the Distributed Computing Engine toolbox which might result in your job failing due to various toolbox license errors. Submitting your jobs as described below will avoid toolbox license problems.

Running Matlab

Instructions for running Matlab with the GUI are presented below:

1.  Login to Ada using SSH

2.  Configure your Ada environment to run Matlab

After you have logged into Ada, use the module command to configure your Ada environment to run Matlab.

adauser@adahost:~>  module load matlab/2007a 

The module command will establish all of the environment variables needed to run the Matlab program.

3.  Launch Matlab

Start the matlab program either with the GUI or without at the command prompt:

matlab -nosplash (with the GUI)
-or-
matlab -nodisplay (without the GUI)

At this point Matlab will be running interactively on one of the login nodes, not one of the compute nodes. When you get the matlab prompt, start writing your code as your normally would. When you submit a Matlab compute job (see below), the Matlab job manager will allocate a set of compute nodes for your task. You do not need to use a PBS batch script to request the nodes. Matlab's job manager will utilize PBS for you in order to allocate nodes.

Submitting a Matlab Job

The following is a sample Matlab program submitted as a distributed job:

1. Create a scheduler object and set the SubmitFcn property:

   sched = findResource('scheduler', 'type', 'generic')
   set(sched, 'SubmitFcn', @submitFcn)
   
   
   
2. Check the scheduler (optional):
   
   get(sched)
   
   This command will show you the scheduler properties, such as the current value of the DataLocation property. You can run this command at any time.
   
   
3. Create a job handle and optionally check it:
   
   myjob = createJob(sched)
   
   

   Job Id 1 Information
   ====================
   
        UserName : adauser 
        State : pending
        SubmitTime : 
        StartTime : 
        Running Duration : 

   - Data Dependencies

        FileDependencies : {}
        PathDependencies : {}

   - Associated Task(s)

        Number Pending  : 0
        Number Running  : 0
        Number Finished : 0
        TaskID of errors : 

   
   This command creates a job handle named myjob. The output means that the job you just created has been assigned the ID of 1. You can confirm this at any time with the following command:
   
   
   get(myjob)
   

4. Create distributed tasks.  The following are examples only:

   createTask(myjob, @rand, 1, {3,3})

   ans =

   Task ID 1 from Job ID 1 Information
   ===================================

    State : pending
         Function : @rand
         StartTime : 
         Running Duration : 

   - Task Result Properties

         ErrorIdentifier : 
         ErrorMessage : 

   createTask(myjob, @rand, 1, {3,3}) #output truncated
   createTask(myjob, @rand, 1, {3,3}) #output truncated
   
   The above commands create three tasks. Each task will execute the @rand function and will have one output value and two input values (the values 3 and 3); All three tasks will be assigned to the job named myjob and each will be assigned its own task ID . Run get(myjob) again and you will see that the task count is now 3. You can also inspect the job by clicking on the Matlab Workspace tab.
   
   Note that this is an example only. If you have written your own function in a .m file that is writing output to a file rather than returning output, you might create the task this way:
   
   set(sched,'DataLocation','/home/adauser/path_to_data')
   set(myjob,'PathDependencies',{'/home/adauser/path_to_scripts'});
   createTask(myjob, @myfunction, 0, {4})
   
   This will create a task in myjob that calls a function named @myfunction which is in a .m file. It has zero output values and a single input value (the value 4). It is necessary to set the DataLocation and PathDependencies values so that your function and any data files can be found by the job.
   

5. Submit jobs:

   submit(myjob)
   Submitting task 1
   647077.ada759-6.ada.rice.edu
   
   Submitting task 2
   647078.ada759-6.ada.rice.edu
   
   Submitting task 3
   647079.ada759-6.ada.rice.edu
   
   When you submit a job, you will receive a PBS job ID number for each task in myjob. You can now go to a terminal window on Ada and run the showq command to look for your job in the queue. It may take a few seconds after submission before you will see the job in the queue.
   

6. Wait for the job to finish execution (optional):

   waitForState(myjob);

7. Get and view the results if any are returned by the function (optional):

   results = getAllOutputArguments(myjob);
   results{1:3}
   
   This will show you the 1 return value from each of the 3 tasks submitted in step 5.

Destroying Tasks and Creating Additional Tasks

If you want to create additional tasks at this point, be sure to create a new job first. If you simply create new tasks and assign them to myjob, you will be appending the new tasks to the list of tasks in myjob. Submitting the job in this state will result in both the new and old tasks being submitted. You can simply create a new job, such as myjob2, and assign new tasks to this job, or you can use destroy(myjob) to remove myjob and its tasks from memory before repeating the steps to create a new job and its tasks using the same job handle name as before, myjob.

Job Size Limitations / Jobs Waiting in Queue

NOTE:  Ada only has 32 Matlab client licenses.  If you submit a Matlab job that contains more than 32 tasks, those tasks greater than 32 will wait in the job queue until licenses are available. This is also the case if other users have submitted jobs. Ada can only run 32 tasks using the Distributed Computing Engine as described in this document. All jobs greater than 32 will wait in the queue until a license is available regardless of whether or not there are idle processors available to run the jobs.

Setting the Job Time Limit (walltime)

Using the job submission method above will result in your job inheriting the default queue walltime value of 8 hours regardless of how long it will take for your job to run. This could result in delayed execution of your job if the queue is busy. Accurate walltime values make job scheduling more efficient. If you need to reduce this value, you need to use the PBS qalter command to change the walltime of a job after it is in the queue. Once you receive your PBS job ID number from step 5 above, go to a terminal window on Ada and run the following command:

adauser@adahost:~>  qalter -l walltime=00:30:00 <jobID>  


                    

This will set the default walltime to 30 minutes for the job specified by <jobID>. NOTE: This will not work if the job is already running. This will only work if the job is waiting to run. After the walltime has been changed run qstat -a <jobID> to verify that it has been set to the correct value.

Getting More Help (Online Help and User's Guide)

To get more help with Matlab, use the Matlab User's Guide. It can be accessed by launching Matlab with a GUI as described above and then accessing the Help menu. This menu will provide a full set of Matlab documentation. Help can also be obtained on the Mathworks web site.

While using Matlab, press F1 to view the Matlab help screen and click on the Distributed Computing Toolbox for more information on the commands presented in this FAQ.