# Contents of /trunk/doc/user/execute.tex

Revision 2316 - (show annotations)
Thu Mar 19 01:22:15 2009 UTC (10 years, 6 months ago) by gross
File MIME type: application/x-tex
File size: 7124 byte(s)
some documentation on the escript wrapper added.

 1 \chapter{Execution of an {\it escript} Script} 2 \label{EXECUTION} 3 4 \section{Overview} 5 A typical way of starting your {\it escript} script \file{myscript.py} is done through 6 \begin{verbatim} 7 escript myscript.py 8 \end{verbatim} 9 as already shown in section~\ref{FirstSteps}\footnote{It is assumed that your \program{escript} is included in your \env{PATH} environment. See installation guide for details.} 10 \footnote{The \program{escript} launcher is not supported under \WINDOWS yet.}. In some cases 11 it can be useful to interactively work e.g. when debugging a script with the command 12 \begin{verbatim} 13 escript -i myscript.py 14 \end{verbatim} 15 the script \var{myscript.py} is processed and after completion or if an error occured the 16 \program{escript} will remain in the \PYTHON prompt. To leave the prompt press \kbd{Control-d}. 17 18 To start 19 \program{escript} using four threads (eg. if you use a multi-core processor) you can use 20 \begin{verbatim} 21 escript -t 4 myscript.py 22 \end{verbatim} 23 This will require {\it escript} to be compiled for \OPENMP. 24 25 To start \program{escript} using \MPI with 8 processors you use 26 \begin{verbatim} 27 escript -n 8 myscript.py 28 \end{verbatim} 29 If the processors which are used are multi--core processors or multi--processor shared memory archtiectures you can use threading in addition to \MPI. For instance to run $8$ \MPI processors with using $4$ threads each you use the command 30 \begin{verbatim} 31 escript -n 8 -t 4 myscript.py 32 \end{verbatim} 33 Alternatively one can use $4$ \MPI processors on each of the $8$ compute nodes through the command 34 \begin{verbatim} 35 escript -n 8 -s 4 myscript.py 36 \end{verbatim} 37 where $4$ now specifies the number of slots per compute node. It is also possible 38 to combine the usage of slots and threading however. Threading has a 39 performance advantage over the usage of slots. 40 41 \section{Options} 42 The general form of the \program{escript} launcher is as follows: 43 44 \program{escript} 45 \optional{\programopt{-n \var{nn}}} 46 \optional{\programopt{-s \var{ns}}} 47 \optional{\programopt{-t \var{nt}}} 48 \optional{\programopt{-f \var{hostfile}}} 49 \optional{\programopt{-x}} 50 \optional{\programopt{-V}} 51 \optional{\programopt{-e}} 52 \optional{\programopt{-h}} 53 \optional{\programopt{-v}} 54 \optional{\programopt{-o}} 55 \optional{\programopt{-c}} 56 \optional{\programopt{-i}} 57 \optional{\var{file}} 58 \optional{\var{ARGS}} 59 60 where \var{file} is the name of a script, \var{ARGS} are arguments. 61 The \program{escript} program will import your current environment. 62 The options are used as follows: 63 \begin{itemize} 64 65 \item[\programopt{-n} \var{nn}] the number of compute nodes \var{nn} to be used. The total number of process being used is 66 $\var{nn} \cdot \var{ns}$. This option overwrites the value of the \env{ESCRIPT_NUM_NODES} environment variable. If $\var{nn}>1$ but {\it escript} is not compiled for \MPI a warning is pronted but execution is continued with $\var{nn}=1$. The default value is 1. 67 68 \item[\programopt{-s} \var{ns}] the number of processor slots per node. This options specifies how many \MPI processors are used on each node. The total number of process being used is 69 $\var{nn} \cdot \var{ns}$. This option overwrites the value of the \env{ESCRIPT_NUM_SLOTS} environment variable. If $\var{ns}=1$ but {\it escript} is not compiled for \MPI a warning is printed but execution is continued with $\var{ns}>1$. The default value is 1. 70 71 \item[\programopt{-t} \var{nt}] the number of threads used per processor. This options specifies how many threads are used on each node. The option overwrites the value of the \env{ESCRIPT_NUM_THREADS} environment variable. If $\var{nt}>1$ but {\it escript} is not compiled for \OPENMP a warning is printed but execution is continued with $\var{nt}=1$. The default value is 1. 72 73 \item[\programopt{-f} \var{hostfile}] the name of a file with a list of host names. Some systems require to specify the addresses or names of the compute nodes where \MPI process should be spawned. The list of addresses or names of the compute nodes is listed in the file with the name \var{hostfile}. In order to avoid oversubsription the number of differnt 74 hosts defined in \var{hostfile} must be greater or equalt to the number of requsted compute nodes \var{nn}. The option overwrites the value of the \env{ESCRIPT_HOSTFILE} environment variable. By default value no host file is used. 75 \item[\programopt{-c}] prints the information about the settings used to compile {\it escript} and stops execution.. 76 \item[\programopt{-V}] prints the version of {\it escript} and stops execution. 77 \item[\programopt{-h}] prints a help message and stops execution. 78 \item[\programopt{-i}] excutes the script \var{file} and switches to interactive mode after the execution is finished or an exception has occured. This option is useful for debugging a script. The option cannot be used if more then one processor ($\var{nn} \cdot \var{ns}>1$) is used. 79 80 \item[\programopt{-e}] shows additional environment variables and commands used during \program{escript} execution. This option is useful if users wish to excute scripts without using \program{escript}. 81 82 \item[\programopt{-o}] switches on the redirection of standart and error output of processors with \MPI rank greater than zero to the files \file{stdout_\var{r}.out} and \file{stderr_\var{r}.out} where \var{r} is the rank of the processor. The option overwrites the value of the \env{ESCRIPT_STDFILES} environment variable 83 84 \item[\programopt{-x}] uses \var{file} as an \esysxml. 85 This option is still expermental. 86 87 \item[\programopt{-v}] prints some diagonstic information. 88 \end{itemize} 89 90 \section{Input and Output} 91 The \program{escript} launcher can be run in the interactive mode, i.e. 92 \programopt{-i} or no script name \var{file} is given, if used on a single processor (possibly with several threads). When \MPI is used on more than one processor ($\var{np} \cdot \var{ns} >1$) no input from the standart input is excepted. Standart output on any processor other the the master processor (\var{rank}=0) will not be available. Error output from any processor will be redirected to the node where \program{escript} has been envoked. If the \programopt{-o} or \env{ESCRIPT_STDFILES} is set the standart and error output from any processor other the the master processor will be written 93 to files of the names \file{stdout_\var{r}.out} and \file{stderr_\var{r}.out} where 94 \var{r} is the rank of the processor. 95 96 If files are created or read by individual \MPI processors with information local to the processor (e.g in the \function{dump} function) and more than one processor is used ($\var{np} \cdot \var{ns} >1$), file names are extended by the \MPI processor rank. This will avoid problems if processors are using a shared file system. Files which collect data which are global for all \MPI processors will created on the processor with \MPI rank 0 only. Users should keep in mind that if the file system is not shared a file containing global information 97 which is read by all processors needs to be copied to the local file system before \program{escript} is invoked. 98 99 100 \section{Hints for MPI programming} 101 Later