LRC (Linguistic Research Cluster) is a name of ÚFAL's computational grid/cluster, which has (as of 2018/06) about 1728 CPU cores (65 servers + 10 submission heads), with a total 7.2 TiB of RAM. It uses (Sun/Oracle/Son of) Grid Engine software (SGE) for job scheduling etc. You can submit many computing tasks (jobs) at once, they will be placed in a queue and once a machine (slot) with the required capabilities (e.g. RAM, number of cores) is available, your job will be executed (scheduled) on this machine. This way we can maximize the usefulness of the computing resources and divide it among users in a fair way.

If you need GPU processing, see a special page about our GPU cluster called DLL (which is actually a subsystem of LRC with an independent queue gpu-ms.q).
TODO: describe alternatives, e.g.: MetaCentrum / Cesnet cluster (all MFF students can use it), Amazon EC2, Microsoft Azure (some colleagues may have sometime free vouchers).

Last update: 2017/06. All machines have Ubuntu 18.04.
Some machines are at Malá Strana (ground floor, new server room built from Lindat budget), some are at Troja (5 km north-east).
If you need to quickly distinguish which machine is located where, you can use your knowledge of Trojan war-related heroes, qhost -q, or the tables below.

Machines from old cluster (do not use!):

You can ssh to one of the sol machines and submit jobs from here. It is allowed to compute here, which is useful e.g. when you have a script which submits your jobs, but it also collects statistics from the jobs outputs (and possibly submits new jobs conditioned on the statistics). However, the sol machines are relatively slow and may be occupied by your colleagues, so for bigger (longer) tasks, always prefer submission as separate jobs.

Add the following line into your '~/.bash_profile'.

source /opt/LRC/sge_profile

Or call one of these scripts directly:

/opt/LRC/common/settings.sh (for bash) 
/opt/LRC/common/settings.csh (for tcsh/csh)

This detects if you are on one of the cluster machines (including sol) and sets env variables accordingly. It also prints a status message.
Usually, this is the first line of your '~/.bash_profile' and the second-and-last line is

[ -f ~/.bashrc ] && source ~/.bashrc

Make sure you have correctly configured locale (otherwise qrsh may not show accented letters in less and you may get errors when printing utf8 on stdout/stderr from your script in qsub). For example add the following line to your ~/.bashrc:

export LC_ALL=en_US.UTF-8

First, you need to ssh to one of the submit hosts (sol[1-10]). The full address is (for example) sol1.ufal.hide.ms.mff.cuni.cz, but you can use just ssh sol1 (“hide” means it is accessible only from the ÚFAL network, not from outside; if working from home/Eduroam, you need to login/VPN to the ÚFAL network first).
In the following tutorial, we will prepare a wrapper shell script script.sh with a toy task. In practice you can name the script whatever you want and you can execute the real task, e.g. a Python/Perl/… script. It is recommended to use the wrapper shell scripts, but with -b y (see advanced usage) you can execute a Python/Perl/… directly without any wrapper.

ssh sol1
echo 'hostname; pwd; echo The second parameter is $2' > script.sh
  # prepare a shell script describing your task
qsub -cwd -j y script.sh Hello World
  # This submits your job to the default queue, which is currently ''cpu-ms.q''.
  # Usually, there is a free slot, so the job will be scheduled within few seconds.
  # We have used two handy qsub parameters:
  #  -cwd  ... the script is executed in the current directory (the default is your home)
  #  -j y  ... stdout and stderr outputs are merged and redirected to a file (''script.sh.o$JOB_ID'')
  # We have also provided two parameters for our script "Hello" and "World".
  # The qsub prints something like
  #   Your job 121144 ("script.sh") has been submitted
qstat
  # This way we inspect all our jobs (both waiting in queue and scheduled, i.e. running).
qstat -u '*' | less
  # This shows jobs of all users.
qstat -j 121144
  # This shows detailed info about the job with this number (if it is still running).
less script.sh.o*
  # We can inspect the job's output (in our case stored in script.sh.o121144).
  # Hint: if the job is still running, press F in 'less' to simulate 'tail -f'.

The output of our job should look like:

LRC:ubuntu 14.04: 8.1.7a Son of Grid Engine variables set...
lucifer5
/home/popel/tmp
The second parameter is World
======= EPILOG: Tue Sep 26 19:49:05 CEST 2017
== Limits:   
== Usage:    cpu=00:00:00, mem=0.00000 GB s, io=0.00000 GB, vmem=N/A, maxvmem=N/A
== Duration: 00:00:02 (2 s)

Our admins configured the SGE to print some extra info on stderr: the first line and then the epilog.
The mem=XY GB s means gigabytes of RAM used times the duration of the job in seconds, so don't be afraid XY is usually a very high number (unlike in this toy example).
The maxvmem means the peak virtual memory consumption (which is useful for setting h_vmem, see below).

qdel 121144
  # This way you can delete ("kill") a job with a given number, or comma-or-space separated list of job numbers.
qdel \*
  # This way you can delete all your jobs. Don't be afraid - you cannot delete others jobs.

The purpose of these rules is to prevent your jobs to damage the work of your colleagues and to divide the resources among users in a fair way.

• Read about our network first (so you know that e.g. reading big data from your home in 200 parallel jobs is not a good idea, but regular cleanup of your data is a good idea). Ask your colleagues (possibly via devel) if you are not sure, esp. if you plan to submit jobs with unusual/extreme disk/mem/CPU requirements.
• While your jobs are running (or queued), check your jobs (esp. previously untested setups) and your email (esp. devel) regularly. If you really need to leave e.g. for two-week vacation offline, consult it first with it@ufal (whether they can kill your jobs if needed).
• You can ssh to any cluster machine, which can be useful e.g. to diagnose what's happening there (using htop etc.).
• However, never execute any computing manually on a cluster machine where you are sshed (i.e. not via qsub or qrsh). If you break this rule, your task will take CPU and memory, but the SGE will not know, so it may schedule other users' jobs on the same machine and their jobs may fail or run slowly. The sol machines are an exception from this rule.
• For interactive work, you can use qrsh, but please try to end the job (exit with Ctrl+D) once finished with your work, especially if you ask for a lot of memory or CPUs (see below). One semi-permanent qrsh job (with non-extreme CPU/mem requirements) per user is acceptable.
• Specify the memory and CPU requirements (if higher than the defaults) and don't exceed them.
  • If your job needs more than one CPU (on a single machine) for most of the time, reserve the given number of CPU cores (and SGE slots) with

    qsub -pe smp <number-of-CPU-cores>

    As you can see in List of Machines, the maximum is 32 cores. If your job needs e.g. up to 110% CPU most of the time and just occasionally 200%, it is OK to reserve just one core (so you don't waste). TODO: when using -pe smp -l mf=8G,amf=8G,h_vmem=12G, which memory limits are per machine and which are per core?

  • If you are sure your job needs less than 1GB RAM, then you can skip this. Otherwise, if you need e.g. 8 GiB, you must always use qsub (or qrsh) with -l mem_free=8G. You should specify also act_mem_free with the same value and h_vmem with possibly a slightly bigger value. See memory for details. TL;DR:

    qsub -l mem_free=8G,act_mem_free=8G,h_vmem=12G

• Be kind to your colleagues. If you are going to submit jobs that effectively occupy more than one fifth of our cluster for more than several hours, check if the cluster is free (with qstat -g c or qstat -u \*) and/or ask your colleagues if they don't plan to use the cluster intensively in the near future. Note that if you allocate one slot (CPU core) on a machine, but (almost) all its RAM, you have effectively occupied the whole machine and all its cores. If you are submitting more than 100 jobs, consider using setting them a low priority (e.g. -p -1024, see below) or use qunhold or (even better) array jobs.
• Don't submit more than ca 5000 jobs at once, even if you make sure that at most 100 are running/waiting and the rest is in the hold state (e.g. using qunhold). More than 5000 jobs in the queue can overload the SGE, so then no one can execute qstat (or it takes too long).

• There are three commonly used options for specifying memory requirements: mem_free, act_mem_free and h_vmem. Each has a different purpose.
• mem_free=1G means 1024×1024×1024 bytes, i.e. one GiB (gibibyte). mem_free=1g means 1000×1000×1000 bytes, i.e. one gigabyte. Similarly for the other options and other prefixes (k, K, m, M).
• mem_free (or mf) specifies a consumable resource tracked by SGE and it affects job scheduling. Each machine has an initial value assigned (slightly lower than the real total physical RAM capacity). When you specify qsub -l mem_free=4G, SGE finds a machine with mem_free >= 4GB, and subtracts 4GB from it. This limit is not enforced, so if a job exceeds this limit, it is not automatically killed and thus the SGE value of mem_free may not represent the real free memory. The default value is 1G. By not using this option and eating more than 1 GiB, you are breaking the rules.
• act_mem_free (or amf) is a ÚFAL-specific option, which specifies the real amount of free memory (at the time of scheduling). You can specify it when submitting a job and it will be scheduled to a machine with at least this amount of memory free. In an ideal world, where no jobs are exceeding their mem_free requirements, we would not need this options. However, in real world it is recommended to use this option with the same value as mem_free to protect your job from failing with out-of-memory error (because of naughty jobs of other users).
• h_vmem is equivalent to setting ulimit -v, i.e. it is a hard limit on the size of virtual memory (see RLIMIT_AS in man setrlimit). If your job exceeds this limit, memory allocation fails (i.e., malloc or mmap will return NULL), and your job will probably crash on SIGSEGV. TODO: according to man queue_conf, the job is killed with SIGKILL, not with SIGSEGV. Note that h_vmem specifies the maximal size of allocated_memory, not used_memory, in other words it is the VIRT column in top, not the RES column. SGE does not use this parameter in any other way. Notably, job scheduling is not affected by this parameter and therefore there is no guarantee that there will be this amount of memory on the chosen machine. The problem is that some programs (e.g. Java with the default setting) allocate much more (virtual) memory than they actually use in the end. If we want to be ultra conservative, we should set h_vmem to the same value as mem_free. If we want to be only moderately conservative, we should specify something like h_vmem=1.5*mem_free, because some jobs will not use the whole mem_free requested, but still our job will be killed if it allocated much more than declared. The default effectively means that your job has no limits.
• It is recommended to profile your task first (see profiling below), so you can estimate reasonable memory requirements before submitting many jobs with the same task (varying in parameters which do not affect memory consumption). So for the first time, declare mem_free with much more memory than expected and ssh to a given machine and check htop (sum all processes of your job) or (if the job is done quickly) check the epilog. When running other jobs of this type, set mem_free (and act_mem_free and h_vmem) so you are not wasting resources, but still have some reserve.
• s_vmem is similar to h_vmem, but instead of SIGSEGV/SIGKILL, the job is sent a SIGXCPU signal which can be caught by the job and exit gracefully before it is killed. So if you need it, set s_vmem to a lower value than h_vmem and implement SIGXCPU handling and cleanup.

qsub -q troja-all.q
This way your job is submitted to the Troja queue. The default is ms-all.q. You can also use e.g.
-q '(troja*|ms*)' to submit on any machine in those two queues (but don't use -q '*' as this includes also gpu.q),
-q '*@hector[14]' to submit on hector1 or hector4,
-q '[tm]*@!(hector*|iridium)' to submit on any troja/ms machine except hectors and iridium.
However, usually you should specify just the queue (troja-all.q vs. ms-all.q), not a particular machine, and instead use -l to specify the needed resources in a general way.

qsub -l …
See man complex (run it on lrc or sol machines) for a list of possible resources you may require (in addition to mem_free etc. discussed above).

qsub -p -99
Define a priority of your job as a number between -1024 and 0. Only SGE admins may use a number higher than 0. In January 2018, we changed the default to -100 (it used to be 0). SGE uses the priority to decide when to start which pending job in the queue (it computes a real number called prior, which is reported in qstat, which grows as the job is waiting in the queue). Note that once a job is started, you cannot “unschedule” it, so from that moment on, it is irrelevant what was its priority. You can ask for a higher priority (-99…0) if your job is urgent and/or will finish soon and you want to skip your colleagues' jobs in the queue. You should ask for lower priority (-1024..-101) if you submit many jobs at once or if the jobs are not urgent.

qsub -o LOG.stdout -e LOG.stderr
redirect std{out,err} to separate files with given names, instead of the defaults $JOB_NAME.o$JOB_ID and $JOB_NAME.e$JOB_ID.

qsub -@ optionfile
Instead of specifying all the qsub options on the command line, you can store them in a file (you can use # comments in the file). See also In-script options.

qsub -a 12312359
Execute your job no sooner than at the given time (in [YY]MMDDhhmm format). An alternative to sleep 3600 && qsub … &.

qsub -b y
Treat script.sh (or whatever is the name of the command you execute) as a binary, i.e. don't search for in-script options within the file, don't transfer it to the qmaster and then to the execution node. This makes the execution a bit faster and it may prevent some rare but hard-to-detect errors caused SGE interpreting the script. The script must be available on the execution node via NFS, Lustre (which is our case), etc. With -b y (shortcut for -b yes), script.sh can be a script or a binary. With -b n (which is the default for qsub), script.sh must be a script (text file).

qsub -M popel@ufal.mff.cuni.cz,rosa@ufal.mff.cuni.cz -m beas
Specify the emails where you want to be notified when the job has been b started, e ended, a aborted or rescheduled, s suspended.
The default is now -m ea (TODO check this) and the default email address is forwarded to you (so there is no need to use -M). You can use -m n to override the defaults and send no emails.

qsub -hold_jid 121144,121145 (or qsub -hold_jid get_src.sh,get_tgt.sh)
The current job is not executed before all the specified jobs are completed.

qsub -now y
Start the job immediately or not at all, i.e. don't put it as pending to the queue. This is the default for qrsh, but you can change it with -now n (which is the default for qsub).

qsub -N my-name
By default the name of a job (which you can see e.g. in qstat) is the name of the script.sh. This way you can override it.

qsub -S /bin/bash
The hashbang (!#/bin/bash) in your script.sh is ignored, but you can change the interpreter with -S. I think /bin/bash is now (2017/09) the default (but it used to be csh).

qsub -v PATH[=value]
Export a given environment variable from the current shell to the job.

qsub -V
Export all environment variables. (This is not so needed now, when bash is the default interpreter and it seems your ~/.bashrc is always sourced.)

qsub -soft -l … -hard -l … -q …
By default, all the resource requirements (specified with -l) and queue requirements (specified with -q) are hard, i.e. your job won't be scheduled unless they can be fulfilled. You can use -soft to mark all following requirements as nice-to-have. And with -hard you can switch back to hard requirements.

qsub -sync y
This causes qsub to wait for the job to complete before exiting (with the same exit code as the job). Useful in scripts.

qalter
You can change some properties of already submitted jobs, which are still waiting in the queue (pending).

man qsub qstat qalter qhold queue_conf sge_types complex
Find out all the gory details which are missing here. You'll have to do it one day anyway:-).

If you often run (ad-hoc) bash commands via qsub, check ~bojar/tools/shell/qsubmit or ~stepanek/bin/qcmd, which allow you to enter the command on command line without creating any temp script files. The wrappers have also other features (some qsub options have changed default values). qcmd is older, but unlike qsubmit it has POD documentation, correct time computation and you don't need to quote the command.

~stepanek/bin/qunhold tries to keep the number of running SGE jobs under a given threshold: all jobs over the threshold are held. If the number of running jobs goes below the threshold (default: 100), 10 jobs (by default) are unheld. Beware: if your jobs submit new jobs, you can get far over the threshold!

Don't submit more than ca 5000 jobs with qunhold - it overloads the SGE queue and slows done e.g. qstat (and qunhold uses qstat internally).

This is useful not only when sshing to sol machines. Add the following lines to your ~/.bashrc.

function sshcwd () {
  # save the current history so that it is available
  # immediately on the remote machine
  history -a;
  # setup the working directory by setting WD, delete possible ".nfs/"
  ssh -X -Y -C -t $@ "WD='${PWD/.nfs\//}' /bin/bash --login -i";
}

# use WD to setup the working directory
if [ -n "$WD" ]; then
  echo "Autochanging dir to $WD" >&2
  cd $WD;
fi

alias sol1="sshcwd sol1.ufal.hide.ms.mff.cuni.cz"

If you don't use -b y, you can write the qsub options into script.sh instead of providing them on the command line. So your script.sh can be e.g.

#$ -l mem_free=10G,act_mem_free=10G,h_vmem=10G
#$ -pe smp 8
#$ -cwd -j y
#$ -N name-of-my-job
./what/to/run

and you execute it now simply with qsub script.sh.

You can change the defaults for any option by creating a personal configuration file ~/.sge_request. For example, you can add there a line -m n, so you will get no email notifications (unless overridden from the command line or in-script options).

If you have a set of tasks (of the same type) and want to run them on multiple machines, use qsub -t.

• -t 1-n start array job with n tasks numbered 1 … n
• environmental variable SGE_TASK_ID
• output and error files $JOB_NAME.[eo]$JOB_ID.$TASK_ID
• -t m-n[:s] start array job with tasks m, m + s, …, n
• environmental variables SGE_TASK_FIRST, SGE_TASK_LAST, SGE_TASK_STEPSIZE
• -tc j run at most j tasks simultaneously
• -hold_jid_ad comma_separated_job_list array jobs that must finish before this job starts; task i of the current job depends only on task i of the specified jobs

If you use -tc, then SGE can handle array jobs of virtually any size. It only starts as many tasks as specified in -tc at any time, and each scheduling interval (15 seconds in our current configuration) it starts new tasks if less than the specified -tc limit are running. However, note that it means the maximum throughput is 4 * tc tasks per minute, so the individual array job tasks need to run for at least tens of seconds for this to be effective.

The advantage of array jobs over qunhold is that it does not overload the SGE job queue. Also if you start an array job, the others can see that it is an array job, how many individual tasks there are and how many of them have already finished.

For deleting all your jobs use qdel \*. For deleting array jobs (see above), you can use comma-separated ranges of task ids, e.g. qdel -t 1,10,50-100.
For deleting a range of (normal) job ids, you can use bash expansion (as an alternative to seq), e.g. qdel {17979..18028}.

Ondřej Bojar suggests to add the following alias to your .bashrc (cf. sshcwd):

alias cluster='comp=$(($RANDOM /4095 +1)); ssh -o "StrictHostKeyChecking no" sol$comp'

• qstat [-u user] – print a list of running/waiting jobs of a given user
• qhost – print available/total resources
• /SGE/REPORTER/LRC-UFAL/bin/lrc_users_real_mem_usage -u user -w – current memory usage of a given user
• /SGE/REPORTER/LRC-UFAL/bin/lrc_users_limits_requested -w – required resources of all users
• /SGE/REPORTER/LRC-UFAL/bin/lrc_nodes_meminfo – memory usage of all nodes
  • mem_total:
  • mem_free: total memory minus reserved memory (using qsub -l mem_free) for each node
  • act_mem_free: really free memory
  • mem_used: really used memory
• /SGE/REPORTER/LRC-UFAL/bin/lrc_state_overview – overall summary (with per-user stats for users with running jobs)
• cat /SGE/REPORTER/LRC-UFAL/stats/userlist.weight – all users sorted according to their activity (number of submitted jobs × their average duration), updated each night
• Munin: graph of cluster usage by day and user and Munin monitoring of Apophis disk server (both accessible only from ÚFAL network)

As stated above, you should always specify the exact memory limits when running your tasks, so that you neither waste RAM nor starve others of memory by using more than you requested. However, memory requirements can be difficult to estimate in advance. That's why you should profile your tasks first.

A simple method is to run the task and observe the memory usage reported in the epilog, but SGE may not record transient allocations. As documented in man 5 accounting and observed in qconf -sconf, SGE only collects stats every accounting_flush_time. If this is not set, it defaults to flush_time, which is preset to 15 seconds. But the kernel records all info immediately without polling, and you can view these exact stats by looking into /proc/$PID/status while the task is running.

You can still miss allocations made shortly before the program exits – which often happens when trying to debug why your program gets killed by SGE after exhausting the reserved space. To record these, use /usr/bin/time -v (the actual binary, not the shell-builtin command time). Be aware that unlike the builtin, it cannot measure shell functions and behaves differently on pipelines.

Obtaining peak usage of multiprocess applications is trickier. Detached and backgrounded processes are ignored completely by time -v and you get the maximum footprint of any children, not the sum of all maximal footprints nor the largest footprint in any instant.

If you program in C and need to know the peak memory usage of your children, you can also use the wait4() syscall and calculate the stats yourself.

If your job is the only one on a given machine, you can also look how much free memory is left when running the job (e.g. with htop if you know when is the peak moment).

• There is a great course Data intensive computing, see the 2016 handouts if you missed the course. It covers the usage of Spark (MapReduce/Hadoop alternative, but better) and HDFS (Hadoop filesystem).
• This course had used a special DLRC (Demo LRC) cluster (students had to login with ssh -p 11422 ufallab.ms.mff.cuni.cz and special NPFL102-only LDAP logins) with six virtual machines on one physical. During the years when NPFL102 is not taught (e.g. 2017), the DLRC cluster has just one virtual machine.
• Note: soma hadoop basics and a lot of NoSQL technologies are covered by Big Data Management and NoSQL Databases
• You can use environment variables $JOB_ID, $JOB_NAME.
• One job can submit other jobs (but be careful with recursive:-)). A job submitted to the CPU cluster may submit GPU jobs (to the qpu.q queue).
• It is important, that the files that are sourced during a login such as .bash_profile, .profile, .bashrc, .login etc. don't produce any output when a non-interactive login is done. If they do, changes are that your job will run, but that the batch system is unable to deliver to you the standard output and error files. In that case the status of your job will be 'E' after the job is finished. Here is an example how you can test in a .bash_profile or .bashrc if this is an interactive login:

unset INTERACTIVE
/usr/bin/tty > /dev/null 2>&1
/usr/bin/test $? = 0 && INTERACTIVE=yes
...
if [ "$INTERACTIVE" ]; then
  ... commands only for truly interactive sessions ...
fi

TODO: Is this restriction still true (for our cluster)? E.g. .bash_profile with /net/projects/SGE/user/sge_profile prints info messages on stderr and it is OK.