Access to the cluster is restricted. By default, new user accounts do not have access. If you cannot login, contact to request access.
If you need help with launchpad usage, read all of the documentation below, especially the section on troubleshooting. If you still require assistance, send email to . You must be subscribed to the batch-users mailing list in order to post to it.
The Martinos Center High-Performance Compute Cluster is called launchpad. It consists of 127 nodes (GPU and nonGPU). Each node has 8 processors (CPUs) and 56GB of shared virtual memory. By default, when a job is submitted to the cluster, it is allotted 1 CPU and 7GB of vmem. Eight jobs can normally run on each node at once, and a maximum of 1,016 on the cluster at a time. Read through the tutorial, Troubleshooting, the FAQ and advanced info sections. If you still have a question (request access, usage, etc.), send a message to clusteradm [at] nmr.mgh.harvard.edu. To ask advice from other users or have a question that others might be interested in as well, post it to the mailing list batch-users [at] nmr.mgh.harvard.edu.
Quick Start Guide
This tutorial is a guide to help users use the launchpad cluster with a step-by-step example using actual data. This example shows a standard FreeSurfer reconstruction on the sample subject, bert.
Log in to launchpad
Source the current FreeSurfer stable environment and set the SUBJECTS_DIR environmental variable, the same as you normally would if you were to run it locally.
$ source /usr/local/freesurfer/nmr-stable51-env
$ setenv SUBJECTS_DIR /autofs/cluster/freesurfer/subjects/
$ cd $SUBJECTS_DIR
Change the SUBJECTS_DIR path in the example to the path where your actual data is.
In order to run your command, it must be submitted to the scheduler on the batch cluster and queued for execution. The wrapper script, pbsubmit, will do this for you. Here is an example command.
$ pbsubmit -m mehlsa -c "recon-all -subjid bert -all"
> Opening pbsjob_2
> qsub -V -S /bin/sh -m abe -M mehlsa -l nodes=1:ppn=1,vmem=7gb -r n /pbs/mehlsa/pbsjob_2
This will submit your command [recon-all] to the batch cluster and send an email to user 'mehlsa' when the job begins execution and when it is completed. Change the user 'mehlsa' in this example, and all subsequent examples, to your username.
As seen in the output above:
- pbsjob_2 is the Job Name
- qsub [...] is the actual command used to send the job to the cluster
- 3440112.launchpad.nmr.mgh.harvard.edu is the Job ID
The job has been sent to the scheduler. If there are any nodes available, the job will begin execution, and you should get an email to inform you. If there are no nodes available, your job will be queued for execution and wait till a node becomes available.
To check on the status of your job:
$ qstat | grep mehlsa
> 3440112.launchpad pbsjob_2 mehlsa 00:03:05 R default
This display shows all your jobs on the cluster. The columns specifiy:
- Job ID
- Job Name
- CPU Time
- Status: (R)unning, (Q)ueued, or (H)eld
- Queue - Read this question to specify other priorities
When the job is done, you will get another email to confirm that the job has completed execution. Make sure that the job completed as expected and with an exit status of 0. To do this, either look in the 'status' file, or run jobinfo:
$ cat /pbs/mehlsa/pbsjob_2.status
> running Mon May 14 16:23:22 EDT 2012
> done Tue May 15 10:36:25 EDT 2012 status 0
The job completed on Tuesday May 15 2012 at 10:36am with an exit status of 0. That means the job ran, and completed properly.
Or you can check on the exit status by running jobinfo:
$ jobinfo 3440112
> JOB INFO FOR 3440112:
> Queued on 05/14/2012 16:23:21
> Started on 05/14/2012 16:23:22
> Ended on 05/15/2012 10:36:25
> Run on host compute-0-62
> User is mehlsa
> Cputime: 17:27:07
> Walltime: 18:12:56
> Resident Memory: 1515836kb
> Virtual Memory: 2429044kb
> Exit status: 0
There are several advantages with this method. The first, is the amount of virtual memory required during execution is listed. If you need to explicitly specify the amount of vmem, please read these questions concerning memory usage in the FAQ section. The second is the comparison between Cputime and Walltime. This will help to determine whether a job is bogged down by I/O or multithreading. Please read these questions concerning this topic in the FAQ section.
If your job exited with a non-zero exit status, then something went wrong. See the Troubleshooting and FAQ sections below for help.
Use the 'jobinfo' command shown above. If your job finished with a non-zero exit status, check the log files. After termination of a job, the standard output and standard error from the job are sent to log files in your pbs directory. Read through those files, and search for any helpful exit messages.
$ less /pbs/mehlsa/pbsjob_2.o3440112
$ less /pbs/mehlsa/pbsjob_2.e3440112
If you are having trouble diagnosing the problem, trying running the command locally. Additionally, you can ssh into 'oct' to test-run a command or compile software before using launchpad. The problem may not be related to launchpad.
If this section does not address or solve your problems, read the "FAQ" section below.
How many jobs can I submit at once? and how?
Good question. We generally recommend running a maximum of 100 standard jobs at once (1 CPU and 7GB, which is the default amount of resources allocated). If you require more cores or virtual memory than the default, you can only run 100 jobs worth of computational resources. Read this question for a more detailed explanation. During busy times, consider running only 50 jobs at once.
If you plan to submit dozens or hundreds of jobs that run a command you've never used before, only run a couple at once and wait for them to finish to get a good idea of the computation resources required. Use the 'jobinfo' command to inspect the memory required, and the I/O performed.
If you've run a couple test-cases and are ready to submit hundreds of jobs, use one of the max queues: max10, max20, max50, max75, max100 (See here for usage). These allow for self-imposed limits on the number of jobs running at once.
Lastly, if you plan to run more than 10 jobs that each request more than 2 CPUs and/or 14GB of vmem, please contact us at clusteradm [at] nmr.mgh.harvard.edu to discuss proper cluster-sharing etiquette.
Why is my job automically cancelled after running for 96 hours?
We restrict jobs to run for 96 hours. After that, they are automatically deleted. If you submitted a job and are worried that it will not complete before the time limit, email clusteradm [at] nmr.mgh.harvard.edu. We can extend the job for you. If you know, before you submit the job, that you will need more time use the 'extended' queue.
$ pbsubmit -q extended ....
$ qsub -q extended ...
This queue imposes a time limit of 192 hours.
I just submitted my job but it is not running, it is in a queued state. Why?
If the cluster is filled up with other jobs and there are no available resources (CPUs or Mem) to execute your job, it will be queued. As soon as another job finishes, opening up a slot, the scheduler will automatically begin execution on the next job in the queue, according to priority.
Someone just submittted 1,000 jobs and the cluster is now full. All I want is to run 1 job, will I have to wait for all their jobs to finish??
The user should have used one of the max queues (max100). This means their jobs can only occupy 100 CPUs at a time. After that, the rest of their jobs enter a 'blocked' state. There are three job states; Running, Idle and Blocked. If you subsequently submit a job while the cluster is full, it will enter the idle state. It is from this state which jobs are selected for execution, according to priority, when resources become available. For the max100 user, once one of their jobs complete, and they only have 99 CPUs occupied, one of their blocked jobs enters the idle state with your job. In this manner, the cluster won't be highjacked by any single user.
How can I tell if my job uses too much I/O or is multithreading?
After your job finishes, run the jobinfo command. Compare the two values for Walltime and CPUtime. Walltime measures from the beginning till the end of execution, in real world time. CPUtime is the amount of time the processor was active during the execution of the command.
If the CPUtime is larger than the Walltime, then the job used multiple processors during execution. These extra CPUs were either requested, or the program used multithreading.
If the Walltime is longer than the CPUtime, then the job was held back for some time by large I/O. I/O covers situations where the node needs to access (reading and writing) data that is not located in /cluster/ directory branch. If this is the case, limit the amount of jobs that run at one time to 20 or 30. Also space out the submissions by several seconds or minutes, so the jobs aren't all reading and/or writing at the same time. Also consider moving your data to the /cluster/ space to limit the amount of I/O. You may use /cluster/scratch/*day/ and /scratch/ on launchpad and on each node. These locations will be cleared after a file is over 21 days old. When complete you may move the data from this space back to your personal space.
To see the activity during execution, ssh directly onto the node your job is running, and run 'top'. The column CPU% will give a good idea of what the job is currently doing. Over 100% and the job is using multiple cores. Less than 100% of a CPU means that either your job, or someone else's job is clogging up the I/O bottleneck.
How can I tell if my job requires more processors or memory?
You may not know till you run it. Run the command once as a test case. When it is completed, use jobinfo to get a summary of the required resources. If it failed due to insufficient memory, increment your memory request by 7GB at a time, until it successfully executes. To track it in real time, you may ssh directly onto the node the job is running and run 'top'. There should be a column called 'VIRT'. Never ssh directly onto a node to do anything other than 'top'. More advanced users can run the command locally, or on oct, with /usr/bin/time. If you explicitly select the CPUs and vmem, only use what you need. Taking extra CPUs or vmem wastes resources and blocks other users jobs from running. Not requesting enough CPUs forces sharing on the node and makes your job, and all the other jobs on that node to run slower. Know thyself.
What if my job requires multiple processors or more memory?
By default a job is allotted 1 CPU with 7GB of virtual memory. If you are absolutely 100% positive that you need more of either or both you can request more.
$ pbsubmit -n 3 ...
$ qsub -l nodes=1:ppn=3,vmem=21gb ...
Will ask for 3 CPUs with a total of 21GB of virtual memory for your job.
Be aware that if you ask for more than 7GB of memory, you are using up a limited resource on a node. If you submit a job that asks for 1 CPU, but 8-14GB of memory, you are actually using up two-sevenths of the nodes' vmem resource. This one job actually counts as 2 jobs. Keep this in mind. If you plan more than 10 jobs that require more than 2CPUs and/or 14GB of virtual memory, please email us to discuss the proper protocol. clusteradm [at] nmr.mgh.harvard.edu
How do I select a different queue to use?
Typically, you should only submit your jobs using the default queue. However, for special circumstances there are other queues available.
- High Priority Queues - You need permission to use these queues.
- Max Queues - Use one of these if you have hundreds of jobs, they restrict the total number of your active jobs. The rest are blocked, until another one of your jobs completes. Please only have 100 jobs running at once, consider 50 during busy times.
- Matlab Queue - Use this queue to run any Matlab jobs. Since there are a finite number of Matlab licenses for the Center, this queue limits the total number of jobs to 60 and for each user to only 20 at once. Read this post on how to run a Matlab script, without running Matlab!
- Extended Queue - This queue is for any jobs that require more than 96 hours to complete. The time limit for this queue is 192 hours.
- GPU Queue - This queue is only for jobs that require GPU nodes.
For example, to use the max100 queue:
$ pbsubmit -q max100 ...
$ qsub -q max100 ...
How do I run a series of jobs together that each depend on the previous job completing?
The easiest way to do it is to write a parent script that runs a series of programs. Then submit the parent script for execution on the cluster. In C-Shell, the parent script should look like this:
!# /bin/csh -e
The '-e' flag in the script above, specifies that it should exit if any of the individual processes exit with an error (a non-zero exit status). Make the script executable and then submit it for execution.
If this is not sufficient, there are other ways to accomplish this. Slightly more complicated is passing '-W depend=afterok:JobID' in the qsub call. If you have two jobs and the second should only start after the first one has completed execution, you can follow this example:
While the first job is running, the second job remains in a 'Hold' state until the first job properly executes and completes. After that, the dependency for the second job is lifted, and is free to run.
$ pbsubmit -c "Program1"
> Opening pbsjob_5
> qsub -V -S /bin/sh -l nodes=1:ppn=1,vmem=7gb -r n /pbs/mehlsa/pbsjob_5
$ pbsubmit -o "-W depend=afterok:70593.launchpad.nmr.mgh.harvard.edu" -c "Program2"
How can I run a Matlab job?
Create your matlab script (i.e. - analyze_data.m) with the last line of the script 'exit'. Make sure it is in your current directory or your Matlab path.
$ pbsubmit -q matlab -m mehlsa -c "matlab.new -nodisplay -nodesktop -nojvm -r analyze_data"
This will run your Matlab script on the cluster using the matlab queue and mail you when the job begins and ends.
We recommend deploying your Matlab code by "compiling" it. This is more efficient for all the Matlab users at the Center. See the question below for instructions on how to do this.
My Matlab job is exiting with license failures. Why?
There are a limited amount of Matlab licenses for use throughout the Martinos Center as well as on the cluster. Because of this restriction, please exit out of any idle Matlab instances and any toolboxes to free up resources for everyone to share. To see a list of current Matlab licenses in use:
We highly recommend deploying your Matlab code into a stand-alone program. The main advantage of this method is that the program can be exported and run without even needing Matlab. This preserves the finite number of Matlab licenses to users running individual instances of Matlab. Read these step-by-step instructions, written by Jean-Phillipe Coutu. Thanks.
My job is running, but I need to cancel it. Can you help?
You can help yourself. Use the qdel command with the Job ID to cancel that specific job.
$ qdel 3440112.launchpad.nmr.mgh.harvard.edu
How do I run an interactive job?
Use qsub to specify an interactive job and allow X11 forwarding:
@launchpad] $ qsub -I -X -m b -M mehlsa
> qsub: waiting for job <JobID>.launchpad.nmr.mgh.harvard.edu to start
> qsub: job <JobID>.launchpad.nmr.mgh.harvard.edu ready
-:Run Interactive Job Here:-
@<node>] $ exit
> qsub: job <JobID>.launchpad.nmr.mgh.harvard.edu completed
If there is a waiting list on the cluster, append '-q p30' so that you will be given a high priority. Do not submit an interactive job with the default queue if there is a long waiting list. When a slot opens up, you must be able to actively attend to it. When your interactive session begins execution, you will be ssh'ed into the node. Run your interactive job directly in that window. Once the job is done, exit out of the node. Your job will still be considered "running" and thereby occupying a processor until you exit out of the node. So don't submit a job, or leave the job idle after execution, if you can't actively attend to it.
If your problem/question is not addressed in the Troubleshooting or FAQ sections, email clusteradm [at] nmr.mgh.harvard.edu. Provide as many details as possible for someone to help diagnose the problem.
Run 'pbsubmit -h' for help.
| -l resource_list ||: || passes resource list options to qsub|
| -q queue ||:|| select a priority queue|
| -o qsub_options ||:|| passes additional options to the qsub command call |
| -O file ||:|| redirect standard output to <file> |
| -E file ||:|| redirect standard error to <file> |
| -T ||:|| write the script for submission, but doesn't submit job|
Run 'man qsub' for help.
| -a datetime ||:|| specify time for submission of job. datetime in the format [[[[CC]YY]MM]DD]hhmm[.SS] |
| -e path ||:|| set path where standard error file is written |
| -h ||:|| put a hold on the job |
| -l resource_list ||:|| specify the resource requirements of the job. In the form of resource_name=value,resource_name=value,... |
| -m options ||:|| specify the condition(s) where mail is sent to the user. <options> is 'n' for none, or any combination of 'a' for when the job is aborted, 'b' when the job begins execution, and 'e' when the job terminates. |
| -M users ||:|| list of users to send the email updates. |
| -N jobname ||:|| explicitly set the Job Name. Standard output and error files are automatically assigned <jobname>.o<jobid> and <jobname>.e<jobid>. |
| -o path ||:|| set path where standard output file is written |
| -q queue ||:|| set the priority queue for the job |
| -r y/n ||:|| yes or no, whether the job is rerunable. default is y. |
| -S shell ||:|| specify the shell to interpret the script being submitted. defaults to the user's login shell. |
| -v variables ||:|| pass extra environmental variables to the job. in the form variable=value,variable=value,var... |
| -V ||:|| all environmental variables are passed to the batch job. |
| -W attribute_list ||:|| can assign different attributes to the job, including dependencies and synchronizing with other jobids, and set the group. Dependencies in the form of depend=attribute:value,attribute:value,attr.... Group in the form of group_list=value. |