Red Cloud with MATLAB/Install

From CAC Documentation wiki
Revision as of 12:03, 30 September 2015 by Ad876 (talk | contribs)
Jump to navigation Jump to search

Automated Installer Quick Start

Note: if you plan to use Red Cloud with MATLAB from muliple client machines, the installation procedure must be completed on every client machine you plan to use.


  • MATLAB version R2010b, R2011a, R2011b, R2012a, or R2013a, with Parallel Computing Toolbox (PCT)
  • An active CAC project (you must be a project member on a CAC project, and you must be enabled to use the project's subscription)

Client Install

Recommended preliminary step: change your CAC password if it was just issued to you, or if you have not changed your password recently. For established users, an alternative method is available. (You may want to review CAC's password complexity requirements first.)

  1. Start MATLAB. The install process must be run within the default startup folder (i.e. the one returned by the MATLAB command "userpath"). In the Linux commandline, you must first cd to "userpath" before starting matlab.
  2. Have you ever previously installed the client code for Red Cloud with MATLAB, or the earlier MATLAB on the TeraGrid? If so, you will need to delete the cacscheduler configuration before proceeding, regardless of whether you deleted the client code:
    • Select Parallel, then Manage Configurations (in R2012a and R2013a: Manage Cluster Profiles)
    • Highlight cacscheduler
    • Select Edit, then Delete (in R2012a and R2013a: click the Delete button)
  3. Download and run the installation script
    1. Download the Installation Script:
      >> urlwrite('https://{{SERVERNAME}}/redcloud/downloads/cac_install.m','cac_install.m')
      This will save a file called cac_install.m to your MATLAB user directory.
    2. Run the installation script
      >> cac_install()
    3. cac_install.m can be removed if you wish
  4. Restart MATLAB
    >> exit

Initial Configuration

  1. Register your CAC (or XSEDE) Certificate.
     >> cacRegisterCertificate()
    You may skip this step if both of the following are true:
    • The Red Cloud client code (this software installation) was previously installed on your machine, and
    • You have not changed your password since the last time you ran cacRegisterCertificate()
  2. Create a MATLAB config file
    >> cac_make_config('YOUR_USER_NAME'); 
    where YOUR_USER_NAME is your CAC-issued username. You may be prompted for a username and password.
  3. Make this configuration the default:
    • Drop down the Parallel menu
    • Select the cacscheduler configuration.


  1. Set up the scheduler object; you may be prompted for your certificate username/password
    >> sched = findResource('scheduler', 'configuration', 'cacscheduler')
  2. Set Job Parameters
    1. Set your wall time limit to 10 minutes
      >> ClusterInfo.setWallTime(10);
    2. Specify the quick turnaround queue
      >> ClusterInfo.setQueueName('Quick');
    3. Specify the project you are on
      >> ClusterInfo.setProjectName('YOUR_PROJECT_NAME')
      where YOUR_PROJECT_NAME is your CAC project name. It typically resembles xyz3_0001.
  3. Run the tests. Normally this takes a few minutes; it will be longer if there are not enough free cores available
    >> cac_runtests(sched,0);

Subsequent Sessions

With the Red Cloud with MATLAB client installed, keep the following in mind each time you start MATLAB

  • MATLAB should remember your choice of scheduler between sessions. However, you should always verify that the selected scheduler is the one you want.
    • Under the Parallel menu, make sure cacscheduler is chosen whenever you wish to run jobs on Red Cloud with MATLAB
    • Make sure local (or some other choice) is selected when you do not want jobs to run on Red Cloud with MATLAB (e.g. testing locally)
  • Wall time limits and choice of queue persist between sessions. Always check these values to make sure they match your current assumptions. see help ClusterInfo for how to verify the various job settings.
  • If you are using a function or script that requires access to the scheduler data itself, you will need to create a MATLAB object as shown:
    sched = findResource('scheduler', 'configuration', 'cacscheduler');
  • Run this periodically to download the newest contrib folder files:

Manual Install

These are the manual installation instructions for those who prefer to avoid using an installation script. For example, if you have a customized MATLAB environment or you are an administrator installing the software in a computer lab/shared environment, the detailed instructions give additional options on how to install the program.


  • MATLABROOT refers to the MATLAB installation directory.
    • View in MATLAB using >> matlabroot
  • MATLABSTARTUP refers to the default directory that MATLAB starts in.
    • View in MATLAB using >> userpath
  • CACSCHEDULERHOME refers to the location where you install these files.
    • Be sure to substitute your folder path for CACSCHEDULERHOME in all installation steps.


Recommended preliminary step: change your CAC password if it was just issued to you, or if you have not changed your password recently. For established users, an alternative method is available. (You may want to review CAC's password complexity requirements first.) Then:

  1. Download the zip file,
  2. Unzip in a location accessible by MATLAB; we suggest MATLABSTARTUP. This location will be known as CACSCHEDULERHOME.
    • Note: if this installation is a shared machine or lab environment, we suggest MATLABROOT\toolbox\local
  3. Start MATLAB
  4. Add the installation path
    >> addpath('CACSCHEDULERHOME');
  5. Load additional paths and attempt to create startup.m
    >> cac_addpath();
  6. Load additional files
    >> updateContrib();
  7. Create classpath.txt
    >> cacMakeClassPath();
  8. If this installation is a shared machine or lab environment
    • Copy startup.m to location accessible by all users, e.g. MATLABROOT ‘toolbox\local\startup.m’
    • Save a copy of the original classpath.txt file, then copy classpath.txt to location accessible by all users , e.g. MATLABROOT ‘toolbox\local\classpath.txt’
  9. The user(s) should then complete the Initial Configuration and Verification steps above.

Installation Notes

For releases prior to R2013a:

  • The cac_install script will attempt to create files called startup.m and classpath.txt in the default or userpath startup folder. If these files already exist, the user can choose either to replace them (by using the supplied "override" options) or modify them by hand. A copy of the existing classpath.txt file (if any) will be preserved.
  • In order to use the cacscheduler, MATLAB must always start up in the same directory where these files were created. Otherwise, the Java class path will not be set correctly.
  • If a user wants the Java path to be set correctly regardless of the startup folder, he or she should copy the new classpath.txt file into matlabroot/toolbox/local, after renaming the one already in that location.

For R2013a:

  • A file called javaclasspath.txt (rather than classpath.txt) will always be created in the prefdir directory. A copy of any existing javaclasspath.txt file will be preserved.

For a list of past and present client versions and associated release notes, please see CHANGELOG.txt in the CACSCHEDULERHOME directory.