Differences

This shows you the differences between two versions of the page.

--- grid [2017/09/27 12:01]
popel
+++ grid [2017/10/02 16:56]
popel [Advanced usage]
@@ Line 70: / Line 70: @@
   # 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*'')
+  #  -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
@@ Line 112: / Line 112: @@
 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 [[internal:linux-network|network]] first (so you know that e.g. reading big data from your home in 200 parallel jobs is not a good idea). Ask your colleagues (possibly via [[internal:mailing-lists|devel]]) if you are not sure, esp. if you plan to submit jobs with unusual/extreme disk/mem/CPU requirements.
+  * Read about our [[internal:linux-network|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 [[internal:mailing-lists|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. [[internal:mailing-lists|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.).
@@ Line 118: / Line 118: @@
   * 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 <code>qsub -pe smp <number-of-CPU-cores></code> (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).
+    * 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 <code>qsub -pe smp <number-of-CPU-cores></code> 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?
-    * <code>qsub -hard -l mem_free=8G -l act_mem_free=8G -l h_vmem=8G</code>
+    * 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: <code>qsub -l mem_free=8G,act_mem_free=8G,h_vmem=12G</code>
+  * 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]]. Don't submit more than ca 2000 jobs at once (this can overload the SGE).
-Další doporučení:
+=== Memory ===
-  * Uklízet po sobě lokální data, protože jinak si tam už nikdo nic užitečného nepustí.
-  * Vyhnout se hodně divokému paralelnímu přístupu ke sdíleným diskům. NFS server to pak nepěkně zpomalí pro všechny. Distribuujte tedy i data.
+  * There are three commonly used options for specifying memory requirements: ''mem_free, act_mem_free'' and ''h_vmem''. Each has a different purpose.
-  * Pokud chci spouštět úlohy, které poběží dlouhou dobu (hodiny, dny), nepustím je všechny najednou, aby cluster mohli využívat i ostatní.
+  * ''mem_free=1G'' means 1024×1024×1024 bytes, i.e. one [[https://en.wikipedia.org/wiki/Gibibyte|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**, 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.
 ===== Advanced usage =====
-Other useful commands:
+''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|gpu.q]]),
+''-q '*@hector[14]''' to submit on hecor1 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.
-<code>
+''qsub **-l** ...''
-qsub -o LOG.stdout -e LOG.stderr skript.sh
+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).
-  # když chcete přesměrovat výstup skriptu do určených souborů
-qsub -S /bin/bash
+''qsub **-p** -100''
-  # když chcete, aby skript běžel v bashi
+Define a priority of your job as a number between -1024 and 0. Only SGE admins may use a number higher than 0. The default is 0, i.e. the highest possible priority. 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.
-qsub -V
-  # když chcete předat proměnné prostředí
+''qsub **-o** LOG.stdout **-e** LOG.stderr''
-qdel \*
+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''.
-  # když chcete zrušit všechny své joby (rušit cizí nesmíte)
-</code>
+''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.
+''qsub **-hold_jid** 121144,121145''
+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''
+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:-).
+=== qsub wrappers ===
-==== ~bojar/tools/shell/qsubmit ====
+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.
-qsubmit je jako qsub, ale příjemnější:
+=== qunhold ===
+''~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!
-  * nemusíte vyrábět skript, vyrobí ho sám (pozn.: nemusíte vyrábět skript, když použijete přepínač ''-b y'')
+=== sshcwd ===
-  * nemusíte připisovat ''-cwd -j y -S /bin/bash''
+This is useful not only when sshing to sol machines. Add the following lines to your ''~/.bashrc''.
 <code>
-~bojar/tools/shell/qsubmit "bashovy_prikaz < prismeruj > presmeruj 2> atd..."
+function sshcwd () {
-</code>
+  # save the current history so that it is available
+  # immediately on the remote machine
+  history -a;
+  # setup the working directory by setting WD
+  ssh -X -Y -C -t $@ "WD='$PWD' /bin/bash --login -i";
+}
-lépe funguje ''~{stepanek,pajas}/bin/qcmd'' (nemusí se kvotovat parametry, správně počítá čas běhu...)
+# 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"
+</code>
+=== In-script options ===
+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''.
+=== Array jobs ===
+If you have a set of tasks (of the same type) and want to run them on multiple machines, use ''qsub -t''...
+TODO
 ===== Monitorování úloh =====
@@ Line 196: / Line 279: @@
 Pokud chcete submittovaný program pouštět ve svém oblíbeném prostředí (např. nastavení ''PATH''), musíte v obalujícím skriptu příslušné ''.bash*'' načíst. Vždy je ale bezpečnější všude psát plné cesty, než spoléhat na PATH.
-==== Jiný shell ====
-Abych mohl poslat nějakou úlohu do fronty, musím pro ni vyrobit vlastní skript. Budiž, vyrobil jsem vlastní skript:
-<code>
-#!/bin/bash
-program > log.out 2> log.err
-</code>
-Když tento skript spustím, stane se očekávané. Přesměrují se výstupy z daného programu do souborů a je to.
-Když takový skript submitnu, program se **nespustí**. V logu zjistím, že (standardní chybový) výstup shellu, který pouštěl můj skript praví kryptickou zprávu "Ambiguous redirect".
-Nebudu vás napínat, zde je vysvětlení: SGE ignoruje první řádek skriptu (ve skutečnosti je pravda horší, hledá v něm nějaké parametry pro sebe) a spouští skript v ''csh''. Rozdíl mezi bashem a csh se v primitivních skriptech na první pohled nepozná, pozná se až v konstrukci if-then-else, a také v přesměrovávání. csh nerozumí přesměrování ''2>''
-Takto SGE přinutíte, aby použilo bash:
-<code>
-  qsub -S /bin/bash skript
-</code>
-Jinou možností je přesměrovat stderr a stdout pomocí syntaxe csh:
-<code>
-( command >stdout_file ) >&stderr_file
-</code>
 ==== bashrc a podobné nesmí nic vypisovat na konzoli ====
@@ Line 250: / Line 305: @@
 hard resource_list:         mem_free=16g
 hard resource_list:         mem_free=31g</code>
-==== Jak rezervovat více jader na stejném stroji pro 1 job ====
-<code>
-qsub -pe smp <pocet jader>
-</code>

[ Back to the navigation ] [ Back to the content ]

Institute of Formal and Applied Linguistics Wiki

Differences